title: Revamp database requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [PUT](#put-bdbs-actions-revamp) | `/v1/bdbs/{uid}/actions/revamp` | Update database configuration and optimize shard placement |

title: Revamp database {#put-bdbs-actions-revamp}

text:
[code example]

Updates the topology-related configurations of an active database and optimizes the shard placement for the new configuration.

#### Required permissions

| Permission name | Roles |
|-----------------|-------|
| [update_bdb_with_action]() | admin
cluster_member
db_member |

title: Request {#put-request}

text:
You can include the following parameters in the request JSON body to update their values:

| Field | Type/Value | Description |
|-------|------------|-------------|
| avoid_nodes | array of strings | Cluster node UIDs to avoid when placing the database's shards and binding its endpoints. |
| bigstore_ram_size | integer | Memory size of bigstore RAM part. |
| memory_size | integer (default: 0) | Database memory limit in bytes. 0 is unlimited. |
| replication | boolean | If `true`, enable in-memory database replication mode. |
| shards_count | integer, (range: 1-512) (default: 1) | Number of database server-side shards. |
| shards_placement | "dense"
"sparse" | Control the density of shards. Values:
**dense**: Shards reside on as few nodes as possible.
**sparse**: Shards reside on as many nodes as possible. |

#### Example HTTP request

[code example]

Dry-run example:

[code example]

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database to update. |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| dry_run | boolean | If true, returns a blueprint of the database update without actually changing the database. Default is false. |
| pause_persistence | boolean | If true, pause the persistence during the update. Default is false. |

title: Response {#put-response}

text:
- If `dry_run` is `false`, returns an `action_uid`. You can track the action's progress with a [`GET /v1/actions/<action_uid>`]() request.

- If `dry_run` is `true`, returns a blueprint of the database update.

#### Example response

If `dry_run` is `false`:

[code example]

If `dry_run` is `true`:

[code example]

#### Status codes {#put-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | When `dry_run` is false: The request is accepted and is being processed. The database state will be `active-change-pending` until the request has been fully processed. <br />When `dry_run` is true: No error. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to perform an action on a nonexistent database. |
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | The requested configuration is invalid. |
| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-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 re-attempted later. |

code: PUT /v1/bdbs/{int: uid}/actions/revamp

section_id: revamp-database-put-bdbs-actions-revamp

code:
PUT /v1/bdbs/1/actions/revamp
{
    "replication": true,
    "shards_count": 12
}

code:
PUT /v1/bdbs/1/actions/revamp?dry_run=true
{
  "replication": true,
  "shards_count": 12
}


title: Stop database traffic requests

summary: REST API requests to stop traffic for a database

page_type: content

title: Overview

role: overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [POST](#post-bdbs-actions-stop-traffic) | `/v1/bdbs/{uid}/actions/stop_traffic` | Stop database traffic |

title: Stop database traffic {#post-bdbs-actions-stop-traffic}

role: content

text:
[code example]

Stop handling traffic for the database.

Use this action to stop read and write traffic on a database. To resume traffic afterward, use the [`resume_traffic`]() action.

#### Required permissions

| Permission name | Roles |
|-----------------|-------|
| [update_bdb_with_action]() | admin
cluster_member
db_member |

title: Request {#post-request}

text:
#### Example HTTP request

[code example]

#### URL parameters

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

title: Response {#post-response}

role: returns

text:
Returns a JSON object with an `action_uid`. You can track the action's progress with a [`GET /v1/actions/<action_uid>`]() request.

#### Status codes {#post-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-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](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to perform an action on a nonexistent database. |
| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Attempting to change a database while it is busy with another configuration change. This is a temporary condition, and the request should be reattempted later. |

code: POST /v1/bdbs/1/actions/stop_traffic

section_id: request-post-request


title: Database alerts requests

summary: Database alert requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-bdbs-alerts) | `/v1/bdbs/alerts` | Get all alert states for all databases |
| [GET](#get-bdbs-alerts) | `/v1/bdbs/alerts/{uid}` | Get all alert states for a specific database |
| [GET](#get-bdbs-alert) | `/v1/bdbs/alerts/{uid}/{alert}` | Get a specific database alert state |
| [POST](#post-bdbs-alerts) | `/v1/bdbs/alerts/{uid}` | Update a database’s alerts configuration |

title: Get all database alerts {#get-all-bdbs-alerts}

text:
GET /v1/bdbs/alerts

Get all alert states for all databases.

#### Required permissions

| Permission name |
|-----------------|
| [view_all_bdbs_alerts]() |

title: Request {#get-all-request}

text:
#### Example HTTP request

	GET /v1/bdbs/alerts

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

title: Response {#get-all-response}

text:
Returns a hash of alert UIDs and the [alerts]() states for each database.

#### Example JSON body

[code example]

title: Status codes {#get-all-status-codes}

title: Get database alerts {#get-bdbs-alerts}

text:
GET /v1/bdbs/alerts/{int: uid}

Get all alert states for a database.

#### Required permissions

| Permission name |
|-----------------|
| [view_bdb_alerts]() |

title: Request {#get-request-alerts}

text:
#### Example HTTP request

	GET /v1/bdbs/alerts/1

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

title: Response {#get-response-alerts}

text:
Returns a hash of [alert objects]() and their states.

#### Example JSON body

[code example]

title: Status codes {#get-status-codes-alerts}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified bdb does not exist |

title: Get database alert {#get-bdbs-alert}

text:
GET /v1/bdbs/alerts/{int: uid}/{alert}

Get a database alert state.

#### Required permissions

| Permission name |
|-----------------|
| [view_bdb_alerts]() |

title: Request {#get-request}

text:
#### Example HTTP request

	GET /v1/bdbs/alerts/1/bdb_size

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database |
| alert | string | The alert name |

title: Response {#get-response}

text:
Returns an [alert object]().

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad request |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified alert or bdb does not exist |

title: Update database alert {#post-bdbs-alerts}

text:
POST /v1/bdbs/alerts/{int: uid}

Updates a database's alerts configuration.

#### Required permissions

| Permission name |
|-----------------|
| [update_bdb_alerts]() |

title: Request {#post-request}

text:
If passed with the dry_run URL query string, the function will validate the alert thresholds, but not commit them.

#### Example HTTP request

	POST /v1/bdbs/alerts/1

#### Example JSON body

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | Database ID |
| dry_run | string | Validate the alert thresholds but do not apply them |

#### Request body

The request must contain a single JSON object with one or many database [alert objects]().

title: Response {#post-response}

text: The response includes the updated database [alerts]().

title: Status codes {#post-status-codes}

text:
| Code | Description |
|------|-------------|
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified database was not found. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Invalid configuration parameters provided. |
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, database alerts updated. |

code:
{
    "1": {
        "bdb_size": {
            "enabled": true,
            "state": true,
            "threshold": "80",
            "change_time": "2014-08-29T11:19:49Z",
            "severity": "WARNING",
            "change_value": {
                "state": true,
                "threshold": "80",
                "memory_util": 81.2
            }
        },
        "..."
    },
    "..."
}

section_id: response-get-all-response

code:
{
    "bdb_size": {
        "enabled": true,
        "state": true,
        "threshold": "80",
        "severity": "WARNING",
        "change_time": "2014-08-29T11:19:49Z",
        "change_value": {
            "state": true,
            "threshold": "80",
            "memory_util": 81.2
        }
    },
    "..."
}

section_id: response-get-response-alerts

severity: WARNING

section_id: response-get-response


title: Database availability requests

summary: REST API requests to check database availability

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-db-endpoint-availability) | `/v1/local/bdbs/{uid}/endpoint/availability` | Verifies local database endpoint availability |
| [GET](#get-db-availability) | `/v1/bdbs/{uid}/availability` | Verifies database availability |

title: Get database endpoint availability {#get-db-endpoint-availability}

text:
[code example]

Verifies the local database endpoint is available. This request does not redirect to the primary node.

title: Permissions

role: security

text:
| Permission name | Roles |
|-----------------|-------|
| [view_bdb_info]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-endpoint-request}

text:
#### Example HTTP requests

To check database endpoint availability without any additional checks:

[code example]

To perform a lag-aware database endpoint availability check using the cluster's default lag tolerance threshold:

[code example]

To perform a lag-aware database endpoint availability check and override the cluster's default lag tolerance threshold:

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

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

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| extend_check | list of comma-separated strings | List of additional availability checks to perform (optional)
Values:
**lag**: Enables lag-aware checks to assess replication health. Determines if a replica is sufficiently synced with the primary for failover/failback scenarios. |
| availability_lag_tolerance_ms | integer | Overrides the cluster's default lag tolerance threshold when using `extend_check=lag`. Recommended value: 100 milliseconds. |

title: Response {#get-endpoint-response}

text:
Returns the status code `200 OK` if the local database endpoint is available.

If the local database endpoint is unavailable, returns an error status code and a JSON object that contains `error_code` and `description` fields.

title: Error codes {#get-endpoint-error-codes}

role: errors

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

| Code | Description |
|------|-------------|
| no_quorum | Master healthcheck failed (no quorum in the cluster) |
| db_not_found | Database does not exist in the cluster |
| bdb_endpoint_unavailable | Local database endpoint is not available |

title: Status codes {#get-endpoint-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Database endpoint is available. |
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Invalid schema. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Database not found. |
| [503 Service Unavailable](https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable) | Database endpoint is unavailable. |

title: Get database availability {#get-db-availability}

text:
[code example]

Gets the availability status of a database.

- If the OSS Cluster API is enabled, verifies all endpoints for this database are available.

- Otherwise, verifies the database has at least one available endpoint.

title: Permissions

title: Request {#get-db-request}

text:
#### Example HTTP requests

To check database availability without any additional checks:

[code example]

To perform a lag-aware database availability check using the cluster's default lag tolerance threshold:

[code example]

To perform a lag-aware database availability check and override the cluster's default lag tolerance threshold:

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

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

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| extend_check | list of comma-separated strings | List of additional availability checks to perform (optional)
Values:
**lag**: Enables lag-aware checks to assess replication health. Determines if a replica is sufficiently synced with the primary for failover/failback scenarios. |
| availability_lag_tolerance_ms | integer | Overrides the cluster's default lag tolerance threshold when using `extend_check=lag`. Recommended value: 100 milliseconds. |

title: Response {#get-db-response}

text:
Returns the status code `200 OK` if the database is available.

If the database is unavailable, returns an error status code and a JSON object that contains `error_code` and `description` fields.

title: Error codes {#get-db-error-codes}

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

| Code | Description |
|------|-------------|
| no_quorum | Master healthcheck failed (no quorum in the cluster) |
| db_not_found | Database does not exist in the cluster |
| bdb_unavailable | Database is not available |

title: Status codes {#get-db-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Database is available. |
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Invalid schema. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Database not found. |
| [503 Service Unavailable](https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable) | Database is unavailable or doesn't have quorum. |

section_id: request-get-endpoint-request

code: GET /v1/bdbs/{uid}/availability

code: GET /v1/bdbs/1/availability

section_id: request-get-db-request


title: Database CRDT sources alerts requests

summary: Conflict-free replicated data type (CRDT) source alert requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-bdbs-crdt-sources-alerts) | `/v1/bdbs/crdt_sources/alerts` | Get all CRDT sources alert states for all CRDB databases |
| [GET](#get-bdbs-crdt-sources-alerts) | `/v1/bdbs/crdt_sources/alerts/{uid}` | Get all CRDT sources alert states for a database |
| [GET](#get-bdbs-crdt-source-all-alerts) | `/v1/bdbs/crdt_sources/alerts/{uid}/{crdt_src_id}` | Get all alert states for a CRDT source |
| [GET](#get-bdbs-crdt-source-alert) | `/v1/bdbs/crdt_sources/alerts/{uid}/{crdt_src_id}/{alert}` | Get a database alert state |

title: Get all CRDB CRDT source alert states {#get-all-bdbs-crdt-sources-alerts}

text:
GET /v1/bdbs/crdt_sources/alerts

Get all alert states for all CRDT sources of all CRDBs.

#### Required permissions

| Permission name |
|-----------------|
| [view_all_bdbs_alerts]() |

title: Request {#get-all-request}

text:
#### Example HTTP request

	GET /v1/bdbs/crdt_sources/alerts

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

title: Response {#get-all-response}

text:
Returns a hash of alert UIDs and the [alerts states]() for each local BDB of CRDB.

#### Example JSON body

[code example]

title: Status codes {#get-all-status-codes}

title: Get all BDB CRDT sources alert states {#get-bdbs-crdt-sources-alerts}

text:
GET /v1/bdbs/crdt_sources/alerts/{int: uid}

Get all alert states for all crdt sources for a specific local bdb of a CRDB.

#### Required permissions

| Permission name |
|-----------------|
| [view_bdb_alerts]() |

title: Request {#get-request-all-crdt-alerts}

text:
#### Example HTTP request

	GET /v1/bdbs/crdt_sources/alerts/1

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database |

title: Response {#get-response-all-crdt-alerts}

text:
Returns a hash of [alert objects]() and their states.

#### Example JSON body

[code example]

title: Status codes {#get-status-codes-all-crdt-alerts}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified bdb does not exist |

title: Get all CRDT source alert states {#get-bdbs-crdt-source-all-alerts}

text:
GET /v1/bdbs/crdt_sources/alerts/{int: uid}/{int: crdt_src_id}

Get all alert states for specific crdt source for a specific local BDB
of a CRDB.

#### Required permissions

| Permission name |
|-----------------|
| [view_bdb_alerts]() |

title: Request {#get-request-crdt-alerts}

text:
#### Example HTTP request

	GET /v1/bdbs/crdt_sources/alerts/1/2

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database |
| crdt_src_id | integer | The ID of the crdt source in this BDB |

title: Response {#get-response-crdt-alerts}

title: Status codes {#get-status-codes-crdt-alerts}

title: Get database alert state {#get-bdbs-crdt-source-alert}

text:
GET /v1/bdbs/crdt_sources/alerts/{int: uid}/{int: crdt_src_id}/{alert}

Get a BDB alert state.

#### Required permissions

| Permission name |
|-----------------|
| [view_bdb_alerts]() |

title: Request {#get-request-alert}

text:
#### Example HTTP request

	GET /v1/bdbs/crdt_sources/alerts/1/2/crdt_src_syncer_connection_error

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database |
| crdt_src_id | integer | The ID of the crdt source in this BDB |
| alert | string | The alert name |

title: Response {#get-response-alert}

text:
Returns an [alert object]().

#### Example JSON body

[code example]

title: Status codes {#get-status-codes-alert}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad request |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified alert or bdb does not exist |

code:
{
    "1": {
        "crdt_src_syncer_connection_error": {
            "enabled": true,
            "state": true,
            "threshold": "80",
            "change_time": "2014-08-29T11:19:49Z",
            "severity": "WARNING",
            "change_value": {
                "state": true,
                "threshold": "80",
                "memory_util": 81.2
            }
        },
        "..."
    },
    "..."
}

code:
{
    "crdt_src_syncer_connection_error": {
        "enabled": true,
        "state": true,
        "threshold": "80",
        "severity": "WARNING",
        "change_time": "2014-08-29T11:19:49Z",
        "change_value": {
            "state": true,
            "threshold": "80",
            "memory_util": 81.2
        }
    },
    "..."
}

section_id: response-get-response-all-crdt-alerts

section_id: response-get-response-crdt-alerts

section_id: response-get-response-alert


title: Database debug info requests

summary: Documents the Redis Software REST API /bdbs/debuginfo requests.

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-debuginfo-bdb) | `/v1/bdbs/debuginfo` | Get debug info from all databases |
| [GET](#get-debuginfo-bdb) | `/v1/bdbs/{bdb_uid}/debuginfo` | Get debug info from a specific database |

title: Get debug info from all databases {#get-all-debuginfo-bdb}

text:
GET /v1/bdbs/debuginfo

Downloads a tar file that contains debug info from all databases.

#### Required permissions

| Permission name |
|-----------------|
| [view_debugging_info]() |

title: Request {#get-all-request}

text:
#### Example HTTP request

	GET /v1/bdbs/debuginfo

title: Response {#get-all-response}

text:
Downloads the debug info in a tar file called `filename.tar.gz`. Extract the files from the tar file to access the debug info.

#### Response headers

| Key | Value | Description |
|-----|-------|-------------|
| Content-Type | application/x-gzip | Media type of request/response body |
| Content-Length | 653350 | Length of the response body in octets |
| Content-Disposition | attachment; filename=debuginfo.tar.gz | Display response in browser

title: Status codes {#get-all-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success. |
| [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Failed to get debug info. |

title: Get database debug info {#get-debuginfo-bdb}

text:
GET /v1/bdbs/{int: bdb_uid}/debuginfo

Downloads a tar file that contains debug info from the database specified by `bdb_uid`.

#### Required permissions

| Permission name |
|-----------------|
| [view_debugging_info]() |

title: Request {#get-request}

text:
#### Example HTTP request

	GET /v1/bdbs/1/debuginfo

title: Response {#get-response}

title: Status codes {#get-status-codes}


title: Database requests

summary: Database requests

summary: Database action requests

title: Database actions requests

summary: Database alert requests

title: Database alerts requests

title: Database availability requests

title: Database CRDT sources alerts requests

title: Database debug info requests

summary: Redis module requests

title: Database modules requests

summary: Database password requests

title: Database passwords requests

summary: Active-Active peer instance statistics requests

title: CRDB peer stats requests

summary: Replica source alert requests

title: Database replica sources alerts requests

summary: REST API requests for database shards

title: Database shards requests

summary: Database statistics requests

title: Database stats requests

summary: Syncer source statistics requests

title: Database syncer source stats requests

summary: Syncer state requests

title: Syncer state requests

summary: Database upgrade requests

title: Database upgrade requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-bdbs) | `/v1/bdbs` | Get all databases |
| [GET](#get-bdbs) | `/v1/bdbs/{uid}` | Get a single database |
| [PUT](#put-bdbs) | `/v1/bdbs/{uid}` | Update database configuration |
| [PUT](#put-bdbs-action) | `/v1/bdbs/{uid}/{action}` | Update database configuration and perform additional action |
| [POST](#post-bdbs-v1) | `/v1/bdbs` | Create a new database |
| [POST](#post-bdbs-v2) | `/v2/bdbs` | Create a new database |
| [DELETE](#delete-bdbs) | `/v1/bdbs/{uid}` | Delete a database |

title: Get all databases {#get-all-bdbs}

text:
[code example]

Get all databases in the cluster.

title: Permissions

text:
| Permission name | Roles   |
|-----------------|---------|
| [view_all_bdbs_info]() |  admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-all-request}

text:
#### Example HTTP requests

The following request returns the unique IDs and names of all databases:

[code example]

The following request returns all fields for the databases, including configuration fields for modules like search, probabilistic, and timeseries:

[code example]

#### 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) |
| extended | boolean | If true, includes configuration fields for modules, such as search, timeseries, and probabilistic, in the response. If the `extended` query parameter is not included in the request, module configuration fields do not appear in the response. (optional) |

title: Response {#get-all-response}

text:
The response body contains a JSON array with all databases, represented as [BDB objects]().

#### Body

[code example]

#### Status codes {#get-all-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |

title: Example requests

role: example

text:
#### cURL

[code example]

#### Python

[code example]

title: Get a database {#get-bdbs}

text:
[code example]

Get a single database.

#### Permissions

| Permission name | Roles |
|-----------------|-------|
| [view_bdb_info]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-request}

text:
#### Example HTTP requests

The following request returns all fields for the specified database, except for module configuration fields:

[code example]

The following request returns all fields for the specified database, including configuration fields for modules like search, probabilistic, and timeseries:

[code example]

#### 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) |
| extended | boolean | If true, includes configuration fields for modules, such as search, timeseries, and probabilistic, in the response. If the `extended` query parameter is not included in the request, module configuration fields do not appear in the response. (optional) |

title: Response {#get-response}

text:
Returns a [BDB object]().

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Database UID does not exist |

title: Update database configuration {#put-bdbs}

text:
[code example]
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](#put-bdbs-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.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [update_bdb]() | admin
cluster_member
db_member |

title: Request {#put-request}

text:
#### Example HTTP request

[code example]

#### 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

[code example]

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

title: Response {#put-response}

text:
Returns the updated [BDB object]().

#### Example JSON body

[code example]

title: Status codes {#put-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | 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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to change a nonexistent database. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | The requested configuration is invalid. |
| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | 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 {#put-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.<br />• 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. |

title: Update database and perform action {#put-bdbs-action}

text:
[code example]
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 |

title: Request {#put-request-action}

text:
#### Example HTTP request

[code example]
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

[code example]

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

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

title: Response {#put-response-action}

text:
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 {#put-status-codes-action}

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | 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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | redislabs license expired. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to change a nonexistent database. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | The requested configuration is invalid. |
| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | 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 {#put-error-codes-action}

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.<br />• 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. |

title: Create database v1 {#post-bdbs-v1}

text:
[code example]
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.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [create_bdb]() | admin
cluster_member
db_member |

title: Request {#post-request-v1}

text:
#### Example HTTP request

[code example]

#### 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

[code example]

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

title: Response {#post-response-v1}

text:
The response includes the newly created [BDB object]().

#### Example JSON body

[code example]

#### Error codes {#post-error-codes-v1}

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.<br/>• 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 {#post-status-codes-v1}

| Code | Description |
|------|-------------|
| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | redislabs license expired. |
| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Database with the same UID already exists. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Invalid configuration parameters provided. |
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, database is being created. |

title: Create database v2 {#post-bdbs-v2}

text:
[code example]
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.

title: Request {#post-request-v2}

text:
#### Example HTTP request

[code example]

#### 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

[code example]

title: Response {#post-response-v2}

title: Delete database {#delete-bdbs}

text:
[code example]
Delete an active database.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [delete_bdb]() | admin
cluster_member
db_member |

title: Request {#delete-request}

text:
#### Example HTTP request

[code example]
#### 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. |

title: Response {#delete-response}

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

title: Status codes {#delete-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. The database state will be 'delete-pending' until the request has been fully processed. |
| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | Attempting to delete an internal database. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to delete a nonexistent database. |
| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | 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. |

code: GET /v1/bdbs

section_id: get-all-databases-get-all-bdbs

code: GET /v1/bdbs?fields=uid,name

section_id: request-get-all-request

code: GET /v1/bdbs?extended=true

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

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

section_id: example-requests

code:
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)

code: GET /v1/bdbs/{int: uid}

section_id: get-a-database-get-bdbs

code: GET /v1/bdbs/1

section_id: request-get-request

code: GET /v1/bdbs/1?extended=true

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

section_id: update-database-configuration-put-bdbs

code: PUT /v1/bdbs/1

section_id: request-put-request

data_persistence: aof

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

section_id: response-put-response

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

code: PUT /v1/bdbs/1/reset_admin_pass

section_id: request-put-request-action

code: POST /v1/bdbs

test-database

type: redis

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

code: POST /v2/bdbs

role: master

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

code: DELETE /v1/bdbs/{int: uid}

section_id: delete-database-delete-bdbs

code: DELETE /v1/bdbs/1

section_id: request-delete-request


title: Database modules config requests

summary: Configure Redis module requests

title: Overview

text:
This REST API path is deprecated as of Redis Software version 7.4. Use [`PUT /v2/bdbs/<uid>`]() instead.

| Method | Path | Description |
|--------|------|-------------|
| [POST](#post-bdb-modules-config) | `/v1/bdbs/{uid}/modules/config` | Configure module |

title: Configure module {#post-bdb-modules-config}

role: configuration

text:
POST /v1/bdbs/{string: uid}/modules/config

Use the module runtime configuration command (if defined) to configure new arguments for the module.

#### Required permissions

| Permission name |
|-----------------|
| [edit_bdb_module]() |

title: Request {#post-request}

text:
#### Example HTTP request

	POST /v1/bdbs/1/modules/config

#### Example JSON body

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Request body

| Field | Type | Description |
|-------|------|-------------|
| modules | list of JSON objects | List of modules (module_name) and their new configuration settings (module_args) |
| module_name | `search`
`ReJSON`
`graph`
`timeseries`
`bf` | Module's name |
| module_args | string | Module command line arguments (pattern does not allow special characters &,<,>,") |

title: Response {#post-response}

text: Returns a status code. If an error occurs, the response body may include an error code and message with more details.

title: Error codes {#post-error-codes}

text:
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 |
|------|-------------|
| db_not_exist | Database with given UID doesn't exist in cluster |
| missing_field | "module_name" or "module_args" are not defined in request |
| invalid_schema | JSON object received is not a dict object |
| param_error | "module_args" parameter was not parsed properly |
| module_not_exist | Module with given "module_name" does not exist for the database |

title: Status codes {#post-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, module updated on bdb. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb not found. |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing configuration parameters. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Module does not support runtime configuration of arguments. |

module_name: search

module_args: MINPREFIX 3 MAXEXPANSIONS 1000

section_id: request-post-request


title: Database modules requests

summary: Redis module requests

summary: Configure Redis module requests

title: Database modules config requests

summary: Upgrade Redis module requests

title: Database upgrade modules requests

title: Configure module

text:
| Method | Path | Description |
|--------|------|-------------|
| [POST]() | `/v1/bdbs/{uid}/modules/config` | Configure module |

title: Upgrade module

text:
| Method | Path | Description |
|--------|------|-------------|
| [POST]() | `/v1/bdbs/{uid}/modules/upgrade` | Upgrade module |


title: Database upgrade modules requests

summary: Upgrade Redis module requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [POST](#post-bdb-modules-upgrade) | `/v1/bdbs/{uid}/modules/upgrade` | Upgrade module |

title: Upgrade module {#post-bdb-modules-upgrade}

text:
POST /v1/bdbs/{string: uid}/modules/upgrade

Upgrades module version on a specific BDB.

#### Required permissions

| Permission name |
|-----------------|
| [edit_bdb_module]() |

title: Request {#post-request}

text:
#### Example HTTP request

	POST /v1/bdbs/1/modules/upgrade

#### Example JSON body

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Request body

| Field | Type | Description |
|-------|------|-------------|
| modules | list | List of dicts representing the modules that will be upgraded. Each dict must include:

 • **current_module**: uid of a module to upgrade

 • **new_module**: UID of the module we want to upgrade to

 • **new_module_args**: args list for the new module |
| preserve_roles | boolean | Preserve shards’ master/replica roles (optional) |
| may_discard_data | boolean | Discard data in a non-replicated non-persistent bdb (optional) |

title: Response {#post-response}

text:
Returns the upgraded [module object]().

#### Example JSON body

[code example]

title: Error codes {#post-error-codes}

text:
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 |
|------|-------------|
| missing_module | Module is not present in cluster.|
| module_downgrade_unsupported | Module downgrade is not allowed.|
| redis_incompatible_version | Module min_redis_version is bigger than the current Redis version.|
| redis_pack_incompatible_version | Module min_redis_pack_version is bigger than the current Redis Software version.|
| unsupported_module_capabilities | New version of module does support all the capabilities needed for the database configuration|

title: Status codes {#post-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, module updated on bdb. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb or node not found. |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing configuration parameters. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | The requested configuration is invalid. |

code:
{
     "modules": [
         {"module_name": "ReJson",
         "current_semantic_version": "2.2.1",
         "new_module": "aa3648d79bd4082d414587c42ea0b234"}
     ],
     "// Optional fields to fine-tune restart and failover behavior:",
     "preserve_roles": true,
     "may_discard_data": false
}

code:
{
    "uid": 1,
    "name": "name of database #1",
    "module_id": "aa3648d79bd4082d414587c42ea0b234",
    "module_name": "ReJson",
    "semantic_version": "2.2.2"
    "// additional fields..."
}

section_id: response-post-response


title: Database passwords requests

summary: Database password requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [PUT](#put-bdbs-password) | `/v1/bdbs/{uid}/passwords` | Update database password |
| [POST](#post-bdbs-password) | `/v1/bdbs/{uid}/passwords` | Add database password |
| [DELETE](#delete-bdbs-password) | `/v1/bdbs/{uid}/passwords` | Delete database password |

title: Update database password {#put-bdbs-password}

text:
PUT /v1/bdbs/{int: uid}/passwords

Set a single password for the bdb's default user (i.e., for `AUTH` `<password>` authentications).

#### Required permissions

| Permission name |
|-----------------|
| [update_bdb]() |

title: Request {#put-request}

text:
#### Example HTTP request

	PUT /v1/bdbs/1/passwords

#### Example JSON body

[code example]

The above request resets the password of the bdb to ‘new password’.

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database to update the password. |

#### Request body

| Field | Type | Description |
|-------|------|-------------|
| password | string | New password |

title: Response {#put-response}

text: Returns a status code that indicates password update success or failure.

title: Status codes {#put-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The password was changed. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | A nonexistent database. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Invalid configuration parameters provided. |

title: Add database password {#post-bdbs-password}

text:
POST /v1/bdbs/{int: uid}/passwords

Add a password to the bdb's default user (i.e., for `AUTH` `<password>` authentications).

#### Required permissions

| Permission name |
|-----------------|
| [update_bdb]() |

title: Request {#post-request}

text:
#### Example HTTP request

	POST /v1/bdbs/1/passwords

#### Example JSON body

[code example]

The above request adds a password to the bdb.

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database to add password. |

#### Request body

| Field | Type | Description |
|-------|------|-------------|
| password | string | Password to add |

title: Response {#post-response}

text: Returns a status code that indicates password creation success or failure.

title: Status codes {#post-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The password was added. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | A nonexistent database. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Invalid configuration parameters provided. |

title: Delete database password {#delete-bdbs-password}

text:
DELETE /v1/bdbs/{int: uid}/passwords

Delete a password from the bdb's default user (i.e., for `AUTH` `<password>` authentications).

#### Required permissions

| Permission name |
|-----------------|
| [update_bdb]() |

title: Request {#delete-request}

text:
#### Example HTTP request

	DELETE /v1/bdbs/1/passwords

#### Example JSON body

[code example]

The above request deletes a password from the bdb.

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

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

#### Request body

| Field | Type | Description |
|-------|------|-------------|
| password | string | Password to delete |

title: Response {#delete-response}

text: Returns a status code that indicates password deletion success or failure.

title: Status codes {#delete-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The password was deleted. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | A nonexistent database. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Invalid configuration parameters provided. |

password: new password

password: password to add

password: password to delete


title: CRDB peer stats requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-bdbs-peer_stats) | `/v1/bdbs/{bdb_uid}/peer_stats` | Get stats for all CRDB peer instances |
| [GET](#get-bdbs-peer_stats) | `/v1/bdbs/{bdb_uid}/peer_stats/{uid}` | Get stats for a specific CRDB peer instance |

title: Get all CRDB peer stats {#get-all-bdbs-peer_stats}

text:
[code example]

Get statistics for all peer instances of a local CRDB instance.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [view_bdb_stats]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-all-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| bdb_uid | integer | The unique ID of the local CRDB instance. |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| interval | string | Time interval for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) |
| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |
| etime | ISO_8601 | End time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |

title: Response {#get-all-response}

text:
Returns [statistics]() for all CRDB peer instances.

#### Example JSON body

[code example]

#### Status codes {#get-all-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Database does not exist. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Database is not a CRDB. |

title: Get CRDB peer stats {#get-bdbs-peer_stats}

text:
[code example]

Get statistics for a specific CRDB peer instance.

title: Permissions

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| bdb_uid | integer | The unique ID of the local CRDB instance. |
| uid | integer | The peer instance uid, as specified in the CRDB instance list. |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| interval | string | Time interval for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) |
| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |
| etime | ISO_8601 | End time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |

title: Response {#get-response}

text:
Returns [statistics]() for a specific CRDB peer instance.

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Database or peer does not exist. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Database is not a CRDB. |

code: GET /v1/bdbs/{bdb_uid}/peer_stats

code: GET /v1/bdbs/1/peer_stats?interval=5min

section_id: response-get-all-response

section_id: get-crdb-peer-stats-get-bdbs-peer-stats

section_id: response-get-response


summary: Replica source alert requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-bdbs-replica-sources-alerts) | `/v1/bdbs/replica_sources/alerts` | Get all replica sources alert states for all BDBs |
| [GET](#get-bdbs-replica-sources-alerts) | `/v1/bdbs/replica_sources/alerts/{uid}` | Get all replica sources alert states for a BDB |
| [GET](#get-bdbs-replica_source-all-alerts) | `/v1/bdbs/replica_sources/alerts/{uid}/{replica_src_id}` | Get all alert states for a replica source |
| [GET](#get-bdbs-replica-source-alert) | `/v1/bdbs/replica_sources/alerts/{uid}/{replica_src_id}/{alert}` | Get a replica source alert state |

title: Get all DBs replica sources alert states {#get-all-bdbs-replica-sources-alerts}

text:
GET /v1/bdbs/replica_sources/alerts

Get all alert states for all replica sources of all BDBs.

#### Required permissions

| Permission name |
|-----------------|
| [view_all_bdbs_alerts]() |

title: Request {#get-all-request}

text:
#### Example HTTP request

	GET /v1/bdbs/replica_sources/alerts

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

title: Response {#get-all-response}

text:
Returns a hash of alert UIDs and the alerts states for each BDB.

See [REST API alerts overview]() for a description of the alert state object.

#### Example JSON body

[code example]

title: Status codes {#get-all-status-codes}

title: Get DB replica source alert states {#get-bdbs-replica-sources-alerts}

text:
GET /v1/bdbs/replica_sources/alerts/{int: uid}

Get all alert states for all replica sources of a specific bdb.

#### Required permissions

| Permission name |
|-----------------|
| [view_bdb_alerts]() |

title: Request {#get-request-all-replica-alerts}

text:
#### Example HTTP request

	GET /v1/bdbs/replica_sources/alerts/1

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database |

title: Response {#get-response-all-replica-alerts}

text:
Returns a hash of [alert objects]() and their states.

#### Example JSON body

[code example]

title: Status codes {#get-status-codes-all-replica-alerts}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified bdb does not exist |

title: Get replica source alert states {#get-bdbs-replica_source-all-alerts}

text:
GET /v1/bdbs/replica_sources/alerts/{int: uid}/{int: replica_src_id}

Get all alert states for a specific replica source of a bdb.

#### Required permissions

| Permission name |
|-----------------|
| [view_bdb_alerts]() |

title: Request {#get-request-replica-alerts}

text:
#### Example HTTP request

	GET /v1/bdbs/replica_sources/alerts/1/2

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database |
| replica_src_id | integer | The ID of the replica source in this BDB |

title: Response {#get-response-replica-alerts}

title: Status codes {#get-status-codes-replica-alerts}

title: Get replica source alert state {#get-bdbs-replica-source-alert}

text:
GET /v1/bdbs/replica_sources/alerts/{int: uid}/{int: replica_src_id}/{alert}

Get a replica source alert state of a specific bdb.

#### Required permissions

| Permission name |
|-----------------|
| [view_bdb_alerts]() |

title: Request {#get-request-alert}

text:
#### Example HTTP request

	GET /v1/bdbs/replica_sources/alerts/1/2/replica_src_syncer_connection_error

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database |
| replica_src_id | integer | The ID of the replica source in this BDB |
| alert | string | The alert name |

title: Response {#get-response-alert}

text:
Returns an [alert state object]().

#### Example JSON body

[code example]

title: Status codes {#get-status-codes-alert}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad request |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified alert or bdb does not exist |

code:
{
    "1": {
        "replica_src_syncer_connection_error": {
            "enabled": true,
            "state": true,
            "threshold": "80",
            "change_time": "2014-08-29T11:19:49Z",
            "severity": "WARNING",
            "change_value": {
                "state": true,
                "threshold": "80",
                "memory_util": 81.2
            }
        },
        "..."
    },
    "..."
}

code:
{
    "replica_src_syncer_connection_error": {
        "enabled": true,
        "state": true,
        "threshold": "80",
        "severity": "WARNING",
        "change_time": "2014-08-29T11:19:49Z",
        "change_value": {
            "state": true,
            "threshold": "80",
            "memory_util": 81.2
        }
    },
    "..."
}

section_id: response-get-response-replica-alerts

section_id: response-get-response-alert


title: Database shards requests

summary: REST API requests for database shards

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-bdb-shards) | `/v1/bdbs/{bdb_uid}/shards` | Get the status of a database's shards |

title: Get database shards {#get-bdb-shards}

text:
GET /v1/bdbs/{int: bdb_uid}/shards

Gets the status for all shards that belong to the specified database.

title: Request {#get-request}

text:
#### Example HTTP request

	GET /v1/bdbs/1/shards?extra_info_keys=used_memory_rss&extra_info_keys=connected_clients

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| bdb_uid | integer | The unique ID of the database. |

title: Response {#get-response}

text:
The response body contains a JSON array with all shards, represented as [shard objects]().

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | bdb uid does not exist. |

code:
[
    {
        "uid": "1",
		"role": "master",
		"assigned_slots": "0-8191",
        "bdb_uid": 1,
        "detailed_status": "ok",
        "loading": {
            "status": "idle"
        },
        "node_uid": "1",
        "redis_info": {
			"connected_clients": 14,
            "used_memory_rss": 12460032
        },
        "report_timestamp": "2024-09-13T15:28:10Z",
        "status": "active"
    },
    {
        "uid": 2,
        "role": "slave",
        // additional fields...
    }
]


title: Database stats requests

summary: Database statistics requests

summary: Most recent database statistics requests

title: Latest database stats requests

title: Overview

text:
The v1 statistics REST API endpoints are deprecated as of Redis Software version 7.22. Use the [metrics stream engine for monitoring v2]() instead for real-time monitoring and metrics collection.

| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-bdbs-stats) | `/v1/bdbs/stats` | Get stats for all databases |
| [GET](#get-bdbs-stats) | `/v1/bdbs/stats/{uid}` | Get stats for a specific database |

title: Get all database stats {#get-all-bdbs-stats}

text:
[code example]

Get statistics for all databases.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [view_all_bdb_stats]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-all-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| interval | string | Time interval for for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) |
| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |
| etime | ISO_8601 | End time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |

title: Response {#get-all-response}

text:
Returns [statistics]() for all databases.

#### Example JSON body

[code example]

#### Status codes {#get-all-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | No bdbs exist |

title: Example requests

text:
#### cURL

[code example]

#### Python

[code example]

title: Get database stats {#get-bdbs-stats}

text:
[code example]

Get statistics for a specific database.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [view_bdb_stats]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the BDB requested. |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| interval | string | Time interval for for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) |
| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |
| etime | ISO_8601 | End time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |

title: Response {#get-response}

text:
Returns [statistics]() for a specific database.

#### Example JSON body

[code example]

#### Status codes {#get-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb does not exist |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | bdb isn't currently active |
| [503 Service Unavailable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4) | bdb is in recovery state |

code: GET /v1/bdbs/stats

section_id: request-get-all-request

code:
$ curl -k -u "[username]:[password]" -X GET
        https://[host][:port]/v1/bdbs/stats?interval=1hour

code:
import requests

url = "https://[host][:port]/v1/bdbs/stats?interval=1hour"
auth = ("[username]", "[password]")

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

print(response.text)

code: GET /v1/bdbs/stats/{int: uid}

section_id: get-database-stats-get-bdbs-stats


title: Latest database stats requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-bdbs-stats-last) | `/v1/bdbs/stats/last` | Get most recent stats for all databases |
| [GET](#get-bdbs-stats-last) | `/v1/bdbs/stats/last/{uid}` | Get most recent stats for a specific database |

title: Get latest stats for all databases {#get-all-bdbs-stats-last}

text:
[code example]

Get the most recent statistics for all databases.

#### Required permissions

| Permission name | Roles |
|-----------------|-------|
| [view_all_bdb_stats]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-all-request}

text:
#### Example HTTP request

1. Without metrics filter (returns all metrics by default)
    [code example]

2. With metrics filter
    [code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| metrics | string | Comma-separated list of metric names for which we want statistics (default is all). (optional) |

title: Response {#get-all-response}

text:
Returns [statistics]() for all databases.

#### Example JSON body

1. Without metrics filter (returns all metrics by default)
    [code example]

2. With metrics filter
    [code example]

title: Status codes {#get-all-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | No bdbs exist |

title: Get latest database stats {#get-bdbs-stats-last}

text:
[code example]

Get the most recent statistics for a specific database.

#### Permissions

| Permission name | Roles |
|-----------------|-------|
| [view_bdb_stats]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the requested BDB. |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| metrics | string | Comma-separated list of metric names for which we want statistics (default is all). (optional) |

title: Response {#get-response}

text:
Returns the most recent [statistics]() for a specific database.

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb does not exist |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | bdb isn't currently active |
| [503 Service Unavailable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4) | bdb is in recovery state |

code: GET /v1/bdbs/stats/last

code: GET /v1/bdbs/stats/last/{int: uid}


title: Database syncer source stats requests

summary: Syncer source statistics requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-bdbs-sync_source_stats) | `/v1/bdbs/{bdb_uid}/sync_source_stats` | Get stats for all syncer sources |
| [GET](#get-bdbs-sync_source_stats) | `/v1/bdbs/{bdb_uid}/sync_source_stats/{uid}` | Get stats for a specific syncer instance |

title: Get all syncer source stats {#get-all-bdbs-sync_source_stats}

text:
[code example]

Get stats for all syncer sources of a local database.

title: Permissions

title: Request {#get-all-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| bdb_uid | integer | The unique ID of the local database. |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| interval | string | Time interval for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) |
| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |
| etime | ISO_8601 | Optional end time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |

title: Response {#get-all-response}

text:
Returns [statistics]() for all syncer sources.

#### Example JSON body

[code example]

title: Status codes {#get-all-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Database does not exist. |

title: Get syncer instance stats {#get-bdbs-sync_source_stats}

text:
[code example]

Get stats for a specific syncer (Replica Of) instance.

#### Permissions

| Permission name | Roles |
|-----------------|-------|
| [view_bdb_stats]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| bdb_uid | integer | The unique ID of the local database. |
| uid | integer | The sync_source uid. |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| interval | string | Time interval for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) |
| stime | ISO_8601 | Optional start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |
| etime | ISO_8601 | Optional end time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |

title: Response {#get-response}

text:
Returns [statistics]() for a specific syncer instance.

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Database or sync_source do not exist. |


title: CRDT syncer state requests

summary: CRDT syncer state requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-syncer-state) | `/v1/bdbs/{uid}/syncer_state/crdt` |  Get a CRDB's syncer state |

title: Get CRDB syncer state {#get-syncer-state}

text:
[code example]

Get a CRDB's syncer state as JSON.

title: Permissions

text:
| Permission name | Roles   |
|-----------------|---------|
| [view_bdb_info]() |  admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager|

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### 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. |

title: Response {#get-response}

text:
Returns a JSON object that represents the syncer state.

#### Example JSON body

[code example]

#### Status codes {#get-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | OK |
| [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Syncer state key does not exist |
| [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Internal error |
| [503 Service Unavailable](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4) | Redis connection error, service unavailable |

section_id: get-crdb-syncer-state-get-syncer-state

code: GET /v1/bdbs/1/syncer_state/crdt


title: Syncer state requests

summary: Syncer state requests

summary: CRDT syncer state requests

title: CRDT syncer state requests

summary: Replica syncer state requests

title: Replica syncer state requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-syncer-state) | `/v1/bdbs/{uid}/syncer_state` | Get a CRDB's syncer state |

title: Get syncer state {#get-syncer-state}

text:
[code example]

Get a CRDB's syncer state as JSON.

This endpoint is deprecated as of Redis Software version 7.2.4 and will be removed in a future release. Use [`/v1/bdbs/<uid>/syncer_state/crdt`]() instead.

title: Permissions

text:
| Permission name | Roles   |
|-----------------|---------|
| [view_bdb_info]() |  admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-request}

title: Response {#get-response}

code: GET /v1/bdbs/{int: uid}/syncer_state

section_id: get-syncer-state-get-syncer-state

code: GET /v1/bdbs/1/syncer_state

section_id: request-get-request


title: Replica syncer state requests

summary: Replica syncer state requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-syncer-state) | `/v1/bdbs/{uid}/syncer_state/replica` | Get a CRDB replica's syncer state |

title: Get replica syncer state {#get-syncer-state}

text:
[code example]

Get a CRDB replica's syncer state as JSON.

title: Permissions

title: Request {#get-request}

title: Response {#get-response}

code: GET /v1/bdbs/1/syncer_state/replica


title: Database upgrade requests

summary: Database upgrade requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [POST](#post-bdbs-upgrade) | `/v1/bdbs/{uid}/upgrade` | Upgrade database |

title: Upgrade database {#post-bdbs-upgrade}

text:
POST /v1/bdbs/{int: uid}/upgrade

Upgrade a database.

#### Required permissions

| Permission name |
|-----------------|
| [update_bdb_with_action]() |

title: Request {#post-request}

text:
#### Example HTTP request

	POST /v1/bdbs/1/upgrade

#### Example JSON body

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Request body

| Field | Type | Description |
|-------|------|-------------|
| force_restart | boolean | Restart shards even if no version change (default: false) |
| keep_redis_version | boolean | Keep current Redis version (default: false). Deprecated as of Redis Software v7.8.2. To upgrade modules without upgrading the Redis database version, set `redis_version` to the current Redis database version instead. |
| keep_crdt_protocol_version | boolean | Keep current crdt protocol version (default: false)  |
| may_discard_data | boolean | Discard data in a non-replicated, non-persistent bdb (default: false) |
| force_discard | boolean | Discard data even if the bdb is replicated and/or persistent (default: false) |
| preserve_roles | boolean | Preserve shards' master/replica roles (requires an extra failover) (default: false) |
| parallel_shards_upgrade | integer | Max number of shards to upgrade in parallel (default: all) |
| modules | list of modules | List of dicts representing the modules that will be upgraded. As of Redis Software v7.8.2, `current_module` and `new_module` are deprecated.

Each dict includes:

• `current_module`: uid of a module to upgrade (deprecated)

• `new_module`: uid of the module we want to upgrade to (deprecated)

• `new_module_args`: args list for the new module (no defaults for the three module-related parameters).
| redis_version | version number | Upgrades the database to the specified Redis version instead of the latest version. To upgrade modules without upgrading the Redis database version, set `redis_version` to the current Redis database version instead. |
| latest_with_modules | boolean | Upgrades the database to the latest Redis version and latest supported versions of modules available in the cluster. (default: true as of v7.8.2) Deprecated as of Redis Software v7.8.2. |

title: Response {#post-response}

text:
Returns the upgraded [BDB object]().

#### Example JSON body

[code example]

title: Status codes {#post-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, bdb upgrade initiated (`action_uid` can be used to track progress) |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Malformed or bad command |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb not found |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | New module version capabilities don't comply with the database configuration |
| [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Internal error |

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


title: Bootstrap requests

summary: Bootstrap requests

summary: Boostrap validation requests

title: Bootstrap validation requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-bootstrap) | `/v1/boostrap` | Get the local node's bootstrap status |
| [POST](#post-bootstrap) | `/v1/bootstrap/{action}` | Initiate bootstrapping |

title: Get bootstrap status {#get-bootstrap}

text:
[code example]

Get the local node's bootstrap status.

This request is accepted as soon the cluster software is installed and before the node is part of an active cluster.

Once the node is part of an active cluster, authentication is required.

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Accept | application/json | Accepted media type |

title: Response {#get-response}

text:
The JSON response object contains a `bootstrap_status` object and a `local_node_info` object.

The `bootstrap_status` object contains the following information:

| Field | Description |
|-------|-------------|
| state | Current bootstrap state.

`idle`: No bootstrapping started.

`initiated`: Bootstrap request received.

`creating_cluster`: In the process of creating a new cluster.

`recovering_cluster`: In the process of recovering a cluster.

`joining_cluster`: In the process of joining an existing cluster.

`error`: The last bootstrap action failed.

`completed`: The last bootstrap action completed successfully.|
| start_time | Bootstrap process start time |
| end_time | Bootstrap process end time |
| error_code | If state is `error`, this error code describes the type of error encountered. |
| error_details | An error-specific object that may contain additional information about the error. A common field in use is `message` which provides a more verbose error message.

The `local_node_info` object is a subset of a [node object]() that provides information about the node configuration.

#### Example JSON body

[code example]

title: Error codes {#get-error-codes}

text:
| Code | Description |
|------|-------------|
| config_error | An error related to the bootstrap configuration provided (e.g. bad JSON). |
| connect_error | Failed to connect to cluster (e.g. FQDN DNS could not resolve, no/wrong node IP provided, etc. |
| access_denied | Invalid credentials supplied. |
| invalid_license | The license string provided is invalid. Additional info can be fetched from the `error_details` object, which includes the violation code in case the license is valid but its terms are violated. |
| repair_required | Cluster is in degraded mode and can only accept replacement nodes. When this happens, `error_details` contains two fields: `failed_nodes` and `replace_candidate`. The `failed_nodes` field is an array of objects, each describing a failed node with at least a `uid` field and an optional `rack_id`. `replace_candidate` is the UID of the node most suitable for replacement. |
| insufficient_node_memory | An attempt to replace a dead node fails because the replaced node does not have enough memory. When this happens, error_details contains a required_memory field which indicates the node memory requirement. |
| insufficient_node_flash | An attempt to replace a dead node fails because the replaced node does not have enough flash. When this happens, `error_details` contains a `required_flash` field which indicates the node flash requirement. |
| time_not_sync | An attempt to join a node with system time not synchronized with the rest of the cluster. |
| rack_id_required | An attempt to join a node with no `rack_id` in a rack-aware cluster. In addition, a `current_rack_ids` field will include an array of currently used rack ids. |
| socket_directory_mismatch | An attempt to join a node with a socket directory setting that differs from the cluster |
| node_config_mismatch | An attempt to join a node with a configuration setting (e.g. confdir, osuser, installdir) that differs from the cluster |
| path_error | A needed path does not exist or is not accessable. |
| internal_error | A different, unspecified internal error was encountered. |

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |

title: Start bootstrapping {#post-bootstrap}

text:
[code example]

Initiate bootstrapping.

The request must contain a bootstrap configuration JSON object, as
described in [Object attributes]() or a minimal subset.

Bootstrapping is permitted only when the current bootstrap state is
`idle` or `error` (in which case the process will restart with the new
configuration).

This request is asynchronous - once the request has been accepted,
the caller is expected to poll bootstrap status while waiting for it to
complete.

title: Request {#post-request}

text:
#### Example HTTP request

[code example]

#### Example JSON body

##### Join cluster
[code example]

##### Create cluster
[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Request body

Include a [bootstrap object]() in the request body.

title: Response {#post-response}

text:
#### Status codes {#post-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Request received and processing begins. |
| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Bootstrap already in progress (check state) |

code: GET /v1/bootstrap

section_id: get-bootstrap-status-get-bootstrap

state: completed

os_version: Ubuntu 14.04 LTS

code: POST /v1/bootstrap/{action}

section_id: start-bootstrapping-post-bootstrap

code: POST /v1/bootstrap/create_cluster

license:
----- LICENSE START -----
di+iK...KniI9
----- LICENSE END -----