Management Guide

contents

/mgmt/databases

/mgmt/databases — Manage database resources

Synopsis

/mgmt/databases

/mgmt/databases/{database-id}

/mgmt/databases/{database-id}/start

/mgmt/databases/{database-id}/startreplica

/mgmt/databases/{database-id}/recover

/mgmt/databases/{database-id}/stop

/mgmt/databases/{database-id}/pause

/mgmt/databases/{database-id}/resume

/mgmt/databases/{database-id}/snapshot

Methods

GET

Fetches information about the current databases defined within the Enterprise Manager. A call without a database ID returns a list of the known databases. A call with a database ID returns information about that specific database — including the IDs for the deployment, catalog, and server(s).

POST

Adds a database to the Enterprise Manager. You must provide valid IDs for an existing deployment resource, catalog, and one or more servers as part of the request.

PUT

Replaces the database specified by ID in the URL with the database properties defined in the body of the request. It is always best to specify all of the properties when performing a replace, even if only one or two properties are changing. (For example, when changing the name of the database.) Any properties not specified are replaced with the default value, not the current value.

The easiest way to perform an update is to fetch the current properties by doing a GET on the database ID, changing those properties that need changing, and then doing a PUT with the updated JSON structure, ensuring all unchanged properties retain their current value.

START

Starts the database specified by ID in the URL, creating a new, empty database. You specify "start" as part of the URL and send the request using the PUT method.

Optionally, you can add the argument "?pause=1" to the start method URL to start the database in admin mode.

STARTREPLICA

Starts the database specified by ID in the URL, creating a new replica (read-only) database. You specify "startreplica" as part of the URL and send the request using the PUT method. See the Using VoltDB manual for more information about replica databases and the database replication process.

Optionally, you can add the argument "?pause=1" to the start method URL to start the database in admin mode.

RECOVER

Starts the database specified by ID in the URL and recovers the database contents from the command logs of the last session. You specify "recover" as part of the URL and send the request using the PUT method.

Optionally, you can add the argument "?pause=1" to the recover method URL to start the database in admin mode.

STOP

Stops the database specified by ID in the URL. You must specify "stop" as part of the URL and send the request using the PUT method.

PAUSE

Pauses the database specified by ID in the URL. That is, initiates admin mode on the specified cluster. You must specify "pause" as part of the URL and send the request using the PUT method.

RESUME

Resumes, or unpauses, the database specified by ID in the URL, returning the cluster to normal operation. You must specify "resume" as part of the URL and send the request using the PUT method.

SNAPSHOT

Initiates a manual snapshot for the database specified by ID in the URL. Once the snapshot is complete, the snapshot files are copied to the management server and added as a snapshot resource, also available through the REST interface. You must specify "snapshot" as part of the URL and send the request using the PUT method.

DELETE

Deletes the specified database from the Enterprise Manager. You must specify a valid database ID in the URL. The database must be stopped before it can be deleted.

Arguments

To create or update a database using the POST and PUT methods, you must provide information about the database as arguments in the body of the request. The arguments must be encoded as a JSON string. The structure of the database object is as follows:

AttributeTypeDescription
name*TextThe name of the database
statusText (read-only)Current state of the database (running, stopped, or paused)
descriptionTextDescription of the database
maxheapIntegerThe max heap size (in megabytes) to use when starting the server(s)
portIntegerThe client port
internalportIntegerThe internal server port
jmxportIntegerThe JMX port
logportIntegerThe log4j port
zookeeperportIntegerThe zookeeper port
catalog*IntegerID of the catalog to use
deployment*IntegerID of the deployment attributes to use
collectsnapshotsBooleanWhether to copy snapshots to the management server or not
serversListCollection of servers assigned to the database. On input, the collection is specified as an array of "server":{server-ID} pairs. On output, each server object includes read-only attributes specifying the name, IP address, and status of the server.
snapshotsList (read-only)Collection of snapshots that the management server has copied. The collection is an array of "snapshot":{snapshot-ID} pairs.

*Required

Examples

The following example uses curl to create a new database from existing catalog and deployment resources:

curl --data '{"Database":{"name":"Cars",   
                          "catalog":"16777261",
                          "deployment":"33554476"}}' \
     http://voltdbmgr:9000/man/api/1.0/mgmt/databases

The next example uses GET and PUT to update a database and assign an existing server resource. The script uses GET to retrieve the full database object, then uses sed to replace the Servers property before using PUT to update the database with the modified JSON string.

JSON=$( curl http://voltdbmgr:9000/man/api/1.0/mgmt/databases/83886132 )
JSON=$( echo $JSON | \
        sed 's/"Servers":\[\]/"Servers":\[{"server":67108911}\]/g' )
curl -X PUT --data "$JSON" \
http://voltdbmgr:9000/man/api/1.0/mgmt/databases/83886132
contents