rearranged to accommodate all possible database states (#1045) (#1143)

Cherry-picks #1045

Co-authored-by: Jessica Wright <[email protected]>
Co-authored-by: Jens Pryce-Åklundh <[email protected]>

Author: 3 people

modules/ROOT/pages/clustering/databases.adoc

@@ -52,8 +52,8 @@ ALTER DATABASE foo SET TOPOLOGY 2 PRIMARIES 1 SECONDARY
 
 Like the `CREATE DATABASE` command, this command results in an error if the cluster does not contain sufficient servers to satisfy the requested topology.
 
-Additionally, `ALTER DATABASE` is optionally idempotent and also results in an error if the database does not exist.
-It is possible to append the command with `IF EXISTS` to make sure that no error is returned if the database does not exist.
+When there is more than one possible permutation of the specified topology, Neo4j uses an allocator to decide how to spread the database across the cluster.
+Note, like `CREATE DATABASE`, the `ALTER DATABASE` command allocates the database and there is no requirement to execute `REALLOCATE DATABASES` unless there is a desire to re-balance databases across all servers that are part of the cluster.
 
 When there is more than one possible permutation of the specified topology, Neo4j uses an allocator to decide how to spread the database across the cluster.
 Note, like `CREATE DATABASE`, the `ALTER DATABASE` command allocates the database and there is no requirement to execute `REALLOCATE DATABASES` unless there is a desire to re-balance databases across all servers that are part of the cluster.
@@ -73,8 +73,6 @@ Keep in mind that during such a transition, the database will be unavailable for
 `ALTER DATABASE` commands are optionally idempotent, with the default behavior to fail with an error if the database does not exist.
 Appending `IF EXISTS` to the command ensures that no error is returned and nothing happens should the database not exist.
 
-If the `ALTER DATABASE` command decreases the number of allocations of a database, allocations on xref:clustering/servers.adoc#_cordoned_servers[cordoned servers] are removed first.
-
 .Query
 [source, cypher]
 ----

modules/ROOT/pages/clustering/monitoring/show-databases-monitoring.adoc

@@ -41,10 +41,12 @@ Note that for failed databases, `currentStatus` and `requestedStatus` are differ
 This can imply an error.
 For example:
 
-* A database may take a while to transition from "offline" to "online", due to performing recovery.
+* A database may take a while to transition from `offline` to `online`, due to performing recovery.
 * During normal operation, the `currentStatus` of a database may be transiently different from its `requestedStatus`, due to a necessary automatic process, such as one server copying store files from another.
 
-The possible statuses are `initial`, `offline`, `store copying`, `deallocating`, `unknown`, `dirty`, and `quarantined`.
+The possible values for `currentStatus` are `online`, `offline`, `starting`, `stopping`, `store copying`, `initial`, `deallocating`, `dirty`, `quarantined`, and  `unknown`.
+The `requestedStatus` can only be `online` or `offline`.
+See xref::database-administration/standard-databases/manage-databases.adoc#database-states[Database states] for more information.
 
 Additionally, note that databases hosted on servers that are offline are also returned by the `SHOW DATABASES` command.
 For such databases the `address` column displays `NULL`, the `currentStatus` column displays `unknown`, and the `statusMessage` displays `Server is unavailable`.

modules/ROOT/pages/database-administration/standard-databases/errors.adoc

@@ -62,55 +62,22 @@ As a result, the contents of the `statusMessage` column in the `SHOW DATABASE` q
 
 However, databases may only be in one of a select number of states:
 
-[options="header" cols="m,a"]
-|===
-| State
-| Description
-
-| online
-| The database is running.
-
-| offline
-| The database is not running.
-If the `statusMessage` column is filled, the database is not running because of a problem.
-
-| starting
-| The database is not running, but is about to.
-
-| stopping
-| The database is not running anymore, but still has not stopped completely.
-No offline operations (e.g. `load`/`dump`) can be performed yet.
-
-| store copying
-| The database is currently being updated from another instance of Neo4j.
-
-| initial
-| The database has not yet been created.
-
-| dirty
-| This state implies an error has occurred.
-The database's underlying store files may be invalid.
-For more information, consult the `statusMessage` column or the server's logs.
-
-| quarantined
-| The database is effectively stopped and its state may not be changed until no longer quarantined.
-For more information, consult the `statusMessage` column or the server's logs.
-
-| unknown
-| This instance of Neo4j doesn’t know the state of this database.
-
-| dropped
-| The database has been deleted.
-|===
-
+* `online`
+* `offline`
+* `starting`
+* `stopping`
+* `store copying`
+* `initial`
+* `deallocating`
+* `dirty`
+* `quarantined`
+* `unknown`
+
+For more details about the various states, see xref::database-administration/standard-databases/manage-databases.adoc#database-states[Database states].
 Most often, when a database management operation fails, Neo4j attempts to transition the database in question to the `offline` state.
 If the system is certain that no store files have yet been created, it transitions the database to `initial` instead.
 Similarly, if the system suspects that the store files underlying the database are invalid (incomplete, partially deleted, or corrupt), then it transitions the database to `dirty`.
 
-[NOTE]
-====
-While `dropped` is a valid database state, it is only transiently observable, as database records are removed from `SHOW DATABASE` results once the `DROP` operation is complete.
-====
 
 [[database-errors-retry]]
 == Retrying failed operations

modules/ROOT/pages/database-administration/standard-databases/manage-databases.adoc

@@ -86,15 +86,20 @@ The value can be either `online` or `offline`. label:default-output[]
 | currentStatus
 | The actual status of the database. label:default-output[]
 
-The value can be one of the following:
-
-* `online` - the database is running.
-* `offline` - the database is not running.
-* `starting` - the database is not running, but is about to.
-* `stopping` - the database is not running anymore but still has not stopped completely.
-Offline operations (e.g. `load`/`dump`) cannot be performed yet.
-* `store copying` - the database is currently being updated from another instance of Neo4j.
-* For other states, refer to the xref::database-administration/standard-databases/errors.adoc[Errors page].
+The possible statuses are:
+
+* `online`
+* `offline`
+* `starting`
+* `stopping`
+* `store copying`
+* `initial`
+* `deallocating`
+* `dirty`
+* `quarantined`
+* `unknown`
+
+See <<database-states>> for more information.
 | STRING
 
 | statusMessage
@@ -186,13 +191,61 @@ However, some privileges enable users to see additional databases regardless of
 
 If a user has not been granted `ACCESS` privilege to any databases nor any of the above special cases, the command can still be executed but it will only return the `system` database, which is always visible.
 
+[[database-states]]
+=== Database states
+
+A database's `currentStatus` can be one of the following:
+
+[options="header" cols="m,a"]
+|===
+| State
+| Description
+
+| online
+| The database is running.
+
+| offline
+| The database is not running.
+If the `statusMessage` column is filled, the database is not running because of a problem.
+
+| starting
+| The database is not running, but is about to.
+
+| stopping
+| The database is not running anymore, but still has not stopped completely.
+No offline operations (e.g. `load`/`dump`) can be performed yet.
+
+| store copying
+| The database is currently being updated from another instance of Neo4j.
+
+| initial
+| The database has not yet been created.
+
+| deallocating
+| Only applies to databases in a cluster.
+The database is still online but will eventually be offline due to a transfer of its role in the cluster to a different member.
+The status is `deallocting` until the transfer is complete, which can take anything from a second to a day or more.
+
+| dirty
+| This state implies an error has occurred.
+The database's underlying store files may be invalid.
+For more information, consult the `statusMessage` column or the server's logs.
+
+| quarantined
+| The database is effectively stopped and its state may not be changed until no longer quarantined.
+For more information, consult the `statusMessage` column or the server's logs.
+
+| unknown
+| This instance of Neo4j does not know the state of this database.
+
+|===
+
 [NOTE]
 ====
 Note that for failed databases, the `currentStatus` and `requestedStatus` are different.
 This often implies an error, but **that is not always the case**.
 For example, a database may take a while to transition from `offline` to `online` due to a performing recovery.
 Or, during normal operation, a database's `currentStatus` may be transiently different from its `requestedStatus` due to a necessary automatic process, such as one Neo4j instance copying store files from another.
-The possible statuses are `initial`, `online`, `offline`, `store copying` and `unknown`.
 ====