Admin operations
Enterprise EditionNot available on AuraIntroduced in 2025.12

Sharded property databases are managed similarly to standard Neo4j databases, with some differences in certain administrative operations.

Managing aliases for sharded databases

When creating an alias for a sharded database, use the virtual database name when specifying it as the alias target. The following example shows how to create the alias foo for the sharded database foo-sharded:

CREATE ALIAS foo FOR DATABASE `foo-sharded`

Managing servers with sharded databases

Graph references in server management commands must refer to shards. The virtual sharded database is rejected or ignored.

The following example shows how to enable a server and allow allocating the property shard foo-sharded-p000:

ENABLE SERVER 'serverId'  OPTIONS { allowedDatabases: ['foo-sharded-p000'] }

Resizing and resharding

Resizing

You can resize a sharded property database by adding or removing property shards. You can select more shards than needed to start with and allow space for their data to grow, as the Neo4j cluster allows databases to be moved based on server availability. For example, ten property shards can be initially hosted on five servers (two shards per server), and additional servers can be added as needed. For details on managing databases and servers in a cluster, see Managing databases in a cluster and Managing servers in a cluster.

Resharding

You can reshard your data via the neo4j-admin database copy command. See Splitting an existing database into shards for more information.

Backup and restore

A sharded property database is a database made up of multiple databases. This means that when you want to back up a database, you must back up all the shards individually, resulting in a sharded property database backup that is composed of multiple smaller backup chains.

Backup chains for each shard are produced using the neo4j-admin database backup command. For the graph shard, its backup chain must contain one full artefact and 0+ differential artefacts. Each property shard’s backup chain must contain only one full backup and no differential backups. In practical terms, this means that to back up a sharded property database, you start with a full backup of the graph shard and then all of the property shards; any subsequent differential backups would only need to be of the graph shard. This is because the transaction log of the property shards is the same as the graph shard log and is simply filtered when applied, so only the graph shard log is required for a restore.

Backing up a sharded property database

For example, assume there is a sharded property database called foo with a graph shard and 2 property shards.

  1. Back up each shard, for example:

    bin/neo4j-admin database backup "foo*" --to-path=/backups --from=localhost:6361 --remote-address-resolution

  2. Check the validity of the resulting backups. For details on command syntax and options, see Validate a database backup.

    bin/neo4j-admin backup validate --from-path=s3://bucket/backups --database="foo"

    The output will indicate whether the backups are valid. For example:

    | DATABASE |                                                PATH | STATUS |
| foo-g000 | /bucket/backups/foo-g000-2025-06-11T21-04-42.backup |     OK |
| foo-p000 | /bucket/backups/foo-p000-2025-06-11T21-04-37.backup |     OK |
| foo-p001 | /bucket/backups/foo-p001-2025-06-11T21-04-40.backup |     OK |

Restoring a sharded property database

You can use the CREATE DATABASE command to seed a sharded property database from a valid backup. The following example seeds the sharded property database baz from backups stored in an S3 bucket:

CYPHER 25 CREATE DATABASE baz SET GRAPH SHARD { TOPOLOGY 3 PRIMARIES 0 SECONDARIES }
SET PROPERTY SHARDS { COUNT 2 TOPOLOGY 1 REPLICA }
OPTIONS {seedUri:"s3://bucket/backups/"};

Understanding backup validation

Due to potential synchronization issues that might occur when shard backups are not on the exact same transaction IDs (since backups can be taken in parallel or sequentially), the restore process is designed to be very lenient to different shards at different transaction IDs. As a result, a sharded property database backup is considered valid if the store files of each property shard are within the range of transactions recorded in the graph shard’s transaction log.

For example, assume the graph shard’s store files are at tx 10 and it has transaction logs from tx 11-36, and property shard 1’s store files are at 13 and property shard 2’s store files are at 30, then at restore time, all databases can be recovered and made consistent up to transaction 36.

You can use the command neo4j-admin backup validate to check whether a collection of backup chains for a database is valid. For details on command syntax and options, see Validate a database backup.

Additional actions may be required to create a validated backup if a property shard is ahead or behind the range of transactions in the graph shard backup chain.

Example output
| DATABASE |                                         PATH |                                                   STATUS |
| foo-g000 | /backups/foo-g000-2025-06-11T21-04-42.backup |                                                       OK |
| foo-p000 | /backups/foo-p000-2025-06-11T21-04-37.backup | Backup is behind (3 < 5) the graph shard backup chain    |
| foo-p001 | /backups/foo-p001-2025-06-11T21-04-40.backup | Backup is ahead (12 > 8) of the graph shard backup chain |

To form a validated backup, you must ensure that each property shard’s store files are within the range of transactions recorded in the graph shard’s transaction log. In the example above, property shard foo-p000 is behind the graph shard backup chain, and property shard foo-p001 is ahead of the graph shard backup chain. To form a valid sharded property database backup, you need to:

  1. Take a full backup of the property shard foo-p000 so that its store at least includes transaction 5.

  2. Take a differential backup of the graph shard, so that at least transaction 12 is included in its transaction log, so foo-p001 is included in its range.

Once a valid sharded properties database backup is created, differential backups can be performed by taking differential backups of the graph shard, extending the range of the graph shard chain. Continuing with the example, the graph chain contains transactions from 11 to 36, property shard 1’s store files are at 13, and property shard 2’s store files are at 30. You then take a differential backup of the graph shard containing transactions 37 to 50. At restore time, all databases can be recovered up to transaction 50 and made consistent.

Transaction log pruning and recovery

In a sharded property database, property shards pull transaction log entries from the graph shard and apply them to their stores. Thus, it is required that the graph shard does not prune an entry from its transaction log until every replica of each property shard has pulled and applied that entry. Otherwise, a property shard replica that has not yet applied the latest entry will be unable to do so and will be severed, leading to data inconsistency. If this happens to all replicas of a given property shard, then the whole sharded property database is in an unrecoverable state.

To ensure enough transaction logs are kept, you must set db.tx_log.rotation.retention_policy accordingly. A suitable heuristic is to ensure that the transaction log kept covers the transactions written between successive full backups of the sharded property database. It is also important to ensure that there is space for the transaction logs and that the server does not run out of disk space.

Starting from Neo4j 2026.01, to prevent property shard replicas from becoming severed, the system automatically monitors the transaction apply lag of property shard replicas and prevents the graph shard from pruning entries that property shard replicas have not yet applied to their stores.
This mechanism prevents any property shard replica from falling behind the transaction log range available on the graph shard. If the inability to prune persists, then the system puts the sharded property database into read-only mode to prevent the server from running out of disk space. Once the underlying cause behind the lagging property shard is resolved, you can switch the sharded property database back into read-write mode by performing the following steps:

  1. Ensure that all replicas of all property shards are caught up with the graph shard’s transaction log using the following query against the system database:

    CYPHER 25
SHOW DATABASES YIELD name, type, role, lastCommittedTxn, replicationLag, shardTxnLag

    The replicationLag column shows how far behind each replica is from its primary, and the shardTxnLag column shows how far behind each property shard is from the graph shard.
    If any replica shows a non-zero replicationLag or shardTxnLag, wait for it to catch up.
    Once all replicas show zero replicationLag and shardTxnLag, the sharded property database is ready to be brought back to read-write mode.

  2. Run the Cypher command ALTER DATABASE <sharded-db-name> SET ACCESS READ WRITE against the system database to bring the sharded property database back to read-write mode.

In case of a system failover

The monitoring mechanism introduced in 2026.01, described in the previous paragraphs, should prevent property shards from being severed. However, in the unlikely event shards do fail, you can recover them using one of the following options:

  • If only a subset of replicas of a property shard are severed, you can recover them by quarantining each of the replicas and then using dbms.unquarantineDatabase with the replaceStateReplaceStore option:

    1. Connect to the system database on the server hosting the affected replica using the bolt:// scheme.

    2. Quarantine the replica using Cypher 5 CALL dbms.quarantineDatabase().

    3. Unquarantine the replica using Cypher 5 CALL dbms.unquarantineDatabase() with the replaceStateReplaceStore option. This will force the replica to copy the database store files from another replica of the property shard.

  • If all property shard replicas fall behind the transaction log range available on the graph shard, it usually indicates a larger problem, either a property shard database replica has panicked, the pruning strategy on the graph shard could be too aggressive, or there could be network issues between the graph shard and one of the replicas. To resolve the issue, you need to identify and fix the underlying problem first.

  • If for some reason the sharded property database becomes unrecoverable (for example, all replicas of a property shard become severed and the sharded property database is unavailable), the sharded property database must be dropped and recreated from a valid backup. See Backup and restore.