Skip to content

Remove useExisting option; polish examples & page #2287

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: dev
Choose a base branch
from
Open

Remove useExisting option; polish examples & page #2287

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
86c9b3d
Remove `useExisting` option; polish examples & page
stefano-ottolenghi Apr 19, 2025
0ed1c5c
word
stefano-ottolenghi Apr 19, 2025
bdda625
Update seed-from-uri.adoc
stefano-ottolenghi Apr 19, 2025
bb0baca
Bug in path
stefano-ottolenghi Apr 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 45 additions & 30 deletions modules/ROOT/pages/database-administration/standard-databases/seed-from-uri.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
:page-role: enterprise-edition
:description: How to create a database using a seed from URI.
:description: How to create a database using a seed from URI.

[[database-seed-uri]]
= Create a database from a URI
Expand All @@ -8,15 +8,15 @@ This method seeds all databases with an identical seed from an external source,

You specify the seed URI as an argument of the `CREATE DATABASE` command:

[source, cypher, role="noplay"]
[source, cypher]
----
CREATE DATABASE foo OPTIONS {existingData: 'use', seedURI:'s3://myBucket/myBackup.backup'}
CREATE DATABASE foo OPTIONS { seedURI:'s3://myBucket/myBackup.backup' }
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not aware of existingData: 'use' being deprecated and it's not documented. I would suggest that the Clustering team review this PR.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For Cypher 5, this option is still required. But for 25 it's not required, but it'll accept it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which cypher version are these docs for?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They are for Cypher version 5.

----

Download and validation of the seed is only performed as the new database is started.
If it fails, the database is not available and it has the `statusMessage`: `Unable to start database` of the `SHOW DATABASES` command.

[source, cypher, role="noplay"]
[source, cypher]
----
neo4j@neo4j> SHOW DATABASES;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
neo4j@neo4j> SHOW DATABASES;
SHOW DATABASES;
----

+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.Example output
[result]
----
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Expand All @@ -26,7 +26,7 @@ neo4j@neo4j> SHOW DATABASES;
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
----

To determine the cause of the problem, it is recommended to look at the `debug.log`.
To determine the cause of the problem, check the `debug.log` file.

[NOTE]
====
Expand Down Expand Up @@ -55,6 +55,9 @@ The `FileSeedProvider` supports:

** `file:`

[NOTE]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[NOTE]
[NOTE]
====

Local file paths must be absolute paths.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Local file paths must be absolute paths.
Local file paths must be absolute paths.
====


[[url-connection-seed-provider]]
=== URLConnectionSeedProvider

Expand Down Expand Up @@ -90,9 +93,9 @@ include::partial$/aws-s3-credentials.adoc[]

. Create database from `myBackup.backup`.
+
[source,shell, role="nocopy"]
[source,cypher]
----
CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup' }
CREATE DATABASE foo OPTIONS { seedURI: 's3://myBucket/myBackup.backup' }
----

======
Expand All @@ -103,9 +106,9 @@ include::partial$/gcs-credentials.adoc[]

. Create database from `myBackup.backup`.
+
[source,shell]
[source,cypher]
----
CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 'gs://myBucket/myBackup.backup' }
CREATE DATABASE foo OPTIONS { seedURI: 'gs://myBucket/myBackup.backup' }
----
======
[role=include-with-Azure-cloud-storage]
Expand All @@ -115,9 +118,9 @@ include::partial$/azb-credentials.adoc[]

. Create database from `myBackup.backup`.
+
[source,shell]
[source,cypher]
----
CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 'azb://myStorageAccount/myContainer/myBackup.backup' }
CREATE DATABASE foo OPTIONS { seedURI: 'azb://myStorageAccount/myContainer/myBackup.backup' }
----
======
=====
Expand All @@ -129,26 +132,32 @@ Starting from Neo4j 2025.01, the `CloudSeedProvider` supports seeding up to a sp
[role=label--new-2025.01]
Seed up to a specific date::

To seed up to a specific date, you need to pass the differential backup, which contains the data up to that date.
To seed up to a specific date, provide the differential backup containing the data up to that date.
+
[source,shell]
[source,cypher]
----
CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedRestoreUntil: datetime("2019-06-01T18:40:32.142+0100") }
CREATE DATABASE foo OPTIONS {
seedURI: 's3://myBucket/myBackup.backup',
seedRestoreUntil: datetime('2019-06-01T18:40:32.142+0100')
}
----
+
This will seed the database with transactions committed before the provided timestamp.

[role=label--new-2025.01]
Seed up to a specific transaction ID::

To seed up to a specific transaction ID, you need to pass the differential backup that contains the data up to that transaction ID.
To seed up to a specific transaction ID, provide the differential backup containing the data up to that transaction ID.
+
[source,shell]
[source,cypher]
----
CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedRestoreUntil: 123 }
CREATE DATABASE foo OPTIONS {
seedURI: 's3://myBucket/myBackup.backup',
seedRestoreUntil: 123
}
----
+
This will seed the database with transactions up to, but not including transaction 123.
This will seed the database with transactions up to (but not including) transaction 123.

[role=label--deprecated]
[[s3-seed-provider]]
Expand All @@ -164,31 +173,37 @@ The `S3SeedProvider` supports:
[NOTE]
====
Neo4j comes bundled with necessary libraries for AWS S3 connectivity.
Therefore, if you use `S3SeedProvider`,`aws cli` is not required but can be used with the `CloudSeedProvider`.
Therefore, if you use `S3SeedProvider`, `aws cli` is not required (as it instead is with `CloudSeedProvider`).
====

The `S3SeedProvider` requires additional configuration.
This is specified with the `seedConfig` option.
This option expects a comma-separated list of configurations.
Each configuration value is specified as a name followed by `=` and the value, as such:
This is specified with the `seedConfig` option, which expects a comma-separated list of configurations.
Each configuration entry is specified in the format `key=value`, as such:

[source, cypher, role="noplay"]
[source, cypher]
----
CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedConfig: 'region=eu-west-1' }
CREATE DATABASE foo OPTIONS {
seedURI: 's3://myBucket/myBackup.backup',
seedConfig: 'region=eu-west-1'
}
----

`S3SeedProvider` also requires passing in credentials.
These are specified with the `seedCredentials` option.
Seed credentials are securely passed from the Cypher command to each server hosting the database.
For this to work, Neo4j on each server in the cluster must be configured with identical keystores.
This is identical to the configuration required by remote aliases, see xref:database-administration/aliases/remote-database-alias-configuration.adoc#remote-alias-config-DBMS_admin-A[Configuration of DBMS with remote database alias].
If this configuration is not performed, the `seedCredentials` option fails.
Without this configuration, the `seedCredentials` option fails.

[source, cypher, role="noplay"]
[source, cypher]
----
CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedConfig: 'region=eu-west-1', seedCredentials: [accessKey];[secretKey] }
CREATE DATABASE foo OPTIONS {
seedURI: 's3://myBucket/myBackup.backup',
seedConfig: 'region=eu-west-1',
seedCredentials: <accessKey>;<secretKey>
}
----
Where `accessKey` and `secretKey` are provided by AWS.
Where `<accessKey>` and `<secretKey>` are provided by AWS.

=== Seed provider reference

Expand All @@ -200,7 +215,7 @@ Where `accessKey` and `secretKey` are provided by AWS.

| `file:`
| `FileSeedProvider`
| `\file://tmp/backup1.backup`
| `\file:/tmp/backup1.backup`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps, you mean:

Suggested change
| `\file:/tmp/backup1.backup`
| `file:///tmp/backup1.backup`

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, what I wrote is correct. What you wrote is also correct. Both work. I wrote that one because triple slashes are more cumbersome that single slashes.
The only thing that doesn't work is the one that's currently documented 😅


| `ftp:`
| `URLConnectionSeedProvider`
Expand All @@ -226,4 +241,4 @@ Where `accessKey` and `secretKey` are provided by AWS.
| `azb:`
| `CloudSeedProvider`
| `azb://mystorageaccount.blob/backupscontainer/backup1.backup`
|===
|===