Database requests

Get all databases

GET /v1/bdbs

Get all databases in the cluster.

Permissions

Request

Example HTTP request

GET /v1/bdbs?fields=uid,name

Headers

Query parameters

Response

The response body contains a JSON array with all databases, represented as BDB objects.

Body

[
    {
        "uid": 1,
        "name": "name of database #1",
        "// additional fields..."
    },
    {
        "uid": 2,
        "name": "name of database #2",
        "// additional fields..."
    }
]

Status codes

Example requests

cURL

$ curl -k -X GET -u "[username]:[password]" \
       -H "accept: application/json" \
       https://[host][:port]/v1/bdbs?fields=uid,name

Python

import requests
import json

url = "https://[host][:port]/v1/bdbs?fields=uid,name"
auth = ("[username]", "[password]")

headers = {
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, auth=auth, headers=headers)

print(response.text)

Get a database

GET /v1/bdbs/{int: uid}

Get a single database.

Permissions

Request

Example HTTP request

GET /bdbs/1

Headers

URL parameters

Query parameters

Response

Returns a BDB object.

Example JSON body

{
    "uid": 1,
    "name": "name of database #1",
    "// additional fields..."
}

Status codes

Update database configuration

PUT /v1/bdbs/{int: uid}

Update the configuration of an active database.

If called with the dry_run URL query string, the function will validate the BDB object against the existing database, but will not invoke the state machine that will update it.

This is the basic version of the update request. See Update database and perform action to send an update request with an additional action.

To track this request’s progress, poll the /actions/<action_uid> endpoint with the action_uid returned in the response body.

Permissions

Request

Example HTTP request

PUT /bdbs/1

Headers

Query parameters

URL parameters

Body

Include a BDB object with updated fields in the request body.

Example JSON body

{
    "replication": true,
    "data_persistence": "aof"
}

The above request attempts to modify a database configuration to enable in-memory data replication and append-only file data persistence.

Response

Returns the updated BDB object.

Example JSON body

{
    "uid": 1,
    "replication": true,
    "data_persistence": "aof",
    "// additional fields..."
}

Status codes

Error codes

When errors are reported, the server may return a JSON object with error_code and message field that provide additional information. The following are possible error_code values:

Update database and perform action

PUT /v1/bdbs/{int: uid}/{action}

Update the configuration of an active database and perform an additional action.

If called with the dry_run URL query string, the function will validate the BDB object against the existing database, but will not invoke the state machine that will update it.

Permissions

Request

Example HTTP request

PUT /bdbs/1/reset_admin_pass

The above request resets the admin password after updating the database.

Headers

URL parameters

Query parameters

Body

Include a BDB object with updated fields in the request body.

Example JSON body

{
    "replication": true,
    "data_persistence": "aof"
}

The above request attempts to modify a database configuration to enable in-memory data replication and append-only file data persistence.

Response

If the request succeeds, the response body returns the updated BDB object. If an error occurs, the response body may include an error code and message with more details.

Status codes

Error codes

When errors are reported, the server may return a JSON object with error_code and message field that provide additional information. The following are possible error_code values:

Create database v1

POST /v1/bdbs

Create a new database in the cluster.

The request must contain a single JSON BDB object with the configuration parameters for the new database.

The following parameters are required to create the database:

If passed with the dry_run URL query string, the function will validate the BDB object, but will not invoke the state machine that will create it.

To track this request’s progress, poll the /actions/<action_uid> endpoint with the action_uid returned in the response body.

The cluster will use default configuration for any missing database field. The cluster creates a database UID if it is missing.

Permissions

Request

Example HTTP request

POST /bdbs

Headers

Query parameters

Body

Include a BDB object in the request body.

The following parameters are required to create the database:

The uid of the database is auto-assigned by the cluster because it was not explicitly listed in this request. If you specify the database ID (uid), then you must specify the database ID for every subsequent database and make sure that the database ID does not conflict with an existing database. If you do not specify the database ID, then the it is automatically assigned in sequential order.

Defaults are used for all other configuration parameters.

Example JSON body

{
    "name": "test-database",
    "type": "redis",
    "memory_size": 1073741824
}

The above request is an attempt to create a Redis database with a user-specified name and a memory limit of 1GB.

Response

The response includes the newly created BDB object.

Example JSON body

{
    "uid": 1,
    "name": "test-database",
    "type": "redis",
    "memory_size": 1073741824,
    "// additional fields..."
}

Error codes

When errors are reported, the server may return a JSON object with error_code and message field that provide additional information. The following are possible error_code values:

Status codes

Create database v2

POST /v2/bdbs

Create a new database in the cluster. See POST /v1/bdbs for more information.

The database’s configuration should be under the “bdb” field.

This endpoint allows you to specify a recovery_plan to recover a database. If you include a recovery_plan within the request body, the database will be loaded from the persistence files according to the recovery plan. The recovery plan must match the number of shards requested for the database.

The persistence files must exist in the locations specified by the recovery plan. The persistence files must belong to a database with the same shard settings as the one being created (slot range distribution and shard_key_regex); otherwise, the operation will fail or yield unpredictable results.

If you create a database with a shards_blueprint and a recovery plan, the shard placement may not fully follow the shards_blueprint.

Request

Example HTTP request

POST /v2/bdbs

Headers

Query parameters

Body

Include a JSON object that contains a BDB object and an optional recovery_plan object in the request body.

Example JSON body

{
    "bdb": {
        "name": "test-database",
        "type": "redis",
        "memory_size": 1073741824,
        "shards_count": 1
    },
    "recovery_plan": {
        "data_files": [
            {
                "shard_slots": "0-16383",
                "node_uid": "1",
                "filename": "redis-4.rdb"
            }
        ]
    }
}

Response

The response includes the newly created BDB object.

Example JSON body

{
    "uid": 1,
    "name": "test-database",
    "type": "redis",
    "memory_size": 1073741824,
    "shards_count": 1,
    "// additional fields..."
}

Delete database

DELETE /v1/bdbs/{int: uid}

Delete an active database.

Permissions

Request

Example HTTP request

DELETE /bdbs/1

Headers

URL parameters

Response

Returns a status code that indicates the database deletion success or failure.

Status codes