Updates to CREATE DATABASE for Cypher 25 (#2132)

* Explain how existing store files work, this has never really been well
documented
* Add a different set of options for Cypher 25
* WAIT is different in Cypher 25.


---------

Co-authored-by: Nick Giles <[email protected]>
Co-authored-by: akarasavov <[email protected]>
Co-authored-by: Reneta Popova <[email protected]>
Co-authored-by: Nick Giles <[email protected]>

Author: 4 people

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

@@ -19,6 +19,9 @@ For more information, see link:{neo4j-docs-base-uri}/upgrade-migration-guide/upg
 == Create databases
 
 You can create a database using the Cypher command `CREATE DATABASE`.
+The initial contents of the database depend on the state of the server and the options provided to the command.
+When no additional options are provided, `CREATE DATABASE` will attempt to mount any pre-existing store files in place (e.g., as the result of restoring a backup). 
+If no pre-existing store files are available, it will create an empty database.
 
 [NOTE]
 ====
@@ -64,6 +67,11 @@ CREATE OR REPLACE DATABASE name
 [[manage-databases-create-database-options]]
 === Options
 
+[.tabbed-example]
+=====
+[.include-with-cypher-5]
+======
+
 The `CREATE DATABASE` command can have a map of options, e.g. `OPTIONS {key: 'value'}`.
 
 [options="header"]
@@ -90,7 +98,7 @@ Replaced by `existingDataSeedServer`.
 | `seedURI`
 | URI to a backup or a dump from an existing database.
 |
-Defines an identical seed from an external source which will be used to seed all servers.
+Defines a seed from an external source, which will be used to seed all servers.
 
 | `seedConfig`
 | Comma-separated list of configuration values.
@@ -128,7 +136,70 @@ Starting from Neo4j 2025.01, you can use `existingData`, `seedURI`, `seedConfig`
 The `existingDataSeedInstance` and `existingDataSeedServer` are still not supported with the `CREATE OR REPLACE DATABASE` command.
 More details about seeding options can be found in xref::clustering/databases.adoc#cluster-seed[Seed a cluster].
 ====
+======
+[.include-with-cypher-25]
+======
+The `CREATE DATABASE [OR REPLACE]` command can have a map of options, e.g., `OPTIONS {key: 'value'}`.
+
+[options="header"]
+|===
+
+| Key | Value | Description
+
+|`existingDataSeedServer`
+| ID of the cluster server
+|
+Defines which server is used for seeding the data of the created database.
+The server ID can be found in the `serverId` column after running `SHOW SERVERS`.
+
+| `seedURI`
+| URI to a backup, a folder that contains backup artifacts or a dump from an existing database.
+|
+Defines a seed from an external source, which will be used to seed all servers.
+
+| `seedConfig`
+| Comma-separated list of configuration values.
+|
+For more information see xref::clustering/databases.adoc#cluster-seed-uri[Seed from URI].
+
+| `txLogEnrichment`
+| `FULL` \| `DIFF` \| `OFF`
+|
+Defines the level of enrichment applied to transaction logs for Change Data Capture (CDC) purposes.
+
+For details about enrichment mode, see link:{neo4j-docs-base-uri}/cdc/current/get-started/self-managed/#set-enrichment-mode/[Change Data Capture Manual -> Enable CDC on self-managed instances -> Set the enrichment mode].
 
+| `storeFormat`
+| `aligned` \| `standard` \| `high_limit` \| `block`
+|
+Defines the store format if the database created is new.
+`high_limit` and `standard` formats are deprecated from 5.23.
+For more information on store formats, see xref::database-internals/store-formats.adoc[Store formats].
+
+If the store is seeded with `seedURI` or `existingDataSeedServer`, or if the command is used to mount pre-existing store files already present on the disk, they will retain their current store format without any modifications.
+
+| `seedRestoreUntil`
+| Datetime or transaction id. E.g. `datetime("2025-01-01T12:15:00.000+0100")` or `123456`
+| 
+If you are passing a `seedURI` that leads to a backup chain, including differential backups, you can choose to not apply all the transactions in the differential backups.
+To seed up to a specific date, specify a `datetime`.
+This will seed the database with transactions committed before the provided timestamp.
+To seed up to a specific transaction ID, specify a transaction ID.
+This will seed the database with transactions up to, but not including the specified transaction.
+
+| `seedSourceDatabase`
+| A source database name
+|
+If the `seedURI` points to a folder containing backups for multiple databases, you can specify the database name to filter the artifacts.
+
+| `existingData` label:deprecated[Deprecated]
+| `use`
+|
+Included for backward compatibility only, has no effect and will be removed in a future version.
+
+|===
+======
+=====
 
 === Examples
 
@@ -164,7 +235,11 @@ SHOW DATABASES YIELD name
 
 ==== Create a database with xref:database-administration/standard-databases/wait-options.adoc[`WAIT`]
 
-Sub-clause `WAIT` allows you to specify a time limit in which the command must complete and return.
+[.tabbed-example]
+=====
+[.include-with-cypher-5]
+======
+Sub-clause `WAIT` allows you to specify a time limit for the command to complete and return.
 
 [source, cypher]
 ----
@@ -183,7 +258,33 @@ CREATE DATABASE slow WAIT 5 SECONDS
 
 The `success` column provides an aggregate status of whether or not the command is considered successful.
 Thus, every row has the same value, determined on a successful completion without a timeout.
+======
+[.include-with-cypher-25]
+======
+Sub-clause `WAIT` allows you to specify a time limit for the command to complete and return.
+
+[source, cypher]
+----
+CREATE DATABASE slow WAIT 5 SECONDS
+----
+
+.Result
+[role="queryresult"]
+----
+info: Server `ServerId{b55c6551}` at address `server1:7687` has caught up.
+03N85 (Neo.ClientNotification.Cluster.ServerCaughtUp)
+
+info: Server `ServerId{a9e7e8f1}` at address `server2:7687` has caught up.
+03N85 (Neo.ClientNotification.Cluster.ServerCaughtUp)
+
+info: Server `ServerId{0f7cb48e}` at address `server3:7687` has caught up.
+03N85 (Neo.ClientNotification.Cluster.ServerCaughtUp)
+----
 
+The command returns a notification for each server in the cluster to indicate the status of that command on that server.
+In this example, all three cluster members have returned `Neo.ClientNotification.Cluster.ServerCaughtUp`, which indicates that the server has applied the command successfully and is up to date.
+======
+=====
 
 ==== Create databases with `IF NOT EXISTS` or `OR REPLACE`