数据库请求

数据库请求

Redis 企业软件
方法 路径 描述
获取 /v1/bdbs 获取所有数据库
获取 /v1/bdbs/{uid} 获取单个数据库
放 /v1/bdbs/{uid} 更新数据库配置
放 /v1/bdbs/{uid}/{action} 更新数据库配置并执行其他作
发布 /v1/bdbs 创建新数据库
发布 /v2/bdbs 创建新数据库
删除 /v1/bdbs/{uid} 删除数据库

获取所有数据库

GET /v1/bdbs

Get all databases in the cluster.

Permissions

Permission name Roles
view_all_bdbs_info admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager

Request

Example HTTP request

GET /v1/bdbs?fields=uid,name

Headers

Key Value
Host The domain name or IP of the cluster
Accept application/json

Query parameters

Field Type Description
fields string Comma-separated list of field names to return (by default all fields are returned). (optional)

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

Code Description
200 OK No error

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

Permission name Roles
view_bdb_info admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager

Request

Example HTTP request

GET /v1/bdbs/1

Headers

Key Value
Host The domain name or IP of the cluster
Accept application/json

URL parameters

Field Type Description
uid integer The unique ID of the database requested.

Query parameters

Field Type Description
fields string Comma-separated list of field names to return (by default all fields are returned). (optional)

Response

Returns a BDB object.

Example JSON body

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

Status codes

Code Description
200 OK No error
404 Not Found Database UID does not exist

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

Permission name Roles
update_bdb admin
cluster_member
db_member

Request

Example HTTP request

PUT /v1/bdbs/1

Headers

Key Value
Host The domain name or IP of the cluster
Accept application/json
Content-type application/json

Query parameters

Field Type Description
dry_run Validate the new BDB object but don't apply the update.

URL parameters

Field Type Description
uid integer The unique ID of the database for which update is requested.

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

Code Description
200 OK The request is accepted and is being processed. The database state will be 'active-change-pending' until the request has been fully processed.
404 Not Found Attempting to change a nonexistent database.
406 Not Acceptable The requested configuration is invalid.
409 Conflict Attempting to change a database while it is busy with another configuration change. In this context, this is a temporary condition, and the request should be reattempted later.

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:

Code Description
rack_awareness_violation • Non rack-aware cluster.
• Not enough nodes in unique racks.
invalid_certificate SSL client certificate is missing or malformed.
certificate_expired SSL client certificate has expired.
duplicated_certs An SSL client certificate appears more than once.
insufficient_resources Shards count exceeds shards limit per bdb.
not_supported_action_on_crdt reset_admin_pass action is not allowed on CRDT enabled BDB.
name_violation CRDT database name cannot be changed.
bad_shards_blueprint The sharding blueprint is broken or doesn’t fit the BDB.
replication_violation CRDT database must use replication.
eviction_policy_violation LFU eviction policy is not supported on bdb version<4
replication_node_violation Not enough nodes for replication.
replication_size_violation Database limit too small for replication.
invalid_oss_cluster_configuration BDB configuration does not meet the requirements for OSS cluster mode
missing_backup_interval BDB backup is enabled but backup interval is missing.
crdt_sharding_violation CRDB created without sharding cannot be changed to use sharding
invalid_proxy_policy Invalid proxy_policy value.
invalid_bdb_tags Tag objects with the same key parameter were passed.
unsupported_module_capabilities Not all modules configured for the database support the capabilities needed for the database configuration.
redis_acl_unsupported Redis ACL is not supported for this database.

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

Permission name Roles
update_bdb_with_action admin
cluster_member
db_member

Request

Example HTTP request

PUT /v1/bdbs/1/reset_admin_pass

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

Headers

Key Value
Host The domain name or IP of the cluster
Accept application/json
Content-type application/json

URL parameters

Field Type Description
uid integer The unique ID of the database to update.
action string Additional action to perform. Currently supported actions are: flush, reset_admin_pass.

Query parameters

Field Type Description
dry_run Validate the new BDB object but don't apply the update.

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.

Note:
To change the shard hashing policy, you must flush all keys from the database.

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

Code Description
200 OK The request is accepted and is being processed. The database state will be 'active-change-pending' until the request has been fully processed.
403 Forbidden redislabs license expired.
404 Not Found Attempting to change a nonexistent database.
406 Not Acceptable The requested configuration is invalid.
409 Conflict Attempting to change a database while it is busy with another configuration change. In this context, this is a temporary condition, and the request should be reattempted later.

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:

Code Description
rack_awareness_violation • Non rack-aware cluster.
• Not enough nodes in unique racks.
invalid_certificate SSL client certificate is missing or malformed.
certificate_expired SSL client certificate has expired.
duplicated_certs An SSL client certificate appears more than once.
insufficient_resources Shards count exceeds shards limit per bdb.
not_supported_action_on_crdt reset_admin_pass action is not allowed on CRDT enabled BDB.
name_violation CRDT database name cannot be changed.
bad_shards_blueprint The sharding blueprint is broken or doesn’t fit the BDB.
replication_violation CRDT database must use replication.
eviction_policy_violation LFU eviction policy is not supported on bdb version<4
replication_node_violation Not enough nodes for replication.
replication_size_violation Database limit too small for replication.
invalid_oss_cluster_configuration BDB configuration does not meet the requirements for OSS cluster mode
missing_backup_interval BDB backup is enabled but backup interval is missing.
crdt_sharding_violation CRDB created without sharding cannot be changed to use sharding
invalid_proxy_policy Invalid proxy_policy value.
invalid_bdb_tags Tag objects with the same key parameter were passed.
unsupported_module_capabilities Not all modules configured for the database support the capabilities needed for the database configuration.
redis_acl_unsupported Redis ACL is not supported for this database.

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:

Parameter Type/Value Description
name string Name of the new database
memory_size integer Size of the database, in bytes

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

Permission name Roles
create_bdb admin
cluster_member
db_member

Request

Example HTTP request

POST /v1/bdbs

Headers

Key Value
Host The domain name or IP of the cluster
Accept application/json
Content-type application/json

Query parameters

Field Type Description
dry_run Validate the new BDB object but don't create the database.

Body

Include a BDB object in the request body.

The following parameters are required to create the database:

Paramter Type/Value Description
name string Name of the new database
memory_size integer Size of the database, in bytes

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:

Code Description
uid_exists The specified database UID is already in use.
missing_db_name DB name is a required property.
missing_memory_size Memory Size is a required property.
missing_module Modules missing from the cluster.
port_unavailable The specified database port is reserved or already in use.
invalid_sharding Invalid sharding configuration was specified.
bad_shards_blueprint The sharding blueprint is broken.
not_rack_aware Cluster is not rack-aware and a rack-aware database was requested.
invalid_version An invalid database version was requested.
busy The request failed because another request is being processed at the same time on the same database.
invalid_data_persistence Invalid data persistence configuration.
invalid_proxy_policy Invalid proxy_policy value.
invalid_sasl_credentials SASL credentials are missing or invalid.
invalid_replication Not enough nodes to perform replication.
insufficient_resources Not enough resources in cluster to host the database.
rack_awareness_violation • Rack awareness violation.
• Not enough nodes in unique racks.
invalid_certificate SSL client certificate is missing or malformed.
certificate_expired SSL client certificate has expired.
duplicated_certs An SSL client certificate appears more than once.
replication_violation CRDT database must use replication.
eviction_policy_violation LFU eviction policy is not supported on bdb version<4
invalid_oss_cluster_configuration BDB configuration does not meet the requirements for OSS cluster mode
memcached_cannot_use_modules Cannot create a memcached database with modules.
missing_backup_interval BDB backup is enabled but backup interval is missing.
wrong_cluster_state_id The given CLUSTER-STATE-ID does not match the current one
invalid_bdb_tags Tag objects with the same key parameter were passed.
unsupported_module_capabilities Not all modules configured for the database support the capabilities needed for the database configuration.
redis_acl_unsupported Redis ACL is not supported for this database.

Status codes

Code Description
403 Forbidden redislabs license expired.
409 Conflict Database with the same UID already exists.
406 Not Acceptable Invalid configuration parameters provided.
200 OK Success, database is being created.

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

Key Value
Host The domain name or IP of the cluster
Accept application/json
Content-type application/json

Query parameters

Field Type Description
dry_run Validate the new BDB object but don't create the database.

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

Permission name Roles
delete_bdb admin
cluster_member
db_member

Request

Example HTTP request

DELETE /v1/bdbs/1

Headers

Key Value
Host The domain name or IP of the cluster
Accept application/json

URL parameters

Field Type Description
uid integer The unique ID of the database to delete.

Response

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

Status codes

Code Description
200 OK The request is accepted and is being processed. The database state will be 'delete-pending' until the request has been fully processed.
403 Forbidden Attempting to delete an internal database.
404 Not Found Attempting to delete a nonexistent database.
409 Conflict Either the database is not in 'active' state and cannot be deleted, or it is busy with another configuration change. In the second case, this is a temporary condition, and the request should be re-attempted later.
RATE THIS PAGE
Back to top ↑