Recreate a database

The recreate procedure

The recreate procedure allows you to:

  • Change the database store to a specified backup, while keeping all the associated privileges for the database.

  • Make your database write-available again after it has been lost (for example, due to a disaster). See Disaster recovery for more information.

  • Introduced in 2025.02 Delete the data and schema for a database, while keeping the database privileges assigned to each role.

  • Introduced in 2025.04 Alter the database store format when clearing the data and schema.

The recreate procedure works only for real user databases and not for composite databases, or the system database.

Remember that the recreate procedure results in downtime while the stores get updated. The time is unbounded and may depend on different factors — for example, the size of the store, network speed, etc.

In Neo4j 2025.04, the dbms.cluster.recreateDatabase() procedure is deprecated in favor of dbms.recreateDatabase().

Syntax

dbms.recreateDatabase(database :: STRING, options = {} :: MAP)

Input arguments are the database name and list of the seeding and topology options used for recreating a database.

Table 1. Seeding and topology options of the recreate procedure
Option Description

seedingServers

A list of possible seeding servers. You can define available servers or provide an empty list. For details, see Use available servers as a seed.

seedURI

External source specified by URI.

clearData Introduced in 2025.02

Allows you to delete the data and schema for a database, while keeping the database privileges assigned to each role.

storeFormat Introduced in 2025.04

Allows you to change the database store format when clearing the data and schema.

primaries

Number of primary allocations for the recreated database. If you set number of primaries without secondaries, then secondaries is set to 0. For more details, see Change the topology.

secondaries

Number of secondary allocations for the recreated database. You cannot set secondaries without primaries.

Prerequisites and considerations

The database in question can be in an online or offline state when it is recreated, but a successful operation starts the database regardless of its previous state.

If your database has Change Data Capture (CDC) enabled, the CDC chain will stop when the database is recreated, even though CDC remains enabled in the recreated database. To restore CDC functionality, follow the guide on how to initialize CDC applications from an existing database.

Before recreating a database, any eventual quarantined states need to be addressed. For more information, see Standard databases → Error handling.

You need the CREATE DATABASE and DROP DATABASE privileges to run the recreate procedure.

Additionally, in a cluster deployment, you have the option to modify the topology during the recreation process.

However, note that the store format (up to Neo4j 2025.04), access, and enrichment cannot be altered during recreation. Starting with 2025.04, the store format can only be altered if the clearData option is used.

To check if the recreation is successful, use the SHOW DATABASES command and verify that all allocations have been started.

Seeding options

The store to be used during the recreation of a database can be defined in different ways. One method uses a backup, while others use available allocations in the cluster.

You can use either seedURI or seedingServers to specify the source from which the database should be recreated.

  • If you define neither, an error is thrown.

  • If you define both of them, then seedingServers must be an empty list. See Undefined servers with fallback backup for more details.

  • If seedingServers is not empty and seedURI is also defined, an error will occur.

Use a backup as a seed

If you provide a URI to a backup or a dump, the stores on all allocations will be replaced by the backup or the dump at the given URI. The new allocations can be put on any ENABLED server in the cluster. See Seed from URI for more details.

CALL dbms.recreateDatabase("neo4j", {seedURI: "s3://myBucket/myBackup.backup"});

Use available servers as a seed

After the recreation is complete, the database will have the latest data store from the seeding servers.

Recreation is based on available remaining stores or specific stores explicitly defined by the user. Stores that are lost or not explicitly specified are excluded from the recreation process. Therefore, if the excluded stores contained more recent data than those used, data loss may occur.
Specified servers

You can specify a set of available servers. The stores on all allocations will be synchronized to the most up-to-date store from the defined servers. The number of defined servers cannot exceed the number of total allocations in the desired topology.

CALL dbms.recreateDatabase("neo4j", {seedingServers: ["serverId1", "serverId2", "serverId3"]});
Undefined servers

If you provide an empty list of seeding servers and do not specify a seedURI, Neo4j will select all allocations of the database (primaries and secondaries) on currently enabled and non-cordoned servers to act as seeders.

Before running the procedure, ensure that all unavailable servers are cordoned; otherwise, the procedure will fail.

To determine where the database is allocated, use the SHOW DATABASES command. To identify all enabled and available servers hosting the required database, run the SHOW SERVERS command. Servers have to show health = Available and status = Enabled. Cordon all unreachable servers by running the dbms.cluster.cordonServer() procedure.

Then Neo4j will select the most up-to-date seeder available in the cluster to recreate the database.

CALL dbms.recreateDatabase("neo4j", {seedingServers: []});
Undefined servers with fallback backup

If both an empty list of seeding servers and a seedURI are provided, Neo4j finds all allocations of the database and use those as seeders. Unavailable servers must be cordoned.

However, if no available servers can be found, the database is recreated based on the backup or the dump specified by the URI. This means the store is replaced by the most up-to-date seeder if available; otherwise, the backup is used.

CALL dbms.recreateDatabase("neo4j", {seedingServers: [], seedURI: "s3://myBucket/myBackup.backup"});

Change the topology

In a cluster deployment, there is an option to define a new topology when recreating a database. This can be beneficial during a disaster, if enough servers are not available to recreate the database with the original topology. When altering the total number of allocations down during a recreation, it is important to remember that the number of seeding servers cannot exceed the number of total allocations of the database. This also holds true when using recreate with an empty list of seeders. If there are more available servers in the cluster hosting the database than the number of new allocations, the recreation will fail.

CALL dbms.recreateDatabase("neo4j", {seedingServers: [], primaries: 3, secondaries: 0});

Clear data option

In Neo4j 2025.02, the clearData option was added to the recreate procedure. This option allows you to delete the data (e.g., nodes and relationships) and the schema (e.g., constraints and indexes) for the database. This means you end up with an empty store, but as with the other recreate database options, all privileges associated with the database are kept.

Using the clear data option means the data and schema will be deleted permanently. If you want to have the option of getting them back later, make sure to take a backup before clearing the database. See Online backup for more information.

Alter the database store format

In Neo4j 2025.04, the database store format can also be altered during recreation, but only when the clearData option is specified.

See Store formats, for more details about available database store formats in Neo4j. If the store format option is not defined, the recreated database ends up with the same store format as before the recreation.

CALL dbms.recreateDatabase("neo4j", {clearData: true, storeFormat: "block"});