Create a database from a URI

This method seeds all databases with an identical seed from an external source, specified by a URI.

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

CREATE DATABASE foo OPTIONS {existingData: 'use', seedURI:'s3://myBucket/myBackup.backup'}

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.

neo4j@neo4j> SHOW DATABASES;
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name    | type       | aliases | access       | address          | role      | writer | requestedStatus | currentStatus | statusMessage                                            | default | home  | constituents |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "seed3" | "standard" | []      | "read-write" | "localhost:7682" | "unknown" | FALSE  | "online"        | "offline"     | "Unable to start database `DatabaseId{3fe1a59b[seed3]}`" | FALSE   | FALSE | []           |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

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

Starting from Neo4j 2025.01, seed from URI can also be used in combination with CREATE OR REPLACE DATABASE.

Seed providers in Neo4j

The seed can either be a full backup, a differential backup (see CloudSeedProvider), or a dump from an existing database. The sources of seeds are called seed providers.

The mechanism is pluggable, allowing new sources of seeds to be supported (see Java Reference → Implement custom seed providers for more information).

The product has built-in support for seed from a mounted file system (file), FTP server, HTTP/HTTPS server, Amazon S3, Google Cloud Storage, and Azure Cloud Storage.

Amazon S3, Google Cloud Storage, and Azure Cloud Storage are supported by default, but the other providers require configuration of dbms.databases.seed_from_uri_providers.

FileSeedProvider

The FileSeedProvider supports:

file:

URLConnectionSeedProvider

The URLConnectionSeedProvider supports the following:

ftp:
http:
https:

Starting from Neo4j 2025.01, the URLConnectionSeedProvider does not support file.

CloudSeedProvider

The CloudSeedProvider supports:

s3:
gs:
azb:

The CloudSeedProvider supports using differential backup files as seeds. With the provided differential backup file, the CloudSeedProvider searches the directory containing differential backup files for a backup chain ending at the specified differential backup, and then seeds using this backup chain.

Neo4j uses the AWS SDK v2 to call the APIs on AWS using AWS URLs. Alternatively, you can override the endpoints so that the AWS SDK can communicate with alternative storage systems, such as Ceph, Minio, or LocalStack, using the system variables aws.endpointUrls3, aws.endpointUrlS3, or aws.endpointUrl, or the environments variables AWS_ENDPOINT_URL_S3 or AWS_ENDPOINT_URL.

Install the AWS CLI by following the instructions in the AWS official documentation — Install the AWS CLI version 2.
Create an S3 bucket and a directory to store the backup files using the AWS CLI:
```
aws s3 mb --region=us-east-1 s3://myBucket
aws s3api put-object --bucket myBucket --key myDirectory/
```
For more information on how to create a bucket and use the AWS CLI, see the AWS official documentation — Use Amazon S3 with the AWS CLI and Use high-level (s3) commands with the AWS CLI.
Verify that the ~/.aws/config file is correct by running the following command:
```
cat ~/.aws/config
```
The output should look like this:
```
[default]
region=us-east-1
```
Configure the access to your AWS S3 bucket by setting the aws_access_key_id and aws_secret_access_key in the ~/.aws/credentials file and, if needed, using a bucket policy. For example:
1. Use aws configure set aws_access_key_id aws_secret_access_key command to set your IAM credentials from AWS and verify that the ~/.aws/credentials is correct:
  cat ~/.aws/credentials
  The output should look like this:
  [default] aws_access_key_id=this.is.secret aws_secret_access_key=this.is.super.secret
2. Additionally, you can use a resource-based policy to grant access permissions to your S3 bucket and the objects in it. Create a policy document with the following content and attach it to the bucket. Note that both resource entries are important to be able to download and upload files.
  { "Version": "2012-10-17", "Id": "Neo4jBackupAggregatePolicy", "Statement": [ { "Sid": "Neo4jBackupAggregateStatement", "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::myBucket/*", "arn:aws:s3:::myBucket" ] } ] }

Create database from myBackup.backup.

CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup' }

Ensure you have a Google account and a project created in the Google Cloud Platform (GCP).
1. Install the gcloud CLI by following the instructions in the Google official documentation — Install the gcloud CLI.
2. Create a service account and a service account key using Google official documentation — Create service accounts and Creating and managing service account keys.
3. Download the JSON key file for the service account.
4. Set the GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_CLOUD_PROJECT environment variables to the path of the JSON key file and the project ID, respectively:
  export GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json" export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
5. Authenticate the gcloud CLI with the e-mail address of the service account you have created, the path to the JSON key file, and the project ID:
  gcloud auth activate-service-account service-account@example.com --key-file=$GOOGLE_APPLICATION_CREDENTIALS --project=$GOOGLE_CLOUD_PROJECT
  For more information, see the Google official documentation — gcloud auth activate-service-account.
6. Create a bucket in the Google Cloud Storage using Google official documentation — Create buckets.
7. Verify that the bucket is created by running the following command:
  gcloud storage ls
  The output should list the created bucket.

Create database from myBackup.backup.

CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 'gs://myBucket/myBackup.backup' }

Ensure you have an Azure account, an Azure storage account, and a blob container.
1. You can create a storage account using the Azure portal.
  For more information, see the Azure official documentation on Create a storage account.
2. Create a blob container in the Azure portal.
  For more information, see the Azure official documentation on Quickstart: Upload, download, and list blobs with the Azure portal.
Install the Azure CLI by following the instructions in the Azure official documentation — Azure official documentation.
Authenticate the neo4j or neo4j-admin process against Azure using the default Azure credentials.
See the Azure official documentation on default Azure credentials for more information.
```
az login
```
Then you should be ready to use Azure URLs in either neo4j or neo4j-admin.

To validate that you have access to the container with your login credentials, run the following commands:

# Upload a file:
az storage blob upload --file someLocalFile  --account-name accountName - --container someContainer --name remoteFileName  --auth-mode login

# Download the file
az storage blob download  --account-name accountName --container someContainer --name remoteFileName --file downloadedFile --auth-mode login

# List container files
az storage blob list  --account-name someContainer --container someContainer  --auth-mode login

Create database from myBackup.backup.

CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 'azb://myStorageAccount/myContainer/myBackup.backup' }

Support for seeding up to a date or a transaction ID

Starting from Neo4j 2025.01, the CloudSeedProvider supports seeding up to a specific date or transaction ID using the seedRestoreUntil option.

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.

CREATE DATABASE foo OPTIONS { existingData: 'use', 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.

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.

CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedRestoreUntil: 123 }

This will seed the database with transactions up to, but not including transaction 123.

S3SeedProvider

The S3SeedProvider supports:

s3: Deprecated in 5.26

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.

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:

CREATE DATABASE foo OPTIONS { existingData: 'use', 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 Configuration of DBMS with remote database alias. If this configuration is not performed, the seedCredentials option fails.

CREATE DATABASE foo OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup', seedConfig: 'region=eu-west-1', seedCredentials: [accessKey];[secretKey] }

Where accessKey and secretKey are provided by AWS.

Seed provider reference

URL scheme Seed provider URI example

URL scheme	Seed provider	URI example
`file:`	`FileSeedProvider`	`file://tmp/backup1.backup`
`ftp:`	`URLConnectionSeedProvider`	`ftp://myftp.com/backups/backup1.backup`
`http:`	`URLConnectionSeedProvider`	`http://myhttp.com/backups/backup1.backup`
`https:`	`URLConnectionSeedProvider`	`https://myhttp.com/backups/backup1.backup`
`s3:`	`S3SeedProvider` Deprecated in 5.26, `CloudSeedProvider`	`s3://mybucket/backups/backup1.backup`
`gs:`	`CloudSeedProvider`	`gs://mybucket/backups/backup1.backup`
`azb:`	`CloudSeedProvider`	`azb://mystorageaccount.blob/backupscontainer/backup1.backup`

file:

FileSeedProvider

file://tmp/backup1.backup

ftp:

URLConnectionSeedProvider

ftp://myftp.com/backups/backup1.backup

http:

URLConnectionSeedProvider

http://myhttp.com/backups/backup1.backup

https:

URLConnectionSeedProvider

https://myhttp.com/backups/backup1.backup

s3:

S3SeedProvider Deprecated in 5.26,
CloudSeedProvider

s3://mybucket/backups/backup1.backup

gs:

CloudSeedProvider

gs://mybucket/backups/backup1.backup

azb:

CloudSeedProvider

azb://mystorageaccount.blob/backupscontainer/backup1.backup