Skip to content
Merged
103 changes: 103 additions & 0 deletions modules/ROOT/pages/clustering/databases.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,109 @@ neo4j@neo4j> DRYRUN REALLOCATE DATABASES;
+----------------------------------------------------------------------------------------------------------------------------------------+
----

[role=label--new-5.24]
[[recreate-databases]]
== Recreate databases using a procedure

Neo4j 5.24 introduces the xref:reference/procedures.adoc#procedure_dbms_cluster_recreateDatabase[`dbms.cluster.recreateDatabase()`] procedure, which allows you:

* To restore a database store to a specified backup, while keeping all the users and roles (metadata) for the database.

* To restore a database to a write mode again after it has been lost (for example, due to a disaster).
See xref:clustering/disaster-recovery.adoc[] for more information.

[CAUTION]
====
The recreate procedure works only for real user databases and not for composite databases, or the `system` database.

Keep in mind the recreate procedure results in downtime while the stores get updated.
The time is unbounded and may depend on the store size and network speed.

The recreate procedure selects the most up-to-date seed from the defined seeding servers.
If only a subset of the previous cluster members is specified as seeders, there is a risk of data loss.
To avoid this, ensure you back up the current store before replacing it with a seed from a URI, so the latest state can be restored if needed.
====

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 the previous state.

If CDC is enabled for the database, it will still be enabled after recreating the database, however the chain will be broken.
See link:https://neo4j.com/docs/cdc/current/[CDC documentation] for more details.

Before recreating a database, any eventual quarantined states need to be addressed.
For more information, refer to the quarantined state documentation.

You need xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-database-management[the DBMS `DATABASE MANAGEMENT` privileges] to run the recreate procedure.

[[recreate-seeding-options]]
=== Seeding options and configurations

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

Additionally, you have the option to modify <<alter-topology-recreate, the topology>> during the recreation process.
However, note that the store format, access, and enrichment cannot be altered during recreation.

[[uri-seed]]
==== `seedURI`

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 <<cluster-seed-uri, Seed from URI>> for more details.

[source, shell]
----
CALL dbms.cluster.recreateDatabase("neo4j", {seedURI: "myBackup"});
----

[[seed-servers]]
==== `seedingServers`

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.

[source, shell]
----
CALL dbms.cluster.recreateDatabase("neo4j", {seedingServers: ["serverId1", "serverId2", "serverId3"]});
----

[[undefined-servers]]
==== Undefined servers

If you provide an empty list of seeding servers or do not specify a `seedURI`, Neo4j automatically selects all available allocations of the database as seeders.
The store will be replaced by the most up-to-date seeder available in the cluster.

[source, shell]
----
CALL dbms.cluster.recreateDatabase("neo4j", {seedingServers: []});
----

[[undefined-servers-backup]]
===== Undefined servers with fallback backup

If both an empty list of seeding servers and a `seedURI` are provided, the system finds all available allocations of the database and use those as seeders.
However, if no available servers can be found, the database is recreated based on the backup or the dump defined by the URI.
This means the store is replaced by the most up-to-date seeder if available; otherwise, the backup is used.

[source, shell]
----
CALL dbms.cluster.recreateDatabase("neo4j", {seedingServers: [], seedURI: "myBackup"});
----

[[alter-topology-recreate]]
=== Change the topology

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.

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

[[cluster-seed]]
== Seed a cluster

Expand Down
2 changes: 1 addition & 1 deletion modules/ROOT/pages/clustering/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ This chapter describes the following:
* Setting up a cluster -- The basics of configuring and deploying a new cluster.
** xref:clustering/setup/deploy.adoc[Deploy a basic cluster] -- How to set up a basic cluster.
** xref:clustering/setup/analytics-cluster.adoc[Deploy an analytics cluster] -- How to deploy a special case Neo4j cluster for analytic queries.
** xref:clustering/setup/single-to-cluster.adoc[Move from single server to cluster] -- This section describes how to move from a single Neo4j server to Neo4j cluster.
** xref:clustering/setup/single-to-cluster.adoc[Move from a standalone deployment to a cluster] -- This section describes how to move from a single Neo4j server to Neo4j cluster.
** xref:clustering/setup/discovery.adoc[Cluster server discovery] -- How servers in a cluster discover each other and form a cluster.
** xref:clustering/setup/routing.adoc[Leadership, routing and load balancing] -- Election of leaders, routing and load balancing.
** xref:clustering/setup/encryption.adoc[Intra-cluster encryption] -- How to secure the cluster communication.
Expand Down