Skip to content

Commit d9ac4e0

Browse files
renetapopovarenetapopova
authored
Add consolidating databases (#3068)
1 parent 1719e56 commit d9ac4e0

1 file changed

Lines changed: 137 additions & 3 deletions

File tree

‎modules/ROOT/pages/scalability/sharded-property-databases/resharding-databases.adoc‎

Lines changed: 137 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
:page-role: new-2025.12 infinigraph not-on-aura
2-
:description: This page describes how to create a sharded property database by splitting an existing Neo4j database.
3-
:keywords: sharded property database, resharding, reshard, split, existing database, data migration, data redistribution
4-
= Resharding databases
2+
:description: This page describes how to reshard an existing database into a new sharded property database, as well as how to consolidate a sharded property database into a standard database.
3+
:keywords: sharded property database, resharding, reshard, split, server resharding, database resharding, data redistribution, consolidating, scale-in, scale-out, server consolidation, database consolidation
4+
= Resharding and consolidating databases
55

66
Neo4j supports several methods for resharding a database, depending on your specific requirements and constraints:
77

@@ -286,6 +286,140 @@ DROP DATABASE foo-sharded;
286286

287287
Change the access mode of the old database `foo-sharded` to read-write:
288288

289+
[source, cypher]
290+
----
291+
ALTER DATABASE foo-sharded SET ACCESS READ WRITE;
292+
----
293+
======
294+
=====
295+
296+
== Database consolidation
297+
298+
You can consolidate a sharded property database into a standard database by copying the data from the sharded property database into a new standard database, or by creating a new standard database from a backup of the sharded property database.
299+
300+
=== Consolidating a sharded property database into a standard database
301+
302+
To consolidate a sharded property database into a standard database, you can use the `neo4j-admin database copy` command to create a new standard database from an existing sharded property database.
303+
The existing sharded property database must be stopped during the copying process.
304+
305+
The following options can be specified for the `neo4j-admin database copy` command:
306+
307+
* `--copy-schema` -- (optional) to copy the schema of the existing database if needed.
308+
* `--target-location` -- a path to a folder for target backup artifact data. Used together with `--target-format=backup`.
309+
* `--target-format` -- the format of the output data.
310+
Possible values are `backup` and `database` (default).
311+
* `--to-format=block` -- the store format of the output data, which must be `block` for standard databases.
312+
* `--compress` -- label:new[Introduced in 2026.04] (optional) produces compressed backup artifacts.
313+
See xref:backup-restore/copy-database.adoc#copy-database-command-options[Copy a database store] for more information.
314+
315+
The following example shows how to create a new standard database, called `foo`, in a cluster deployment, from the existing sharded property database `foo-sharded`.
316+
The `foo-sharded` database must be stopped during the copying process.
317+
318+
. Copy the data from the existing database `foo-sharded` into the database `foo`, creating a standard database with no property shards:
319+
+
320+
[source, shell]
321+
----
322+
neo4j-admin database copy foo-sharded foo --copy-schema --to-format=block --target-location=s3://bucket/folder/ --target-format=backup
323+
----
324+
+
325+
For more information about the syntax and options of the `neo4j-admin database copy` command, see xref:backup-restore/copy-database.adoc[Copy a database store].
326+
+
327+
Copying a database does not automatically create it.
328+
Therefore, it will not be visible if you do `SHOW DATABASES` at this point.
329+
330+
. Connect to the DBMS either via the driver or Cypher Shell, and run the following command to create the database `foo`, as a standard database by seeding it from your backup folder in the AWS S3 bucket:
331+
+
332+
[source, cypher]
333+
----
334+
CREATE DATABASE `foo`
335+
DEFAULT LANGUAGE CYPHER 25
336+
OPTIONS {seedUri: “s3://bucket/folder/”};
337+
----
338+
+
339+
The cluster automatically distributes the data across its servers.
340+
For other seed data options, see xref:scalability/sharded-property-databases/creating-sharded-databases.adoc#creating-sharded-db-from-uri[Creating a sharded database from a URI (online)].
341+
. Verify that the new database is online by running the following command:
342+
+
343+
[source, cypher]
344+
----
345+
SHOW DATABASES;
346+
----
347+
348+
=== Consolidating a sharded property database into a standard database by using a backup of the sharded property database
349+
350+
To consolidate a sharded property database into a standard database, you can use the `neo4j-admin database copy` command to create a new standard database from a backup of an existing sharded property database.
351+
The process is similar to creating a standard database from a sharded property database, but instead of using a sharded property database as the source, you use a backup of an existing sharded property database as the source.
352+
353+
The following options can be specified for the `neo4j-admin database copy` command:
354+
355+
* `--source-location` -- a path to a folder containing all backups of an existing sharded property database, including the full backup and all the diff backups in the chain of the graph shard and the last full backup for each property shard.
356+
This folder can be located locally or remotely (e.g., an S3 bucket).
357+
* `--source-format=backup` -- the format of the source backup.
358+
* `--copy-schema` -- (optional) to copy the schema of the existing database if needed.
359+
* `--target-location` -- a path to a folder for target backup artifact data. Used together with `--target-format=backup`.
360+
* `--target-format` -- the format of the output data.
361+
Possible values are `backup` and `database` (default).
362+
* `--to-format=block` -- the store format of the output data, which must be `block` for standard databases.
363+
* `--compress` -- label:new[Introduced in 2026.04] (optional) produces compressed backup artifacts.
364+
See xref:backup-restore/copy-database.adoc#copy-database-command-options[Copy a database store] for more information.
365+
* The name of the database to copy from must be the name of the virtual database.
366+
367+
`--source-location` and `--source-format` cannot be used together with `--from-path-data` and/or `--from-path-txn` due to the conflict in trying to supply data from two different locations at once.
368+
369+
The following example shows how to create a standard database, called `foo` from a backup of the existing sharded property database, `foo-sharded`, in a cluster deployment.
370+
It assumes that you have a backup of your existing sharded property database `foo-sharded` in an AWS S3 bucket. +
371+
If you do not have a backup of your database or you are unsure whether you have a current backup, see xref:scalability/sharded-property-databases/admin-operations.adoc#backup-and-restore[Backup and restore] for instructions on how to back up your database.
372+
To be completely sure that all backups are on the same transaction, it is recommended to put the database into read-only mode, running `ALTER DATABASE foo-sharded SET ACCESS READ ONLY` using Cypher Shell or the driver.
373+
Copy works even if the backups of the shards have different last applied transactions but there might be some data loss due to one shard not having all information from the last transactions.
374+
375+
. Copy the data from a backup of your sharded property database `foo-sharded` into a standard database `foo`:
376+
+
377+
[source, shell]
378+
----
379+
neo4j-admin database copy foo-sharded foo --to-format=block --source-location=s3://bucket/folder --source-format=backup --copy-schema --target-location=s3://bucket/folder/ --target-format=backup
380+
----
381+
+
382+
For more information about the syntax and options of the `neo4j-admin database copy` command, see xref:backup-restore/copy-database.adoc[Copy a database store].
383+
+
384+
Copying a database does not automatically create it.
385+
Therefore, it will not be visible if you do `SHOW DATABASES` at this point.
386+
387+
. Connect to the DBMS either via the driver or Cypher Shell, and run the following command to create the database `foo` as a standard database by seeding it from your backup folder in the AWS S3 bucket:
388+
+
389+
[source, cypher]
390+
----
391+
CREATE DATABASE `foo`
392+
DEFAULT LANGUAGE CYPHER 25
393+
OPTIONS {seedUri: “s3://bucket/folder/”};
394+
----
395+
+
396+
The cluster automatically distributes the data across its servers.
397+
For other seed data options, see xref:database-administration/standard-databases/seed-from-uri.adoc[Create a database from a URI].
398+
. Verify that the new database is online by running the following command:
399+
+
400+
[source, cypher]
401+
----
402+
SHOW DATABASES;
403+
----
404+
. After the new database is online, you can drop the old database `foo-sharded` if it is no longer needed, or put it into read-write mode if you want to keep it for other purposes.
405+
+
406+
[.tabbed-example]
407+
=====
408+
[.include-with-drop-database]
409+
======
410+
411+
Run the following command to drop the old database `foo-sharded`:
412+
413+
[source, cypher]
414+
----
415+
DROP DATABASE foo-sharded;
416+
----
417+
======
418+
[.include-with-change-access-mode]
419+
======
420+
421+
Change the access mode of the old database `foo-sharded` to read-write:
422+
289423
[source, cypher]
290424
----
291425
ALTER DATABASE foo-sharded SET ACCESS READ WRITE;

0 commit comments

Comments
 (0)