Skip to content

RS: Added missing CRDB parameters to crdb-cli and REST API references #1775

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

RS: Added missing CRDB parameters to crdb-cli and REST API references #1775

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
e31001b
DOC-5354 Added missing parameters for crdb-cli crdb create and more d…
rrelledge Jun 25, 2025
9a77c54
DOC-5354 Added some examples of CRDB instance parameters
rrelledge Jun 26, 2025
1bb3f76
DOC-5354 Edited optional instance parameters for crd-cli crdb create
rrelledge Jun 27, 2025
203d898
DOC-5354 Added missing instance parameters and details to crdb-cli cr…
rrelledge Jun 27, 2025
4201ded
DOC-5354 Copied missing instance parameters and details to RS 7.4 crd…
rrelledge Jun 27, 2025
381ac87
DOC-5354 Copied missing instance parameters and details to RS 7.8 crd…
rrelledge Jun 27, 2025
425acb6
DOC-5354 Added missing CRDB requests and fields to RS REST API reference
rrelledge Jun 27, 2025
0594b7d
DOC-5354 Copied missing CRDB requests and fields to RS 7.8 and 7.4 RE…
rrelledge Jun 27, 2025
6d16e47
Apply suggestions from code review
rrelledge Jun 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions content/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/add-instance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,19 +15,20 @@ Adds a peer replica to an existing Active-Active database in order to host the d

```sh
crdb-cli crdb add-instance --crdb-guid <guid>
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=<url>,replication_endpoint=<endpoint>]
[ --compression <0-6> ]
[ --no-wait ]
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=https://<hostname-or-IP>:9443,replication_endpoint=<hostname-or-IP>:<port>,replication_tls_sni=<hostname>]
[--compression <0-6>]
[--wait | --no-wait]
```

### Parameters

| 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 <br> <br> 6=High compression and resource load (Default: 3) |
| no-wait | | Does not wait for the task to complete |
| instance fqdn=\<cluster_fqdn\>,username=\<username\>,password=\<password\>,url=https://\<hostname-or-IP\>:9443,replication_endpoint=\<hostname-or-IP\>:\<port\>,replication_tls_sni=\<hostname\> | strings | The connection information for the new participating cluster (required)<br/><br/>**Required:**<br/>• `fqdn` - Cluster fully qualified domain name<br/>• `username` - Cluster username<br/>• `password` - Cluster password<br/><br/>**Optional:**<br/>• `url` - URL to access the cluster's REST API<br/>• `replication_endpoint` - Address to access the database instance for peer replication<br/>• `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: <br /><br > 0 = No compression <br /><br > 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

Expand Down
14 changes: 9 additions & 5 deletions content/operate/rs/7.4/references/cli-utilities/crdb-cli/crdb/create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,10 @@ Creates an Active-Active database.
```sh
crdb-cli crdb create --name <name>
--memory-size <maximum_memory>
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=<url>,replication_endpoint=<endpoint>]
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=<url>,replication_endpoint=<endpoint>]
--instance fqdn=<cluster1.example.com>,username=<username>,password=<password>[,url=https://<hostname-or-IP>:9443,replication_endpoint=<hostname-or-IP>:<port>,replication_tls_sni=<hostname>]
--instance fqdn=<cluster2.example.com>,username=<username>,password=<password>[,url=https://<hostname-or-IP>:9443,replication_endpoint=<hostname-or-IP>:<port>,replication_tls_sni=<hostname>]
[--port <port_number>]
[--no-wait]
[--wait | --no-wait]
[--default-db-config <configuration>]
[--default-db-config-file <filename>]
[--compression <0-6>]
Expand All @@ -31,8 +31,11 @@ crdb-cli crdb create --name <name>
[--shards-count <number_of_shards>]
[--shard-key-regex <regex_rule>]
[--oss-cluster { true | false } ]
[--oss-sharding { true | false } ]
[--bigstore { true | false }]
[--bigstore-ram-size <maximum_memory>]
[--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=<module_name>,version=<module_version>,args=<module_args>]
```

Expand All @@ -50,11 +53,12 @@ Before you create an Active-Active database, you must have:
|---------------------------------------------------------------------------------------|-------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| name \<CRDB_name\> | string | Name of the Active-Active database (required) |
| memory-size \<maximum_memory\> | size in bytes, kilobytes (KB), or gigabytes (GB) | Maximum database memory (required) |
| instance<br/>&nbsp;&nbsp; fqdn=\<cluster_fqdn\>,<br/>&nbsp;&nbsp; username=\<username\>,<br/>&nbsp;&nbsp; password=\<password\> | strings | The connection information for the participating clusters (required for each participating cluster) |
| instance fqdn=\<cluster_fqdn\>,username=\<username\>,password=\<password\>,url=https://\<hostname-or-IP\>:9443,replication_endpoint=\<hostname-or-IP\>:\<port\>,replication_tls_sni=\<hostname\> | strings | The connection information for the participating clusters (required for each participating cluster)<br/><br/>**Required:**<br/>• `fqdn` - Cluster fully qualified domain name<br/>• `username` - Cluster username<br/>• `password` - Cluster password<br/><br/>**Optional:**<br/>• `url` - URL to access the cluster's REST API<br/>• `replication_endpoint` - Address to access the database instance for peer replication<br/>• `replication_tls_sni` - Cluster [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) hostname for TLS connections |
| port \<port_number\> | integer | TCP port for the Active-Active database on all participating clusters |
| default-db-config \<configuration\> | string | Default database configuration options |
| default-db-config-file \<filename\> | 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: <br /><br > 0 = No compression <br /><br > 6 = High compression and resource load (Default: 3) |
| causal-consistency | true <br/> 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 \<password\> | string | Password for access to the database |
Expand Down
6 changes: 6 additions & 0 deletions content/operate/rs/7.4/references/rest-api/objects/crdb/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,5 +26,11 @@ An object that represents an Active-Active database.
"bdb_uid": string,
"id": integer
}, ...] {{</code>}} | Mapping of instance IDs for local databases to local BDB IDs |
| managed_by | string | The component that manages the Active-Active database |
| modules | {{<code>}}[{
"featureset_version": integer,
"module_name": string
}, ...] {{</code>}} | 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 |
16 changes: 14 additions & 2 deletions content/operate/rs/7.4/references/rest-api/objects/crdb_task.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 | {{<code>}}
[{
"cluster_name": string,
"description": string,
"error_code": string
}, ...] {{</code>}} | Details for errors that occurred on a cluster |
| status | 'queued' <br />'started' <br />'finished' <br />'failed' | CRDB task status (read only) |
| operation | string | The operation that is running (read-only) |
| progress | {{<code>}}
{
"clusters": [{
"name": string,
"progress": string
}, ...],
"worker": string
} {{</code>}} | • `name`: The instance cluster name<br />• `progress`: The step the instance coordinator is running<br />• `worker`: The step the worker is running |
| started | string | Timestamp when the task started (read-only) |
| status | 'queued' <br />'started' <br />'finished' <br />'failed' | CRDB task status (read-only) |
| worker_name | string | The worker that runs the task (read-only) |
85 changes: 82 additions & 3 deletions content/operate/rs/7.4/references/rest-api/requests/crdb_tasks/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}

Expand Down Expand Up @@ -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" >}}).
Expand All @@ -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. |
6 changes: 6 additions & 0 deletions content/operate/rs/7.4/references/rest-api/requests/crdbs/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 6 additions & 0 deletions content/operate/rs/7.4/references/rest-api/requests/crdbs/flush.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" >}}).
Expand Down
12 changes: 9 additions & 3 deletions content/operate/rs/7.4/references/rest-api/requests/crdbs/updates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 |
|------|-------------|
Expand Down
13 changes: 7 additions & 6 deletions content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/add-instance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,19 +15,20 @@ Adds a peer replica to an existing Active-Active database in order to host the d

```sh
crdb-cli crdb add-instance --crdb-guid <guid>
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=<url>,replication_endpoint=<endpoint>]
[ --compression <0-6> ]
[ --no-wait ]
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password>[,url=https://<hostname-or-IP>:9443,replication_endpoint=<hostname-or-IP>:<port>,replication_tls_sni=<hostname>]
[--compression <0-6>]
[--wait | --no-wait]
```

### Parameters

| 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 <br> <br> 6=High compression and resource load (Default: 3) |
| no-wait | | Does not wait for the task to complete |
| instance fqdn=\<cluster_fqdn\>,username=\<username\>,password=\<password\>,url=https://\<hostname-or-IP\>:9443,replication_endpoint=\<hostname-or-IP\>:\<port\>,replication_tls_sni=\<hostname\> | strings | The connection information for the new participating cluster (required)<br/><br/>**Required:**<br/>• `fqdn` - Cluster fully qualified domain name<br/>• `username` - Cluster username<br/>• `password` - Cluster password<br/><br/>**Optional:**<br/>• `url` - URL to access the cluster's REST API<br/>• `replication_endpoint` - Address to access the database instance for peer replication<br/>• `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: <br /><br > 0 = No compression <br /><br > 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

Expand Down
Loading