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

[role=label--new-5.24]
[[recreate-databases]]
== Recreate databases

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

* to a specified backup, while keeping all the associated privileges for the 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 different factors -- for example, the size of the store, network speed, etc.

The database recreation process is designed to select the latest seed from the defined seeding servers.
Specifying only a subset of the previous cluster servers as seeders carries a risk of data loss.
====

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, see xref:database-administration/standard-databases/errors.adoc#quarantine[Standard databases -> Error handling].

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

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

The store to be used during the recreation of a database 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.

To avoid possible data loss, 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.

[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 and 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