A newer version of this documentation is available.

View Latest

Perform an Immediate Merge

      +
      The Backup Service REST API allows an immediate merge to be performed, on existing backups within a specified repository.

      HTTP Methods and URIs

      POST /cluster/self/repository/active/<repository-id>/merge

      Description

      Triggers an immediate merge for the specified active repository: thus, the need to wait for a scheduled backup can be eliminated as required. The period of time for which backups should be merged must be specified as a JSON payload.

      Note that merges are supported for filesystem-based repositories only: they are not supported for cloud-based repositories. Therefore, an immediate merge cannot be triggered for a cloud-based repository.

      Curl Syntax

      curl -x POST http://<backup-node-ip-address-or-domain-name>:8097/cluster/self\
      /repository/active/<repository-id>/merge \
        -u <username>:<password>
        -d <merge-period-specification>

      The username and password must identify an administrator with the Full Admin role. The repository-id must be the name of an active repository on the cluster.

      The merge-period-specification must be a JSON document, containing the following:

      • The most recent day whose backups should be included in the merge.

      • The least recent day whose backups should be included in the merge.

      Each day is specified as an integer; a lower integer representing a more recent day than does a higher; with 0 representing the current day. The backups for all days that lie between the most and least recent specified are included in the merge.

      Syntactically, the merge-period-specification is as follows:

      {
        "offset_start": <integer-representing-most-recent-day>,
        "offset_end": <integer-representing-least-recent-day>
      }

      Responses

      If the call is successful, the merge-process is started, and 200 OK is returned, with an object that provides a task-id for the merge. For example: {"task_name":"MERGE-9d10fefc-b9be-4980-879b-c66c9101644b"}.

      If the specified repository cannot be located, 404 Object Not Found is returned, with an object such as the following: {"status":404,"msg":"repository `restR3epo does not exist"}`.

      If the call is improperly formatted, 400 Bad Request is returned; with an object such as the following: {"status":400,"msg":"invalid request body","extras":"invalid character '{' looking for beginning of object key string"}.

      If an internal error prevents successful execution, 500 Internal Server Error is returned, with an object containing a further error description.

      Failure to authenticate returns 401 Unauthorized. An incorrectly specified URI returns 404 Object Not Found.

      Example

      The following example triggers an immediate merge of all backups for the active repository restRepo, from the current day to two days ago:

      curl -v -X POST http://127.0.0.1:8097/api/v1/cluster/self/\
      repository/active/restRepo/merge \
      -u Administrator:password \
      -d '{"offset_start": 0,"offset_end": 2}'

      If execution is successful, an object such as the following is returned:

      {"task_name":"MERGE-759b7f20-acac-474d-8b9d-6fbbbaf7302d"}

      See Also

      An overview of the Backup Service is provided in Backup Service. A step-by-step guide to using Couchbase Web Console to configure and use the Backup Service is provided in Manage Backup and Restore. For information on scheduling merges by means of plans, see Create and Edit Plans.