From ab5ede7036cb97127105bdfec0f26950ce4f1e8b Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Mon, 17 Nov 2025 08:59:44 +0100 Subject: [PATCH] =?UTF-8?q?Label=20the=20Error=20handling=20page,=20remove?= =?UTF-8?q?=20inconsistencies=20around=20quaranti=E2=80=A6=20(#2691)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit …ned state --- .../standard-databases/errors.adoc | 37 ++++++++++--------- modules/ROOT/pages/procedures.adoc | 10 ++--- 2 files changed, 24 insertions(+), 23 deletions(-) diff --git a/modules/ROOT/pages/database-administration/standard-databases/errors.adoc b/modules/ROOT/pages/database-administration/standard-databases/errors.adoc index d1a1c8bb3..2ccffee41 100644 --- a/modules/ROOT/pages/database-administration/standard-databases/errors.adoc +++ b/modules/ROOT/pages/database-administration/standard-databases/errors.adoc @@ -1,5 +1,6 @@ :description: This section describes how to manage errors that you may encounter while managing databases. :page-aliases: manage-databases/errors.adoc +:page-role: enterprise-edition [[manage-database-errors]] = Error handling @@ -11,8 +12,9 @@ When running the database management queries, such as `CREATE DATABASE`, it is p Because database management operations are performed asynchronously, these errors may not be returned immediately upon query execution. Instead, you must monitor the output from the `SHOW DATABASE` command; particularly the `statusMessage` and `currentStatus` columns. -.Fail to create a database -==== +=== Fail to create a database + + [source, cypher] ---- neo4j@system> CREATE DATABASE foo; @@ -51,7 +53,6 @@ In a cluster: 3 row available after 100 ms, consumed after another 6 ms ---- -==== [[database-management-states]] @@ -91,8 +92,8 @@ However, these retries are not guaranteed to succeed, and errors may persist thr If a database is in the `quarantined` state, retrying the last operation will not work. ==== -.Retry to start a database -==== +=== Retry to start a database + [source, cypher] ---- neo4j@system> START DATABASE foo; @@ -146,7 +147,7 @@ neo4j@system> SHOW DATABASE foo; 1 rows available after 4 ms, consumed after another 1 ms ---- -==== + If repeated retries of a command have no effect, or if a database is in a `dirty` state, you may drop and recreate the database, as detailed in xref:database-administration/standard-databases/create-databases.adoc[Create database]. @@ -162,11 +163,11 @@ It produces a database dump that can be further examined and potentially repaire When a database encounters a severe error during its normal run, which prevents it from a further operation, Neo4j stops that database and brings it into a `quarantined` state. Meaning, it is not possible to restart it with a simple `START DATABASE` command. -You have to run `CALL dbms.unquarantineDatabase(server, database, operation)` to lift the quarantine, specifying as `server` the instance with the failing database. +You have to run `CALL dbms.unquarantineDatabase(server, database, operation)` to lift the quarantine, specifying the `server` with the failing database. The `dbms.unquarantineDatabase()` procedure is introduced in Neo4j 2025.01 to replace the now-deprecated xref:procedures.adoc#procedure_dbms_quarantineDatabase[`dbms.quarantineDatabase`()]. -After lifting the quarantine, the instance will automatically try to bring the database to the desired state. +After lifting the quarantine, Neo4j automatically tries to bring the database to the desired state. *Syntax:* @@ -188,15 +189,15 @@ The possible values for the optional operation are: * `replaceStateKeepStore` -- join as a new member, clearing the current cluster state but keeping the store. * `replaceStateReplaceStore` -- join as a new member, clearing both the current cluster state and the store. -If you choose to clear the current cluster state, the server will try to join as a new member, -but this joining can succeed if and only if there is a majority of old members "letting" the new members in. -Let's assume your cluster has a topology with three primaries. -If there is only one server in `QUARANTINED` mode, then it is safe to choose `replaceStateKeepStore` or `replaceStateReplaceStore`. -If there are two servers in `QUARANTINED` mode, then you should not use concurrently `replaceStateKeepStore` or `replaceStateReplaceStore` for both servers because there would be no majority to let them in. +If you choose to clear the current cluster state, the defined database allocation will try to join as a new member. +This joining process can succeed if and only if a majority of the existing members allow the new member to join. +Assume your database has a topology with three primary allocations. +If there is only one allocation in `quarantined` mode, then it is safe to choose `replaceStateKeepStore` or `replaceStateReplaceStore`. +If there are two allocations in `quarantined` mode (meaning that the database is `quarantined` on two servers), then you should not use concurrently `replaceStateKeepStore` or `replaceStateReplaceStore` for both of them because there would be no majority to let them in. *Return arguments:* -The procedure doesn't return any value. +The procedure does not return any value. .Check if a database is quarantined @@ -220,9 +221,9 @@ neo4j@system> SHOW DATABASE foo; [NOTE] ==== A `quarantined` state is persisted for user databases. -This means that if a database is quarantined, it will remain so even if that Neo4j instance is restarted. -You can remove it only by running the xref:procedures.adoc#procedure_dbms_unquarantineDatabase[`dbms.unquarantineDatabase()`] procedure. +This means that if a database is quarantined, it will remain so even if the Neo4j process is restarted. +You can remove the `quarantined` state only by running the xref:procedures.adoc#procedure_dbms_unquarantineDatabase[`dbms.unquarantineDatabase()`] procedure. -The one exception to this rule is for the built-in `system` database. -Any quarantine for that database is removed automatically after instance restart. +The one exception to this rule is for the `system` database. +Any quarantine for that database is removed automatically after the Neo4j process restart. ==== diff --git a/modules/ROOT/pages/procedures.adoc b/modules/ROOT/pages/procedures.adoc index 8e5ac9cb8..1ac181643 100644 --- a/modules/ROOT/pages/procedures.adoc +++ b/modules/ROOT/pages/procedures.adoc @@ -1173,11 +1173,11 @@ The possible values for the optional operation are: * `replaceStateKeepStore` -- join as a new member, clearing the current cluster state but keeping the store. * `replaceStateReplaceStore` -- join as a new member, clearing both the current cluster state and the store. -If you choose to clear the current cluster state, the server will try to join as a new member, -but this joining can succeed if and only if there is a majority of old members "letting" the new members in. -Let's assume your cluster has a topology with three primaries. -If there is only one server in `QUARANTINED` mode, then it is safe to choose `replaceStateKeepStore` or `replaceStateReplaceStore`. -If there are two servers in `QUARANTINED` mode, then you should not use concurrently `replaceStateKeepStore` or `replaceStateReplaceStore` for both servers because there would be no majority to let them in. +If you choose to clear the current cluster state, the defined database allocation will try to join as a new member. +This joining process can succeed if and only if a majority of the existing members allow the new member to join. +Assume your database has a topology with three primary allocations. +If there is only one allocation in `quarantined` mode, then it is safe to choose `replaceStateKeepStore` or `replaceStateReplaceStore`. +If there are two allocations in `quarantined` mode (meaning that the database is `quarantined` on two servers), then you should not use concurrently `replaceStateKeepStore` or `replaceStateReplaceStore` for both of them because there would be no majority to let them in. ==== [role=label--admin-only label--deprecated-5.9 label--removed-cypher-25]