From e9ad0d29abef1b9e9db2199cfcd9a8792df95d8b Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Tue, 23 Jun 2026 18:03:51 -0500 Subject: [PATCH] DOC-6768 RS: Documented CRDB default_db_config usage and config requirements --- .../rs/databases/active-active/planning.md | 10 ++-- .../memory-performance/memory-limit.md | 10 ++-- .../cli-utilities/crdb-cli/crdb/create.md | 4 +- .../cli-utilities/crdb-cli/crdb/update.md | 2 +- .../rest-api/objects/crdb/_index.md | 12 ++--- .../rest-api/objects/crdb/database_config.md | 48 +++++++++++++------ .../rest-api/objects/crdb/instance_info.md | 2 +- .../rest-api/requests/crdbs/_index.md | 10 +++- .../rest-api/requests/crdbs/updates.md | 10 ++-- 9 files changed, 72 insertions(+), 36 deletions(-) diff --git a/content/operate/rs/databases/active-active/planning.md b/content/operate/rs/databases/active-active/planning.md index d2815fd92b..774afdffc0 100644 --- a/content/operate/rs/databases/active-active/planning.md +++ b/content/operate/rs/databases/active-active/planning.md @@ -68,11 +68,15 @@ The `replication_oom_threshold_percent` setting works as follows: - If memory reaches `maxmemory` despite the client block, the standard out-of-memory behavior applies to all operations, including replication. -`replication_oom_threshold_percent` defaults to `5`, which means 5% of `maxmemory` is reserved. To adjust the reserved percentage, use an [update database configuration]({{}}) REST API request: +`replication_oom_threshold_percent` defaults to `5`, which means 5% of `maxmemory` is reserved. To adjust the reserved percentage in all participating clusters, use an [update Active-Active database configuration]({{}}) REST API request: ```sh -PUT https://:/v1/bdbs/ -{ "replication_oom_threshold_percent": } +PATCH https://:/v1/crdbs/ +{ + "default_db_config": { + "replication_oom_threshold_percent": + } +} ``` ## Networking diff --git a/content/operate/rs/databases/memory-performance/memory-limit.md b/content/operate/rs/databases/memory-performance/memory-limit.md index c05489d9c1..1021f967c9 100644 --- a/content/operate/rs/databases/memory-performance/memory-limit.md +++ b/content/operate/rs/databases/memory-performance/memory-limit.md @@ -87,11 +87,15 @@ The `replication_oom_threshold_percent` setting works as follows: - If memory reaches `maxmemory` despite the client block, the standard out-of-memory behavior applies to all operations, including replication. -`replication_oom_threshold_percent` defaults to `5`, which means 5% of `maxmemory` is reserved. To adjust the reserved percentage, use an [update database configuration]({{}}) REST API request: +`replication_oom_threshold_percent` defaults to `5`, which means 5% of `maxmemory` is reserved. To adjust the reserved percentage in all participating clusters, use an [update Active-Active database configuration]({{}}) REST API request: ```sh -PUT https://:/v1/bdbs/ -{ "replication_oom_threshold_percent": } +PATCH https://:/v1/crdbs/ +{ + "default_db_config": { + "replication_oom_threshold_percent": + } +} ``` ## Adaptive memory allocation 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 17e13603c9..62560d419f 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 @@ -54,8 +54,8 @@ Before you create an Active-Active database, you must have: | 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 | +| default-db-config \ | string | Default database configuration options. For a list of database settings, see the [CRDB database config object]({{}}) reference.| +| default-db-config-file \ | filepath | Default database configuration options from a file. For a list of database settings, see the [CRDB database config object]({{}}) reference.| | 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) | diff --git a/content/operate/rs/references/cli-utilities/crdb-cli/crdb/update.md b/content/operate/rs/references/cli-utilities/crdb-cli/crdb/update.md index a9432bb2c9..5ef4f3d23e 100644 --- a/content/operate/rs/references/cli-utilities/crdb-cli/crdb/update.md +++ b/content/operate/rs/references/cli-utilities/crdb-cli/crdb/update.md @@ -44,7 +44,7 @@ If you want to change the configuration of the local instance only, use [`rladmi | compression | 0-6 | The level of data compression:

0 = No compression

6 = High compression and resource load (Default: 3) | | credentials id=\,username=\,password=\ | strings | Updates the credentials for access to the instance | | default-db-config \ | | Default database configuration from stdin. For a list of database settings, see the [CRDB database config object]({{}}) reference. | -| default-db-config-file \ | filepath | Default database configuration from file | +| default-db-config-file \ | filepath | Default database configuration from file. For a list of database settings, see the [CRDB database config object]({{}}) reference.| | encryption | true
false | Activates or deactivates encryption | | force | | Force an update even if there are no changes | | no-wait | | Do not wait for the command to finish | 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 a2218c11ff..ad68bc9a04 100644 --- a/content/operate/rs/references/rest-api/objects/crdb/_index.md +++ b/content/operate/rs/references/rest-api/objects/crdb/_index.md @@ -17,19 +17,19 @@ An object that represents an Active-Active database. |------|------------|-------------| | guid | string | The global unique ID of the Active-Active database | | causal_consistency | boolean | Enables causal consistency across CRDT instances | -| default_db_config| [CRDB database_config]({{< relref "/operate/rs/references/rest-api/objects/crdb/database_config" >}}) object | Default database configuration applied to all instances in the CRDB object. In most cases, instances should use the same configuration. If you need to override `default_db_config` or add configuration values for specific instances, you can use `db_config` in individual [instance objects]({{< relref "/operate/rs/references/rest-api/objects/crdb/instance_info" >}}). | +| default_db_config| [CRDB database_config]({{< relref "/operate/rs/references/rest-api/objects/crdb/database_config" >}}) object | Default database configuration applied to all instances in the CRDB object. In most cases, instances should use the same configuration. If you need to override `default_db_config` or add configuration values for specific instances, you can use `db_config` in individual [instance objects]({{< relref "/operate/rs/references/rest-api/objects/crdb/instance_info" >}}). For a list of which settings must be identical across all instances and which to set per instance, see the [CRDB database config object]({{}}) reference. | | encryption | boolean | Encrypt communication | | featureset_version | integer | Active-Active database active FeatureSet version | instances | array of [CRDB instance_info]({{< relref "/operate/rs/references/rest-api/objects/crdb/instance_info" >}}) objects | | -| local_databases | {{}}[{ +| local_databases | object | Mapping of instance IDs for local databases to local BDB IDs
{{}}[{ "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 | {{}}[{ +| modules | object | Modules used by the Active-Active database
{{}}[{ "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 | +| 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/database_config.md b/content/operate/rs/references/rest-api/objects/crdb/database_config.md index 53bd333f28..cd96bc9bb8 100644 --- a/content/operate/rs/references/rest-api/objects/crdb/database_config.md +++ b/content/operate/rs/references/rest-api/objects/crdb/database_config.md @@ -16,34 +16,52 @@ An object that represents the database configuration. This configuration object - As `db_config` in individual [instance objects]({{< relref "/operate/rs/references/rest-api/objects/crdb/instance_info" >}}) to override `default_db_config` or add configuration values for specific instances. Use `db_config` only when an instance needs different settings than the default configuration. +## `default_db_config` settings + +Use `default_db_config` to set the following fields so they apply to every instance in the Active-Active database. Do not set these fields in `db_config` at the instance level because if they differ between instances, replication can fail to start, stop syncing, or return errors. + +| Name | Type/Value | Description | +|------|------------|-------------| +| module_list | array of module objects | List of modules to be loaded to all participating clusters of the Active-Active database
{{}}[{
"module_id": string,
"module_args": string,
"module_name": string,
"semantic_version": string,
}, ...]{{}}
**module_id**: Module UID (deprecated; use `module_name` instead)
**module_args**: Module command-line arguments (pattern does not allow special characters &,\<,>,")
**module_name**: Module's name
**semantic_version**: Module's semantic version (deprecated; use `module_args` instead)

**module_id** and **semantic_version** are optional as of Redis Software v7.4.2 and deprecated as of v7.8.2. | +| oss_sharding | boolean (default: false) | An alternative to `shard_key_regex` for using the common case of the OSS shard hashing policy | +| sharding | boolean (default: false) | Cluster mode (server-side sharding). When true, shard hashing rules must be provided by either `oss_sharding` or `shard_key_regex` | +| shard_key_regex | `[{ "regex": string }, ...]` | Custom keyname-based sharding rules (required if sharding is enabled)

To use the default rules you should set the value to:
`[{"regex": ".*\\{(?.*)\\}.*"}, {"regex": "(?.*)"}]` | +| tls_mode | 'enabled'
**'disabled'**
'replica_ssl' | Encrypt communication | + +## Recommended `default_db_config` settings + +The following fields don't break replication if they differ between instances. However, because mismatches can cause problems over time or inconsistent behavior across clusters, you should set them in `default_db_config` so they apply to every instance in the Active-Active database. + | Name | Type/Value | Description | |------|------------|-------------| | aof_policy | **'appendfsync-every-sec'**
'appendfsync-always' | Policy for Append-Only File data persistence | -| authentication_admin_pass | string | Administrative databases access token | | authentication_redis_pass | string | Redis AUTH password (deprecated as of Redis Software v7.2, replaced with multiple passwords feature in version 6.0.X) | -| bigstore | boolean (default: false) | Database driver is Auto Tiering | -| bigstore_ram_size | integer (default: 0) | Memory size of RAM size | -| cert | string | Optional PEM-encoded server certificate for the underlying database instance | | data_persistence | 'disabled'
'snapshot'
**'aof'** | Database on-disk persistence policy. For snapshot persistence, a [snapshot_policy]({{< relref "/operate/rs/references/rest-api/objects/bdb/snapshot_policy" >}}) must be provided | -| enforce_client_authentication | **'enabled'**
'disabled' | Require authentication of client certificates for SSL connections to the database. If enabled, a certificate should be provided in either `authentication_ssl_client_certs` or `authentication_ssl_crdt_certs` | -| authentication_ssl_client_certs | array | List of authorized client certificates. For Active-Active databases, it is strongly advised to configure the client certificates individually for each instance instead of using the default database configuration, even if the same certificate is used across all instances.
{{}}[{
"client_cert": string
}, ...]{{}}
**client_cert**: X.509 PEM (Base64) encoded certificate | -| mtls_allow_outdated_certs | boolean (default: false) | An optional mTLS relaxation flag for certs verification | -| mtls_allow_weak_hashing | boolean (default: false) | An optional mTLS relaxation flag for certs verification | +| eviction_policy | **'noeviction'**
'allkeys-lru'
'allkeys-lfu'
'allkeys-random'
'volatile-lru'
'volatile-lfu'
'volatile-random'
'volatile-ttl' | Database memory eviction policy. See [eviction policy]({{< relref "/operate/rs/databases/memory-performance/eviction-policy" >}}) for more information. | | max_aof_file_size | integer | Maximum AOF file size in bytes | | max_aof_load_time | integer (default: 3600) | Maximum AOF reload time in seconds | | memory_size | integer (default: 0) | Database memory size limit in bytes. 0 is unlimited. | -| module_list | array of module objects | List of modules to be loaded to all participating clusters of the Active-Active database
{{}}[{
"module_id": string,
"module_args": string,
"module_name": string,
"semantic_version": string,
}, ...]{{}}
**module_id**: Module UID (deprecated; use `module_name` instead)
**module_args**: Module command-line arguments (pattern does not allow special characters &,\<,>,")
**module_name**: Module's name
**semantic_version**: Module's semantic version (deprecated; use `module_args` instead)

**module_id** and **semantic_version** are optional as of Redis Software v7.4.2 and deprecated as of v7.8.2. | | oss_cluster | boolean (default: false) | Enables OSS Cluster mode | | oss_cluster_api_preferred_ip_type | 'internal'
'external' | Indicates preferred IP type in OSS cluster API | -| oss_sharding | boolean (default: false) | An alternative to `shard_key_regex` for using the common case of the OSS shard hashing policy | -| port | integer | TCP port for database access | -| private_key | string | Optional PEM-encoded private key matching the certificate for the underlying database instance | | proxy_policy | 'single'
'all-master-shards'
'all-nodes' | The policy used for proxy binding to the endpoint | | rack_aware | boolean (default: false) | Require the database to be always replicated across multiple racks | | replication | boolean (default: true) | Database replication | -| sharding | boolean (default: false) | Cluster mode (server-side sharding). When true, shard hashing rules must be provided by either `oss_sharding` or `shard_key_regex` | -| shard_key_regex | `[{ "regex": string }, ...]` | Custom keyname-based sharding rules (required if sharding is enabled)

To use the default rules you should set the value to:
`[{"regex": ".*\\{(?.*)\\}.*"}, {"regex": "(?.*)"}]` | +| replication_oom_threshold_percent | integer (range: 0-20) (default: 5) | Reserved memory buffer percentage below `maxmemory` that blocks client writes while allowing Active-Active replication. Requires Redis database version 8.4 or later. See [Replication OOM protection]({{}}) for more information. | | shards_count | integer (range: 1-512) (default: 1) | Number of database 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 | | snapshot_policy | array of [snapshot_policy]({{< relref "/operate/rs/references/rest-api/objects/bdb/snapshot_policy" >}}) objects | Policy for snapshot-based data persistence. A dataset snapshot will be taken every N secs if there are at least M writes changes in the dataset. | -| tls_mode | 'enabled'
**'disabled'**
'replica_ssl' | Encrypt communication | + +## Per-instance `db_config` settings + +Set the following fields in an individual [instance]({{}})'s `db_config` because they are specific to that cluster's environment. + +| Name | Type/Value | Description | +|------|------------|-------------| +| authentication_admin_pass | string | Administrative databases access token | +| authentication_ssl_client_certs | array | List of authorized client certificates. For Active-Active databases, it is strongly advised to configure the client certificates individually for each instance instead of using the default database configuration, even if the same certificate is used across all instances.
{{}}[{
"client_cert": string
}, ...]{{}}
**client_cert**: X.509 PEM (Base64) encoded certificate | +| cert | string | Optional PEM-encoded server certificate for the underlying database instance | +| enforce_client_authentication | **'enabled'**
'disabled' | Require authentication of client certificates for SSL connections to the database. If enabled, a certificate should be provided in either `authentication_ssl_client_certs` or `authentication_ssl_crdt_certs` | +| mtls_allow_outdated_certs | boolean (default: false) | An optional mTLS relaxation flag for certs verification | +| mtls_allow_weak_hashing | boolean (default: false) | An optional mTLS relaxation flag for certs verification | +| port | integer | TCP port for database access | +| private_key | string | Optional PEM-encoded private key matching the certificate for the underlying database instance | diff --git a/content/operate/rs/references/rest-api/objects/crdb/instance_info.md b/content/operate/rs/references/rest-api/objects/crdb/instance_info.md index b300d08dd2..0707684a25 100644 --- a/content/operate/rs/references/rest-api/objects/crdb/instance_info.md +++ b/content/operate/rs/references/rest-api/objects/crdb/instance_info.md @@ -17,5 +17,5 @@ An object that represents Active-Active instance info. | id | integer | Unique instance ID | | cluster | [CRDB cluster_info]({{< relref "/operate/rs/references/rest-api/objects/crdb/cluster_info" >}}) object | | | compression | integer | Compression level when syncing from this source | -| db_config | [CRDB database_config]({{< relref "/operate/rs/references/rest-api/objects/crdb/database_config" >}}) object | Database configuration for this specific instance. Use `db_config` only when you need to override or add configuration values that differ from the `default_db_config` in the main [CRDB object]({{< relref "/operate/rs/references/rest-api/objects/crdb" >}}). | +| db_config | [CRDB database_config]({{< relref "/operate/rs/references/rest-api/objects/crdb/database_config" >}}) object | Database configuration for this specific instance. Use `db_config` only when you need to override or add configuration values that differ from the `default_db_config` in the main [CRDB object]({{< relref "/operate/rs/references/rest-api/objects/crdb" >}}). For a list of which settings must be identical across all instances and which to set per instance, see the [CRDB database config object]({{}}) reference. | | db_uid | string | ID of local database instance. This field is likely to be empty for instances other than the local one. | 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 e204f32cc0..f584304080 100644 --- a/content/operate/rs/references/rest-api/requests/crdbs/_index.md +++ b/content/operate/rs/references/rest-api/requests/crdbs/_index.md @@ -109,7 +109,13 @@ PATCH /v1/crdbs/{crdb_guid} Update an Active-Active database's configuration. -In order to add or remove instances, use [`POST crdbs/{crdb_guid}/updates`]({{< relref "/operate/rs/references/rest-api/requests/crdbs/updates#post-crdbs-updates" >}}) instead. +Updating `default_db_config` affects both existing and new instances. + +When you update `db_config`, it changes the configuration of the specified database instance. This field overrides any corresponding fields in `default_db_config`. + +For a list of which settings must be identical across all instances and which to set per instance, see the [CRDB database config object]({{}}) reference. + +To add or remove instances, use [`POST crdbs/{crdb_guid}/updates`]({{< relref "/operate/rs/references/rest-api/requests/crdbs/updates#post-crdbs-updates" >}}) instead. ### Request {#patch-request} @@ -158,6 +164,8 @@ POST /v1/crdbs Create a new Active-Active database. +For a list of which settings must be identical across all instances and which to set per instance, see the [CRDB database config object]({{}}) reference. + ### Request {#post-request} #### Example HTTP request 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 2d9ba77610..599417553e 100644 --- a/content/operate/rs/references/rest-api/requests/crdbs/updates.md +++ b/content/operate/rs/references/rest-api/requests/crdbs/updates.md @@ -13,7 +13,7 @@ weight: $weight | Method | Path | Description | |--------|------|-------------| -| [POST](#post-crdbs-updates) | `/v1/crdbs/{crdb_guid}/updates` | Modify Active-Active confgurarion | +| [POST](#post-crdbs-updates) | `/v1/crdbs/{crdb_guid}/updates` | Modify Active-Active configuration | ## Modify Active-Active configuration {#post-crdbs-updates} @@ -25,11 +25,13 @@ Modify Active-Active configuration. This is a very powerful API request and can cause damage if used incorrectly. {{}} -In order to add or remove instances, you must use this API. For simple configuration updates, it is recommended to use PATCH on /crdbs/{crdb_guid} instead. +To add or remove instances, you must use this API. For simple configuration updates, use [`PATCH /crdbs/{crdb_guid}`]({{}}) instead. -Updating default_db_config affects both existing and new instances that may be added. +Updating `default_db_config` affects both existing and new instances. -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. +When you update `db_config`, it changes the configuration of the specified database instance. This field overrides any corresponding fields in `default_db_config`. + +For a list of which settings must be identical across all instances and which to set per instance, see the [CRDB database config object]({{}}) reference. ### Request {#post-request}