HTTP interface for Hot Backups
The HTTP API for Hot Backups lets you manage incremental, zero-downtime data backups
Hot Backup is only available in the Enterprise Edition.
Hot Backups are near instantaneous consistent snapshots of an entire ArangoDB deployment. This includes all databases, collections, indexes, View definitions, and users at any given time.
For creations a label may be specified, which if omitted is replaced with a generated UUID. This label is then combined with a timestamp to generate an identifier for the created hot backup. Subsequently, all other APIs operate on these identifiers.
Make sure to understand all aspects of Hot Backups, most of all the requirements and limitations, before using the API.
Create backup
creates a local backup
POST /_admin/backup/create
Request Body
-
label (string, optional): The label for this backup. The label is used together with a timestamp string create a unique backup identifier,
<timestamp>_<label>
. If no label is specified, the empty string is assumed and a default UUID is created for this part of the ID. -
timeout (number, optional): The time in seconds that the operation tries to get a consistent snapshot. The default is 120 seconds.
-
allowInconsistent (boolean, optional): If this flag is set to
true
and no global transaction lock can be acquired within the given timeout, a possibly inconsistent backup is taken. The default for this flag isfalse
and in this case a timeout results in an HTTP 408 error. -
force (boolean, optional): If this flag is set to
true
and no global transaction lock can be acquired within the given timeout, all running transactions are forcefully aborted to ensure that a consistent backup can be created. This does not include JavaScript transactions. It waits for the transactions to be aborted at mosttimeout
seconds. Thus usingforce
the request timeout is doubled. To abort transactions is almost certainly not what you want for your application. In the presence of intermediate commits it can even destroy the atomicity of your transactions. Use at your own risk, and only if you need a consistent backup at all costs. The default and recommended value isfalse
. If bothallowInconsistent
andforce
are set totrue
, then the latter takes precedence and transactions are aborted. This is only available in the cluster.
Creates a consistent backup “as soon as possible”, very much like a snapshot in time, with a given label. The ambiguity in the phrase “as soon as possible” refers to the next window during which a global write lock across all databases can be obtained in order to guarantee consistency. Note that the backup at first resides on the same machine and hard drive as the original data. Make sure to upload it to a remote site for an actual backup.
Responses
HTTP 201: If all is well, code 201 is returned.
HTTP 400: If the create command is invoked with bad parameters or any HTTP
method other than POST
, then an HTTP 400 is returned. The specifics
are detailed in the returned error document.
HTTP 408: If the operation cannot obtain a global transaction lock within the timeout, then an HTTP 408 is returned.
Examples
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_admin/backup/create <<EOF
{
"label" : "foo"
}
EOF
HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 184
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
The result body
contains besides the above discussed error codes the result
object, if code
is equal to 201
, which holds the unique identifier of this hot backup as the string attribute id
, the full size in bytes as sizeInBytes
, the number of individual files as nrFiles
and the number of database servers as nrDBServers
. Single server deployments list potentially misleadingly nrDBServers: 1
. Furthermore, the body contains a datetime
time stamp and the flag potentiallyInconsistent
, which indicates that the backup could inconsistent. This only happens if allowInconsistent
has happened.
Restore backup
restores from a local backup
POST /_admin/backup/restore
Request Body
- id (string, required): The id of the backup to restore from.
Restores a consistent backup from a snapshot in time, with a given id. The backup snapshot must reside on the ArangoDB service locally.
Responses
HTTP 200: Is returned if the backup could be restored. Note that there is an inevitable discrepancy between the single server and the cluster. In a single server, the request returns successfully, but the restore is only executed afterwards. In the cluster, the request only returns when the restore operation has been completed successfully. The cluster behaviour is obviously the desired one, but in a single instance, one cannot keep a connection open across a restart.
HTTP 400: If the restore command is invoked with bad parameters or any HTTP
method other than POST
, then an HTTP 400 is returned. The specifics
are detailed in the returned error document.
Examples
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_admin/backup/restore <<EOF
{
"id" : "2023-04-04T12.47.27Z_5b2bfe30-2df0-421b-8835-62e97c7ede21"
}
EOF
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 134
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
The result
object returns the id
of the fail safe hot backup to return to, if necessary. And the all telling isCluster
boolean attribute.
Delete a backup
delete a specific local backup
POST /_admin/backup/delete
Request Body
- id (string, required): The identifier for this backup.
Delete a specific local backup identified by the given id
.
Responses
HTTP 200: If all is well, this code 200 is returned.
HTTP 400: If the delete command is invoked with bad parameters or any HTTP
method other than POST
, then an HTTP 400 is returned.
HTTP 404: If a backup corresponding to the identifier id
cannot be found.
Examples
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_admin/backup/delete <<EOF
{
"id" : "2023-04-04T12.46.56Z_d6a7c488-c654-4f6f-800d-401507acc7ba"
}
EOF
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 38
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
List backups
list all local backups
POST /_admin/backup/list
Request Body
- id (string, optional):
The body can either be empty (in which case all available backups are
listed), or it can be an object with an attribute
id
, which is a string. In the latter case the returned list is restricted to the backup with the given id.
Lists all locally found backups.
Responses
HTTP 200: If all is well, code 200 is returned.
HTTP 400: If the list command is invoked with bad parameters, then an HTTP 400 is returned.
HTTP 404: If an id
or a list of ids was given and the given ids were not found
as identifiers of a backup, an HTTP 404 NOT FOUND is returned.
HTTP 405: If the list command is invoked with any HTTP
method other than POST
, then an HTTP 405 METHOD NOT ALLOWED is returned.
Examples
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_admin/backup/list <<EOF
{
}
EOF
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 1047
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
The result consists of a list
object of hot backups by their id
, where id
uniquely identifies a specific hot backup, version
depicts the version of
ArangoDB, which was used to create any individual hot backup and datetime
displays the time of creation of the hot backup. Further parameters are the size
of the backup in bytes as sizeInBytes
, the number of individual data files as
nrFiles
, the number of DB-Servers at time of creation as nrDBServers
, the
number of backup parts, which are found on the currently reachable DB-Servers as
nrPiecesPresent
. If the backup was created allowing inconsistences, it is so
denoted as potentiallyInconsistent
. The available
boolean parameter is
tightly connected to the backup to be present and ready to be restored on all
DB-Servers. It is true
except, when the number of DB-Servers currently
reachable does not match to the number of DB-Servers listed in the backup.
Should the backup be encrypted, the SHA-256 hashes of the user secrets are
published here. This allows you to use the correct user secret for the
encryption at rest feature to be able to restore the backup.
Upload a backup to a remote repository
upload a specific local backup
POST /_admin/backup/upload
Request Body
-
id (string, optional): The identifier for this backup. This is required when an upload operation is scheduled. In this case leave out the
uploadId
attribute. -
remoteRepository (string, optional): URL of remote repository. This is required when an upload operation is scheduled. In this case leave out the
uploadId
attribute. Provided repository URLs are normalized and validated as follows: One single colon must appear separating the configuration section name and the path. The URL prefix up to the colon must exist as a key in the config object below. No slashes must appear before the colon. Multiple back to back slashes are collapsed to one, as..
and.
are applied accordingly. Local repositories must be absolute paths and must begin with a/
. Trailing/
are removed. -
config (object, optional): Configuration of remote repository. This is required when an upload operation is scheduled. In this case leave out the
uploadId
attribute. See the description of the arangobackup program in the manual for a description of theconfig
object. -
uploadId (string, optional): Upload ID to specify for which upload operation progress is queried or the upload operation to abort. If you specify this, leave out all the above body parameters.
-
abort (boolean, optional): Set this to
true
if a running upload operation should be aborted. In this case, the only other body parameter which is needed isuploadId
.
Upload a specific local backup to a remote repository, or query progress on a previously scheduled upload operation, or abort a running upload operation.
Responses
HTTP 200: If all is well, code 200 is returned if progress is inquired or the operation is aborted.
HTTP 202: If all is well, code 202 is returned if a new operation is scheduled.
HTTP 400: If the upload command is invoked with bad parameters or any HTTP
method other than POST
, then an HTTP 400 is returned.
HTTP 401: If the authentication to the remote repository fails, then an HTTP 400 is returned.
HTTP 404: If a backup corresponding to the identifier id
cannot be found, or if
there is no known upload operation with the given uploadId
.
Examples
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_admin/backup/upload <<EOF
{
"id" : "2023-04-04T12.47.37Z_75c10d0f-be57-4e22-bae8-a3d8ee1e224b",
"remoteRepository" : "local://tmp/backups",
"config" : {
"local" : {
"type" : "local"
}
}
}
EOF
HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 56
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
The result
object of the body holds the uploadId
string attribute which can
be used to follow the upload process.
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_admin/backup/upload <<EOF
{
"uploadId" : "68666"
}
EOF
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 222
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Download a backup from a remote repository
download a specific local backup
POST /_admin/backup/download
Request Body
-
id (string, optional): The identifier for this backup. This is required when a download operation is scheduled. In this case leave out the
downloadId
attribute. -
remoteRepository (string, required): URL of remote repository. This is required when a download operation is scheduled. In this case leave out the
downloadId
attribute. Provided repository URLs are normalized and validated as follows: One single colon must appear separating the configuration section name and the path. The URL prefix up to the colon must exist as a key in the config object below. No slashes must appear before the colon. Multiple back to back slashes are collapsed to one, as..
and.
are applied accordingly. Local repositories must be absolute paths and must begin with a/
. Trailing/
are removed. -
config (object, required): Configuration of remote repository. This is required when a download operation is scheduled. In this case leave out the
downloadId
attribute. See the description of the arangobackup program in the manual for a description of theconfig
object. -
downloadId (string, optional): Download ID to specify for which download operation progress is queried, or the download operation to abort. If you specify this, leave out all the above body parameters.
-
abort (boolean, optional): Set this to
true
if a running download operation should be aborted. In this case, the only other body parameter which is needed isdownloadId
.
Download a specific local backup from a remote repository, or query progress on a previously scheduled download operation, or abort a running download operation.
Responses
HTTP 200: If all is well, code 200 is returned if progress is inquired or the operation is aborted.
HTTP 202: If all is well, code 202 is returned if a new operation is scheduled.
HTTP 400: If the download command is invoked with bad parameters or any HTTP
method other than POST
, then an HTTP 400 is returned.
HTTP 401: If the authentication to the remote repository fails, then an HTTP 401 is returned.
HTTP 404: If a backup corresponding to the identifier id
cannot be found, or if
there is no known download operation with the given downloadId
.
Examples
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_admin/backup/download <<EOF
{
"id" : "2023-04-04T12.46.56Z_b50eab99-dd6c-48ff-9927-7d915b599c70",
"remoteRepository" : "local://tmp/backups",
"config" : {
"local" : {
"type" : "local"
}
}
}
EOF
HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 58
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
The result
object of the body holds the downloadId
string attribute which
can be used to follow the download process.
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_admin/backup/download <<EOF
{
"downloadId" : "68640"
}
EOF
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 224
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff