diff --git a/modules/ROOT/pages/clustering/databases.adoc b/modules/ROOT/pages/clustering/databases.adoc index 87ed8f282..fb0ddc566 100644 --- a/modules/ROOT/pages/clustering/databases.adoc +++ b/modules/ROOT/pages/clustering/databases.adoc @@ -225,6 +225,129 @@ neo4j@neo4j> DRYRUN REALLOCATE DATABASES; +----------------------------------------------------------------------------------------------------------------------------------------+ ---- +[role=label--new-5.24] +[[recreate-databases]] +== Recreate a database + +Neo4j 5.24 introduces the xref:reference/procedures.adoc#procedure_dbms_cluster_recreateDatabase[`dbms.cluster.recreateDatabase()`] procedure, which allows you: + +* To change the database store to a specified backup, while keeping all the associated privileges for the database. + +* To make your database write-available 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. + +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. +==== + +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 link:https://neo4j.com/docs/cdc/current/existing-databases/[to initialize CDC applications from an existing database]. + +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. + +To check if the recreation is successful, use the `SHOW DATABASES` command and verify that all allocations have been started. + +Additionally, you have the option to modify <> during the recreation process. +However, note that the store format, access, and enrichment cannot be altered during recreation. + +[[recreate-seeding-options]] +=== 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 <> or <> 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 <> for more details. + +* If `seedingServers` is not empty and `seedURI` is also defined, an error will occur. + +[[uri-seed]] +==== Use 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 <> for more details. + + +[source, shell] +---- +CALL dbms.cluster.recreateDatabase("neo4j", {seedURI: "s3:/myBucket/myBackup.backup"}); +---- + +[[seed-servers]] +==== Use available servers as a seed + +After the recreation is complete, the database will have the latest data store from the seeding servers. + +[CAUTION] +==== +Recreation is based on remaining stores or a store defined by the user. +This means that stores which were lost or not defined are not used for the recreation. +If not used stores were more up to date than the used ones, this results in data loss. +==== + +[[specified-servers]] +===== 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. + +[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, Neo4j 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: "s3:/myBucket/myBackup.backup"}); +---- + +[[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 diff --git a/modules/ROOT/pages/clustering/index.adoc b/modules/ROOT/pages/clustering/index.adoc index 5e181cdf4..2d56ef214 100644 --- a/modules/ROOT/pages/clustering/index.adoc +++ b/modules/ROOT/pages/clustering/index.adoc @@ -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.