ArangoDB Replication API
Control data replication for deployments
OpenAPI Specification
openapi: 3.2.0
info:
contact:
name: ArangoDB Inc.
url: https://arango.ai
license:
name: Business Source License 1.1
url: https://github.com/arangodb/arangodb/blob/devel/LICENSE
summary: The HTTP API of the ArangoDB graph database system
title: ArangoDB Core Replication API
version: 3.12.10 (API v0)
description: Control data replication for deployments
tags:
- description: Control data replication for deployments
name: Replication
paths:
/_db/{database-name}/_api/replication/applier-config:
get:
description: "Returns the configuration of the replication applier.\n\nThe body of the response is a JSON object with the configuration. The\nfollowing attributes may be present in the configuration:\n\n- `endpoint`: the logger server to connect to (e.g. \"tcp://192.168.173.13:8529\").\n\n- `database`: the name of the database to connect to (e.g. \"_system\").\n\n- `username`: an optional ArangoDB username to use when connecting to the endpoint.\n\n- `password`: the password to use when connecting to the endpoint.\n\n- `maxConnectRetries`: the maximum number of connection attempts the applier\n will make in a row. If the applier cannot establish a connection to the\n endpoint in this number of attempts, it will stop itself.\n\n- `connectTimeout`: the timeout (in seconds) when attempting to connect to the\n endpoint. This value is used for each connection attempt.\n\n- `requestTimeout`: the timeout (in seconds) for individual requests to the endpoint.\n\n- `chunkSize`: the requested maximum size for log transfer packets that\n is used when the endpoint is contacted.\n\n- `autoStart`: whether or not to auto-start the replication applier on\n (next and following) server starts\n\n- `adaptivePolling`: whether or not the replication applier will use\n adaptive polling.\n\n- `includeSystem`: whether or not system collection operations will be applied\n\n- `autoResync`: whether or not the follower should perform a full automatic\n resynchronization with the leader in case the leader cannot serve log data\n requested by the follower, or when the replication is started and no tick\n value\n can be found.\n\n- `autoResyncRetries`: number of resynchronization retries that will be performed\n in a row when automatic resynchronization is enabled and kicks in. Setting this\n to `0` will effectively disable `autoResync`. Setting it to some other value\n will limit the number of retries that are performed. This helps preventing endless\n retries in case resynchronizations always fail.\n\n- `initialSyncMaxWaitTime`: the maximum wait time (in seconds) that the initial\n synchronization will wait for a response from the leader when fetching initial\n collection data.\n This wait time can be used to control after what time the initial synchronization\n will give up waiting for a response and fail. This value is relevant even\n for continuous replication when `autoResync` is set to `true` because this\n may re-start the initial synchronization when the leader cannot provide\n log data the follower requires.\n This value will be ignored if set to `0`.\n\n- `connectionRetryWaitTime`: the time (in seconds) that the applier will\n intentionally idle before it retries connecting to the leader in case of\n connection problems.\n This value will be ignored if set to `0`.\n\n- `idleMinWaitTime`: the minimum wait time (in seconds) that the applier will\n intentionally idle before fetching more log data from the leader in case\n the leader has already sent all its log data. This wait time can be used\n to control the frequency with which the replication applier sends HTTP log\n fetch requests to the leader in case there is no write activity on the leader.\n This value will be ignored if set to `0`.\n\n- `idleMaxWaitTime`: the maximum wait time (in seconds) that the applier will\n intentionally idle before fetching more log data from the leader in case the\n leader has already sent all its log data and there have been previous log\n fetch attempts that resulted in no more log data. This wait time can be used\n to control the maximum frequency with which the replication applier sends HTTP\n log fetch requests to the leader in case there is no write activity on the\n leader for longer periods. This configuration value will only be used if the\n option `adaptivePolling` is set to `true`.\n This value will be ignored if set to `0`.\n\n- `requireFromPresent`: if set to `true`, then the replication applier will check\n at start whether the start tick from which it starts or resumes replication is\n still present on the leader. If not, then there would be data loss. If\n `requireFromPresent` is `true`, the replication applier will abort with an\n appropriate error message. If set to `false`, then the replication applier will\n still start, and ignore the data loss.\n\n- `verbose`: if set to `true`, then a log line will be emitted for all operations\n performed by the replication applier. This should be used for debugging\n replication\n problems only.\n\n- `restrictType`: the configuration for `restrictCollections`\n\n- `restrictCollections`: the optional array of collections to include or exclude,\n based on the setting of `restrictType`\n"
operationId: getReplicationApplierConfig
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'If set to `true`, returns the configuration of the global replication applier for all
databases. If set to `false`, returns the configuration of the replication applier in the
selected database.
'
in: query
name: global
required: false
schema:
type: boolean
responses:
'200':
description: 'is returned if the request was executed successfully.
'
'405':
description: 'is returned when an invalid HTTP method is used.
'
'500':
description: 'is returned if an error occurred while assembling the response.
'
summary: Get the replication applier configuration
tags:
- Replication
put:
description: 'Sets the configuration of the replication applier. The configuration can
only be changed while the applier is not running. The updated configuration
will be saved immediately but only become active with the next start of the
applier.
In case of success, the body of the response is a JSON object with the updated
configuration.
'
operationId: updateReplicationApplierConfig
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'If set to `true`, adjusts the configuration of the global replication applier for all
databases. If set to `false`, adjusts the configuration of the replication applier in the
selected database.
'
in: query
name: global
required: false
schema:
type: boolean
requestBody:
content:
application/json:
schema:
properties:
adaptivePolling:
description: 'if set to `true`, the replication applier will fall
to sleep for an increasingly long period in case the logger server at the
endpoint does not have any more replication events to apply. Using
adaptive polling is thus useful to reduce the amount of work for both the
applier and the logger server for cases when there are only infrequent
changes. The downside is that when using adaptive polling, it might take
longer for the replication applier to detect that there are new replication
events on the logger server.
Setting `adaptivePolling` to false will make the replication applier
contact the logger server in a constant interval, regardless of whether
the logger server provides updates frequently or seldom.
'
type: boolean
autoResync:
description: 'whether or not the follower should perform a full automatic resynchronization
with the leader in case the leader cannot serve log data requested by the
follower, or when the replication is started and no tick value can be found.
'
type: boolean
autoResyncRetries:
description: 'number of resynchronization retries that will be performed in a row when
automatic resynchronization is enabled and kicks in. Setting this to `0`
will
effectively disable `autoResync`. Setting it to some other value will limit
the number of retries that are performed. This helps preventing endless
retries
in case resynchronizations always fail.
'
type: integer
autoStart:
description: 'whether or not to auto-start the replication applier on
(next and following) server starts
'
type: boolean
chunkSize:
description: 'the requested maximum size for log transfer packets that
is used when the endpoint is contacted.
'
type: integer
connectTimeout:
description: 'the timeout (in seconds) when attempting to connect to the
endpoint. This value is used for each connection attempt.
'
type: integer
connectionRetryWaitTime:
description: 'the time (in seconds) that the applier will intentionally idle before
it retries connecting to the leader in case of connection problems.
This value will be ignored if set to `0`.
'
type: integer
database:
description: 'the name of the database on the endpoint. If not specified, defaults to the current local database name.
'
type: string
endpoint:
description: 'the logger server to connect to (e.g. "tcp://192.168.173.13:8529"). The endpoint must be specified.
'
type: string
idleMaxWaitTime:
description: 'the maximum wait time (in seconds) that the applier will intentionally idle
before fetching more log data from the leader in case the leader has
already sent all its log data and there have been previous log fetch attempts
that resulted in no more log data. This wait time can be used to control the
maximum frequency with which the replication applier sends HTTP log fetch
requests to the leader in case there is no write activity on the leader for
longer periods. This configuration value will only be used if the option
`adaptivePolling` is set to `true`.
This value will be ignored if set to `0`.
'
type: integer
idleMinWaitTime:
description: 'the minimum wait time (in seconds) that the applier will intentionally idle
before fetching more log data from the leader in case the leader has
already sent all its log data. This wait time can be used to control the
frequency with which the replication applier sends HTTP log fetch requests
to the leader in case there is no write activity on the leader.
This value will be ignored if set to `0`.
'
type: integer
includeSystem:
description: 'whether or not system collection operations will be applied
'
type: boolean
initialSyncMaxWaitTime:
description: 'the maximum wait time (in seconds) that the initial synchronization will
wait for a response from the leader when fetching initial collection data.
This wait time can be used to control after what time the initial
synchronization
will give up waiting for a response and fail. This value is relevant even
for continuous replication when `autoResync` is set to `true` because this
may re-start the initial synchronization when the leader cannot provide
log data the follower requires.
This value will be ignored if set to `0`.
'
type: integer
maxConnectRetries:
description: 'the maximum number of connection attempts the applier
will make in a row. If the applier cannot establish a connection to the
endpoint in this number of attempts, it will stop itself.
'
type: integer
password:
description: 'the password to use when connecting to the endpoint.
'
type: string
requestTimeout:
description: 'the timeout (in seconds) for individual requests to the endpoint.
'
type: integer
requireFromPresent:
description: 'if set to `true`, then the replication applier will check
at start whether the start tick from which it starts or resumes replication is
still present on the leader. If not, then there would be data loss. If
`requireFromPresent` is `true`, the replication applier will abort with an
appropriate error message. If set to `false`, then the replication applier will
still start, and ignore the data loss.
'
type: boolean
restrictCollections:
description: 'the array of collections to include or exclude,
based on the setting of `restrictType`
'
items:
type: string
type: array
restrictType:
description: 'the configuration for `restrictCollections`; Has to be either `include` or `exclude`
'
type: string
username:
description: 'an optional ArangoDB username to use when connecting to the endpoint.
'
type: string
verbose:
description: 'if set to `true`, then a log line will be emitted for all operations
performed by the replication applier. This should be used for debugging replication
problems only.
'
type: boolean
required:
- endpoint
- database
- password
- maxConnectRetries
- connectTimeout
- requestTimeout
- chunkSize
- autoStart
- adaptivePolling
- includeSystem
- requireFromPresent
- verbose
- restrictType
type: object
responses:
'200':
description: 'is returned if the request was executed successfully.
'
'400':
description: 'is returned if the configuration is incomplete or malformed, or if the
replication applier is currently running.
'
'405':
description: 'is returned when an invalid HTTP method is used.
'
'500':
description: 'is returned if an error occurred while assembling the response.
'
summary: Update the replication applier configuration
tags:
- Replication
/_db/{database-name}/_api/replication/applier-start:
put:
description: 'Starts the replication applier. This will return immediately if the
replication applier is already running.
If the replication applier is not already running, the applier configuration
will be checked, and if it is complete, the applier will be started in a
background thread. This means that even if the applier will encounter any
errors while running, they will not be reported in the response to this
method.
To detect replication applier errors after the applier was started, use the
`/_api/replication/applier-state` API instead.
'
operationId: startReplicationApplier
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'If set to `true`, starts the global replication applier for all
databases. If set to `false`, starts the replication applier in the
selected database.
'
in: query
name: global
required: false
schema:
type: boolean
- description: 'The remote `lastLogTick` value from which to start applying. If not specified,
the last saved tick from the previous applier run is used. If there is no
previous applier state saved, the applier will start at the beginning of the
logger server''s log.
'
in: query
name: from
required: false
schema:
type: string
responses:
'200':
description: 'is returned if the request was executed successfully.
'
'400':
description: 'is returned if the replication applier is not fully configured or the
configuration is invalid.
'
'405':
description: 'is returned when an invalid HTTP method is used.
'
'500':
description: 'is returned if an error occurred while assembling the response.
'
summary: Start the replication applier
tags:
- Replication
/_db/{database-name}/_api/replication/applier-state:
get:
description: "Returns the state of the replication applier, regardless of whether the\napplier is currently running or not.\n\nThe response is a JSON object with the following attributes:\n\n- `state`: a JSON object with the following sub-attributes:\n\n - `running`: whether or not the applier is active and running\n\n - `lastAppliedContinuousTick`: the last tick value from the continuous\n replication log the applier has applied.\n\n - `lastProcessedContinuousTick`: the last tick value from the continuous\n replication log the applier has processed.\n\n Regularly, the last applied and last processed tick values should be\n identical. For transactional operations, the replication applier will first\n process incoming log events before applying them, so the processed tick\n value might be higher than the applied tick value. This will be the case\n until the applier encounters the *transaction commit* log event for the\n transaction.\n\n - `lastAvailableContinuousTick`: the last tick value the remote server can\n provide, for all databases.\n\n - `ticksBehind`: this attribute will be present only if the applier is currently\n running. It will provide the number of log ticks between what the applier\n has applied/seen and the last log tick value provided by the remote server.\n If this value is zero, then both servers are in sync. If this is non-zero,\n then the remote server has additional data that the applier has not yet\n fetched and processed, or the remote server may have more data that is not\n applicable to the applier.\n\n Client applications can use it to determine approximately how far the applier\n is behind the remote server, and can periodically check if the value is\n increasing (applier is falling behind) or decreasing (applier is catching up).\n\n Please note that as the remote server will only keep one last log tick value\n for all of its databases, but replication may be restricted to just certain\n databases on the applier, this value is more meaningful when the global applier\n is used.\n Additionally, the last log tick provided by the remote server may increase\n due to writes into system collections that are not replicated due to replication\n configuration. So the reported value may exaggerate the reality a bit for\n some scenarios.\n\n - `time`: the time on the applier server.\n\n - `totalRequests`: the total number of requests the applier has made to the\n endpoint.\n\n - `totalFailedConnects`: the total number of failed connection attempts the\n applier has made.\n\n - `totalEvents`: the total number of log events the applier has processed.\n\n - `totalOperationsExcluded`: the total number of log events excluded because\n of `restrictCollections`.\n\n - `progress`: a JSON object with details about the replication applier progress.\n It contains the following sub-attributes if there is progress to report:\n\n - `message`: a textual description of the progress\n\n - `time`: the date and time the progress was logged\n\n - `failedConnects`: the current number of failed connection attempts\n\n - `lastError`: a JSON object with details about the last error that happened on\n the applier. It contains the following sub-attributes if there was an error:\n\n - `errorNum`: a numerical error code\n\n - `errorMessage`: a textual error description\n\n - `time`: the date and time the error occurred\n\n In case no error has occurred, `lastError` will be empty.\n\n- `server`: a JSON object with the following sub-attributes:\n\n - `version`: the applier server's version\n\n - `serverId`: the applier server's id\n\n- `endpoint`: the endpoint the applier is connected to (if applier is\n active) or will connect to (if applier is currently inactive)\n\n- `database`: the name of the database the applier is connected to (if applier is\n active) or will connect to (if applier is currently inactive)\n\nPlease note that all \"tick\" values returned do not have a specific unit. Tick\nvalues are only meaningful when compared to each other. Higher tick values mean\n\"later in time\" than lower tick values.\n"
operationId: getReplicationApplierState
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'If set to `true`, returns the state of the global replication applier for all
databases. If set to `false`, returns the state of the replication applier in the
selected database.
'
in: query
name: global
required: false
schema:
type: boolean
responses:
'200':
description: 'is returned if the request was executed successfully.
'
'405':
description: 'is returned when an invalid HTTP method is used.
'
'500':
description: 'is returned if an error occurred while assembling the response.
'
summary: Get the replication applier state
tags:
- Replication
/_db/{database-name}/_api/replication/applier-stop:
put:
description: 'Stops the replication applier. This will return immediately if the
replication applier is not running.
'
operationId: stopReplicationApplier
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'If set to `true`, stops the global replication applier for all
databases. If set to `false`, stops the replication applier in the
selected database.
'
in: query
name: global
required: false
schema:
type: boolean
responses:
'200':
description: 'is returned if the request was executed successfully.
'
'405':
description: 'is returned when an invalid HTTP method is used.
'
'500':
description: 'is returned if an error occurred while assembling the response.
'
summary: Stop the replication applier
tags:
- Replication
/_db/{database-name}/_api/replication/batch:
post:
description: "> **INFO:**\nThis is an internally used endpoint.\n\n\nCreates a new dump batch and returns the batch's id.\n\nThe response is a JSON object with the following attributes:\n\n- `id`: the id of the batch\n- `lastTick`: snapshot tick value using when creating the batch\n- `state`: additional leader state information (only present if the\n `state` URL parameter was set to `true` in the request)\n\n> **INFO:**\nOn a Coordinator, this request must have a `DBserver`\nquery parameter which must be an ID of a DB-Server.\nThe very same request is forwarded synchronously to that DB-Server.\nIt is an error if this attribute is not bound in the Coordinator case.\n"
operationId: createReplicationBatch
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'Setting `state` to `true` makes the response also contain
a `state` attribute with information about the leader state.
This is used only internally during the replication process
and should not be used by client applications.
'
in: query
name: state
required: false
schema:
type: boolean
requestBody:
content:
application/json:
schema:
properties:
ttl:
description: 'The time-to-live for the new batch (in seconds).
'
type: number
required:
- ttl
type: object
responses:
'200':
description: 'is returned if the batch was created successfully.
'
'400':
description: 'is returned if the TTL value is invalid or if the `DBserver` attribute
is not specified or illegal on a Coordinator.
'
'405':
description: 'is returned when an invalid HTTP method is used.
'
summary: Create a new dump batch
tags:
- Replication
/_db/{database-name}/_api/replication/batch/{id}:
delete:
description: '> **INFO:**
This is an internally used endpoint.
Deletes the existing dump batch, allowing compaction and cleanup to resume.
> **INFO:**
On a Coordinator, this request must have a `DBserver`
query parameter which must be an ID of a DB-Server.
The very same request is forwarded synchronously to that DB-Server.
It is an error if this attribute is not bound in the Coordinator case.
'
operationId: deleteReplicationBatch
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'The id of the batch.
'
in: path
name: id
required: true
schema:
type: string
responses:
'204':
description: 'is returned if the batch was deleted successfully.
'
'400':
description: 'is returned if the batch was not found.
'
'405':
description: 'is returned when an invalid HTTP method is used.
'
summary: Delete an existing dump batch
tags:
- Replication
put:
description: '> **INFO:**
This is an internally used endpoint.
Extends the time-to-live (TTL) of an existing dump batch, using the batch''s ID and
the provided TTL value.
If the batch''s TTL can be extended successfully, the response is empty.
> **INFO:**
On a Coordinator, this request must have a `DBserver`
query parameter which must be an ID of a DB-Server.
The very same request is forwarded synchronously to that DB-Server.
It is an error if this attribute is not bound in the Coordinator case.
'
operationId: extendReplicationBatch
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'The id of the batch.
'
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
ttl:
description: 'The time-to-live for the new batch (in seconds)
'
type: number
required:
- ttl
type: object
responses:
'204':
description: 'is returned if the batch''s ttl was extended successfully.
'
'400':
description: 'is returned if the ttl value is invalid or the batch was not found.
'
'405':
description: 'is returned when an invalid HTTP method is used.
'
summary: Extend the TTL of a dump batch
tags:
- Replication
/_db/{database-name}/_api/replication/clusterInventory:
get:
description: 'Returns the array of collections and indexes available on the cluster.
The response will be an array of JSON objects, one for each collection.
Each collection contains exactly two keys, `parameters` and `indexes`.
This information comes from `Plan/Collections/{DB-Name}/*` in the Agency,
just that the `indexes` attribute there is relocated to adjust it to
the data format of arangodump.
'
operationId: getReplicationClusterInventory
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'Include system collections in the result.
'
in: query
name: includeSystem
required: false
schema:
default: true
type: boolean
responses:
'200':
description: 'is returned if the request was executed successfully.
'
'405':
description: 'is returned when an invalid HTTP method is used.
'
'500':
description: 'is returned if an error occurred while assembling the response.
'
summary: Get the cluster collections and indexes
tags:
- Replication
/_db/{database-name}/_api/replication/dump:
get:
description: "Returns the data from a collection for the requested range.\n\nThe `chunkSize` query parameter can be used to control the size of the result.\nIt must be specified in bytes. The `chunkSize` value will only be honored\napproximately. Otherwise a too low `chunkSize` value could cause the serv
# --- truncated at 32 KB (95 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arangodb/refs/heads/main/openapi/arangodb-replication-api-openapi.yml