diff --git a/content/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/add-instance.md b/content/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/add-instance.md index 7d5e7d121d..6b1b43ac17 100644 --- a/content/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/add-instance.md +++ b/content/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/add-instance.md @@ -15,9 +15,9 @@ Adds a peer replica to an existing Active-Active database in order to host the d ```sh crdb-cli crdb add-instance --crdb-guid - --instance fqdn=,username=,password=[,url=,replication_endpoint=] - [ --compression <0-6> ] - [ --no-wait ] + --instance fqdn=,username=,password=[,url=https://:9443,replication_endpoint=:,replication_tls_sni=] + [--compression <0-6>] + [--wait | --no-wait] ``` ### Parameters @@ -25,9 +25,10 @@ crdb-cli crdb add-instance --crdb-guid | Parameter | Value | Description | |-----------|---------|-------------| | crdb-guid | string | The GUID of the database (required) | -| instance | strings | The connection information for the new participating cluster (required) | -| compression | 0-6 | The level of data compression: 0=Compression disabled

6=High compression and resource load (Default: 3) | -| no-wait | | Does not wait for the task to complete | +| instance fqdn=\,username=\,password=\,url=https://\:9443,replication_endpoint=\:\,replication_tls_sni=\ | strings | The connection information for the new participating cluster (required)

**Required:**
• `fqdn` - Cluster fully qualified domain name
• `username` - Cluster username
• `password` - Cluster password

**Optional:**
• `url` - URL to access the cluster's REST API
• `replication_endpoint` - Address to access the database instance for peer replication
• `replication_tls_sni` - Cluster [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) hostname for TLS connections | +| compression | 0-6 | The level of data compression:

0 = No compression

6 = High compression and resource load (Default: 3) | +| wait | | Prevents `crdb-cli` from running another command before this command finishes | +| no-wait | | `crdb-cli` can run another command before this command finishes | ### Returns diff --git a/content/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/create.md b/content/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/create.md index c55b4fcaf8..1b0a925f9f 100644 --- a/content/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/create.md +++ b/content/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/create.md @@ -16,10 +16,10 @@ Creates an Active-Active database. ```sh crdb-cli crdb create --name --memory-size - --instance fqdn=,username=,password=[,url=,replication_endpoint=] - --instance fqdn=,username=,password=[,url=,replication_endpoint=] + --instance fqdn=,username=,password=[,url=https://:9443,replication_endpoint=:,replication_tls_sni=] + --instance fqdn=,username=,password=[,url=https://:9443,replication_endpoint=:,replication_tls_sni=] [--port ] - [--no-wait] + [--wait | --no-wait] [--default-db-config ] [--default-db-config-file ] [--compression <0-6>] @@ -31,8 +31,11 @@ crdb-cli crdb create --name [--shards-count ] [--shard-key-regex ] [--oss-cluster { true | false } ] + [--oss-sharding { true | false } ] [--bigstore { true | false }] [--bigstore-ram-size ] + [--eviction-policy { noeviction | allkeys-lru | allkeys-lfu |allkeys-random | volatile-lru | volatile-lfu | volatile-random | volatile-ttl }] + [--proxy-policy { all-nodes | all-master-shards | single }] [--with-module name=,version=,args=] ``` @@ -50,11 +53,12 @@ Before you create an Active-Active database, you must have: |---------------------------------------------------------------------------------------|-------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | name \ | string | Name of the Active-Active database (required) | | memory-size \ | size in bytes, kilobytes (KB), or gigabytes (GB) | Maximum database memory (required) | -| instance
   fqdn=\,
   username=\,
   password=\ | strings | The connection information for the participating clusters (required for each participating cluster) | +| instance fqdn=\,username=\,password=\,url=https://\:9443,replication_endpoint=\:\,replication_tls_sni=\ | strings | The connection information for the participating clusters (required for each participating cluster)

**Required:**
• `fqdn` - Cluster fully qualified domain name
• `username` - Cluster username
• `password` - Cluster password

**Optional:**
• `url` - URL to access the cluster's REST API
• `replication_endpoint` - Address to access the database instance for peer replication
• `replication_tls_sni` - Cluster [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) hostname for TLS connections | | port \ | integer | TCP port for the Active-Active database on all participating clusters | | default-db-config \ | string | Default database configuration options | | default-db-config-file \ | filepath | Default database configuration options from a file | -| no-wait | | Prevents `crdb-cli` from running another command before this command finishes | +| wait | | Prevents `crdb-cli` from running another command before this command finishes | +| no-wait | | `crdb-cli` can run another command before this command finishes | | compression | 0-6 | The level of data compression:

0 = No compression

6 = High compression and resource load (Default: 3) | | causal-consistency | true
false (*default*) | [Causal consistency]({{< relref "/operate/rs/7.4/databases/active-active/causal-consistency.md" >}}) applies updates to all instances in the order they were received | | password \ | string | Password for access to the database | diff --git a/content/operate/rs/7.4/references/rest-api/objects/crdb/_index.md b/content/operate/rs/7.4/references/rest-api/objects/crdb/_index.md index 5e0804d6e9..ac6a349f26 100644 --- a/content/operate/rs/7.4/references/rest-api/objects/crdb/_index.md +++ b/content/operate/rs/7.4/references/rest-api/objects/crdb/_index.md @@ -26,5 +26,11 @@ An object that represents an Active-Active database. "bdb_uid": string, "id": integer }, ...] {{}} | Mapping of instance IDs for local databases to local BDB IDs | +| managed_by | string | The component that manages the Active-Active database | +| modules | {{}}[{ + "featureset_version": integer, + "module_name": string +}, ...] {{}} | Modules used by the Active-Active database | | name | string | Name of Active-Active database | | protocol_version | integer | Active-Active database active protocol version | +| volatile_config_fields | array of strings | A list of database configuration fields that will be set even if unchanged | diff --git a/content/operate/rs/7.4/references/rest-api/objects/crdb_task.md b/content/operate/rs/7.4/references/rest-api/objects/crdb_task.md index f6fb253a2b..ed04f99196 100644 --- a/content/operate/rs/7.4/references/rest-api/objects/crdb_task.md +++ b/content/operate/rs/7.4/references/rest-api/objects/crdb_task.md @@ -15,12 +15,24 @@ An object that represents an Active-Active (CRDB) task. | Name | Type/Value | Description | |------|------------|-------------| -| id | string | CRDB task ID (read only) | +| id | string | CRDB task ID (read-only) | | crdb_guid | string | Globally unique Active-Active database ID (GUID) (read-only) | +| ended | string | Timestamp when the task ended (read-only) | | errors | {{}} [{ "cluster_name": string, "description": string, "error_code": string }, ...] {{}} | Details for errors that occurred on a cluster | -| status | 'queued'
'started'
'finished'
'failed' | CRDB task status (read only) | +| operation | string | The operation that is running (read-only) | +| progress | {{}} +{ + "clusters": [{ + "name": string, + "progress": string + }, ...], + "worker": string +} {{}} | • `name`: The instance cluster name
• `progress`: The step the instance coordinator is running
• `worker`: The step the worker is running | +| started | string | Timestamp when the task started (read-only) | +| status | 'queued'
'started'
'finished'
'failed' | CRDB task status (read-only) | +| worker_name | string | The worker that runs the task (read-only) | diff --git a/content/operate/rs/7.4/references/rest-api/requests/crdb_tasks/_index.md b/content/operate/rs/7.4/references/rest-api/requests/crdb_tasks/_index.md index c293942707..94ba85f0b3 100644 --- a/content/operate/rs/7.4/references/rest-api/requests/crdb_tasks/_index.md +++ b/content/operate/rs/7.4/references/rest-api/requests/crdb_tasks/_index.md @@ -15,7 +15,36 @@ url: '/operate/rs/7.4/references/rest-api/requests/crdb_tasks/' | Method | Path | Description | |--------|------|-------------| +| [GET](#get-all-crdb_tasks) | `/v1/crdb_tasks` | Get all running tasks | | [GET](#get-crdb_task) | `/v1/crdb_tasks/{task_id}` | Get the status of an executed task | +| [POST](#post-crdb_task-cancel) | `/v1/crdb_tasks/{task_id}/actions/cancel` | Cancel a running or queued task | + +## Get all running tasks {#get-all-crdb_tasks} + +```sh +GET /v1/crdb_tasks +``` + +Get all running tasks. + +### Request {#get-all-request} + +#### Example HTTP request + +```sh +GET /v1/crdb_tasks +``` + +### Response {#get-all-response} + +Returns a JSON array of [CRDB task objects]({{< relref "/operate/rs/7.4/references/rest-api/objects/crdb_task" >}}). + +#### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | A list of running tasks. | +| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. | ## Get task status {#get-crdb_task} @@ -43,6 +72,12 @@ The status of a completed task is kept for 500 seconds by default. |-------|------|-------------| | task_id | string | Task ID | +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| verbose | boolean | Return detailed task information (optional) | + ### Response {#get-response} Returns a [CRDB task object]({{< relref "/operate/rs/7.4/references/rest-api/objects/crdb_task" >}}). @@ -51,6 +86,50 @@ Returns a [CRDB task object]({{< relref "/operate/rs/7.4/references/rest-api/obj | Code | Description | |------|-------------| -| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Task status. | -| [401 Unauthorized](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) | Unauthorized request. Invalid credentials | -| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Task not found. | +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Task status. | +| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Task not found. | + +## Cancel task {#post-crdb_task-cancel} + +```sh +POST /v1/crdb_tasks/{task_id}/actions/cancel +``` + +Gracefully cancels a running or queued task. + +A task that already reached the commit phase cannot be canceled. + +### Request {#post-cancel-request} + +#### Example HTTP request + +```sh +POST /v1/crdb_tasks/1/actions/cancel +``` + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| task_id | string | Task ID | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| force | boolean | Cancel even when the task is during commit. **WARNING**: Can break the CRDB in CCS, use with caution! (optional) | + +### Response {#post-cancel-response} + +Returns a success message. + +#### Status codes {#post-cancel-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | The request has been accepted. | +| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Task not found. | +| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Task cannot be canceled. | +| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Failed to cancel task. | diff --git a/content/operate/rs/7.4/references/rest-api/requests/crdbs/_index.md b/content/operate/rs/7.4/references/rest-api/requests/crdbs/_index.md index 9d3f35b9c8..7666e69eaa 100644 --- a/content/operate/rs/7.4/references/rest-api/requests/crdbs/_index.md +++ b/content/operate/rs/7.4/references/rest-api/requests/crdbs/_index.md @@ -174,6 +174,12 @@ Create a new Active-Active database. | X-Task-ID | string | Specified task ID | | X-Result-TTL | integer | Time (in seconds) to keep task result | +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| dry_run | boolean | Validate the request without creating the database (optional) | + #### Request body Include a [CRDB object]({{< relref "/operate/rs/7.4/references/rest-api/objects/crdb" >}}), which defines the Active-Active database, in the request body. diff --git a/content/operate/rs/7.4/references/rest-api/requests/crdbs/flush.md b/content/operate/rs/7.4/references/rest-api/requests/crdbs/flush.md index da612d8509..d9641f3c3c 100644 --- a/content/operate/rs/7.4/references/rest-api/requests/crdbs/flush.md +++ b/content/operate/rs/7.4/references/rest-api/requests/crdbs/flush.md @@ -45,6 +45,12 @@ PUT /v1/crdbs/552bbccb-99f3-4142-bd17-93d245f0bc79/flush |-------|------|-------------| | crdb_guid | string | Globally unique Active-Active database ID (GUID) | +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| async_flush | boolean | Perform asynchronous flush operation (optional) | + ### Response {#put-response} Returns a [CRDB task object]({{< relref "/operate/rs/7.4/references/rest-api/objects/crdb_task" >}}). diff --git a/content/operate/rs/7.4/references/rest-api/requests/crdbs/updates.md b/content/operate/rs/7.4/references/rest-api/requests/crdbs/updates.md index 446c9598a4..8a185a683e 100644 --- a/content/operate/rs/7.4/references/rest-api/requests/crdbs/updates.md +++ b/content/operate/rs/7.4/references/rest-api/requests/crdbs/updates.md @@ -32,7 +32,7 @@ Updating default_db_config affects both existing and new instances that may be a When you update db_config, it changes the configuration of the database that you specify. This field overrides corresponding fields (if any) in default_db_config. -### Request {#post-request} +### Request {#post-request} #### Example HTTP request @@ -51,15 +51,21 @@ When you update db_config, it changes the configuration of the database that you |-------|------|-------------| | crdb_guid | string | Globally unique Active-Active database ID (GUID) | +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| dry_run | boolean | Validate the request without applying changes (optional) | + #### Request body Include a [CRDB modify_request object]({{< relref "/operate/rs/7.4/references/rest-api/objects/crdb/modify_request" >}}) with updated fields in the request body. -### Response {#post-response} +### Response {#post-response} Returns a [CRDB task object]({{< relref "/operate/rs/7.4/references/rest-api/objects/crdb_task" >}}). -### Status codes {#post-status-codes} +### Status codes {#post-status-codes} | Code | Description | |------|-------------| diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/add-instance.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/add-instance.md index f968d412ee..bc93df90c2 100644 --- a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/add-instance.md +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/add-instance.md @@ -15,9 +15,9 @@ Adds a peer replica to an existing Active-Active database in order to host the d ```sh crdb-cli crdb add-instance --crdb-guid - --instance fqdn=,username=,password=[,url=,replication_endpoint=] - [ --compression <0-6> ] - [ --no-wait ] + --instance fqdn=,username=,password=[,url=https://:9443,replication_endpoint=:,replication_tls_sni=] + [--compression <0-6>] + [--wait | --no-wait] ``` ### Parameters @@ -25,9 +25,10 @@ crdb-cli crdb add-instance --crdb-guid | Parameter | Value | Description | |-----------|---------|-------------| | crdb-guid | string | The GUID of the database (required) | -| instance | strings | The connection information for the new participating cluster (required) | -| compression | 0-6 | The level of data compression: 0=Compression disabled

6=High compression and resource load (Default: 3) | -| no-wait | | Does not wait for the task to complete | +| instance fqdn=\,username=\,password=\,url=https://\:9443,replication_endpoint=\:\,replication_tls_sni=\ | strings | The connection information for the new participating cluster (required)

**Required:**
• `fqdn` - Cluster fully qualified domain name
• `username` - Cluster username
• `password` - Cluster password

**Optional:**
• `url` - URL to access the cluster's REST API
• `replication_endpoint` - Address to access the database instance for peer replication
• `replication_tls_sni` - Cluster [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) hostname for TLS connections | +| compression | 0-6 | The level of data compression:

0 = No compression

6 = High compression and resource load (Default: 3) | +| wait | | Prevents `crdb-cli` from running another command before this command finishes | +| no-wait | | `crdb-cli` can run another command before this command finishes | ### Returns diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/create.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/create.md index 8ef1173361..492b89ed8e 100644 --- a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/create.md +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/create.md @@ -16,10 +16,10 @@ Creates an Active-Active database. ```sh crdb-cli crdb create --name --memory-size - --instance fqdn=,username=,password=[,url=,replication_endpoint=] - --instance fqdn=,username=,password=[,url=,replication_endpoint=] + --instance fqdn=,username=,password=[,url=https://:9443,replication_endpoint=:,replication_tls_sni=] + --instance fqdn=,username=,password=[,url=https://:9443,replication_endpoint=:,replication_tls_sni=] [--port ] - [--no-wait] + [--wait | --no-wait] [--default-db-config ] [--default-db-config-file ] [--compression <0-6>] @@ -31,8 +31,11 @@ crdb-cli crdb create --name [--shards-count ] [--shard-key-regex ] [--oss-cluster { true | false } ] + [--oss-sharding { true | false } ] [--bigstore { true | false }] [--bigstore-ram-size ] + [--eviction-policy { noeviction | allkeys-lru | allkeys-lfu |allkeys-random | volatile-lru | volatile-lfu | volatile-random | volatile-ttl }] + [--proxy-policy { all-nodes | all-master-shards | single }] [--with-module name=,version=,args=] ``` @@ -50,11 +53,12 @@ Before you create an Active-Active database, you must have: |---------------------------------------------------------------------------------------|-------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | name \ | string | Name of the Active-Active database (required) | | memory-size \ | size in bytes, kilobytes (KB), or gigabytes (GB) | Maximum database memory (required) | -| instance
   fqdn=\,
   username=\,
   password=\ | strings | The connection information for the participating clusters (required for each participating cluster) | +| instance fqdn=\,username=\,password=\,url=https://\:9443,replication_endpoint=\:\,replication_tls_sni=\ | strings | The connection information for the participating clusters (required for each participating cluster)

**Required:**
• `fqdn` - Cluster fully qualified domain name
• `username` - Cluster username
• `password` - Cluster password

**Optional:**
• `url` - URL to access the cluster's REST API
• `replication_endpoint` - Address to access the database instance for peer replication
• `replication_tls_sni` - Cluster [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) hostname for TLS connections | | port \ | integer | TCP port for the Active-Active database on all participating clusters | | default-db-config \ | string | Default database configuration options | | default-db-config-file \ | filepath | Default database configuration options from a file | -| no-wait | | Prevents `crdb-cli` from running another command before this command finishes | +| wait | | Prevents `crdb-cli` from running another command before this command finishes | +| no-wait | | `crdb-cli` can run another command before this command finishes | | compression | 0-6 | The level of data compression:

0 = No compression

6 = High compression and resource load (Default: 3) | | causal-consistency | true
false (*default*) | [Causal consistency]({{< relref "/operate/rs/7.8/databases/active-active/causal-consistency.md" >}}) applies updates to all instances in the order they were received | | password \ | string | Password for access to the database | diff --git a/content/operate/rs/7.8/references/rest-api/objects/crdb/_index.md b/content/operate/rs/7.8/references/rest-api/objects/crdb/_index.md index 846e9e479f..cc9f7b1ab1 100644 --- a/content/operate/rs/7.8/references/rest-api/objects/crdb/_index.md +++ b/content/operate/rs/7.8/references/rest-api/objects/crdb/_index.md @@ -26,5 +26,11 @@ An object that represents an Active-Active database. "bdb_uid": string, "id": integer }, ...] {{}} | Mapping of instance IDs for local databases to local BDB IDs | +| managed_by | string | The component that manages the Active-Active database | +| modules | {{}}[{ + "featureset_version": integer, + "module_name": string +}, ...] {{}} | Modules used by the Active-Active database | | name | string | Name of Active-Active database | | protocol_version | integer | Active-Active database active protocol version | +| volatile_config_fields | array of strings | A list of database configuration fields that will be set even if unchanged | diff --git a/content/operate/rs/7.8/references/rest-api/objects/crdb_task.md b/content/operate/rs/7.8/references/rest-api/objects/crdb_task.md index 44b82f8071..5c2d32ef81 100644 --- a/content/operate/rs/7.8/references/rest-api/objects/crdb_task.md +++ b/content/operate/rs/7.8/references/rest-api/objects/crdb_task.md @@ -15,12 +15,24 @@ An object that represents an Active-Active (CRDB) task. | Name | Type/Value | Description | |------|------------|-------------| -| id | string | CRDB task ID (read only) | +| id | string | CRDB task ID (read-only) | | crdb_guid | string | Globally unique Active-Active database ID (GUID) (read-only) | +| ended | string | Timestamp when the task ended (read-only) | | errors | {{}} [{ "cluster_name": string, "description": string, "error_code": string }, ...] {{}} | Details for errors that occurred on a cluster | -| status | 'queued'
'started'
'finished'
'failed' | CRDB task status (read only) | +| operation | string | The operation that is running (read-only) | +| progress | {{}} +{ + "clusters": [{ + "name": string, + "progress": string + }, ...], + "worker": string +} {{}} | • `name`: The instance cluster name
• `progress`: The step the instance coordinator is running
• `worker`: The step the worker is running | +| started | string | Timestamp when the task started (read-only) | +| status | 'queued'
'started'
'finished'
'failed' | CRDB task status (read-only) | +| worker_name | string | The worker that runs the task (read-only) | diff --git a/content/operate/rs/7.8/references/rest-api/requests/crdb_tasks/_index.md b/content/operate/rs/7.8/references/rest-api/requests/crdb_tasks/_index.md index 08a950abd6..c05df4ef38 100644 --- a/content/operate/rs/7.8/references/rest-api/requests/crdb_tasks/_index.md +++ b/content/operate/rs/7.8/references/rest-api/requests/crdb_tasks/_index.md @@ -15,7 +15,36 @@ url: '/operate/rs/7.8/references/rest-api/requests/crdb_tasks/' | Method | Path | Description | |--------|------|-------------| +| [GET](#get-all-crdb_tasks) | `/v1/crdb_tasks` | Get all running tasks | | [GET](#get-crdb_task) | `/v1/crdb_tasks/{task_id}` | Get the status of an executed task | +| [POST](#post-crdb_task-cancel) | `/v1/crdb_tasks/{task_id}/actions/cancel` | Cancel a running or queued task | + +## Get all running tasks {#get-all-crdb_tasks} + +```sh +GET /v1/crdb_tasks +``` + +Get all running tasks. + +### Request {#get-all-request} + +#### Example HTTP request + +```sh +GET /v1/crdb_tasks +``` + +### Response {#get-all-response} + +Returns a JSON array of [CRDB task objects]({{< relref "/operate/rs/7.8/references/rest-api/objects/crdb_task" >}}). + +#### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | A list of running tasks. | +| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. | ## Get task status {#get-crdb_task} @@ -43,6 +72,12 @@ The status of a completed task is kept for 500 seconds by default. |-------|------|-------------| | task_id | string | Task ID | +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| verbose | boolean | Return detailed task information (optional) | + ### Response {#get-response} Returns a [CRDB task object]({{< relref "/operate/rs/7.8/references/rest-api/objects/crdb_task" >}}). @@ -51,6 +86,50 @@ Returns a [CRDB task object]({{< relref "/operate/rs/7.8/references/rest-api/obj | Code | Description | |------|-------------| -| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Task status. | -| [401 Unauthorized](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) | Unauthorized request. Invalid credentials | -| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Task not found. | +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Task status. | +| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Task not found. | + +## Cancel task {#post-crdb_task-cancel} + +```sh +POST /v1/crdb_tasks/{task_id}/actions/cancel +``` + +Gracefully cancels a running or queued task. + +A task that already reached the commit phase cannot be canceled. + +### Request {#post-cancel-request} + +#### Example HTTP request + +```sh +POST /v1/crdb_tasks/1/actions/cancel +``` + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| task_id | string | Task ID | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| force | boolean | Cancel even when the task is during commit. **WARNING**: Can break the CRDB in CCS, use with caution! (optional) | + +### Response {#post-cancel-response} + +Returns a success message. + +#### Status codes {#post-cancel-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | The request has been accepted. | +| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Task not found. | +| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Task cannot be canceled. | +| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Failed to cancel task. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/crdbs/_index.md b/content/operate/rs/7.8/references/rest-api/requests/crdbs/_index.md index 92d9d5b1da..bb5628b333 100644 --- a/content/operate/rs/7.8/references/rest-api/requests/crdbs/_index.md +++ b/content/operate/rs/7.8/references/rest-api/requests/crdbs/_index.md @@ -174,6 +174,12 @@ Create a new Active-Active database. | X-Task-ID | string | Specified task ID | | X-Result-TTL | integer | Time (in seconds) to keep task result | +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| dry_run | boolean | Validate the request without creating the database (optional) | + #### Request body Include a [CRDB object]({{< relref "/operate/rs/7.8/references/rest-api/objects/crdb" >}}), which defines the Active-Active database, in the request body. diff --git a/content/operate/rs/7.8/references/rest-api/requests/crdbs/flush.md b/content/operate/rs/7.8/references/rest-api/requests/crdbs/flush.md index f5bd2e477b..2d883e110e 100644 --- a/content/operate/rs/7.8/references/rest-api/requests/crdbs/flush.md +++ b/content/operate/rs/7.8/references/rest-api/requests/crdbs/flush.md @@ -45,6 +45,12 @@ PUT /v1/crdbs/552bbccb-99f3-4142-bd17-93d245f0bc79/flush |-------|------|-------------| | crdb_guid | string | Globally unique Active-Active database ID (GUID) | +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| async_flush | boolean | Perform asynchronous flush operation (optional) | + ### Response {#put-response} Returns a [CRDB task object]({{< relref "/operate/rs/7.8/references/rest-api/objects/crdb_task" >}}). diff --git a/content/operate/rs/7.8/references/rest-api/requests/crdbs/updates.md b/content/operate/rs/7.8/references/rest-api/requests/crdbs/updates.md index 15307f1f7e..52d26137e0 100644 --- a/content/operate/rs/7.8/references/rest-api/requests/crdbs/updates.md +++ b/content/operate/rs/7.8/references/rest-api/requests/crdbs/updates.md @@ -51,6 +51,12 @@ When you update db_config, it changes the configuration of the database that you |-------|------|-------------| | crdb_guid | string | Globally unique Active-Active database ID (GUID) | +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| dry_run | boolean | Validate the request without applying changes (optional) | + #### Request body Include a [CRDB modify_request object]({{< relref "/operate/rs/7.8/references/rest-api/objects/crdb/modify_request" >}}) with updated fields in the request body. diff --git a/content/operate/rs/references/cli-utilities/crdb-cli/crdb/add-instance.md b/content/operate/rs/references/cli-utilities/crdb-cli/crdb/add-instance.md index bfeb031036..c991a447b0 100644 --- a/content/operate/rs/references/cli-utilities/crdb-cli/crdb/add-instance.md +++ b/content/operate/rs/references/cli-utilities/crdb-cli/crdb/add-instance.md @@ -14,9 +14,9 @@ Adds a peer replica to an existing Active-Active database in order to host the d ```sh crdb-cli crdb add-instance --crdb-guid - --instance fqdn=,username=,password=[,url=,replication_endpoint=] - [ --compression <0-6> ] - [ --no-wait ] + --instance fqdn=,username=,password=[,url=https://:9443,replication_endpoint=:,replication_tls_sni=] + [--compression <0-6>] + [--wait | --no-wait] ``` ### Parameters @@ -24,9 +24,10 @@ crdb-cli crdb add-instance --crdb-guid | Parameter | Value | Description | |-----------|---------|-------------| | crdb-guid | string | The GUID of the database (required) | -| instance | strings | The connection information for the new participating cluster (required) | -| compression | 0-6 | The level of data compression: 0=Compression disabled

6=High compression and resource load (Default: 3) | -| no-wait | | Does not wait for the task to complete | +| instance fqdn=\,username=\,password=\,url=https://\:9443,replication_endpoint=\:\,replication_tls_sni=\ | strings | The connection information for the new participating cluster (required)

**Required:**
• `fqdn` - Cluster fully qualified domain name
• `username` - Cluster username
• `password` - Cluster password

**Optional:**
• `url` - URL to access the cluster's REST API
• `replication_endpoint` - Address to access the database instance for peer replication
• `replication_tls_sni` - Cluster [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) hostname for TLS connections | +| compression | 0-6 | The level of data compression:

0 = No compression

6 = High compression and resource load (Default: 3) | +| wait | | Prevents `crdb-cli` from running another command before this command finishes | +| no-wait | | `crdb-cli` can run another command before this command finishes | ### Returns diff --git a/content/operate/rs/references/cli-utilities/crdb-cli/crdb/create.md b/content/operate/rs/references/cli-utilities/crdb-cli/crdb/create.md index 740200660a..e9581c43c2 100644 --- a/content/operate/rs/references/cli-utilities/crdb-cli/crdb/create.md +++ b/content/operate/rs/references/cli-utilities/crdb-cli/crdb/create.md @@ -15,10 +15,10 @@ Creates an Active-Active database. ```sh crdb-cli crdb create --name --memory-size - --instance fqdn=,username=,password=[,url=,replication_endpoint=] - --instance fqdn=,username=,password=[,url=,replication_endpoint=] + --instance fqdn=,username=,password=[,url=https://:9443,replication_endpoint=:,replication_tls_sni=] + --instance fqdn=,username=,password=[,url=https://:9443,replication_endpoint=:,replication_tls_sni=] [--port ] - [--no-wait] + [--wait | --no-wait] [--default-db-config ] [--default-db-config-file ] [--compression <0-6>] @@ -30,8 +30,11 @@ crdb-cli crdb create --name [--shards-count ] [--shard-key-regex ] [--oss-cluster { true | false } ] + [--oss-sharding { true | false } ] [--bigstore { true | false }] [--bigstore-ram-size ] + [--eviction-policy { noeviction | allkeys-lru | allkeys-lfu |allkeys-random | volatile-lru | volatile-lfu | volatile-random | volatile-ttl }] + [--proxy-policy { all-nodes | all-master-shards | single }] [--with-module name=,version=,args=] ``` @@ -48,24 +51,26 @@ Before you create an Active-Active database, you must have: | Parameter & options(s)           | Value | Description | |---------------------------------------------------------------------------------------|-------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | name \ | string | Name of the Active-Active database (required) | -| memory-size \ | size in bytes, kilobytes (KB), or gigabytes (GB) | Maximum database memory (required) | -| instance
   fqdn=\,
   username=\,
   password=\ | strings | The connection information for the participating clusters (required for each participating cluster) | +| memory-size \ | size in bytes, megabytes (MB), or gigabytes (GB) | Maximum database memory (required) | +| instance fqdn=\,username=\,password=\,url=https://\:9443,replication_endpoint=\:\,replication_tls_sni=\ | strings | The connection information for the participating clusters (required for each participating cluster)

**Required:**
• `fqdn` - Cluster fully qualified domain name
• `username` - Cluster username
• `password` - Cluster password

**Optional:**
• `url` - URL to access the cluster's REST API
• `replication_endpoint` - Address to access the database instance for peer replication
• `replication_tls_sni` - Cluster [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) hostname for TLS connections | | port \ | integer | TCP port for the Active-Active database on all participating clusters | | default-db-config \ | string | Default database configuration options | | default-db-config-file \ | filepath | Default database configuration options from a file | -| no-wait | | Prevents `crdb-cli` from running another command before this command finishes | +| wait | | Prevents `crdb-cli` from running another command before this command finishes | +| no-wait | | `crdb-cli` can run another command before this command finishes | | compression | 0-6 | The level of data compression:

0 = No compression

6 = High compression and resource load (Default: 3) | -| causal-consistency | true
false (*default*) | [Causal consistency]({{< relref "/operate/rs/databases/active-active/causal-consistency.md" >}}) applies updates to all instances in the order they were received | +| causal-consistency | true
false (default: false) | [Causal consistency]({{< relref "/operate/rs/databases/active-active/causal-consistency.md" >}}) applies updates to all instances in the order they were received | | password \ | string | Password for access to the database | | replication | true
false (*default*) | Activates or deactivates [database replication]({{< relref "/operate/rs/databases/durability-ha/replication.md" >}}) where every master shard replicates to a replica shard | | encryption | true
false (*default*) | Activates or deactivates encryption | | sharding | true
false (*default*) | Activates or deactivates sharding (also known as [database clustering]({{< relref "/operate/rs/databases/durability-ha/replication.md" >}})). Cannot be updated after the database is created | | shards-count \ | integer | If sharding is enabled, this specifies the number of Redis shards for each database instance | | oss-cluster | true
false (*default*) | Activates [OSS cluster API]({{< relref "/operate/rs/clusters/optimize/oss-cluster-api" >}}) | +| oss-sharding | true
false | Use the OSS sharding policy instead of regex rules | | shard-key-regex \ | string | If clustering is enabled, this defines a regex rule (also known as a [hashing policy]({{< relref "/operate/rs/databases/durability-ha/clustering#custom-hashing-policy" >}})) that determines which keys are located in each shard (defaults to `{u'regex': u'.*\\{(?.*)\\}.*'}, {u'regex': u'(?.*)'} `) | | bigstore | true

false (*default*) | If true, the database uses Auto Tiering to add flash memory to the database | -| bigstore-ram-size \ | size in bytes, kilobytes (KB), or gigabytes (GB) | Maximum RAM limit for databases with Auto Tiering enabled | -| with-module
  name=\,
  version=\,
  args=\ | strings | Creates a database with a specific module | +| bigstore-ram-size \ | size in bytes, megabytes (MB), or gigabytes (GB) | Maximum RAM limit for databases with Auto Tiering enabled | +| with-module name=\,version=\,args=\ | strings | Creates a database with a specific module | | eviction-policy | noeviction (*default*)
allkeys-lru
allkeys-lfu
allkeys-random
volatile-lru
volatile-lfu
volatile-random
volatile-ttl | Sets [eviction policy]({{< relref "/operate/rs/databases/memory-performance/eviction-policy" >}}) | | proxy-policy | all-nodes
all-master-shards
single | Sets proxy policy | diff --git a/content/operate/rs/references/rest-api/objects/crdb/_index.md b/content/operate/rs/references/rest-api/objects/crdb/_index.md index a0282c7f73..050f2bbaef 100644 --- a/content/operate/rs/references/rest-api/objects/crdb/_index.md +++ b/content/operate/rs/references/rest-api/objects/crdb/_index.md @@ -25,5 +25,11 @@ An object that represents an Active-Active database. "bdb_uid": string, "id": integer }, ...] {{}} | Mapping of instance IDs for local databases to local BDB IDs | +| managed_by | string | The component that manages the Active-Active database | +| modules | {{}}[{ + "featureset_version": integer, + "module_name": string +}, ...] {{}} | Modules used by the Active-Active database | | name | string | Name of Active-Active database | | protocol_version | integer | Active-Active database active protocol version | +| volatile_config_fields | array of strings | A list of database configuration fields that will be set even if unchanged | diff --git a/content/operate/rs/references/rest-api/objects/crdb_task.md b/content/operate/rs/references/rest-api/objects/crdb_task.md index 7915c977ed..f5721de6e9 100644 --- a/content/operate/rs/references/rest-api/objects/crdb_task.md +++ b/content/operate/rs/references/rest-api/objects/crdb_task.md @@ -14,12 +14,24 @@ An object that represents an Active-Active (CRDB) task. | Name | Type/Value | Description | |------|------------|-------------| -| id | string | CRDB task ID (read only) | +| id | string | CRDB task ID (read-only) | | crdb_guid | string | Globally unique Active-Active database ID (GUID) (read-only) | +| ended | string | Timestamp when the task ended (read-only) | | errors | {{}} [{ "cluster_name": string, "description": string, "error_code": string }, ...] {{}} | Details for errors that occurred on a cluster | -| status | 'queued'
'started'
'finished'
'failed' | CRDB task status (read only) | +| operation | string | The operation that is running (read-only) | +| progress | {{}} +{ + "clusters": [{ + "name": string, + "progress": string + }, ...], + "worker": string +} {{}} | • `name`: The instance cluster name
• `progress`: The step the instance coordinator is running
• `worker`: The step the worker is running | +| started | string | Timestamp when the task started (read-only) | +| status | 'queued'
'started'
'finished'
'failed' | CRDB task status (read-only) | +| worker_name | string | The worker that runs the task (read-only) | diff --git a/content/operate/rs/references/rest-api/requests/crdb_tasks/_index.md b/content/operate/rs/references/rest-api/requests/crdb_tasks/_index.md index 69130b5362..854d99ccbd 100644 --- a/content/operate/rs/references/rest-api/requests/crdb_tasks/_index.md +++ b/content/operate/rs/references/rest-api/requests/crdb_tasks/_index.md @@ -14,7 +14,36 @@ weight: $weight | Method | Path | Description | |--------|------|-------------| +| [GET](#get-all-crdb_tasks) | `/v1/crdb_tasks` | Get all running tasks | | [GET](#get-crdb_task) | `/v1/crdb_tasks/{task_id}` | Get the status of an executed task | +| [POST](#post-crdb_task-cancel) | `/v1/crdb_tasks/{task_id}/actions/cancel` | Cancel a running or queued task | + +## Get all running tasks {#get-all-crdb_tasks} + +```sh +GET /v1/crdb_tasks +``` + +Get all running tasks. + +### Request {#get-all-request} + +#### Example HTTP request + +```sh +GET /v1/crdb_tasks +``` + +### Response {#get-all-response} + +Returns a JSON array of [CRDB task objects]({{< relref "/operate/rs/references/rest-api/objects/crdb_task" >}}). + +#### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | A list of running tasks. | +| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. | ## Get task status {#get-crdb_task} @@ -42,6 +71,12 @@ The status of a completed task is kept for 500 seconds by default. |-------|------|-------------| | task_id | string | Task ID | +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| verbose | boolean | Return detailed task information (optional) | + ### Response {#get-response} Returns a [CRDB task object]({{< relref "/operate/rs/references/rest-api/objects/crdb_task" >}}). @@ -50,6 +85,50 @@ Returns a [CRDB task object]({{< relref "/operate/rs/references/rest-api/objects | Code | Description | |------|-------------| -| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Task status. | -| [401 Unauthorized](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2) | Unauthorized request. Invalid credentials | -| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Task not found. | +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Task status. | +| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Task not found. | + +## Cancel task {#post-crdb_task-cancel} + +```sh +POST /v1/crdb_tasks/{task_id}/actions/cancel +``` + +Gracefully cancels a running or queued task. + +A task that already reached the commit phase cannot be canceled. + +### Request {#post-cancel-request} + +#### Example HTTP request + +```sh +POST /v1/crdb_tasks/1/actions/cancel +``` + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| task_id | string | Task ID | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| force | boolean | Cancel even if the task is in the commit phase. **WARNING**: This can break the CRDB in the cluster configuration store (CCS), so use with caution. (optional) | + +### Response {#post-cancel-response} + +Returns a status code. + +#### Status codes {#post-cancel-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | The request has been accepted. | +| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | Unauthorized request. Invalid credentials. | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Task not found. | +| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Task cannot be canceled. | +| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Failed to cancel task. | diff --git a/content/operate/rs/references/rest-api/requests/crdbs/_index.md b/content/operate/rs/references/rest-api/requests/crdbs/_index.md index 47d7f26c0c..e204f32cc0 100644 --- a/content/operate/rs/references/rest-api/requests/crdbs/_index.md +++ b/content/operate/rs/references/rest-api/requests/crdbs/_index.md @@ -173,6 +173,12 @@ Create a new Active-Active database. | X-Task-ID | string | Specified task ID | | X-Result-TTL | integer | Time (in seconds) to keep task result | +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| dry_run | boolean | Validate the request without creating the database (optional) | + #### Request body Include a [CRDB object]({{< relref "/operate/rs/references/rest-api/objects/crdb" >}}), which defines the Active-Active database, in the request body. diff --git a/content/operate/rs/references/rest-api/requests/crdbs/flush.md b/content/operate/rs/references/rest-api/requests/crdbs/flush.md index 1b3d2079fa..c9330e61a6 100644 --- a/content/operate/rs/references/rest-api/requests/crdbs/flush.md +++ b/content/operate/rs/references/rest-api/requests/crdbs/flush.md @@ -44,6 +44,12 @@ PUT /v1/crdbs/552bbccb-99f3-4142-bd17-93d245f0bc79/flush |-------|------|-------------| | crdb_guid | string | Globally unique Active-Active database ID (GUID) | +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| async_flush | boolean | Perform asynchronous flush operation (optional) | + ### Response {#put-response} Returns a [CRDB task object]({{< relref "/operate/rs/references/rest-api/objects/crdb_task" >}}). diff --git a/content/operate/rs/references/rest-api/requests/crdbs/updates.md b/content/operate/rs/references/rest-api/requests/crdbs/updates.md index 664e600a38..2d9ba77610 100644 --- a/content/operate/rs/references/rest-api/requests/crdbs/updates.md +++ b/content/operate/rs/references/rest-api/requests/crdbs/updates.md @@ -50,6 +50,12 @@ When you update db_config, it changes the configuration of the database that you |-------|------|-------------| | crdb_guid | string | Globally unique Active-Active database ID (GUID) | +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| dry_run | boolean | Validate the request without applying changes (optional) | + #### Request body Include a [CRDB modify_request object]({{< relref "/operate/rs/references/rest-api/objects/crdb/modify_request" >}}) with updated fields in the request body.