Add notifications for WAIT commands

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`.

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
 

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