From b207b1e50f2b717f0de4f0c623f5b3a2c80b5c9c Mon Sep 17 00:00:00 2001 From: Lasse Heemann <7661319+l-heemann@users.noreply.github.com> Date: Wed, 11 Dec 2024 17:36:11 +0100 Subject: [PATCH] Add notifications for WAIT commands (#231) Depends on https://github.com/neo-technology/neo4j/pull/28163 --------- Co-authored-by: Reneta Popova --- modules/ROOT/pages/changelogs.adoc | 12 + .../notifications/all-notifications.adoc | 304 ++++++++++++++++++ modules/ROOT/pages/notifications/index.adoc | 10 +- 3 files changed, 324 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/changelogs.adoc b/modules/ROOT/pages/changelogs.adoc index 5a83b6d..548293f 100644 --- a/modules/ROOT/pages/changelogs.adoc +++ b/modules/ROOT/pages/changelogs.adoc @@ -1,6 +1,18 @@ :description: This page lists all changes to status codes per Neo4j version. = Changes to status codes per Neo4j version +== Neo4j 2025.01 +**New:** +[source, status codes, role="noheader"] +----- +Neo.ClientNotification.Cluster.ServerNotAvailable +Neo.ClientNotification.Cluster.ServerCatchingUp +Neo.ClientNotification.Cluster.ServerFailed +Neo.ClientNotification.Cluster.ServerCaughtUp +----- +Starting from 2025.01, when using Cypher25, queries using `WAIT` return the notifications listed above instead of result rows. +The behaviour for Cypher5 remains unchanged. + == Neo4j 5.25 Starting from 5.25, the query log includes the GQL error information under the JSON object `errorInfo`. diff --git a/modules/ROOT/pages/notifications/all-notifications.adoc b/modules/ROOT/pages/notifications/all-notifications.adoc index 8d3d418..1d07adf 100644 --- a/modules/ROOT/pages/notifications/all-notifications.adoc +++ b/modules/ROOT/pages/notifications/all-notifications.adoc @@ -3939,6 +3939,310 @@ The requested topology matched the current topology. No allocations were changed ====== ===== +[role=label--new-2025.01 label--Cypher25] +[#_neo_clientnotification_cluster_servercaughtup] +=== Server has caught up during `WAIT` command + +.Notification category details +[cols="<1s,<4"] +|=== +|Neo4j code +m|Neo.ClientNotification.Cluster.ServerCaughtUp +|Title +a|Server has caught up. +|Description +a|Server `(%s)` at address `(%s)` has caught up. +|Category +m|TOPOLOGY +|GQLSTATUS code +m|03N85 +|Status description +a| +info: server has caught up. Server `${ name }` at address `${ address }` has caught up. +|Classification +m|TOPOLOGY +|SeverityLevel +m|INFORMATION +|=== + +.Successful completion of a `WAIT` command with two servers +[.tabbed-example] +===== +[.include-with-GQLSTATUS-code] +====== +Query:: ++ +[source,cypher] +---- +CREATE DATABASE foo TOPOLOGY 2 PRIMARIES WAIT +---- + +One notification is returned for each server in the cluster: + +Returned GQLSTATUS code:: +03N85 + +Returned status description:: +info: server has caught up. Server `ServerId\{0e010000}` at address `localhost:20025` has caught up. + +Returned GQLSTATUS code:: +03N85 + +Returned status description:: +info: server has caught up. Server `ServerId\{0e020000}` at address `localhost:20026` has caught up. +====== +[.include-with-neo4j--code] +====== +Query:: ++ +[source,cypher] +---- +CREATE DATABASE foo TOPOLOGY 2 PRIMARIES WAIT +---- +One notification is returned for each server in the cluster: + +Description of the returned code:: +Server `ServerId\{0e010000}` at address `localhost:20025` has caught up. + +Description of the returned code:: +Server `ServerId\{0e020000}` at address `localhost:20026` has caught up. +====== +===== + +[role=label--new-2025.01 label--Cypher25] +[#_neo_clientnotification_cluster_serverfailed] +=== Server failed during `WAIT` command + +.Notification category details +[cols="<1s,<4"] +|=== +|Neo4j code +m|Neo.ClientNotification.Cluster.ServerFailed +|Title +a|Server failed. +|Description +a|Server `(%s)` at address `(%s)` failed: (%s) +|Category +m|TOPOLOGY +|GQLSTATUS code +m|01N80 +|Status description +a| +warn: server failed. Server `${ name }` at address `${ address }` failed: `${ message }` +|Classification +m|TOPOLOGY +|SeverityLevel +m|WARNING +|=== + + +.One out of two servers failed during `WAIT` command +[.tabbed-example] +===== +[.include-with-GQLSTATUS-code] +====== +Query:: ++ +[source,cypher] +---- +CREATE DATABASE foo TOPOLOGY 2 PRIMARIES WAIT +---- + +One notification is returned for each server in the cluster: + +Returned GQLSTATUS code:: +03N85 + +Returned status description:: +info: server has caught up. Server `ServerId\{0e010000}` at address `localhost:20025` has caught up. + +Returned GQLSTATUS code:: +01N80 + +Returned status description:: +warn: server failed. Server `ServerId\{0e020000}` at address `localhost:20026` failed: Caught up but has failure for DatabaseId{0db00002[foo]} Failure: java.nio.file.FileAlreadyExistsException: <...> + +Suggestions for improvement:: +Investigate the failing server using the provided message. +====== +[.include-with-neo4j--code] +====== +Query:: ++ +[source,cypher] +---- +CREATE DATABASE foo TOPOLOGY 2 PRIMARIES WAIT +---- +One notification is returned for each server in the cluster: + +Description of the returned code:: +Server `ServerId\{0e010000}` at address `localhost:20025` has caught up. + +Description of the returned code:: +Server `ServerId\{0e020000}` at address `localhost:20026` failed: Caught up but has failure for DatabaseId{0db00002[foo]} Failure: java.nio.file.FileAlreadyExistsException: <...> + +Suggestions for improvement:: +Investigate the failing server using the provided message. +====== +===== + +[role=label--new-2025.01 label--Cypher25] +[#_neo_clientnotification_cluster_servercatchingup] +=== Server is still catching up during `WAIT` command + +.Notification category details +[cols="<1s,<4"] +|=== +|Neo4j code +m|Neo.ClientNotification.Cluster.ServerCachingUp +|Title +a|Server is still catching up. +|Description +a|Server `(%s)` at address `(%s)` is still catching up. +|Category +m|TOPOLOGY +|GQLSTATUS code +m|01N81 +|Status description +a| +warn: server is catching up. Server `${ name }` at address `${ address }` is still catching up. +|Classification +m|TOPOLOGY +|SeverityLevel +m|WARNING +|=== + + +.One out of two servers is still catching up during `WAIT` command +[.tabbed-example] +===== +[.include-with-GQLSTATUS-code] +====== +Query:: ++ +[source,cypher] +---- +CREATE DATABASE foo TOPOLOGY 2 PRIMARIES WAIT +---- + +One notification is returned for each server in the cluster: + +Returned GQLSTATUS code:: +03N85 + +Returned status description:: +info: server has caught up. Server `ServerId\{0e010000}` at address `localhost:20025` has caught up. + +Returned GQLSTATUS code:: +01N81 + +Returned status description:: +warn: server is catching up. Server `ServerId\{0e020000}` at address `localhost:20026` is still catching up. + +Suggestions for improvement:: +This behaviour indicates that one of the servers is lagging behind. +Investigate the server and network for performance issues or increase the wait timeout. +====== +[.include-with-neo4j--code] +====== +Query:: ++ +[source,cypher] +---- +CREATE DATABASE foo TOPOLOGY 2 PRIMARIES WAIT +---- +One notification is returned for each server in the cluster: + +Description of the returned code:: +Server `ServerId\{0e010000}` at address `localhost:20025` has caught up. + +Description of the returned code:: +Server `ServerId\{0e020000}` at address `localhost:20026` is still catching up. + +Suggestions for improvement:: +This behaviour indicates that one of the servers is lagging behind. +Investigate the server and network for performance issues or increase the wait timeout. +====== +===== + +[role=label--new-2025.01 label--Cypher25] +[#_neo_clientnotification_cluster_serverunavailable] +=== Server is not available during `WAIT` command + +.Notification category details +[cols="<1s,<4"] +|=== +|Neo4j code +m|Neo.ClientNotification.Cluster.ServerNotAvailable +|Title +a|Server is not available. +|Description +a|Server `(%s)` at address `(%s)` is not available. +|Category +m|TOPOLOGY +|GQLSTATUS code +m|01N82 +|Status description +a| +warn: server is not available. Server `${ name }` at address `${ address }` is not available. +|Classification +m|TOPOLOGY +|SeverityLevel +m|WARNING +|=== + + +.One out of two servers is not available during `WAIT` command +[.tabbed-example] +===== +[.include-with-GQLSTATUS-code] +====== +Query:: ++ +[source,cypher] +---- +CREATE DATABASE foo TOPOLOGY 2 PRIMARIES WAIT +---- + +One notification is returned for each server in the cluster: + +Returned GQLSTATUS code:: +03N85 + +Returned status description:: +info: server has caught up. Server `ServerId\{0e010000}` at address `localhost:20025` has caught up. + +Returned GQLSTATUS code:: +01N82 + +Returned status description:: +warn: server is not available. Server `ServerId\{0e020000}` at address `localhost:20026` is not available. + +Suggestions for improvement:: +Investigate the server to determine why it is not available. +====== +[.include-with-neo4j--code] +====== +Query:: ++ +[source,cypher] +---- +CREATE DATABASE foo TOPOLOGY 2 PRIMARIES WAIT +---- +One notification is returned for each server in the cluster: + +Description of the returned code:: +Server `ServerId\{0e010000}` at address `localhost:20025` has caught up. + +Description of the returned code:: +Server `ServerId\{0e020000}` at address `localhost:20026` is not available. + +Suggestions for improvement:: +Investigate the server to determine why it is not available. +====== +===== + + [#_schema_notifications] == `SCHEMA` category diff --git a/modules/ROOT/pages/notifications/index.adoc b/modules/ROOT/pages/notifications/index.adoc index e78ff17..d096be5 100644 --- a/modules/ROOT/pages/notifications/index.adoc +++ b/modules/ROOT/pages/notifications/index.adoc @@ -128,12 +128,18 @@ The following table lists the Neo4j-defined groups of GQLSTATUS codes and their | 01N7[y] | Security warnings -| 03N9[y] -| Performance information +| 01N8[y] +| Topology warnings | 03N6[y] | Generic information +| 03N8[y] +| Topology information + +| 03N9[y] +| Performance information + | 00N5[y] | Unrecognized information under successful completion