Restore a Database

ArcadeDB allows to restore a database previously backed up.

The easiest way to restore a database on a running server is via the server command HTTP API. This supports both local files and remote URLs:

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "restore database mydb file:///path/to/mydb-backup.zip"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Restoring from a remote URL (e.g., a backup hosted on a server or cloud storage):

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "restore database mydb https://example.com/backups/mydb-backup.zip"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

The database must not already exist. The server downloads the backup file, extracts it, and opens the database automatically.

For security reasons, restoring from an http:///https:// URL refuses by default to reach a local-file, loopback, link-local, or private-network address, including a redirect that lands on one. This protects the server from being made to fetch from internal-only hosts (e.g. a cloud metadata endpoint) via a crafted or hijacked backup URL. If you need to restore from a backup hosted on such an address (for example, an internal artifact server), set arcadedb.server.restoreImportAllowLocalUrls=true on the server.

Restore via command line

If the server is not running, you can restore a database using the command-line tool.

If a server is running, it must be restarted in order to access a database restored via command line.

Example

Example for restoring the database "mydb" from the backup located in backups/mysb/mydb-backup-20210921-172750767.zip.

$ bin/restore.sh -f backups/mysb/mydb-backup-20210921-172750767.zip -d databases/mydb
A restore forces every restored file to disk (fsync) before it reports success, together with the database directory and its parent. A power loss after the restore completes cannot leave the restored database partially written.
(Since v26.11.1) the archive is extracted into a hidden staging directory next to database-path, and moved to database-path only once the extraction succeeded and the result was verified to be a database. A restore that fails (a truncated or corrupted archive, a wrong encryption key, a full disk) leaves nothing behind, so it can be retried with the same command. Previously the half-extracted directory stayed at database-path, and every later restore into it was refused with "already exist" until it was removed by hand. With -o, the database being replaced is kept until the restored copy is complete and only then replaced, so a failed restore no longer destroys it. This means the disk must have room for both the existing database and the restored copy while the restore runs, as was already the case for a restore through the server. If the process is killed while the restore runs, what it leaves are hidden directories next to database-path, never a half-written database-path: .<name>.restore-<n> is an unfinished restored copy and can be deleted, and .<name>.replaced-<n>, left only by a kill in the instant of the -o swap, is the previous database, which can be renamed back to database-path if that is missing.
(Since v26.11.1) a restore refuses an archive the backup did not finish writing (one missing the ZIP central directory a completed backup writes last, or whose central directory does not match its content), whatever the source: a local file, an encrypted archive or an http:///https:// URL. Previously the single-threaded path (always used for encrypted and remote archives) stopped at the last complete file and reported success over a partial database. A local archive is checked before anything is extracted.

Configuration

  • -f <backup-file> (string) path to the backup file to restore.

  • -d <database-path> (string) path on local filesystem where to create the ArcadeDB database.

  • -o (boolean) true to overwrite the database if already exists. If false and the database-path already exists, an error is thrown. Default is false.