Resharding databases
InfinigraphNot available on AuraIntroduced in 2025.12

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

  • Server resharding (online): Selecting more property shards than needed at creation time to allow space for their data to grow or by adjusting the number of property shard replicas to allow for more or less redundancy and read scalability.

  • Database resharding: Copying an existing standard database, or starting with Neo4j 2026.03, a backup of an existing standard or sharded property database, to create a new sharded property database with the desired number of property shards.

Server resharding (online)

There are two ways to reshard a sharded property database online:

Select more property shards than needed at creation time (online)

You can select more property shards than needed at creation time and allow space for their data to grow, as the Neo4j cluster allows databases to be moved based on server availability. For example, six property shards can be initially hosted across three servers (two shards per server), with additional servers added as needed.

Creating a sharded property database with more property shards than needed at creation time
CREATE DATABASE foo
GRAPH SHARD     { TOPOLOGY 1 PRIMARY 0 SECONDARIES }
PROPERTY SHARDS { COUNT 6 TOPOLOGY 1 REPLICA };

For details on managing databases and servers in a cluster, see Managing databases in a cluster and Managing servers in a cluster.

Scale by adjusting the number of property shard replicas (online)

You can adjust the number of property shard replicas in a sharded property database to allow for more or less redundancy and read scalability without downtime.

For example, to change the number of replicas for the property shard foo-sharded-p000, connect to the DBMS either via the driver or Cypher Shell, and run the following command:

ALTER DATABASE `foo-sharded-p000`
SET TOPOLOGY 2 REPLICAS;

Database resharding

You can create a new sharded property database with the desired number of property shards by copying an existing database, which can be a standard database, or starting with Neo4j 2026.03, a backup of an existing standard or sharded property database.

Split an existing database into shards (offline)

You can use the neo4j-admin database copy command to create a sharded property database from a standard database, specifying the number of property shards for the new database. The existing database must be stopped during the copying process.

The following options can be specified for the neo4j-admin database copy command:

  • --copy-schema — to copy the schema of the existing database if needed.

  • --property-shard-count — the number of property shards to create for the new database, which must be more than 0.

  • --target-location — a path to a folder for target backup artifact data. Used together with --target-format=backup.

  • --target-format — the format of the output data. Possible values are backup and database (default).

It is not possible to specify a store format for sharded databases; if specified, it will be ignored, and a warning will be logged.

The following example shows how to create a new sharded property database, called foo-sharded, in a cluster deployment, from the existing standard database foo. The foo database must be stopped during the copying process.

  1. Copy the data from the existing database foo into the database foo-sharded, creating one graph shard and three property shards:

    neo4j-admin database copy foo foo-sharded --copy-schema --property-shard-count 3 --target-location=s3://bucket/folder/ --target-format=backup

    For more information about the syntax and options of the neo4j-admin database copy command, see Copy a database store.

    Copying a database does not automatically create it. Therefore, it will not be visible if you do SHOW DATABASES at this point.

  2. Connect to the DBMS either via the driver or Cypher Shell, and run the following command to create the database foo-sharded, as a sharded property database by seeding it from your backup folder in the AWS S3 bucket:

    CREATE DATABASE `foo-sharded`
DEFAULT LANGUAGE CYPHER 25
PROPERTY SHARDS { COUNT 3 }
OPTIONS {seedUri: “s3://bucket/folder/”};

    The cluster automatically distributes the data across its servers. For more information on seed providers, see Creating a sharded database from a URI (online).

  3. Verify that the new database is online by running the following command:

    SHOW DATABASES;

Create a sharded property database from a backup of a standard database (online)
Introduced in 2026.03

You can use the neo4j-admin database copy command to create a sharded property database from a backup of a standard database. The process is similar to resharding a database by splitting an existing database into shards, but instead of using a standard database as the source, you use a backup of a standard database.

The following options should be specified for the neo4j-admin database copy command:

  • --source-location — a path to the full backup of an existing database or the last diff backup in the chain. This folder can be located locally or remotely (e.g., an S3 bucket) and must contain the full backup and all the diff backups in the chain, if any.

  • --source-format=backup — the format of the source backup.

  • --copy-schema — to copy the schema of the existing database if needed.

  • --property-shard-count — the number of property shards to create for the new database, which must be more than 0.

  • --target-location — a path to a folder for target backup artifact data. Used together with --target-format=backup.

  • --target-format — the format of the output data. Possible values are backup and database (default).

--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.
It is also not possible to specify a store format for sharded databases; if specified, it will be ignored, and a warning will be logged.

The following example shows how to create a sharded property database, called foo-sharded, with 3 property shards, from a backup of the existing database foo, in a cluster deployment. It assumes that you have a backup of your existing database foo in an AWS S3 bucket. If you do not have a backup of your database or you are unsure whether you have a current backup, follow steps 1 and 2. Otherwise, proceed directly to step 3.

  1. Connect to the DBMS either via the driver or Cypher Shell, and put the database foo into read-only mode to ensure your sharded version of foo will have all the data after copying as the old database.

    ALTER DATABASE foo SET ACCESS READ ONLY;

  2. Back up the database foo to a location that is accessible by the cluster, such as an AWS S3 bucket, using the neo4j-admin database backup command. The --type=full option forces the creation of a full backup of the database even if there are existing full backups in the specified location.

    bin/neo4j-admin database backup --type=full --to-path=s3://bucket/folder/ foo

    For more information about the syntax and options of the neo4j-admin database backup command, see Back up a database to a cloud storage.

  3. Copy the data from a backup of your standard database foo into the database foo-sharded, creating one graph shard and three property shards.

    neo4j-admin database copy foo foo-sharded --source-location=s3://bucket/folder/foo.backup --source-format=backup --copy-schema --property-shard-count 3 --target-location=s3://bucket/folder --target-format=backup

    For more information about the syntax and options of the neo4j-admin database copy command, see Copy a database store.

    Copying a database does not automatically create it. Therefore, it will not be visible if you do SHOW DATABASES at this point.

  4. Connect to the DBMS either via the driver or Cypher Shell, and run the following command to create the database foo-sharded as a sharded property database by seeding it from your backup folder in the AWS S3 bucket:

    CREATE DATABASE `foo-sharded`
DEFAULT LANGUAGE CYPHER 25
PROPERTY SHARDS { COUNT 3 }
OPTIONS {seedUri: “s3://bucket/folder/”};

    The cluster automatically distributes the data across its servers. For more information on seed providers, see Create a database from a URI.

  5. Wait until the last committed transaction ID is the same for all allocations of the database and then verify that the new database is online by running the following command:

    SHOW DATABASES;

  6. After the new database is online, you can drop the old database foo if it is no longer needed, or put it into read-write mode if you want to keep it for other purposes.

    Run the following command to drop the old database foo:

    DROP DATABASE foo;

    Change the access mode of the old database foo to read-write:

    ALTER DATABASE foo SET ACCESS READ WRITE;

Create a sharded property database from a backup of a sharded property database (online)
Introduced in 2026.03

You can use the neo4j-admin database copy command to create a new sharded property database from a backup of an existing sharded property database and specify a different number of property shards for the new database. The process is similar to creating a sharded property database from a backup of a standard database, but instead of using a backup file as the source, you specify the folder containing all backups of an existing sharded property database as the source.

Keep in mind that this process can take a long time to complete, especially if the existing database is large, as it involves copying all data from all the shards and redistributing it across the new shards.

The following options should be specified for the neo4j-admin database copy command:

  • --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. This folder can be located locally or remotely (e.g., an S3 bucket).

  • --source-format=backup — the format of the source backup.

  • --copy-schema — to copy the schema of the existing database if needed.

  • --property-shard-count — the number of property shards to create for the new database, which must be more than 0.

  • --target-location — a path to a folder for target backup artifact data. Used together with --target-format=backup.

  • --target-format — the format of the output data. Possible values are backup and database (default).

  • The name of the database to copy from must be the name of the virtual database.

--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.
It is also not possible to specify a store format for sharded databases; if specified, it will be ignored, and a warning will be logged.

The following example shows how to create a sharded property database, called foo-sharded-new, with 5 property shards, from a backup of the existing sharded property database, foo-sharded, in a cluster deployment. It assumes that you have a backup of your existing sharded property database foo-sharded in an AWS S3 bucket.
If you do not have a backup of your database or you are unsure whether you have a current backup, see Backup and restore for instructions on how to back up your database. 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. 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.

  1. Copy the data from a backup of your sharded property database foo-sharded into the database foo-sharded-new, changing the number of property shards to 5:

    neo4j-admin database copy foo-sharded foo-sharded-new --source-location=s3://bucket/folder --source-format=backup --copy-schema --property-shard-count 5 --target-location=s3://bucket/folder/ --target-format=backup

    For more information about the syntax and options of the neo4j-admin database copy command, see Copy a database store.

    Copying a database does not automatically create it. Therefore, it will not be visible if you do SHOW DATABASES at this point.

  2. Connect to the DBMS either via the driver or Cypher Shell, and run the following command to create the database foo-sharded-new as a sharded property database by seeding it from your backup folder in the AWS S3 bucket:

    CREATE DATABASE `foo-sharded-new`
DEFAULT LANGUAGE CYPHER 25
PROPERTY SHARDS { COUNT 5 }
OPTIONS {seedUri: “s3://bucket/folder/”};

    The cluster automatically distributes the data across its servers. For more information on seed providers, see Create a database from a URI.

  3. Wait until the last committed transaction ID is the same for all allocations of the database and then verify that the new database is online by running the following command:

    SHOW DATABASES;

  4. 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.

    Run the following command to drop the old database foo-sharded:

    DROP DATABASE foo-sharded;

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

    ALTER DATABASE foo-sharded SET ACCESS READ WRITE;