Loading TOC...

POST /manage/v2/databases/{id|name}

Summary

This resource address can be used to clear the contents of the named database and to perform various configuration operations on the database. The database can be identified either by id or name.

URL Parameters
format The format of the posted data. Can be either html, json, or xml (default). This parameter is not meaningful with view=edit. This value overrides the Accept header if both are present.
Request Headers
Accept The expected MIME type of the response. If the format parameter is present, it takes precedence over the Accept header.
Content-type The MIME type of the data in the request body. Depending upon the value of the format parameter or Accept header, one of application/xml, application/json, or text/html.
Response Headers
Content-type The MIME type of the data in the response body. Depending upon the value of the format parameter or Accept header, one of application/xml, application/json, or text/html.

Response

Upon success, MarkLogic Server returns status code 202 (Accepted). If the payload is malformed, a status code of 400 (Bad Request) is returned. A status code of 401 (Unauthorized) is returned if the user does not have the necessary privileges.

Required Privileges

This operation requires one of the following:

Required Privileges

All operations require the manage-admin role, or the following privilege:

http://marklogic.com/xdmp/privileges/manage-admin

Usage Notes

The available database operations are summarized in the following list. The details on each operation follow.

Clear Database

The following operation clears the database.

The request body looks like:

JSON


     {
       "operation": "clear-database"
     }

XML


  <clear-database-operation xmlns="http://marklogic.com/manage">
    <operation>clear-database</operation>
  </clear-database-operation>

Backup Database

The following operation initiates backup on database. The operation and backup-dir properties are required. The incremental-dir, journal-archiving, journal-archive-path, and lag-limit properties are optional.

If forests are specified, they must be forests attached to this database. If no forests are specified, then all forests attached to this database will be backed up. If incremental is true, then an incremental backup is performed, otherwise a full backup is performed. It is an error to specify incremental-dir if incremental is false.

If include-replicas is true, then any replica forests are backed up, otherwise they are not backed up.

The request body looks like:

JSON


    {
      "operation": "backup-database",
      "forest": [
        "a",
        "b",
        "c"
      ],
      "backup-dir": "/path",
      "incremental": true,
      "incremental-dir": "/path/i",
      "journal-archiving": true,
      "journal-archive-path": "/path/j",
      "include-replicas": "true",
      "lag-limit": 30,
      "password": "yourpassword"
    }

XML


 <backup-database-operation xmlns="http://marklogic.com/manage">
  <operation>backup-database</operation>
  <forests>
    <forest>a</forest>
    <forest>b</forest>
    <forest>c</forest>
  </forests>
  <backup-dir>/path</backup-dir>
  <incremental>true</incremental>
  <incremental-dir>/path/i</incremental-dir>
  <journal-archiving>true</journal-archiving>
  <journal-archive-path>/path/j</journal-archive-path>
  <include-replicas>true</include-replicas>
  <lag-limit>30</lag-limit>
  <password>yourpassword</password>
 </backup-database-operation>

The response body looks like: 


  <database-backup xmlns="http://marklogic.com/manage">
    <job-id>13338009140041297636</job-id>
    <host-name>hpzbook-2908.marklogic.com</host-name>
  </database-backup>

Validate Database Backup

The following operation validates that the database can be backed up to the backup data directory. The operation and backup-dir properties are required. The incremental-dir, journal-archiving, journal-archive-path, and lag-limit properties are optional.

If forests are specified, they must be forests attached to this database. If no forests are specified, then all forests attached to this database will be validated for back up. If incremental is true, then an incremental backup is performed, otherwise a full backup is performed. It is an error to specify incremental-dir if incremental is false. If include-replicas is true, then replica forests are included in the validation, otherwise they are not included.

The request body looks like:

JSON


    {
      "operation": "backup-validate",
      "forest": [
        "a",
        "b",
        "c"
      ],
      "backup-dir": "/path",
      "incremental": true,
      "incremental-dir": "/path/i",
      "include-replicas": false,
      "journal-archiving": true,
      "journal-archive-path": "/path/j",
      "lag-limit": 30
    }

XML


 <backup-validate-operation xmlns="http://marklogic.com/manage">
  <operation>backup-validate</operation>
  <forests>
    <forest>a</forest>
    <forest>b</forest>
    <forest>c</forest>
  </forests>
  <backup-dir>/path</backup-dir>
  <incremental>true</incremental>
  <incremental-dir>/path/i</incremental-dir>
  <include-replicas>false</include-replicas>
  <journal-archiving>true</journal-archiving>
  <journal-archive-path>/path/j</journal-archive-path>
  <lag-limit>30</lag-limit>
 </backup-validate-operation>

Backup Status

The following operation checks the status of the outstanding backup job with the specified backup job ID. The operation and job-id properties are required. The host-id property is optional.

The request body looks like:

JSON


    {
      "operation": "backup-status",
      "job-id": "12345678910",
      "host-name": "my-host"
    }

XML


     <backup-status-operation xmlns="http://marklogic.com/manage">
       <operation>backup-status</operation>
       <job-id>12345678910</job-id>
       <host-name>my-host</host-name>
     </backup-status-operation>

The response body looks like: 


    {
      "job-id": "12345678910",
      "host-name": "my-host",
      "status": "in-progress"
    }

Backup Cancel

The following operation cancels in-progress backup job with the specified backup job ID. The operation and job-id properties are required.

The request body looks like:

JSON


    {
      "operation": "backup-cancel",
      "job-id": "12345678910"
    }

XML


        <backup-cancel-operation xmlns="http://marklogic.com/manage">
         <operation>backup-cancel</operation>
         <job-id>12345678910</job-id>
        </backup-cancel-operation>

The response body looks like: 


    {
      "job-id": "12345678910",
      "canceled": true
    }

Purge Old Backups

The following operation purges old backups from the specified directory. The operation, backup-dir, and keep-num-backups properties are required. The backup-dir property specifies the directory under which to look for backups. The keep-num-backups property specifies the maximum number of old backups to keep.

The request body looks like:

JSON


    {
      "operation": "backup-purge",
      "backup-dir": "/path/to/somewhere",
      "keep-num-backups": 3
    }

XML


    <backup-purge-operation xmlns="http://marklogic.com/manage">
      <operation>backup-purge</operation>
      <backup-dir>/path/to/somewhere</backup-dir>
      <keep-num-backups>3</keep-num-backups>
    </backup-purge-operation>

The response body looks like: 


    {
      "purged": true
    }

Restore Database

The following operation initiates an asynchronous restore of a database from the backup data directory. The operation and backup-dir properties are required. The incremental, incremental-dir, journal-archiving, journal-archive-path, and restore-to-time properties are optional.

If forests are specified, they must be forests attached to this database. If no forests are specified, then all forests attached to this database will be restored. If incremental is true, then an incremental restore is performed, otherwise a full restore is performed. It is an error to specify incremental-dir if incremental is false.

If include-replicas is true, then any replica forests are restored, otherwise they are not restored.

The request body looks like:

JSON


    {
      "operation": "restore-database",
      "forest": [
        "a",
        "b"
      ],
      "backup-dir": "/path",
      "incremental": true,
      "incremental-dir": "/path/i",
      "restore-to-time": "2014-03-14T15:00:00Z",
      "journal-archiving": true,
      "journal-archive-path": "/path/j",
      "include-replicas": "true",
      "password": "yourpassword"
    }

XML


	  <restore-database-operation xmlns="http://marklogic.com/manage">
       <operation>restore-database</operation>
       <forests>
        <forest>a</forest>
        <forest>b</forest>
       </forests>
       <backup-dir>/path</backup-dir>
       <incremental>true</incremental>
       <incremental-dir>/path/i</incremental-dir>
       <restore-to-time>2014-03-14T15:00:00Z</restore-to-time>
       <journal-archiving>true</journal-archiving>
       <journal-archive-path>/path/j</journal-archive-path>
       <include-replicas>true</include-replicas>
       <password>yourpassword</password>
      </restore-database-operation>

Validate Database Restore

The following operation validates that the database can be restored from the backup data directory. The operation and backup-dir properties are required. The incremental, incremental-dir, journal-archiving, journal-archive-path, and restore-to-time properties are optional.

If forests are specified, they must be forests attached to this database. If no forests are specified, then all forests attached to this database will be validated for restore. If incremental is true, then an incremental restore is validated, otherwise a full restore is validated. It is an error to specify incremental-dir if incremental is false.

The request body looks like:

JSON


    {
      "operation": "restore-validate",
      "forest": [
        "a",
        "b",
        "c"
      ],
      "backup-dir": "/path",
      "incremental": true,
      "incremental-dir": "/path/i",
      "restore-to-time": "2014-03-14T15:00:00Z",
      "journal-archiving": true,
      "journal-archive-path": "/path/j",
      "password": "yourpassword" 
    }

XML


	   <restore-validate-operation xmlns="http://marklogic.com/manage">
        <operation>restore-validate</operation>
        <forests>
         <forest>a</forest>
         <forest>b</forest>
         <forest>c</forest>
        </forests>
        <backup-dir>/path</backup-dir>
        <incremental>true</incremental>
        <incremental-dir>/path/i</incremental-dir>
        <restore-to-time>2014-03-14T15:00:00Z</restore-to-time>
        <journal-archiving>true</journal-archiving>
        <journal-archive-path>/path/j</journal-archive-path>
        <password>yourpassword</password>
       </restore-validate-operation>

The response body is a summary of the restore set.

Restore Status

The following operation checks the status of the outstanding restore job with the specified restore job ID. The operation and job-id properties are required. The host-id property is optional.

The request body looks like:

JSON


    {
      "operation": "restore-status",
      "job-id": "12345678910"
    }

XML


	  <restore-status-operation xmlns="http://marklogic.com/manage">
        <operation>restore-status</operation>
        <job-id>12345678910</job-id>
       </restore-status-operation>

The response body is a description of the job status.

Cancel Database Restore

The following operation cancels in-progress restore job with the specified restore job ID. The operation and job-id properties are required.

The request body looks like:

JSON


    {
      "operation": "restore-cancel"
      "job-id": "12345678910"
    }

XML


     <restore-cancel-operation xmlns="http://marklogic.com/manage">
       <operation>restore-cancel</operation>
       <job-id>12345678910</job-id>
     </restore-cancel-operation>

The response body looks like: 


    {
      "job-id": "12345678910",
      "canceled": true
    }

Merge Database

The following operation initiates a merge on the database.

The request body looks like:

JSON


    {
      "operation": "merge-database",
    }

XML


	  <merge-database-operation xmlns="http://marklogic.com/manage">
	  <operation>merge-database</operation>
	  </merge-database-operation>

There is no response body. Check the status view to find out if the merge is still in progress.

Reindex Database

The following operation initiates a reindex on the database.

The request body looks like:

JSON


    {
      "operation": "reindex-database",
    }

XML


	  <reindex-database-operation xmlns="http://marklogic.com/manage">
	  <operation>reindex-database</operation>
	  </reindex-database-operation>

There is no response body.

Check the status view to find out if the indexing is still in progress.

Set Database Defaults

The following operation sets the defaults on the database.

The request body looks like:

JSON


    {
      "operation": "set-database-defaults",
    }

XML


	<set-database-defaults-operation xmlns="http://marklogic.com/manage">
	<operation>set-database-defaults</operation>
	</set-database-defaults-operation>

There is no response body.

Add Foreign Replica to Database Replication Configuration

The following operation adds a foreign replica to the database replication configuration for the database. The overwrite-replica property is false by default, which specifies not to overwrite replicas with existing data. If true, then replicas with existing data are overwritten. The foreign-database-name specifies the name of the foreign database to be used as the replica and foreign-cluster-name is the name of the foreign cluster that holds the replica database. For details on configuring database replication, see Configuring Database Replication in the Database Replication Guide. For an example use of this operation, see Setting the Master and Replica Databases in the Scripting Administrative Tasks Guide.

The request body looks like:

JSON


    {
      "operation": "add-foreign-replicas",
      "foreign-replica": [
        {
          "foreign-cluster-name": "localhost-cluster",
          "foreign-database-name": "Documents",
          "connect-forests-by-name": true,
          "lag-limit": 23,
	  "enabled": true,
	  "queue-size":10
        }
      ]
    }

XML


	  <add-foreign-replicas-operation xmlns="http://marklogic.com/manage">
        <operation>add-foreign-replicas</operation>
        <foreign-replicas>
         <foreign-replica>
          <foreign-cluster-name>localhost-cluster</foreign-cluster-name>
          <foreign-database-name>Documents</foreign-database-name>
          <connect-forests-by-name>true</connect-forests-by-name>
          <lag-limit>23</lag-limit>
          <enabled>true</enabled>
          <queue-size>10</queue-size>
         </foreign-replica>
        </foreign-replicas>
       </add-foreign-replicas-operation>

Remove Foreign Replica from Database Replication Configuration

The following operation removes a foreign replica from the database replication configuration for the database. The foreign-database-name property contains the name of the foreign database. For details on configuring database replication, see Configuring Database Replication in the Database Replication Guide.

The request body looks like:

JSON


    {
      "operation": "remove-foreign-replicas",
      "foreign-database-name": [
        "Documents"
      ]
    }

XML


	  <remove-foreign-replicas-operation xmlns="http://marklogic.com/manage">
        <operation>remove-foreign-replicas</operation>
        <foreign-database-names>
         <foreign-database-name>Documents</foreign-database-name>
        </foreign-database-names>
       </remove-foreign-replicas-operation>

Add Foreign Master to Database Replication Configuration

The following operation adds a foreign master to the database replication configuration for the database. The foreign-database-name is the name of the foreign database and foreign-cluster-name is the name of the foreign cluster that contains the foreign database. Specify true for connect-forests-by-name if the forest names are the same on the Master and Replica clusters, otherwise specify false. For details on configuring database replication, see Configuring Database Replication in the Database Replication Guide. For an example use of this operation, see Setting the Master and Replica Databases in the Scripting Administrative Tasks Guide.

The request body looks like:

JSON


    {
      "operation": "set-foreign-master",
      "foreign-master": {
        "foreign-cluster-name": "replica",
        "foreign-database-name": "Documents",
        "connect-forests-by-name": true
      }
    }

XML


	  <set-foreign-master-operation xmlns="http://marklogic.com/manage">
       <operation>set-foreign-master</operation>
       <foreign-master>
        <foreign-cluster-name>replica</foreign-cluster-name>
        <foreign-database-name>Documents</foreign-database-name>
        <connect-forests-by-name>true</connect-forests-by-name>
       </foreign-master>
      </set-foreign-master-operation>

Remove Foreign Master from Database Replication Configuration

The following operation removes a foreign master from the database replication configuration for the database. For details on configuring database replication, see Configuring Database Replication in the Database Replication Guide.

The request body looks like:

JSON


    {
      "operation": "remove-foreign-master"
    }

XML


	  <remove-foreign-master-operation xmlns="http://marklogic.com/manage">
       <operation>remove-foreign-master</operation>
      </remove-foreign-master-operation>

Roll back forests to minimum non-blocking timestamp

The following operation rolls back database forests to minimum non blocking timestamp.

The request body looks like:

JSON


    {
      "operation": "rollback-forests-to-nonblocking-timestamp"
    }

XML


      <rollback-forests-to-nonblocking-timestamp-operation xmlns="http://marklogic.com/manage">
       <operation>rollback-forests-to-nonblocking-timestamp</operation>
      </rollback-forests-to-nonblocking-timestamp-operation>

Validate Replica Indexes

The following operation validates index data for the database replica forests. repair properties specify whether to perform repair on the replica if index data discrepancy is found.

The request body looks like:

JSON


    {
      "operation": "validate-replica-indexes"
    }

XML


     <validate-replica-indexes-operation xmlns="http://marklogic.com/manage">
      <operation>validate-replica-indexes</operation>
     </validate-replica-indexes-operation>

Suspend Database Replication

The following operation suspends database replication.

The request body looks like:

JSON


    {
      "operation": "suspend-database-replication"
    }

XML


    <suspend-database-replication-operation xmlns="http://marklogic.com/manage">
     <operation>suspend-database-replication</operation>
    </suspend-database-replication-operation>

Resume Database Replication

The following operation resumes database replication. Use force-bulk-replication property to specify whether to force bulk replication.

The request body looks like:

JSON


    {
      "operation": "resume-database-replication",
      "force-bulk-replication": true
    }

XML


    <resume-database-replication-operation xmlns="http://marklogic.com/manage">
     <operation>resume-database-replication</operation>
     <force-bulk-replication>true</force-bulk-replication>
    </resume-database-replication-operation>

Example


curl -X POST  --anyauth -u admin:admin --header "Content-Type:application/json" \
-d '{"operation":"clear-database"}' http://localhost:8002/manage/v2/databases/MyNewDatabase

==>  Clears the contents of the "MyNewDatabase" database. 
    

curl -X POST  --anyauth -u admin:admin --header "Content-Type:application/xml" -d '<clear-database-operation xmlns="http://marklogic.com/manage"><operation>clear-database</operation></clear-database-operation>' http://localhost:8002/manage/v2/databases/MyNewDatabase

==>  Clears the contents of the "MyNewDatabase" database.

Example


curl -X POST  --anyauth -u admin:admin --header "Content-Type:application/json" \
-d '{"operation": "remove-foreign-master"}' \
http://localhost:8002/manage/v2/databases/Documents

==>  Removes the Foreign Master from the "Documents" Database 
     Replication Configuration.

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.