mirror of https://gitee.com/bigwinds/arangodb
406 lines
14 KiB
Plaintext
406 lines
14 KiB
Plaintext
!CHAPTER Replication Applier Commands
|
|
|
|
The applier commands allow to remotely start, stop, and query the state and
|
|
configuration of an ArangoDB database's replication applier.
|
|
|
|
`GET /_api/replication/applier-config`*(returns the configuration of the replication applier)*
|
|
|
|
!SUBSECTION Description
|
|
|
|
Returns the configuration of the replication applier.
|
|
The body of the response is a JSON hash with the configuration. The following attributes may be present in the configuration:
|
|
|
|
* endpoint: the logger server to connect to (e.g. "tcp://192.168.173.13:8529").
|
|
* database: the name of the database to connect to (e.g. "_system").
|
|
* username: an optional ArangoDB username to use when connecting to the endpoint.
|
|
* password: the password to use when connecting to the endpoint.
|
|
* maxConnectRetries: 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.
|
|
* connectTimeout: the timeout (in seconds) when attempting to connect to the endpoint. This value is used for each connection attempt.
|
|
* requestTimeout: the timeout (in seconds) for individual requests to the endpoint.
|
|
* chunkSize: the requested maximum size for log transfer packets that is used when the endpoint is contacted.
|
|
* autoStart: whether or not to auto-start the replication applier on (next and following) server starts
|
|
* adaptivePolling: whether or not the replication applier will use adaptive polling.
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 200`
|
|
|
|
is returned if the request was executed successfully.
|
|
|
|
`HTTP 405`
|
|
|
|
is returned when an invalid HTTP method is used.
|
|
|
|
`HTTP 500`
|
|
|
|
is returned if an error occurred while assembling the response.
|
|
|
|
*Examples*
|
|
|
|
```
|
|
unix> curl --dump - http://localhost:8529/_api/replication/applier-config
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"requestTimeout" : 300,
|
|
"connectTimeout" : 10,
|
|
"maxConnectRetries" : 100,
|
|
"sslProtocol" : 0,
|
|
"chunkSize" : 0,
|
|
"autoStart" : false,
|
|
"adaptivePolling" : true
|
|
}
|
|
```
|
|
set the configuration of the replication applier
|
|
|
|
`PUT /_api/replication/applier-config`*(adjusts the configuration of the replication applier)*
|
|
|
|
!SUBSECTION Body parameters
|
|
|
|
`configuration (json,required)`
|
|
|
|
A JSON representation of the configuration.
|
|
|
|
!SUBSECTION 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.
|
|
The body of the request must be JSON hash with the configuration. The following attributes are allowed for the configuration:
|
|
|
|
* endpoint: the logger server to connect to (e.g. "tcp://192.168.173.13:8529"). The endpoint must be specified.
|
|
* database: the name of the database on the endpoint. If not specified, defaults to the current local database name.
|
|
* username: an optional ArangoDB username to use when connecting to the endpoint.
|
|
* password: the password to use when connecting to the endpoint.
|
|
* maxConnectRetries: 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.
|
|
* connectTimeout: the timeout (in seconds) when attempting to connect to the endpoint. This value is used for each connection attempt.
|
|
* requestTimeout: the timeout (in seconds) for individual requests to the endpoint.
|
|
* chunkSize: the requested maximum size for log transfer packets that is used when the endpoint is contacted.
|
|
* autoStart: whether or not to auto-start the replication applier on (next and following) server starts
|
|
* adaptivePolling: 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 seldomly.
|
|
|
|
In case of success, the body of the response is a JSON hash with the updated configuration.
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 200`
|
|
|
|
is returned if the request was executed successfully.
|
|
|
|
`HTTP 400`
|
|
|
|
is returned if the configuration is incomplete or malformed, or if the replication applier is currently running.
|
|
|
|
`HTTP 405`
|
|
|
|
is returned when an invalid HTTP method is used.
|
|
|
|
`HTTP 500`
|
|
|
|
is returned if an error occurred while assembling the response.
|
|
|
|
*Examples*
|
|
|
|
```
|
|
unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/replication/applier-config
|
|
{"endpoint":"tcp://127.0.0.1:8529","username":"replicationApplier","password":"applier1234@foxx","chunkSize":4194304,"autoStart":false,"adaptivePolling":true}
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"endpoint" : "tcp://127.0.0.1:8529",
|
|
"database" : "_system",
|
|
"username" : "replicationApplier",
|
|
"requestTimeout" : 300,
|
|
"connectTimeout" : 10,
|
|
"maxConnectRetries" : 100,
|
|
"sslProtocol" : 0,
|
|
"chunkSize" : 4194304,
|
|
"autoStart" : false,
|
|
"adaptivePolling" : true
|
|
}
|
|
```
|
|
|
|
`PUT /_api/replication/applier-start`*(starts the replication applier)*
|
|
|
|
!SUBSECTION Query parameters
|
|
|
|
`from (string,optional)`
|
|
|
|
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.
|
|
|
|
!SUBSECTION 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.
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 200`
|
|
|
|
is returned if the request was executed successfully.
|
|
|
|
`HTTP 400`
|
|
|
|
is returned if the replication applier is not fully configured or the configuration is invalid.
|
|
|
|
`HTTP 405`
|
|
|
|
is returned when an invalid HTTP method is used.
|
|
|
|
`HTTP 500`
|
|
|
|
is returned if an error occurred while assembling the response.
|
|
|
|
*Examples*
|
|
|
|
```
|
|
unix> curl -X PUT --dump - http://localhost:8529/_api/replication/applier-start
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"state" : {
|
|
"running" : true,
|
|
"lastAppliedContinuousTick" : null,
|
|
"lastProcessedContinuousTick" : null,
|
|
"lastAvailableContinuousTick" : null,
|
|
"progress" : {
|
|
"time" : "2014-05-29T15:03:18Z",
|
|
"message" : "applier created",
|
|
"failedConnects" : 0
|
|
},
|
|
"totalRequests" : 0,
|
|
"totalFailedConnects" : 0,
|
|
"totalEvents" : 0,
|
|
"lastError" : {
|
|
"errorNum" : 0
|
|
},
|
|
"time" : "2014-05-29T15:03:53Z"
|
|
},
|
|
"server" : {
|
|
"version" : "2.1.0",
|
|
"serverId" : "18804023088184"
|
|
},
|
|
"endpoint" : "tcp://127.0.0.1:8529",
|
|
"database" : "_system"
|
|
}
|
|
```
|
|
|
|
stops the replication applier
|
|
|
|
`PUT /_api/replication/applier-stop`*(stops the replication applier)*
|
|
|
|
!SUBSECTION Description
|
|
|
|
Stops the replication applier. This will return immediately if the replication applier is not running.
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 200`
|
|
|
|
is returned if the request was executed successfully.
|
|
|
|
`HTTP 405`
|
|
|
|
is returned when an invalid HTTP method is used.
|
|
|
|
`HTTP 500`
|
|
|
|
is returned if an error occurred while assembling the response.
|
|
|
|
!SUBSECTION Examples
|
|
|
|
```
|
|
unix> curl -X PUT --dump - http://localhost:8529/_api/replication/applier-stop
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"state" : {
|
|
"running" : false,
|
|
"lastAppliedContinuousTick" : null,
|
|
"lastProcessedContinuousTick" : null,
|
|
"lastAvailableContinuousTick" : null,
|
|
"progress" : {
|
|
"time" : "2014-05-29T15:03:53Z",
|
|
"message" : "fetching master state information",
|
|
"failedConnects" : 1
|
|
},
|
|
"totalRequests" : 2,
|
|
"totalFailedConnects" : 2,
|
|
"totalEvents" : 0,
|
|
"lastError" : {
|
|
"time" : "2014-05-29T15:03:53Z",
|
|
"errorMessage" : "could not connect to master at tcp://127.0.0.1:8529: Could not connect to 'tcp:/...",
|
|
"errorNum" : 1412
|
|
},
|
|
"time" : "2014-05-29T15:03:53Z"
|
|
},
|
|
"server" : {
|
|
"version" : "2.1.0",
|
|
"serverId" : "18804023088184"
|
|
},
|
|
"endpoint" : "tcp://127.0.0.1:8529",
|
|
"database" : "_system"
|
|
}
|
|
```
|
|
|
|
returns the state of the replication applier
|
|
|
|
`GET /_api/replication/applier-state`*(returns the state of the replication applier)*
|
|
|
|
!SUBSECTION Description
|
|
|
|
Returns the state of the replication applier, regardless of whether the applier is currently running or not.
|
|
The response is a JSON hash with the following attributes:
|
|
|
|
*state*: a JSON hash with the following sub-attributes:
|
|
|
|
*running*: whether or not the applier is active and running
|
|
lastAppliedContinuousTick: the last tick value from the continuous replication log the applier has applied.
|
|
lastProcessedContinuousTick: the last tick value from the continuous replication log the applier has processed.
|
|
|
|
Regularly, the last applied and last processed tick values should be identical. For transactional operations, the replication applier will first process incoming log events before applying them, so the processed tick value might be higher than the applied tick value. This will be the case until the applier encounters the transaction commit log event for the transaction.
|
|
|
|
* lastAvailableContinuousTick: the last tick value the logger server can provide.
|
|
* time: the time on the applier server.
|
|
* totalRequests: the total number of requests the applier has made to the endpoint.
|
|
* totalFailedConnects: the total number of failed connection attempts the applier has made.
|
|
* totalEvents: the total number of log events the applier has processed.
|
|
* progress: a JSON hash with details about the replication applier progress. It contains the following sub-attributes if there is progress to report:
|
|
|
|
* message: a textual description of the progress
|
|
* time: the date and time the progress was logged
|
|
* failedConnects: the current number of failed connection attempts
|
|
* lastError: a JSON hash with details about the last error that happened on the applier. It contains the following sub-attributes if there was an error:
|
|
|
|
* errorNum: a numerical error code
|
|
* errorMessage: a textual error description
|
|
* time: the date and time the error occurred
|
|
|
|
In case no error has occurred, lastError will be empty.
|
|
|
|
* server: a JSON hash with the following sub-attributes:
|
|
* version: the applier server's version
|
|
* serverId: the applier server's id
|
|
* endpoint: the endpoint the applier is connected to (if applier is active) or will connect to (if applier is currently inactive)
|
|
* database: the name of the database the applier is connected to (if applier is active) or will connect to (if applier is currently inactive)
|
|
|
|
!SUBSECTION Return codes
|
|
|
|
`HTTP 200`
|
|
|
|
is returned if the request was executed successfully.
|
|
|
|
`HTTP 405`
|
|
|
|
is returned when an invalid HTTP method is used.
|
|
|
|
`HTTP 500`
|
|
|
|
is returned if an error occurred while assembling the response.
|
|
|
|
*Examples*
|
|
|
|
Fetching the state of an inactive applier:
|
|
|
|
```
|
|
unix> curl --dump - http://localhost:8529/_api/replication/applier-state
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"state" : {
|
|
"running" : false,
|
|
"lastAppliedContinuousTick" : null,
|
|
"lastProcessedContinuousTick" : null,
|
|
"lastAvailableContinuousTick" : null,
|
|
"progress" : {
|
|
"time" : "2014-05-29T15:03:53Z",
|
|
"message" : "fetching master state information",
|
|
"failedConnects" : 1
|
|
},
|
|
"totalRequests" : 2,
|
|
"totalFailedConnects" : 2,
|
|
"totalEvents" : 0,
|
|
"lastError" : {
|
|
"time" : "2014-05-29T15:03:53Z",
|
|
"errorMessage" : "could not connect to master at tcp://127.0.0.1:8529: Could not connect to 'tcp:/...",
|
|
"errorNum" : 1412
|
|
},
|
|
"time" : "2014-05-29T15:03:53Z"
|
|
},
|
|
"server" : {
|
|
"version" : "2.1.0",
|
|
"serverId" : "18804023088184"
|
|
},
|
|
"endpoint" : "tcp://127.0.0.1:8529",
|
|
"database" : "_system"
|
|
}
|
|
```
|
|
|
|
Fetching the state of an active applier:
|
|
|
|
```
|
|
unix> curl --dump - http://localhost:8529/_api/replication/applier-state
|
|
|
|
HTTP/1.1 200 OK
|
|
content-type: application/json; charset=utf-8
|
|
|
|
{
|
|
"state" : {
|
|
"running" : true,
|
|
"lastAppliedContinuousTick" : null,
|
|
"lastProcessedContinuousTick" : null,
|
|
"lastAvailableContinuousTick" : null,
|
|
"progress" : {
|
|
"time" : "2014-05-29T15:03:53Z",
|
|
"message" : "fetching master state information",
|
|
"failedConnects" : 1
|
|
},
|
|
"totalRequests" : 2,
|
|
"totalFailedConnects" : 2,
|
|
"totalEvents" : 0,
|
|
"lastError" : {
|
|
"errorNum" : 0
|
|
},
|
|
"time" : "2014-05-29T15:03:53Z"
|
|
},
|
|
"server" : {
|
|
"version" : "2.1.0",
|
|
"serverId" : "18804023088184"
|
|
},
|
|
"endpoint" : "tcp://127.0.0.1:8529",
|
|
"database" : "_system"
|
|
}
|
|
```
|
|
|
|
|
|
<!--
|
|
@anchor HttpReplicationApplierGetConfig
|
|
@copydetails triagens::arango::RestReplicationHandler::handleCommandApplierGetConfig
|
|
|
|
@CLEARPAGE
|
|
@anchor HttpReplicationApplierSetConfig
|
|
@copydetails triagens::arango::RestReplicationHandler::handleCommandApplierSetConfig
|
|
|
|
@CLEARPAGE
|
|
@anchor HttpReplicationApplierStart
|
|
@copydetails triagens::arango::RestReplicationHandler::handleCommandApplierStart
|
|
|
|
@CLEARPAGE
|
|
@anchor HttpReplicationApplierStop
|
|
@copydetails triagens::arango::RestReplicationHandler::handleCommandApplierStop
|
|
|
|
@CLEARPAGE
|
|
@anchor HttpReplicationApplierGetState
|
|
@copydetails triagens::arango::RestReplicationHandler::handleCommandApplierGetState
|
|
--> |