From 45129059011cb6e92efa6f6e8d14fcfbdc54ddb4 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina Date: Thu, 30 Oct 2025 15:06:04 +0100 Subject: [PATCH 1/4] Label the Error handling page, remove inconsistencies around quarantined state --- .../standard-databases/errors.adoc | 33 ++++++++++--------- modules/ROOT/pages/procedures.adoc | 9 +++-- 2 files changed, 21 insertions(+), 21 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..dc458c814 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 +[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:* @@ -190,13 +191,13 @@ The possible values for the optional operation are: 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. +Let's 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 in the `quarantined` state 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..470e301a8 100644 --- a/modules/ROOT/pages/procedures.adoc +++ b/modules/ROOT/pages/procedures.adoc @@ -1173,11 +1173,10 @@ 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 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 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 in the `quarantined` state 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] From 0910a925af2872b794842e82620486302d37fa0a Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Thu, 6 Nov 2025 12:48:37 +0100 Subject: [PATCH 2/4] Update errors.adoc --- .../standard-databases/errors.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/database-administration/standard-databases/errors.adoc b/modules/ROOT/pages/database-administration/standard-databases/errors.adoc index dc458c814..b7ca95f9a 100644 --- a/modules/ROOT/pages/database-administration/standard-databases/errors.adoc +++ b/modules/ROOT/pages/database-administration/standard-databases/errors.adoc @@ -189,11 +189,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 database has a topology with three primary allocations. +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 in the `quarantined` state 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. +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:* From f666aedf36bb8865ab481094f14bb0d9f82b7c0d Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Thu, 6 Nov 2025 12:48:46 +0100 Subject: [PATCH 3/4] Update modules/ROOT/pages/database-administration/standard-databases/errors.adoc --- .../database-administration/standard-databases/errors.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/database-administration/standard-databases/errors.adoc b/modules/ROOT/pages/database-administration/standard-databases/errors.adoc index b7ca95f9a..2ccffee41 100644 --- a/modules/ROOT/pages/database-administration/standard-databases/errors.adoc +++ b/modules/ROOT/pages/database-administration/standard-databases/errors.adoc @@ -1,6 +1,6 @@ :description: This section describes how to manage errors that you may encounter while managing databases. :page-aliases: manage-databases/errors.adoc -[role=enterprise-edition] +:page-role: enterprise-edition [[manage-database-errors]] = Error handling From 427c982cf8ad9a3f556f0fc2c961973fd5c9c045 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Thu, 6 Nov 2025 13:05:13 +0100 Subject: [PATCH 4/4] Update procedures.adoc --- modules/ROOT/pages/procedures.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/procedures.adoc b/modules/ROOT/pages/procedures.adoc index 470e301a8..1ac181643 100644 --- a/modules/ROOT/pages/procedures.adoc +++ b/modules/ROOT/pages/procedures.adoc @@ -1173,10 +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 database has a topology with three primary allocations. +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 in the `quarantined` state 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. +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]