--- title: "yb-master" url: "https://docs.yugabyte.com/stable/reference/configuration/yb-master/" --- # yb-master YugabyteDB Master Server (yb-master) binary and configuration flags to manage cluster metadata and coordinate cluster-wide operations. The YugabyteDB Master Server ([YB-Master](/stable/architecture/yb-master/ "YB-Master")) coordinates cluster-wide control plane work: it stores and replicates system metadata, tracks tablet servers and tablets, drives cluster balancing and automatic tablet splitting, and participates in Raft consensus with other masters for highly available metadata. Together with YB-TServers, it helps keep the cluster consistent and operational as you scale or recover from failures. This reference describes flags for configuring YB-Master processes in a YugabyteDB cluster. Use these flags to align behavior with your topology, security model, and operational goals. Use the yb-master binary and its flags to configure the YB-Master server. The yb-master executable file is located in the `bin` directory of YugabyteDB home. Setting flags in YugabyteDB Anywhere If you are using YugabyteDB Anywhere, set flags using the [Edit Flags](/stable/yugabyte-platform/manage-deployments/edit-config-flags/#modify-configuration-flags "Edit Flags") feature. Flags are organized in the following categories. | Category | Description | |-------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | [General configuration](#general-configuration "General configuration") | Basic server setup including overall system settings, logging, web interface, and metrics export. | | [PostgreSQL configuration parameters](#postgresql-configuration-parameters "PostgreSQL configuration parameters") | Overview and pointers to PostgreSQL configuration; YSQL flags on YB-Master appear under [Security](#security "Security"). | | [Networking](#networking "Networking") | Flags that control network interfaces, RPC endpoints, DNS caching, and geo-distribution settings. | | [Storage and data management](#storage-data-management "Storage and data management") | Parameters for managing data directories, WAL configurations, cluster balancing, sharding, tablet splitting, CDC, and YSQL catalog behavior. | | [Performance tuning](#performance-tuning "Performance tuning") | Options for resource allocation, memory management, Auto Analyze, advisory locks, Raft consensus, index backfill, and preview or advanced tuning flags. | | [Security](#security "Security") | Settings for encryption, SSL/TLS, and authentication to secure both node-to-node and client-server communications. | **Legend** Flags with specific characteristics are highlighted using the following badges: - Restart Needed Changes to this flag require a restart – A restart of the server is required for the flag to take effect. For example, if the flag is used on *yb-master*, you need to restart only *yb-master*. If the flag is used on both the *yb-master* and *yb-tserver*, restart both services. - T-Server / Master Match Flag value must match across all Masters and TServers – The flag must have the same value across all *yb-master* and *yb-tserver* nodes. **Syntax** ```sh yb-master [ flag ] | [ flag ] ``` **Example** ```sh ./bin/yb-master \ --master_addresses 172.151.17.130:7100,172.151.17.220:7100,172.151.17.140:7100 \ --rpc_bind_addresses 172.151.17.130 \ --fs_data_dirs "/home/centos/disk1,/home/centos/disk2" \ --replication_factor=3 ``` **Online help** To display the online help, run `yb-master --help` from the YugabyteDB home directory: ```sh ./bin/yb-master --help ``` ## All flags The following sections describe the flags considered relevant to configuring YugabyteDB for production deployments. For a list of all flags, see [All YB-Master flags](/stable/reference/configuration/all-flags-yb-master/ "All YB-Master flags"). ## General configuration ##### --flagfile Restart Needed Changes to this flag require a restart Specifies the configuration file to load flags from. ##### --version Shows version and build information, then exits. ##### --master\_addresses Restart Needed Changes to this flag require a restart Default: `127.0.0.1:7100` Specifies a comma-separated list of all RPC addresses for YB-Master consensus-configuration. Note The number of comma-separated values should match the total number of YB-Master server (or the replication factor). Required. ##### --max\_clock\_skew\_usec Restart Needed Changes to this flag require a restart Default: `500000` (500,000 µs = 500ms) The expected maximum clock skew, in microseconds (µs), between any two servers in your deployment. ##### --time\_source Restart Needed Changes to this flag require a restart Default: `""` Specifies the time source used by the database. Set this to `clockbound` for configuring a highly accurate time source. Using `clockbound` requires [system configuration](/stable/deploy/manual-deployment/system-config/#set-up-time-synchronization "system configuration"). ### Webserver configuration ##### --webserver\_interface Restart Needed Changes to this flag require a restart Default: `""` (empty; the web UI binds to the first host IP from [--rpc\_bind\_addresses](#rpc-bind-addresses "--rpc_bind_addresses")) The address to bind for the web server user interface. ##### --webserver\_port Restart Needed Changes to this flag require a restart Default: `7000` The port for monitoring the web server. ##### --webserver\_doc\_root Restart Needed Changes to this flag require a restart Default: The `www` directory in the YugabyteDB home directory. The monitoring web server home directory. ##### --webserver\_certificate\_file Restart Needed Changes to this flag require a restart Default: `""` Location of the SSL certificate file (in .pem format) to use for the web server. If empty, SSL is not enabled for the web server. ##### --webserver\_authentication\_domain Restart Needed Changes to this flag require a restart Default: `""` Domain used for `.htpasswd` authentication. This should be used in conjunction with [--webserver\_password\_file](#webserver-password-file "--webserver_password_file"). ##### --webserver\_password\_file Restart Needed Changes to this flag require a restart Default: `""` Location of the `.htpasswd` file containing usernames and hashed passwords, for authentication to the web server. ### Logging flags ##### --log\_dir Restart Needed Changes to this flag require a restart Default: Same as [--fs\_data\_dirs](#fs-data-dirs "--fs_data_dirs") The directory to write YB-Master log files. ##### --colorlogtostderr Default: `false` Color messages logged to `stderr` (if supported by terminal). ##### --logbuflevel Default: `1` Buffer log messages logged at this level (or lower). Valid values: `-1` (don't buffer); `0` (INFO); `1` (WARN); `2` (ERROR); `3` (FATAL) ##### --logbufsecs Default: `30` Buffer log messages for at most this many seconds. ##### --logtostderr Default: `false` Write log messages to `stderr` instead of `logfiles`. ##### --log\_link Restart Needed Changes to this flag require a restart Default: `""` Put additional links to the log files in this directory. ##### --log\_prefix Default: `true` Prepend the log prefix to each log line. ##### --max\_log\_size Default: `1800` (1.8 GB) The maximum log size, in megabytes (MB). A value of `0` will be silently overridden to `1`. ##### --minloglevel Default: `0` (INFO) The minimum level to log messages. Values are: `0` (INFO), `1` (WARN), `2` (ERROR), `3` (FATAL). ##### --stderrthreshold Default: `3` Log messages at, or above, this level are copied to `stderr` in addition to log files. ##### --callhome\_enabled Default: `true` Disable callhome diagnostics. ### Metric export flags YB-Master metrics are available in Prometheus format at `http://localhost:7000/prometheus-metrics`. ##### --export\_help\_and\_type\_in\_prometheus\_metrics Default: `true` This flag controls whether #TYPE and #HELP information is included as part of the Prometheus metrics output by default. To override this flag on a per-scrape basis, set the URL parameter `show_help` to `true` to include, or to `false` to not include type and help information. For example, querying `http://localhost:7000/prometheus-metrics?show_help=true` returns type and help information regardless of the setting of this flag. ##### --max\_prometheus\_metric\_entries Default: `4294967295` Introduced in version 2.21.1.0, this flag limits the number of Prometheus metric entries returned per scrape. If adding a metric with all its entities exceeds this limit, all entries from that metric are excluded. This could result in fewer entries than the set limit. To override this flag on a per-scrape basis, you can adjust the URL parameter `max_metric_entries`. ## PostgreSQL configuration parameters YugabyteDB uses [PostgreSQL server configuration parameters](https://www.postgresql.org/docs/15/config-setting.html "PostgreSQL server configuration parameters") to apply server configuration settings. YSQL-related flags for YB-Master are documented under [Security](#security "Security") in the [YSQL](#ysql "YSQL") subsection. For the complete PostgreSQL and YSQL flag reference on data nodes, see [PostgreSQL configuration parameters](/stable/reference/configuration/yb-tserver/#postgresql-configuration-parameters "PostgreSQL configuration parameters"). ## Networking ### RPC and binding addresses ##### --tserver\_master\_addrs Restart Needed Changes to this flag require a restart Default: `127.0.0.1:7100` Specifies a comma-separated list of all the YB-Master RPC addresses. Required. The number of comma-separated values should match the total number of YB-Master servers (or the replication factor). ##### --rpc\_bind\_addresses Restart Needed Changes to this flag require a restart T-Server / Master Match Flag value must match across all Masters and TServers Default: Private IP address of the host on which the server is running, as defined in `/home/yugabyte/master/conf/server.conf`. For example: ```sh egrep -i rpc /home/yugabyte/master/conf/server.conf --rpc_bind_addresses=172.161.x.x:7100 ``` Specifies the comma-separated list of the network interface addresses to which to bind for RPC connections. The values used must match on all yb-master and [yb-tserver](/stable/reference/configuration/yb-tserver/#rpc-bind-addresses "yb-tserver") configurations. Make sure that the [server\_broadcast\_addresses](#server-broadcast-addresses "server_broadcast_addresses") flag is set correctly if the following applies: - `rpc_bind_addresses` is set to `0.0.0.0` - `rpc_bind_addresses` involves public IP addresses such as, for example, `0.0.0.0:7100`, which instructs the server to listen on all available network interfaces. ##### --server\_broadcast\_addresses Restart Needed Changes to this flag require a restart Default: `""` Specifies the public IP or DNS hostname of the server (with an optional port). This value is used by servers to communicate with one another, depending on the connection policy parameter. ### Private IP and DNS caching ##### --dns\_cache\_expiration\_ms T-Server / Master Match Flag value must match across all Masters and TServers T-Server / Master Match Flag value must match across all Masters and TServers Default: `60000` (1 minute) Specifies the duration, in milliseconds, until a cached DNS resolution expires. When hostnames are used instead of IP addresses, a DNS resolver must be queried to match hostnames to IP addresses. By using a local DNS cache to temporarily store DNS lookups, DNS queries can be resolved quicker and additional queries can be avoided. This reduces latency, improves load times, and reduces bandwidth and CPU consumption. Note If this value is changed from the default, make sure to add the same value to all YB-Master and YB-TSever configurations. ##### --use\_private\_ip Restart Needed Changes to this flag require a restart Default: `never` Specifies the policy that determines when to use private IP addresses for inter-node communication. Possible values are `never`, `zone`, `cloud`, and `region`. Based on the values of the [geo-distribution flags](#geo-distribution-flags "geo-distribution flags"). Valid values for the policy are: - `never` — Always use the [--server\_broadcast\_addresses](#server-broadcast-addresses "--server_broadcast_addresses"). - `zone` — Use the private IP if destination node is located in the same cloud, region and zone; use the [--server\_broadcast\_addresses](#server-broadcast-addresses "--server_broadcast_addresses") outside the zone. - `cloud` - Use the private IP if destination node is located in the same cloud. - `region` — Use the private IP address if destination node is located in the same cloud and region; use [--server\_broadcast\_addresses](#server-broadcast-addresses "--server_broadcast_addresses") outside the region. ### Geo-distribution flags Settings related to managing geo-distributed clusters. ##### --placement\_zone Restart Needed Changes to this flag require a restart Default: `rack1` The name of the availability zone (AZ), or rack, where this instance is deployed. Rack awareness For on-premises deployments, consider racks as zones to treat them as fault domains. ##### --placement\_region Restart Needed Changes to this flag require a restart Default: `datacenter1` Name of the region or data center where this instance is deployed. ##### --placement\_cloud Restart Needed Changes to this flag require a restart Default: `cloud1` Name of the cloud where this instance is deployed. ##### --placement\_uuid Restart Needed Changes to this flag require a restart Default: `""` The unique identifier for the cluster. ##### --force\_global\_transactions Default: `false` If true, forces all transactions through this instance to always be global transactions that use the `system.transactions` transaction status table. This is equivalent to always setting the YSQL parameter `force_global_transaction = TRUE`. Global transaction latency Avoid setting this flag when possible. All distributed transactions *can* run without issue as global transactions, but you may have significantly higher latency when committing transactions, because YugabyteDB must achieve consensus across multiple regions to write to `system.transactions`. When necessary, it is preferable to selectively set the YSQL parameter `force_global_transaction = TRUE` rather than setting this flag. ##### --auto\_create\_local\_transaction\_tables Default: `true` If true, transaction tables will be automatically created for any YSQL tablespace which has a placement and at least one other table in it. ### Network compression flags Use the following two flags to configure RPC compression: ##### --enable\_stream\_compression Restart Needed Changes to this flag require a restart Default: `true` Controls whether YugabyteDB uses RPC compression. ##### --stream\_compression\_algo Restart Needed Changes to this flag require a restart Default: `0` Specifies which RPC compression algorithm to use. Requires `enable_stream_compression` to be set to true. Valid values are: 0: No compression (default value) 1: Gzip 2: Snappy 3: LZ4 In most cases, LZ4 (`--stream_compression_algo=3`) offers the best compromise of compression performance versus CPU overhead. However, the default is set to 0, to avoid latency penalty on workloads. ## Storage & data management ### Filesystem and WAL directories ##### --fs\_data\_dirs Restart Needed Changes to this flag require a restart Specifies a comma-separated list of mount directories, where yb-master will add a `yb-data/master` data directory, `master.err`, `master.out`, and `pg_data` directory. Required. Changing the value of this flag after the cluster has already been created is not supported. ##### --fs\_wal\_dirs Restart Needed Changes to this flag require a restart Default: Same value as `--fs_data_dirs` Specifies a comma-separated list of directories, where yb-master will store write-ahead (WAL) logs. This can be the same as one of the directories listed in `--fs_data_dirs`, but not a subdirectory of a data directory. ### Write ahead log (WAL) flags In a typical deployment, the values used for write ahead log (WAL) flags in [yb-tserver](/stable/reference/configuration/yb-tserver/#write-ahead-log-wal-flags "yb-tserver") configurations should align with those in yb-master configurations. ##### --durable\_wal\_write Restart Needed Changes to this flag require a restart Default: `true` If set to `false`, the writes to the WAL are synced to disk every [interval\_durable\_wal\_write\_ms](#interval-durable-wal-write-ms "interval_durable_wal_write_ms") milliseconds (ms) or every [bytes\_durable\_wal\_write\_mb](#bytes-durable-wal-write-mb "bytes_durable_wal_write_mb") megabyte (MB), whichever comes first. Using `false` is recommended only for multi-AZ or multi-region deployments where the availability zones (AZs) or regions are independent failure domains and there is not a risk of correlated power loss. For single-AZ deployments, keep this flag `true`. ##### --interval\_durable\_wal\_write\_ms Restart Needed Changes to this flag require a restart Default: `1000` When [--durable\_wal\_write](#durable-wal-write "--durable_wal_write") is false, writes to the WAL are synced to disk every `--interval_durable_wal_write_ms` or [--bytes\_durable\_wal\_write\_mb](#bytes-durable-wal-write-mb "--bytes_durable_wal_write_mb"), whichever comes first. ##### --bytes\_durable\_wal\_write\_mb Restart Needed Changes to this flag require a restart Default: `1` When [--durable\_wal\_write](#durable-wal-write "--durable_wal_write") is `false`, writes to the WAL are synced to disk every `--bytes_durable_wal_write_mb` or `--interval_durable_wal_write_ms`, whichever comes first. ##### --log\_min\_seconds\_to\_retain T-Server / Master Match Flag value must match across all Masters and TServers Default: `7200` (2 hours) The minimum duration, in seconds, to retain WAL segments, regardless of durability requirements. WAL segments can be retained for a longer amount of time, if they are necessary for correct restart. This value should be set long enough such that a tablet server which has temporarily failed can be restarted in the given time period. The `--log_min_seconds_to_retain` value should match the value for [--follower\_unavailable\_considered\_failed\_sec](#follower-unavailable-considered-failed-sec "--follower_unavailable_considered_failed_sec"). ##### --log\_min\_segments\_to\_retain T-Server / Master Match Flag value must match across all Masters and TServers Default: `2` The minimum number of WAL segments (files) to retain, regardless of durability requirements. The value must be at least `1`. ##### --log\_segment\_size\_mb T-Server / Master Match Flag value must match across all Masters and TServers Restart Needed Changes to this flag require a restart Default: `64` The size, in megabytes (MB), of a WAL segment (file). When the WAL segment reaches the specified size, then a log rollover occurs and a new WAL segment file is created. ##### --reuse\_unclosed\_segment\_threshold\_bytes T-Server / Master Match Flag value must match across all Masters and TServers Default: `9223372036854775807` When the server restarts from a previous crash, if the tablet's last WAL file size is less than or equal to this threshold value, the last WAL file will be reused. Otherwise, WAL will allocate a new file at bootstrap. To disable WAL reuse, set the value to `-1`. ### Cluster balancing flags For information on YB-Master cluster balancing, see [Cluster balancing](/stable/architecture/yb-master/#cluster-balancing "Cluster balancing"). For cluster balancing commands in yb-admin, see [Cluster balancing commands (yb-admin)](/stable/admin/yb-admin/#cluster-balancing-commands "Cluster balancing commands (yb-admin)"). For detailed information on cluster balancing scenarios, monitoring, and configuration, see [Cluster balancing](/stable/architecture/docdb-sharding/cluster-balancing/ "Cluster balancing"). ##### --enable\_load\_balancing Default: `true` Enables or disables the cluster balancing algorithm, to move tablets around. ##### --leader\_balance\_threshold Default: `0` Specifies the number of leaders per tablet server to balance below. If this is configured to `0` (the default), the leaders will be balanced optimally at extra cost. ##### --leader\_balance\_unresponsive\_timeout\_ms Default: `3000` (3 seconds) Specifies the period of time, in milliseconds, that a YB-Master can go without receiving a heartbeat from a YB-TServer before considering it unresponsive. Unresponsive servers are excluded from leader balancing. ##### --load\_balancer\_max\_concurrent\_adds Default: `25` Specifies the maximum number of tablet peer replicas to add in a cluster balancer operations. ##### --load\_balancer\_max\_concurrent\_moves Default: `100` Specifies the maximum number of tablet leaders on tablet servers (across the cluster) to move in any one run of the cluster balancer. ##### --load\_balancer\_max\_concurrent\_moves\_per\_table Default: `-1` Specifies the maximum number of tablet leaders per table to move in any one run of the cluster balancer. The maximum number of tablet leader moves across the cluster is still limited by the flag `load_balancer_max_concurrent_moves`. This flag is meant to prevent a single table from using all of the leader moves quota and starving other tables. If set to -1, the number of leader moves per table is set to the global number of leader moves (`load_balancer_max_concurrent_moves`). ##### --load\_balancer\_max\_concurrent\_removals Default: `50` Specifies the maximum number of over-replicated tablet peer removals to do in any one run of the cluster balancer. A value less than 0 means no limit. ##### --load\_balancer\_max\_concurrent\_tablet\_remote\_bootstraps Default: `-1` Specifies the maximum number of tablets being remote bootstrapped across the cluster. ##### --load\_balancer\_max\_concurrent\_tablet\_remote\_bootstraps\_per\_table Default: `-1` Maximum number of tablets being remote bootstrapped for any table. The maximum number of remote bootstraps across the cluster is still limited by the flag `load_balancer_max_concurrent_tablet_remote_bootstraps`. This flag is meant to prevent a single table use all the available remote bootstrap sessions and starving other tables. ##### --load\_balancer\_max\_over\_replicated\_tablets Default: `50` Specifies the maximum number of running tablet replicas per table that are allowed to be over the configured replication factor. This controls the amount of space amplification in the cluster when tablet removal is slow. A value less than 0 means no limit. ##### --load\_balancer\_num\_idle\_runs Default: `5` Specifies the number of idle runs of load balancer to deem it idle. ##### --load\_balancer\_skip\_leader\_as\_remove\_victim Deprecated Default: `false` Should the LB skip a leader as a possible remove candidate. ### Sharding flags ##### --replication\_factor Default: `3` The number of replicas, or copies of data, to store for each tablet in the universe. ##### --yb\_num\_shards\_per\_tserver T-Server / Master Match Flag value must match across all Masters and TServers Default: `-1`, where the number of shards is determined at runtime, as follows: The number of shards (tablets) per YB-TServer for each YCQL table when a user table is created. - If [enable\_automatic\_tablet\_splitting](#enable-automatic-tablet-splitting "enable_automatic_tablet_splitting") is `true` - The default value is considered as `1`. - For servers with 4 CPU cores or less, the number of tablets for each table doesn't depend on the number of YB-TServers. Instead, for 2 CPU cores or less, 1 tablet per cluster is created; for 4 CPU cores or less, 2 tablets per cluster are created. - If `enable_automatic_tablet_splitting` is `false` - For servers with up to two CPU cores, the default value is considered as `4`. - For three or more CPU cores, the default value is considered as `8`. Local cluster installations created using yb-ctl and yb-docker-ctl use a default value of `2` for this flag. Clusters created using yugabyted always use a default value of `1`. Note - This value must match on all yb-master and yb-tserver configurations of a YugabyteDB cluster. - If the value is set to *Default* (`-1`), then the system automatically determines an appropriate value based on the number of CPU cores and internally *updates* the flag with the intended value during startup prior to version 2.18 and the flag remains *unchanged* starting from version 2.18. - The [CREATE TABLE ... WITH TABLETS =](/stable/api/ycql/ddl_create_table/#create-a-table-specifying-the-number-of-tablets "CREATE TABLE ... WITH TABLETS = ") clause can be used on a per-table basis to override the `yb_num_shards_per_tserver` value. ##### --ysql\_num\_shards\_per\_tserver T-Server / Master Match Flag value must match across all Masters and TServers Default: `-1`, where the number of shards is determined at runtime, as follows: The number of shards (tablets) per YB-TServer for each YSQL table when a user table is created. - If [enable\_automatic\_tablet\_splitting](#enable-automatic-tablet-splitting "enable_automatic_tablet_splitting") is `true` - The default value is considered as `1`. - For servers with 4 CPU cores or less, the number of tablets for each table doesn't depend on the number of YB-TServers. Instead, for 2 CPU cores or less, 1 tablet per cluster is created; for 4 CPU cores or less, 2 tablets per cluster are created. - If `enable_automatic_tablet_splitting` is `false` - For servers with up to two CPU cores, the default value is considered as `2`. - For servers with three or four CPU cores, the default value is considered as `4`. - Beyond four cores, the default value is considered as `8`. Local cluster installations created using yb-ctl and yb-docker-ctl use a default value of `2` for this flag. Clusters created using yugabyted always use a default value of `1`. Note - This value must match on all yb-master and yb-tserver configurations of a YugabyteDB cluster. - If the value is set to *Default* (`-1`), the system automatically determines an appropriate value based on the number of CPU cores and internally *updates* the flag with the intended value during startup prior to version 2.18 and the flag remains *unchanged* starting from version 2.18. - The [CREATE TABLE ...SPLIT INTO](/stable/api/ysql/the-sql-language/statements/ddl_create_table/#split-into "CREATE TABLE ...SPLIT INTO") clause can be used on a per-table basis to override the `ysql_num_shards_per_tserver` value. ##### --cleanup\_split\_tablets\_interval\_sec Default: `60` Interval at which the tablet manager tries to cleanup split tablets that are no longer needed. Setting this to 0 disables cleanup of split tablets. ##### --ysql\_colocate\_database\_by\_default Restart Needed Changes to this flag require a restart Default: `false` When enabled, all databases created in the cluster are colocated by default. If you enable the flag after creating a cluster, you need to restart the YB-Master and YB-TServer services. For more details, see [clusters in colocated tables](/stable/additional-features/colocation/ "clusters in colocated tables"). ##### enforce\_tablet\_replica\_limits Default: `false` Enables/disables blocking of requests which would bring the total number of tablets in the system over a limit. For more information, see [Tablet limits](/stable/architecture/docdb-sharding/tablet-splitting/#tablet-limits "Tablet limits"). ##### split\_respects\_tablet\_replica\_limits Default: `false` If set, tablets will not be split if the total number of tablet replicas in the cluster after the split would exceed the limit after the split. ##### tablet\_replicas\_per\_core\_limit Default: `0` for no limit. The number of tablet replicas that each core on a YB-TServer can support. ##### tablet\_replicas\_per\_gib\_limit Default: `1462` The number of tablet replicas that each GiB reserved by YB-TServers for tablet overheads can support. ### Tablet splitting flags ##### --max\_create\_tablets\_per\_ts Default: `50` The maximum number of tablets per tablet server that can be specified when creating a table. This also limits the number of tablets that can be created by tablet splitting. ##### --enable\_automatic\_tablet\_splitting T-Server / Master Match Flag value must match across all Masters and TServers Default: Auto flag — initial `false`, target `true` (after promotion, behaves as `true`; see [All YB-Master flags](/stable/reference/configuration/all-flags-yb-master/ "All YB-Master flags") for full metadata) Enables YugabyteDB to [automatically split tablets](/stable/architecture/docdb-sharding/tablet-splitting/#automatic-tablet-splitting "automatically split tablets"), based on the specified tablet threshold sizes configured below. Important This value must match on all yb-master and yb-tserver configurations of a YugabyteDB cluster. ##### --tablet\_split\_low\_phase\_shard\_count\_per\_node Default: `1` The threshold number of shards (per cluster node) in a table below which automatic tablet splitting will use [--tablet\_split\_low\_phase\_size\_threshold\_bytes](/stable/reference/configuration/yb-master/#tablet-split-low-phase-size-threshold-bytes "--tablet_split_low_phase_size_threshold_bytes") to determine which tablets to split. ##### --tablet\_split\_low\_phase\_size\_threshold\_bytes Default: `134217728` The size threshold used to determine if a tablet should be split when the tablet's table is in the "low" phase of automatic tablet splitting. See [--tablet\_split\_low\_phase\_shard\_count\_per\_node](/stable/reference/configuration/yb-master/#tablet-split-low-phase-shard-count-per-node "--tablet_split_low_phase_shard_count_per_node"). ##### --tablet\_split\_high\_phase\_shard\_count\_per\_node Default: `24` The threshold number of shards (per cluster node) in a table below which automatic tablet splitting will use [--tablet\_split\_high\_phase\_size\_threshold\_bytes](/stable/reference/configuration/yb-master/#tablet-split-high-phase-size-threshold-bytes "--tablet_split_high_phase_size_threshold_bytes") to determine which tablets to split. ##### --tablet\_split\_high\_phase\_size\_threshold\_bytes Default: `10737418240` The size threshold used to determine if a tablet should be split when the tablet's table is in the "high" phase of automatic tablet splitting. See [--tablet\_split\_high\_phase\_shard\_count\_per\_node](/stable/reference/configuration/yb-master/#tablet-split-high-phase-shard-count-per-node "--tablet_split_high_phase_shard_count_per_node"). ##### --tablet\_force\_split\_threshold\_bytes Default: `107374182400` The size threshold used to determine if a tablet should be split even if the table's number of shards puts it past the "high phase". ##### --tablet\_split\_limit\_per\_table Default: `0` The maximum number of tablets per table for tablet splitting. Limitation is disabled if this value is set to 0. ##### --index\_backfill\_tablet\_split\_completion\_timeout\_sec Default: `30` Total time to wait for tablet splitting to complete on a table on which a backfill is running before aborting the backfill and marking it as failed. ##### --index\_backfill\_tablet\_split\_completion\_poll\_freq\_ms Default: `2000` Delay before retrying to see if tablet splitting has completed on the table on which a backfill is running. ##### --process\_split\_tablet\_candidates\_interval\_msec Default: `0` The minimum time between automatic splitting attempts. The actual splitting time between runs is also affected by `catalog_manager_bg_task_wait_ms`, which controls how long the background tasks thread sleeps at the end of each loop. ##### --outstanding\_tablet\_split\_limit Default: `0` Limits the number of total outstanding tablet splits. Limitation is disabled if value is set to `0`. Limit includes tablets that are performing post-split compactions. ##### --outstanding\_tablet\_split\_limit\_per\_tserver Default: `-1` Limits the number of outstanding tablet splits per node. Limit includes tablets that are performing post-split compactions. - `-1` (default): the limit is derived from the CPU count (`1` for nodes with up to 4 cores, `2` otherwise). - `0`: limitation is disabled. - A positive value is used as-is. ##### --enable\_tablet\_split\_of\_pitr\_tables Default: `true` Enables automatic tablet splitting of tables covered by Point-In-Time Recovery schedules. ##### --prevent\_split\_for\_ttl\_tables\_for\_seconds Default: `86400` Number of seconds between checks for whether to split a tablet with a default TTL. Checks are disabled if this value is set to 0. ##### --prevent\_split\_for\_small\_key\_range\_tablets\_for\_seconds Default: `300` Number of seconds between checks for whether to split a tablet whose key range is too small to be split. Checks are disabled if this value is set to 0. ##### --sort\_automatic\_tablet\_splitting\_candidates Default: `true` Determines whether to sort automatic split candidates from largest to smallest (prioritizing larger tablets for split). Syntax: ```sh yb-admin --master_addresses --tablet_force_split_size_threshold_bytes ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. - *bytes*: The threshold size, in bytes, after which tablets should be split. Default value of `0` disables automatic tablet splitting. For details on automatic tablet splitting, see the following: - [Automatic tablet splitting](/stable/architecture/docdb-sharding/tablet-splitting/ "Automatic tablet splitting") — Architecture overview. - [Automatic Re-sharding of Data with Tablet Splitting](https://github.com/yugabyte/yugabyte-db/blob/master/architecture/design/docdb-automatic-tablet-splitting.md "Automatic Re-sharding of Data with Tablet Splitting") — Architecture design document in the GitHub repository. ### DDL atomicity flags ##### ysql\_yb\_ddl\_rollback\_enabled Default: `true` Enable DDL atomicity. When a DDL transaction that affects the DocDB system catalog fails, YB-Master will roll back the changes made to the DocDB system catalog. Important In YSQL, a DDL statement creates a separate DDL transaction to execute the DDL statement. A DDL transaction generally needs to read and write PostgreSQL metadata stored in catalog tables in the same way as a native PostgreSQL DDL statement. In addition, some DDL statements also involve updating DocDB system catalog table (for example, a DDL statement such as `alter table add/drop column`). When a DDL transaction fails, the corresponding DDL statement is aborted. This means that the PostgreSQL metadata will be rolled back atomically. Before the introduction of the flag `--ysql_yb_ddl_rollback_enabled`, the DocDB system catalog changes were not automatically rolled back by YB-Master, possibly leading to metadata corruption that had to be manually fixed. Currently, with this flag being set to true, YB-Master can rollback the DocDB system catalog changes automatically to prevent metadata corruption. ##### report\_ysql\_ddl\_txn\_status\_to\_master Default: `true` If set, at the end of a DDL operation the YB-TServer notifies the YB-Master whether the DDL operation was committed or aborted. Important Due to implementation restrictions, after a DDL statement commits or aborts, YB-Master performs a relatively expensive operation by continuously polling the transaction status tablet, and comparing the DocDB schema with PostgreSQL schema to determine whether the transaction was a success. This behavior is optimized with the flag `report_ysql_ddl_txn_status_to_master`, where at the end of a DDL transaction, YSQL sends the status of the transaction (commit/abort) to YB-Master. Once received, YB-Master can stop polling the transaction status tablet, and also skip the relatively expensive schema comparison. ##### ysql\_ddl\_transaction\_wait\_for\_ddl\_verification Default: `true` If set, DDL transactions will wait for DDL verification to complete before returning to the client. Important After a DDL statement that includes updating DocDB system catalog completes, YB-Master still needs to work on the DocDB system catalog changes in the background asynchronously, to ensure that they are eventually in sync with the corresponding PostgreSQL catalog changes. This can take additional time in order to reach eventual consistency. During this period, an immediately succeeding DML or DDL statement can fail due to changes made by YB-Master to the DocDB system catalog in the background, which may cause confusion. When the flag `ysql_ddl_transaction_wait_for_ddl_verification` is enabled, YSQL waits for any YB-Master background operations to finish before returning control to the user. ### Change data capture (CDC) flags To learn about CDC, see [Change data capture (CDC)](/stable/architecture/docdb-replication/change-data-capture/ "Change data capture (CDC)"). For information on other CDC configuration flags, see [YB-TServer's CDC flags](/stable/reference/configuration/yb-tserver/#change-data-capture-cdc-flags "YB-TServer's CDC flags"). ##### --yb\_enable\_cdc\_consistent\_snapshot\_streams [TP](/stable/releases/versioning/#feature-maturity) Default: `false` Support for creating a stream for Transactional CDC is currently in [Tech Preview](/stable/releases/versioning/#feature-maturity "Tech Preview"). Enable support for creating streams for transactional CDC. ##### --cdc\_state\_checkpoint\_update\_interval\_ms Default: `15000` The rate at which CDC state's checkpoint is updated. ##### --cdc\_snapshot\_batch\_size Default: `250` Number of records fetched in a single batch of snapshot operation of CDC. ##### --cdc\_min\_replicated\_index\_considered\_stale\_secs Default: `900` (15 minutes) If `cdc_min_replicated_index` hasn't been replicated in this amount of time, we reset its value to max int64 to avoid retaining any logs. ##### --timestamp\_history\_retention\_interval\_sec Default: `900` (15 minutes) Time interval (in seconds) to retain history or older versions of data. ##### --update\_min\_cdc\_indices\_interval\_secs Default: `60` How often to read the `cdc_state` table to get the minimum applied index for each tablet across all streams. This information is used to correctly keep log files that contain unapplied entries. This is also the rate at which a tablet's minimum replicated index across all streams is sent to the other peers in the configuration. If flag `enable_log_retention_by_op_idx` (default: `true`) is disabled, this flag has no effect. ##### --cdc\_checkpoint\_opid\_interval\_ms Restart Needed Changes to this flag require a restart Default: `60000` Warning If you are using multiple streams, it is advised that you set this flag to `1800000` (30 minutes). ##### --log\_max\_seconds\_to\_retain Restart Needed Changes to this flag require a restart Default: `86400` Number of seconds to retain log files. Log files older than this value will be deleted even if they contain unreplicated CDC entries. If 0, this flag will be ignored. This flag is ignored if a log segment contains entries that haven't been flushed to RocksDB. ##### --log\_stop\_retaining\_min\_disk\_mb Restart Needed Changes to this flag require a restart Default: `100` Stop retaining logs if the space available for the logs falls below this limit, specified in megabytes. As with `log_max_seconds_to_retain`, this flag is ignored if a log segment contains unflushed entries. ##### --cdc\_max\_stream\_intent\_records Default: `1680` Maximum number of intent records allowed in a single CDC batch. ##### --cdc\_state\_table\_num\_tablets Default: `0` (Use the same default number of tablets as for regular tables.) The number of tablets to use when creating the CDC state table. Used in both xCluster and CDCSDK. ##### --cdc\_wal\_retention\_time\_secs Default: `28800` (8 hours) WAL retention time, in seconds, to be used for tables for which a CDC stream was created. Used in both xCluster and CDCSDK. ##### --cdc\_intent\_retention\_ms Default: `28800000` (8 hours) The time period, in milliseconds, after which the intents will be cleaned up if there is no client polling for the change records. ##### --cdcsdk\_tablet\_not\_of\_interest\_timeout\_secs Default: `14400` (4 hours) Timeout after which it is inferred that a particular tablet is not of interest for CDC. To indicate that a particular tablet is of interest for CDC, it should be polled at least once within this interval of stream / slot creation. ##### --enable\_tablet\_split\_of\_cdcsdk\_streamed\_tables Default: `true` Toggle automatic tablet splitting for tables in a CDCSDK stream, enhancing user control over replication processes. ##### --enable\_truncate\_cdcsdk\_table Default: `false` By default, TRUNCATE commands on tables with an active CDCSDK stream will fail. Change this flag to `true` to enable truncating tables. ##### --enable\_tablet\_split\_of\_replication\_slot\_streamed\_tables Default: `true` Toggle automatic tablet splitting for tables under replication slot. Applicable only to CDC using the [PostgreSQL logical replication protocol](/stable/additional-features/change-data-capture/using-logical-replication/ "PostgreSQL logical replication protocol"). ##### --ysql\_yb\_enable\_implicit\_dynamic\_tables\_logical\_replication T-Server / Master Match Flag value must match across all Masters and TServers Restart Needed Changes to this flag require a restart Default: `true` Available in v2026.1 and later. When set to `true`, modifications to a publication are reflected implicitly in logical replication streams, providing PostgreSQL-like semantics for dynamic tables. When set to `false`, CDC uses a periodic publication refresh mechanism. (This is the bahavior in versions earlier than v2026.1.) For more information, refer to [Adding tables to publication](/stable/additional-features/change-data-capture/using-logical-replication/advanced-topic/#adding-tables-to-publication "Adding tables to publication"). ##### --enable\_table\_rewrite\_for\_cdcsdk\_table T-Server / Master Match Flag value must match across all Masters and TServers Default: `true` When set to `true`, CDC does not block DDLs that cause table rewrites on tables with active logical replication streams. CDC streams records from the re-written tablets after finishing data from the older tablets. When set to `false`, any DDL that causes a table rewrite is blocked when CDC is active on the database (this is also the behavior in versions earlier than v2026.1). For more information, refer to [Streaming DDLs causing table rewrite](/stable/additional-features/change-data-capture/using-logical-replication/advanced-topic/#streaming-ddls-causing-table-rewrite "Streaming DDLs causing table rewrite"). ### LISTEN/NOTIFY flags [EA](/stable/releases/versioning/#feature-maturity) Available in v2025.2.3 and later. To learn about LISTEN/NOTIFY, see [LISTEN, NOTIFY, and UNLISTEN](/stable/api/ysql/the-sql-language/statements/cmd_listen_notify/ "LISTEN, NOTIFY, and UNLISTEN"). ##### --ysql\_yb\_enable\_listen\_notify T-Server / Master Match Flag value must match across all Masters and TServers Default: `false` Enables YSQL LISTEN/NOTIFY. ### File expiration based on TTL flags ##### --tablet\_enable\_ttl\_file\_filter Restart Needed Changes to this flag require a restart Default: `false` Turn on the file expiration for TTL feature. ##### --rocksdb\_max\_file\_size\_for\_compaction Default: `0` For tables with a `default_time_to_live` table property, sets a size threshold at which files will no longer be considered for compaction. Files over this threshold will still be considered for expiration. Disabled if value is `0`. Ideally, `rocksdb_max_file_size_for_compaction` should strike a balance between expiring data at a reasonable frequency and not creating too many SST files (which can impact read performance). For instance, if 90 days worth of data is stored, consider setting this flag to roughly the size of one day's worth of data. If `rocksdb_max_file_size_for_compaction` was set to a certain value on a cluster and then it needs to be increased, then it is highly likely that all the existing files on the tablets will become eligible for background compactions and a lot of compaction activity will occur in the system. This can lead to system instability if the concurrent user activity in the system is high. If TTL flags need to be tuned in order to accomodate increased usage on the table, it is better to consider splitting the tablet or increasing the `sst_files_soft_limit` and `sst_files_hard_limit` instead. ##### --sst\_files\_soft\_limit Default: `24` Threshold for number of SST files per tablet. When exceeded, writes to a tablet will be throttled until the number of files is reduced. ##### --sst\_files\_hard\_limit Default: `48` Threshold for number of SST files per tablet. When exceeded, writes to a tablet will no longer be allowed until the number of files is reduced. ##### --file\_expiration\_ignore\_value\_ttl Default: `false` When set to true, ignores any value-level TTL metadata when determining file expiration. Helpful in situations where some SST files are missing the necessary value-level metadata (in case of upgrade, for instance). Warning Use of this flag can potentially result in expiration of live data. Use at your discretion. ##### --file\_expiration\_value\_ttl\_overrides\_table\_ttl Default: `false` When set to true, allows files to expire purely based on their value-level TTL expiration time (even if it is lower than the table TTL). This is helpful for situations where a file needs to expire earlier than its table-level TTL would allow. If no value-level TTL metadata is available, then table-level TTL will still be used. Warning Use of this flag can potentially result in expiration of live data. Use at your discretion. ### Packed row flags The packed row format for the YSQL API is [GA](/stable/releases/versioning/#feature-maturity) as of v2.20.0, and for the YCQL API is [TP](/stable/releases/versioning/#feature-maturity) . To learn about the packed row feature, see [Packed rows in DocDB](/stable/architecture/docdb/packed-rows/ "Packed rows in DocDB") in the architecture section. ##### --ysql\_enable\_packed\_row Default: `true` Whether packed row is enabled for YSQL. Packed Row for YSQL can be used from version 2.16.4 in production environments if the cluster is not used in xCluster settings. For xCluster scenarios, use version 2.18.1 and later. Starting from version 2.19 and later, the flag default is true for new clusters. ##### --ysql\_enable\_packed\_row\_for\_colocated\_table Default: `true` Whether packed row is enabled for colocated tables in YSQL. The colocated table has an additional flag to mitigate [#15143](https://github.com/yugabyte/yugabyte-db/issues/15143 "#15143"). ##### --ysql\_packed\_row\_size\_limit Restart Needed Changes to this flag require a restart Default: `0` Packed row size limit for YSQL. The default value is 0 (use block size as limit). For rows that are over this size limit, a greedy approach will be used to pack as many columns as possible, with the remaining columns stored as individual key-value pairs. ##### --ycql\_enable\_packed\_row [TP](/stable/releases/versioning/#feature-maturity) Default: `false` YCQL packed row support is currently in [Tech Preview](/stable/releases/versioning/#feature-maturity "Tech Preview"). Whether packed row is enabled for YCQL. ##### --ycql\_packed\_row\_size\_limit Restart Needed Changes to this flag require a restart Default: `0` Packed row size limit for YCQL. The default value is 0 (use block size as limit). For rows that are over this size limit, a greedy approach will be used to pack as many columns as possible, with the remaining columns stored as individual key-value pairs. ### Catalog flags For information on setting these flags, see [Customize preloading of YSQL catalog caches](/stable/best-practices-operations/ysql-catalog-cache-tuning-guide/ "Customize preloading of YSQL catalog caches"). ##### --ysql\_catalog\_preload\_additional\_table\_list Restart Needed Changes to this flag require a restart Default: `""` Specifies the names of catalog tables (such as `pg_operator`, `pg_proc`, and `pg_amop`) to be preloaded by PostgreSQL backend processes. This flag reduces latency of first query execution of a particular statement on a connection. If [ysql\_catalog\_preload\_additional\_tables](#ysql-catalog-preload-additional-tables "ysql_catalog_preload_additional_tables") is also specified, the union of the above specified catalog tables and `pg_am`, `pg_amproc`, `pg_cast`, and `pg_tablespace` is preloaded. ##### --ysql\_catalog\_preload\_additional\_tables Restart Needed Changes to this flag require a restart Default: `false` When enabled, the PostgreSQL backend processes preload the `pg_am`, `pg_amproc`, `pg_cast`, and `pg_tablespace` catalog tables. This flag reduces latency of first query execution of a particular statement on a connection. If [ysql\_catalog\_preload\_additional\_table\_list](#ysql-catalog-preload-additional-table-list "ysql_catalog_preload_additional_table_list") is also specified, the union of `pg_am`, `pg_amproc`, `pg_cast`, and `pg_tablespace` and the tables specified in `ysql_catalog_preload_additional_table_list` is preloaded. ##### --ysql\_enable\_read\_request\_caching Restart Needed Changes to this flag require a restart Default: `true` Enables the YB-TServer catalog cache, which reduces YB-Master overhead for starting a connection and internal system catalog metadata refresh (for example, after executing a DDL), when there are many YSQL connections per node. ##### --ysql\_minimal\_catalog\_caches\_preload Restart Needed Changes to this flag require a restart Default: `false` Defines what part of the catalog gets cached and preloaded by default. As a rule of thumb, preloading more means lower first-query latency (as most/all necessary metadata will already be in the cache) at a cost of higher per-connection memory. Preloading less of the catalog means less memory though can result in a higher mean first-query latency (as we may need to ad-hoc lookup more catalog entries first time we execute a query). This flag only loads the system catalog tables (but not the user objects) which should keep memory low, while loading all often used objects. Still user-object will need to be loaded ad-hoc, which can make first-query latency a bit higher (most impactful in multi-region clusters). ##### --ysql\_use\_relcache\_file Restart Needed Changes to this flag require a restart Default: `true` Controls whether to use the PostgreSQL relcache init file, which caches critical system catalog entries. If enabled, each PostgreSQL connection loads only this minimal set of cached entries (except if the relcache init file needs to be re-built, for example, after a DDL invalidates the cache). If disabled, each PostgreSQL connection preloads the catalog cache, which consumes more memory but reduces first query latency. ##### --ysql\_yb\_toast\_catcache\_threshold Default: `2048` Specifies the threshold (in bytes) beyond which catalog tuples will get compressed when they are stored in the PostgreSQL catalog cache. Setting this flag reduces memory usage for certain large objects, including functions and views, in exchange for slower catalog refreshes. To minimize performance impact when enabling this flag, set it to 2KB or higher. ##### --ysql\_enable\_db\_catalog\_version\_mode Deprecated Deprecated Per-database catalog version mode is now mandatory. This flag is deprecated and has no effect; if set explicitly, a deprecation warning is logged at startup and the value is ignored. In per-database catalog version mode, a DDL statement that affects the current database can only increment the catalog version for that database. As a result, multiple DDL statements can be concurrently executed if each DDL only affects its current database and is executed in a separate database. Existing connections only need to refresh their catalog caches if they are connected to the same database as that of a DDL statement. ##### --enable\_heartbeat\_pg\_catalog\_versions\_cache Restart Needed Changes to this flag require a restart Default: `false` Whether to enable the use of heartbeat catalog versions cache for the `pg_yb_catalog_version` table which can help to reduce the number of reads from the table. This is beneficial when there are many databases and/or many yb-tservers in the cluster. Important Each YB-TServer regularly sends a heartbeat request to the YB-Master leader. As part of the heartbeat response, YB-Master leader reads all the rows in the table `pg_yb_catalog_version` and sends the result back in the heartbeat response. As there is one row in the table `pg_yb_catalog_version` for each database, the cost of reading `table pg_yb_catalog_version` becomes more expensive when the number of YB-TServers, or the number of databases goes up. ##### --ysql\_yb\_enable\_invalidation\_messages Default: `true` Enables YSQL backends to generate and consume invalidation messages incrementally for schema changes. When enabled (true), invalidation messages are propagated via the `pg_yb_invalidation_messages` per-database catalog table. Details of the invalidation messages generated by a DDL are also logged when [ysql\_log\_min\_messages](/stable/reference/configuration/yb-tserver/#ysql-log-min-messages "ysql_log_min_messages") is set to `DEBUG1` or when `yb_debug_log_catcache_events` is set to true. When disabled, schema changes cause a full catalog cache refresh on existing backends, which can result in a latency and memory spike on existing YSQL backends. ## Performance tuning ### Memory division flags These flags are used to determine how the RAM of a node is split between the [TServer](/stable/architecture/key-concepts/#tserver "TServer") and other processes, including the PostgreSQL processes and a [Master](/stable/architecture/key-concepts/#master-server "Master") process if present, as well as how to split memory inside of a TServer between various internal components like the RocksDB block cache. Do not oversubscribe memory Ensure you do not oversubscribe memory when changing these flags. When reserving memory for TServer and Master (if present), you must leave enough memory on the node for PostgreSQL, any required other processes like monitoring agents, and the memory needed by the kernel. #### Flags controlling the defaults for the other memory division flags The memory division flags have multiple sets of defaults; which set of defaults is in force depends on these flags. Note that these defaults can differ between TServer and Master. ##### --use\_memory\_defaults\_optimized\_for\_ysql Restart Needed Changes to this flag require a restart Default: `false` When creating a new universe using yugabyted or YugabyteDB Anywhere, the flag is set to `true`. If true, the defaults for the memory division settings take into account the amount of RAM and cores available and are optimized for using YSQL. If false, the defaults will be the old defaults, which are more suitable for YCQL but do not take into account the amount of RAM and cores available. For information on how memory is divided among processes when this flag is set, refer to [Memory division defaults](/stable/reference/configuration/smart-defaults/ "Memory division defaults"). #### Flags controlling the split of memory among processes Note that in general these flags will have different values for TServer and Master processes. ##### --memory\_limit\_hard\_bytes Restart Needed Changes to this flag require a restart Default: `0` Maximum amount of memory this process should use in bytes, that is, its hard memory limit. A value of `0` specifies to instead use a percentage of the total system memory; see [--default\_memory\_limit\_to\_ram\_ratio](#default-memory-limit-to-ram-ratio "--default_memory_limit_to_ram_ratio") for the percentage used. A value of `-1` disables all memory limiting. For Kubernetes deployments, this flag is automatically set from the Kubernetes pod memory limits specified in the Helm chart configuration. See [Memory limits for Kubernetes deployments](/stable/deploy/kubernetes/single-zone/oss/helm-chart/#memory-limits-for-kubernetes-deployments "Memory limits for Kubernetes deployments") for details. ##### --default\_memory\_limit\_to\_ram\_ratio Restart Needed Changes to this flag require a restart Default: `-1000` (use the built-in default ratio; commonly `0.10` when [--use\_memory\_defaults\_optimized\_for\_ysql](#use-memory-defaults-optimized-for-ysql "--use_memory_defaults_optimized_for_ysql") is false). The percentage of available RAM to use for this process if [--memory\_limit\_hard\_bytes](#memory-limit-hard-bytes "--memory_limit_hard_bytes") is `0`. The special value `-1000` selects that built-in default. Available RAM excludes memory reserved by the kernel. This flag does not apply to Kubernetes universes. Memory limits are controlled via Kubernetes resource specifications in the Helm chart, and `--memory_limit_hard_bytes` is automatically set from those limits. See [Memory limits for Kubernetes deployments](/stable/deploy/kubernetes/single-zone/oss/helm-chart/#memory-limits-for-kubernetes-deployments "Memory limits for Kubernetes deployments") for details. #### Flags controlling the split of memory within a Master These settings control the division of memory available to the Master process. ##### --db\_block\_cache\_size\_bytes Restart Needed Changes to this flag require a restart Default: `-1` Size of the shared RocksDB block cache (in bytes). A value of `-1` specifies to instead use a percentage of this processes' hard memory limit; see [--db\_block\_cache\_size\_percentage](#db-block-cache-size-percentage "--db_block_cache_size_percentage") for the percentage used. A value of `-2` disables the block cache. ##### --db\_block\_cache\_size\_percentage Restart Needed Changes to this flag require a restart Default: `-1000` (use the built-in default percentage; commonly `25` when [--use\_memory\_defaults\_optimized\_for\_ysql](#use-memory-defaults-optimized-for-ysql "--use_memory_defaults_optimized_for_ysql") is false). Percentage of the process' hard memory limit to use for the shared RocksDB block cache if [--db\_block\_cache\_size\_bytes](#db-block-cache-size-bytes "--db_block_cache_size_bytes") is `-1`. The special value `-1000` means to use the built-in default for this flag. The special value `-3` means to use an older default that does not take the amount of RAM into account. ##### --tablet\_overhead\_size\_percentage Restart Needed Changes to this flag require a restart Default: `-1000` (use the built-in recommended value; commonly `0` when [--use\_memory\_defaults\_optimized\_for\_ysql](#use-memory-defaults-optimized-for-ysql "--use_memory_defaults_optimized_for_ysql") is false). Percentage of the process' hard memory limit to use for tablet-related overheads. A value of `0` means no limit. Must be between `0` and `100` inclusive. Exception: `-1000` specifies to instead use the default value for this flag. Each tablet replica generally requires 0.7 MiB of this tablet overhead memory. ### Raft and consistency/timing flags With the exception of flags that have different defaults for yb-master vs yb-tserver (for example, `--evict_failed_followers`), for a typical deployment, values used for Raft-related flags in yb-master configurations should match the values in [yb-tserver](/stable/reference/configuration/yb-tserver/#raft-and-consistency-timing-flags "yb-tserver") configurations. For WAL settings, see [Write ahead log (WAL) flags](#write-ahead-log-wal-flags "Write ahead log (WAL) flags"). ##### --follower\_unavailable\_considered\_failed\_sec Default: \`7200\` (2 hours) The duration, in seconds, after which a follower is considered to be failed because the leader has not received a heartbeat. The `--follower_unavailable_considered_failed_sec` value should match the value for [--log\_min\_seconds\_to\_retain](#log-min-seconds-to-retain "--log_min_seconds_to_retain"). ##### --evict\_failed\_followers Restart Needed Changes to this flag require a restart Default: `false` Failed followers will be evicted from the Raft group and the data will be re-replicated. Note that it is not recommended to set the flag to true for Masters as you cannot automatically recover a failed Master once it is evicted. ##### --leader\_failure\_max\_missed\_heartbeat\_periods Restart Needed Changes to this flag require a restart Default: `6` The maximum heartbeat periods that the leader can fail to heartbeat in before the leader is considered to be failed. The total failure timeout, in milliseconds (ms), is [--raft\_heartbeat\_interval\_ms](#raft-heartbeat-interval-ms "--raft_heartbeat_interval_ms") multiplied by `--leader_failure_max_missed_heartbeat_periods`. For read replica clusters, set the value to `10` in all yb-tserver and yb-master configurations. Because the data is globally replicated, RPC latencies are higher. Use this flag to increase the failure detection interval in such a higher RPC latency deployment. ##### --leader\_lease\_duration\_ms Restart Needed Changes to this flag require a restart Default: `2000` The leader lease duration, in milliseconds. A leader keeps establishing a new lease or extending the existing one with every consensus update. A new server is not allowed to serve as a leader (that is, serve up-to-date read requests or acknowledge write requests) until a lease of this duration has definitely expired on the old leader's side, or the old leader has explicitly acknowledged the new leader's lease. This lease allows the leader to safely serve reads for the duration of its lease, even during a network partition. For more information, refer to [Leader leases](/stable/architecture/transactions/single-row-transactions/#leader-leases-reading-the-latest-data-in-case-of-a-network-partition "Leader leases"). Leader lease duration should be longer than the heartbeat interval, and less than the multiple of `--leader_failure_max_missed_heartbeat_periods` multiplied by `--raft_heartbeat_interval_ms`. ##### --raft\_heartbeat\_interval\_ms Restart Needed Changes to this flag require a restart Default: `500` The heartbeat interval, in milliseconds (ms), for Raft replication. The leader produces heartbeats to followers at this interval. The followers expect a heartbeat at this interval and consider a leader to have failed if it misses several in a row. ### RocksDB and compaction/performance flags Use the following two flags to select the SSTable compression type: ##### --enable\_ondisk\_compression Restart Needed Changes to this flag require a restart Default: `true` Enable SSTable compression at the cluster level. ##### --compression\_type Restart Needed Changes to this flag require a restart Default: `Snappy` Change the SSTable compression type. The valid compression types are `Snappy`, `Zlib`, `LZ4`, and `NoCompression`. If you select an invalid option, the cluster will not come up. If you change this flag, the change takes effect after you restart the cluster nodes. Changing this flag on an existing database is supported; a tablet can validly have SSTs with different compression types. Eventually, compaction will remove the old compression type files. ##### --regular\_tablets\_data\_block\_key\_value\_encoding Restart Needed Changes to this flag require a restart Default: `shared_prefix` Key-value encoding to use for regular data blocks in RocksDB. Possible options: `shared_prefix`, `three_shared_parts`. Only change this flag to `three_shared_parts` after you migrate the whole cluster to the YugabyteDB version that supports it. ##### --rocksdb\_compact\_flush\_rate\_limit\_bytes\_per\_sec Default: `1073741824` Used to control rate of memstore flush and SSTable file compaction. ##### --rocksdb\_universal\_compaction\_min\_merge\_width Restart Needed Changes to this flag require a restart Default: `4` Compactions run only if there are at least `rocksdb_universal_compaction_min_merge_width` eligible files and their running total (summation of size of files considered so far) is within `rocksdb_universal_compaction_size_ratio` of the next file in consideration to be included into the same compaction. ##### --rocksdb\_max\_background\_compactions Restart Needed Changes to this flag require a restart Default: `-1` Maximum number of threads to do background compactions (used when compactions need to catch up.) Unless `rocksdb_disable_compactions=true`, this cannot be set to zero. The default of `-1` means that the value is calculated at runtime as follows: - For servers with up to 4 CPU cores, the default value is considered as `1`. - For servers with up to 8 CPU cores, the default value is considered as `2`. - For servers with up to 32 CPU cores, the default value is considered as `3`. - Beyond 32 cores, the default value is considered as `4`. ##### --rocksdb\_compaction\_size\_threshold\_bytes Restart Needed Changes to this flag require a restart Default: `2147483648` Threshold beyond which a compaction is considered large. ##### --rocksdb\_level0\_file\_num\_compaction\_trigger Restart Needed Changes to this flag require a restart Default: `5`. Number of files to trigger level-0 compaction. Set to `-1` if compaction should not be triggered by number of files at all. ##### --rocksdb\_universal\_compaction\_size\_ratio Restart Needed Changes to this flag require a restart Default: `20` Compactions run only if there are at least `rocksdb_universal_compaction_min_merge_width` eligible files and their running total (summation of size of files considered so far) is within `rocksdb_universal_compaction_size_ratio` of the next file in consideration to be included into the same compaction. ##### --timestamp\_history\_retention\_interval\_sec Default: `900` (15 minutes) The time interval, in seconds, to retain history/older versions of data. Point-in-time reads at a hybrid time prior to this interval might not be allowed after a compaction and return a `Snapshot too old` error. Set this to be greater than the expected maximum duration of any single transaction in your application. ##### --remote\_bootstrap\_rate\_limit\_bytes\_per\_sec Default: `268435456` Rate control across all tablets being remote bootstrapped from or to this process. ##### --remote\_bootstrap\_from\_leader\_only Default: `false` Based on the value (`true`/`false`) of the flag, the leader decides whether to instruct the new peer to attempt bootstrap from a closest caught-up peer. The leader too could be the closest peer depending on the new peer's geographic placement. Setting the flag to false will enable the feature of remote bootstrapping from a closest caught-up peer. The number of bootstrap attempts from a non-leader peer is limited by the flag [max\_remote\_bootstrap\_attempts\_from\_non\_leader](#max-remote-bootstrap-attempts-from-non-leader "max_remote_bootstrap_attempts_from_non_leader"). Note The code for the feature is present from version 2.16 and later, and can be enabled explicitly if needed. Starting from version 2.19, the feature is on by default. ##### --max\_remote\_bootstrap\_attempts\_from\_non\_leader Default: `5` When the flag [remote\_bootstrap\_from\_leader\_only](#remote-bootstrap-from-leader-only "remote_bootstrap_from_leader_only") is set to `false` (enabling the feature of bootstrapping from a closest peer), the number of attempts where the new peer tries to bootstrap from a non-leader peer is limited by the flag. After these failed bootstrap attempts for the new peer, the leader peer sets itself as the bootstrap source. ##### --db\_block\_cache\_num\_shard\_bits Default: `-1` `-1` indicates a dynamic scheme that evaluates to 4 if number of cores is less than or equal to 16, 5 for 17-32 cores, 6 for 33-64 cores, and so on. Note Starting from version 2.18, the default is `-1`. Previously it was `4`. ##### --full\_compaction\_pool\_max\_threads Restart Needed Changes to this flag require a restart Default: `-1` The maximum number of threads allowed for non-admin full compactions. This includes post-split compactions (compactions that remove irrelevant data from new tablets after splits) and scheduled full compactions. If the value is `-1` (default) or `0`, the thread count is derived from the CPU count (`1` for nodes with up to 4 cores, `2` otherwise). A positive value is used as-is. ##### --auto\_compact\_check\_interval\_sec Restart Needed Changes to this flag require a restart Default: `60` The interval at which the full compaction task will check for tablets eligible for compaction (both for the statistics-based full compaction and scheduled full compaction features). `0` indicates that the statistics-based full compactions feature is disabled. ##### --auto\_compact\_stat\_window\_seconds Default: `300` Window of time in seconds over which DocDB read statistics are analyzed for the purpose of triggering full compactions to improve read performance. Both [auto\_compact\_percent\_obsolete](#auto-compact-percent-obsolete "auto_compact_percent_obsolete") and [auto\_compact\_min\_obsolete\_keys\_found](#auto-compact-min-obsolete-keys-found "auto_compact_min_obsolete_keys_found") are evaluated over this period of time. `auto_compact_stat_window_seconds` must be evaluated as a multiple of [auto\_compact\_check\_interval\_sec](#auto-compact-check-interval-sec "auto_compact_check_interval_sec"), and will be rounded up to meet this constraint. For example, if `auto_compact_stat_window_seconds` is set to `100` and `auto_compact_check_interval_sec` is set to `60`, it will be rounded up to `120` at runtime. ##### --auto\_compact\_percent\_obsolete Default: `99` The percentage of obsolete keys (over total keys) read over the [auto\_compact\_stat\_window\_seconds](#auto-compact-stat-window-seconds "auto_compact_stat_window_seconds") window of time required to trigger an automatic full compaction on a tablet. Only keys that are past their history retention (and thus can be garbage collected) are counted towards this threshold. For example, if the flag is set to `99` and 100000 keys are read over that window of time, and 99900 of those are obsolete and past their history retention, a full compaction will be triggered (subject to other conditions). ##### --auto\_compact\_min\_obsolete\_keys\_found Default: `10000` Minimum number of keys that must be read over the last [auto\_compact\_stat\_window\_seconds](#auto-compact-stat-window-seconds "auto_compact_stat_window_seconds") to trigger a statistics-based full compaction. ##### --auto\_compact\_min\_wait\_between\_seconds Default: `0` Minimum wait time between statistics-based and scheduled full compactions. To be used if statistics-based compactions are triggering too frequently. ##### --scheduled\_full\_compaction\_frequency\_hours Default: `0` The frequency with which full compactions should be scheduled on tablets. `0` indicates that the feature is disabled. Recommended value: `720` hours or greater (that is, 30 days). ##### --scheduled\_full\_compaction\_jitter\_factor\_percentage Default: `33` Percentage of [scheduled\_full\_compaction\_frequency\_hours](#scheduled-full-compaction-frequency-hours "scheduled_full_compaction_frequency_hours") to be used as jitter when determining full compaction schedule per tablet. Must be a value between `0` and `100`. Jitter is introduced to prevent many tablets from being scheduled for full compactions at the same time. Jitter is deterministically computed when scheduling a compaction, between 0 and (frequency * jitter factor) hours. Once computed, the jitter is subtracted from the intended compaction frequency to determine the tablet's next compaction time. Example: If `scheduled_full_compaction_frequency_hours` is `720` hours (that is, 30 days), and `scheduled_full_compaction_jitter_factor_percentage` is `33` percent, each tablet will be scheduled for compaction every `482` hours to `720` hours. ##### --automatic\_compaction\_extra\_priority Default: `50` Assigns an extra priority to automatic (minor) compactions when automatic tablet splitting is enabled. This deprioritizes post-split compactions and ensures that smaller compactions are not starved. Suggested values are between 0 and 50. ### Concurrency control flags To learn about Wait-on-Conflict concurrency control, see [Concurrency control](/stable/architecture/transactions/concurrency-control/ "Concurrency control"). ##### --enable\_wait\_queues Restart Needed Changes to this flag require a restart Default: `true` When set to true, enables in-memory wait queues, deadlock detection, and wait-on-conflict semantics in all YSQL traffic. ##### --disable\_deadlock\_detection Restart Needed Changes to this flag require a restart Default: `false` When set to true, disables deadlock detection. If `enable_wait_queues=false`, this flag has no effect as deadlock detection is not running anyways. Warning Use of this flag can potentially result in deadlocks that can't be resolved by YSQL. Use this flag only if the application layer can guarantee deadlock avoidance. ##### --wait\_queue\_poll\_interval\_ms Restart Needed Changes to this flag require a restart Default: `100` If `enable_wait_queues=true`, this controls the rate at which each tablet's wait queue polls transaction coordinators for the status of transactions which are blocking contentious resources. ### DDL concurrency flags ##### --ysql\_enable\_db\_catalog\_version\_mode Deprecated Deprecated Per-database catalog version mode is now mandatory. This flag is deprecated and has no effect; if set explicitly, a deprecation warning is logged at startup and the value is ignored. In per-database catalog version mode, a DDL statement that affects the current database can only increment the catalog version for that database. As a result, multiple DDL statements can be concurrently executed if each DDL only affects its current database and is executed in a separate database. Existing connections only need to refresh their catalog caches if they are connected to the same database as that of a DDL statement. ##### --enable\_heartbeat\_pg\_catalog\_versions\_cache Restart Needed Changes to this flag require a restart Default: `false` Whether to enable the use of heartbeat catalog versions cache for the `pg_yb_catalog_version` table which can help to reduce the number of reads from the table. This is beneficial when there are many databases and/or many yb-tservers in the cluster. Important Each YB-TServer regularly sends a heartbeat request to the YB-Master leader. As part of the heartbeat response, YB-Master leader reads all the rows in the table `pg_yb_catalog_version` and sends the result back in the heartbeat response. As there is one row in the table `pg_yb_catalog_version` for each database, the cost of reading `table pg_yb_catalog_version` becomes more expensive when the number of YB-TServers, or the number of databases goes up. ### Cost-based optimizer flag Configure the YugabyteDB [cost-based optimizer](/stable/architecture/query-layer/planner-optimizer/ "cost-based optimizer") (CBO). See also the [yb\_enable\_cbo](#yb-enable-cbo "yb_enable_cbo") configuration parameter. If this flag is set, the parameter takes precedence. ##### --ysql\_yb\_enable\_cbo Restart Needed Changes to this flag require a restart Default: `legacy_mode` Enables the YugabyteDB [cost-based optimizer](/stable/architecture/query-layer/planner-optimizer/ "cost-based optimizer") (CBO). Options are `on`, `off`, `legacy_mode`, and `legacy_stats_mode`. In v2025.2 and later, CBO is enabled ('on') by default in new universes when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. When CBO is enabled (set to `on`), [auto analyze](#auto-analyze-service-flags "auto analyze") is also enabled automatically. If you disable auto analyze explicitly, you are responsible for periodically running ANALYZE on user tables to maintain up-to-date statistics. For information on using this parameter to configure CBO, refer to [Enable cost-based optimizer](/stable/best-practices-operations/ysql-yb-enable-cbo/ "Enable cost-based optimizer"). ### Auto Analyze service flags To learn about the Auto Analyze service, see [Auto Analyze service](/stable/additional-features/auto-analyze/ "Auto Analyze service"). Auto analyze is automatically enabled when the [cost-based optimizer](/stable/architecture/query-layer/planner-optimizer/ "cost-based optimizer") (CBO) is enabled by setting the [yb\_enable\_cbo](/stable/reference/configuration/yb-tserver/#yb_enable_cbo "yb_enable_cbo") flag to `on`. ##### ysql\_enable\_auto\_analyze\_service (deprecated) Default: `false` Use [ysql\_enable\_auto\_analyze](/stable/reference/configuration/yb-tserver/#ysql_enable_auto_analyze "ysql_enable_auto_analyze") on yb-tservers instead. ### Advisory lock flags To learn about advisory locks, see [Advisory locks](/stable/architecture/transactions/concurrency-control/#advisory-locks "Advisory locks"). ##### --ysql\_yb\_enable\_advisory\_locks T-Server / Master Match Flag value must match across all Masters and TServers Default: `true` Enables advisory locking. This value must match on all YB-Master and YB-TServer configurations of a YugabyteDB cluster. ### Index backfill flags ##### --defer\_index\_backfill Default: `false` If enabled, YB-Master avoids launching any new index-backfill jobs on the cluster for all new YCQL indexes. You will need to run [yb-admin backfill\_indexes\_for\_table](/stable/admin/yb-admin/#backfill-indexes-for-table "yb-admin backfill_indexes_for_table") manually for indexes to be functional. See [CREATE DEFERRED INDEX](/stable/api/ycql/ddl_create_index/#deferred-index "CREATE DEFERRED INDEX") for reference. ##### --allow\_batching\_non\_deferred\_indexes Default: `true` If enabled, indexes on the same (YCQL) table may be batched together during backfill, even if they were not deferred. ##### --ysql\_index\_backfill\_rpc\_timeout\_ms Default: `300000` Deadline (in milliseconds) for each internal YB-Master to YB-TServer RPC for backfilling a chunk of the index. ### Multitenancy (Resource Governance) flags These flags control per-database CPU isolation, which lets you treat each database as a tenant and prevent one database from starving others of CPU. For an overview and setup instructions, see [Multitenancy](/stable/additional-features/multitenancy/ "Multitenancy"). For information on other Resource Governance configuration flags, see the [YB-TServer reference](/stable/reference/configuration/yb-tserver/#multitenancy-resource-governance-flags "YB-TServer reference"). ##### --enable\_qos [EA](/stable/releases/versioning/#feature-maturity) Restart Needed Changes to this flag require a restart T-Server / Master Match Flag value must match across all Masters and TServers Default: `false` Enables per-database CPU limits and the maximum database count cap. When `false`, per-database cgroups are not created and none of the other `qos_*` flags have any effect. ##### --qos\_max\_db\_count [EA](/stable/releases/versioning/#feature-maturity) Default: `0` The maximum number of non-template databases that can be created. `CREATE DATABASE` fails if it would exceed this limit. Because per-database cgroups are weighted equally, this cap sets the effective per-database minimum CPU as `1 / qos_max_db_count` (for example, a value of `20` guarantees each database at least 5% of the available CPU). Has no effect unless `enable_qos` is `true`. ### Other performance tuning options ##### --allowed\_preview\_flags\_csv Restart Needed Changes to this flag require a restart Comma-separated values (CSV) formatted catalogue of [preview feature](/stable/releases/versioning/#tech-preview-tp "preview feature") flag names. Preview flags represent experimental or in-development features that are not yet fully supported. Flags that are tagged as "preview" cannot be modified or configured unless they are included in this list. By adding a flag to this list, you explicitly acknowledge and accept any potential risks or instability that may arise from modifying these preview features. This process serves as a safeguard, ensuring that you are fully aware of the experimental nature of the flags you are working with. You still need to set the flag Adding flags to this list doesn't automatically change any settings. It only *grants permission* for the flag to be modified. You still need to configure the flag separately after adding it to this list. Using YugabyteDB Anywhere If you are using YugabyteDB Anywhere, as with other flags, set `allowed_preview_flags_csv` using the [Edit Flags](/stable/yugabyte-platform/manage-deployments/edit-config-flags/#modify-configuration-flags "Edit Flags") feature. After adding a preview flag to the `allowed_preview_flags_csv` list, you still need to set the flag using **Edit Flags** as well. ##### --hide\_dead\_node\_threshold\_mins Default: `1440` (1 day) Number of minutes to wait before no longer displaying a dead node (no heartbeat) in the [YB-Master Admin UI](#admin-ui "YB-Master Admin UI") (the node is presumed to have been removed from the cluster). ##### --ysql\_enable\_write\_pipelining Restart Needed Changes to this flag require a restart T-Server / Master Match Flag value must match across all Masters and TServers Default: `false` Enables concurrent replication of multiple write operations in a transaction. Write requests to DocDB return immediately after completing on the leader, meanwhile the Raft quorum commit happens asynchronously in the background. This enables PostgreSQL to be able to send the next write or read request in parallel, which reduces overall latency. Note that this does not affect the transactional guarantees of the system. The COMMIT of the transaction waits and ensures all asynchronous quorum replication has completed. ## Security ### Security flags for encryption and certificates For details on enabling encryption in transit, see [Encryption in transit](/stable/secure/tls-encryption/ "Encryption in transit"). ##### --certs\_dir Restart Needed Changes to this flag require a restart Default: `""` (uses `/yb-data/master/data/certs`.) Directory that contains certificate authority, private key, and certificates for this server. ##### --certs\_for\_client\_dir Restart Needed Changes to this flag require a restart Default: `""` (Use the same directory as certs\_dir.) The directory that contains certificate authority, private key, and certificates for this server that should be used for client-to-server communications. ##### --allow\_insecure\_connections Restart Needed Changes to this flag require a restart Default: `true` Allow insecure connections. Set to `false` to prevent any process with unencrypted communication from joining a cluster. Note that this flag requires [use\_node\_to\_node\_encryption](#use-node-to-node-encryption "use_node_to_node_encryption") to be enabled and [use\_client\_to\_server\_encryption](#use-client-to-server-encryption "use_client_to_server_encryption") to be enabled. ##### --dump\_certificate\_entries Restart Needed Changes to this flag require a restart Default: `false` Adds certificate entries, including IP addresses and hostnames, to log for handshake error messages. Enable this flag to debug certificate issues. ##### --use\_client\_to\_server\_encryption Restart Needed Changes to this flag require a restart Default: `false` Use client-to-server (client-to-node) encryption to protect data in transit between YugabyteDB servers and clients, tools, and APIs. ##### --use\_node\_to\_node\_encryption Restart Needed Changes to this flag require a restart Default: `false` Enables server-server (node-to-node) encryption between YB-Master and YB-TServer servers in a cluster or universe. To work properly, all YB-TServer servers must also have their [--use\_node\_to\_node\_encryption](/stable/reference/configuration/yb-tserver/#use-node-to-node-encryption "--use_node_to_node_encryption") flag enabled. When enabled, [--allow\_insecure\_connections](#allow-insecure-connections "--allow_insecure_connections") should be set to false to disallow insecure connections. ##### --cipher\_list Restart Needed Changes to this flag require a restart Default: `""` (empty string; library defaults apply) Specify cipher lists for TLS 1.2 and earlier versions. (For TLS 1.3, use [--ciphersuites](#ciphersuites "--ciphersuites").) Use a colon-separated list of TLS 1.2 cipher names in order of preference. Use an exclamation mark ( `!` ) to exclude ciphers. For example: ```sh --cipher_list DEFAULTS:!DES:!IDEA:!3DES:!RC2 ``` This allows all ciphers for TLS 1.2 to be accepted, except those matching the category of ciphers omitted. This flag requires a restart or rolling restart. For more information, refer to [SSL\_CTX\_set\_cipher\_list](https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_cipher_list.html "SSL_CTX_set_cipher_list") in the OpenSSL documentation. ##### --ciphersuites Restart Needed Changes to this flag require a restart Default: `""` (empty string; library defaults apply) Define the available TLS 1.3 ciphersuites. For TLS 1.2 and earlier, use [--cipher\_list](#cipher-list "--cipher_list"). Use a colon-separated list of TLS 1.3 ciphersuite names in order of preference. Use an exclamation mark ( ! ) to exclude ciphers. For example: ```sh --ciphersuites DEFAULTS:!CHACHA20 ``` This allows all ciphersuites for TLS 1.3 to be accepted, except CHACHA20 ciphers. This flag requires a restart or rolling restart. For more information, refer to [SSL\_CTX\_set\_cipher\_list](https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_cipher_list.html "SSL_CTX_set_cipher_list") in the OpenSSL documentation. ##### --ssl\_protocols Restart Needed Changes to this flag require a restart Default: An empty string, which is equivalent to allowing all protocols except "ssl2" and "ssl3". Specifies an explicit allow-list of TLS protocols for YugabyteDB's internal RPC communication. You can pass a comma-separated list of strings, where the strings can be one of "ssl2", "ssl3", "tls10", "tls11", "tls12", and "tls13". You can set the TLS version for node-to-node and client-node communication. To enforce TLS 1.2, set the flag to tls12 as follows: ```sh --ssl_protocols = tls12 ``` To specify a *minimum* TLS version of 1.2, for example, the flag needs to be set to tls12, tls13, and all available subsequent versions. ```sh --ssl_protocols = tls12,tls13 ``` By default, PostgreSQL uses a default minimum version for TLS of v1.2, as set using the [ssl\_min\_protocol\_version](https://www.postgresql.org/docs/15/runtime-config-connection.html#GUC-SSL-MIN-PROTOCOL-VERSION "ssl_min_protocol_version") configuration parameter. As the `ssl_protocols` setting does not propagate to PostgreSQL, if you specify a different minimum TLS version for Master and TServer, you should update the `ssl_min_protocol_version` parameter. For example: ```sh --ysql_pg_conf_csv="ssl_min_protocol_version='TLSv1.3'" ``` ### Authentication and authorization flags #### YSQL The following flags support the use of the [YSQL API](/stable/api/ysql/ "YSQL API"): ##### --enable\_ysql T-Server / Master Match Flag value must match across all Masters and TServers Restart Needed Changes to this flag require a restart Default: `true` Enables the YSQL API when value is `true`. ##### --ysql\_enable\_auth Restart Needed Changes to this flag require a restart Default: `false` Enables YSQL authentication. When YSQL authentication is enabled, you can sign into ysqlsh using the default `yugabyte` user that has a default password of `yugabyte`. ##### --ysql\_enable\_profile Restart Needed Changes to this flag require a restart Default: `false` Enables YSQL [login profiles](/stable/secure/enable-authentication/ysql-login-profiles/ "login profiles"). When YSQL login profiles are enabled, you can set limits on the number of failed login attempts made by users. ##### --pgsql\_proxy\_bind\_address Restart Needed Changes to this flag require a restart Default: `0.0.0.0:5433` Specifies the TCP/IP bind addresses for the YSQL API. The default value of `0.0.0.0:5433` allows listening for all IPv4 addresses access to localhost on port `5433`. The `--pgsql_proxy_bind_address` value overwrites `listen_addresses` (default value of `127.0.0.1:5433`) that controls which interfaces accept connection attempts. To specify fine-grained access control over who can access the server, use [--ysql\_hba\_conf](#ysql-hba-conf "--ysql_hba_conf"). ##### --pgsql\_proxy\_webserver\_port Restart Needed Changes to this flag require a restart Default: `13000` Specifies the web server port for YSQL metrics monitoring. ##### --ysql\_hba\_conf Deprecated Restart Needed Changes to this flag require a restart Deprecated. Use `--ysql_hba_conf_csv` instead. ##### --ysql\_hba\_conf\_csv Restart Needed Changes to this flag require a restart Default: `"host all all 0.0.0.0/0 trust,host all all ::0/0 trust"` Specifies a comma-separated list of PostgreSQL client authentication settings that is written to the `ysql_hba.conf` file. To see the current values in the `ysql_hba.conf` file, run the `SHOW hba_file;` statement and then view the file. Because the file is autogenerated, direct edits are overwritten by the autogenerated content. For details on using `--ysql_hba_conf_csv` to specify client authentication, refer to [Host-based authentication](/stable/secure/authentication/host-based-authentication/ "Host-based authentication"). If a setting includes a comma (`,`) or double quotes (`"`), the setting should be enclosed in double quotes. In addition, double quotes inside the quoted text should be doubled (`""`). Suppose you have two fields: `host all all 127.0.0.1/0 password` and `host all all 0.0.0.0/0 ldap ldapserver=***** ldapsearchattribute=cn ldapport=3268 ldapbinddn=***** ldapbindpasswd="*****"`. Because the second field includes double quotes (`"`) around one of the settings, you need to double the quotes and enclose the entire field in quotes, as follows: ```sh "host all all 0.0.0.0/0 ldap ldapserver=***** ldapsearchattribute=cn ldapport=3268 ldapbinddn=***** ldapbindpasswd=""*****""" ``` To set the flag, join the fields using a comma (`,`) and enclose the final flag value in single quotes (`'`): ```sh --ysql_hba_conf_csv='host all all 127.0.0.1/0 password,"host all all 0.0.0.0/0 ldap ldapserver=***** ldapsearchattribute=cn ldapport=3268 ldapbinddn=***** ldapbindpasswd=""*****"""' ``` ##### --ysql\_pg\_conf Deprecated Restart Needed Changes to this flag require a restart Deprecated. Use `--ysql_pg_conf_csv` instead. ##### --ysql\_pg\_conf\_csv Restart Needed Changes to this flag require a restart Comma-separated list of PostgreSQL server configuration parameters that is appended to the `postgresql.conf` file. If internal quotation marks are required, surround each configuration pair having single quotation marks with double quotation marks. For example: ```sh --ysql_pg_conf_csv="log_line_prefix='%m [%p %l %c] %q[%C %R %Z %H] [%r %a %u %d] '","pgaudit.log='all, -misc'",pgaudit.log_parameter=on,pgaudit.log_relation=on,pgaudit.log_catalog=off,suppress_nonpg_logs=on ``` For information on available PostgreSQL server configuration parameters, refer to [Server Configuration](https://www.postgresql.org/docs/15/runtime-config.html "Server Configuration") in the PostgreSQL documentation. The configuration parameters for YugabyteDB are the same as for PostgreSQL, with some minor exceptions. Refer to [Configuration parameters](/stable/reference/configuration/yb-tserver/#postgresql-configuration-parameters "Configuration parameters"). ##### --ysql\_timezone Restart Needed Changes to this flag require a restart Default: Uses the YSQL time zone. Specifies the time zone for displaying and interpreting timestamps. ##### --ysql\_datestyle Restart Needed Changes to this flag require a restart Default: Uses the ISO, MDY display format. Specifies the display format for data and time values. ##### --ysql\_max\_connections Restart Needed Changes to this flag require a restart Default: If `ysql_max_connections` is not set, the database startup process will determine the highest number of connections the system can support, from a minimum of 50 to a maximum of 300 (per node). Specifies the maximum number of concurrent YSQL connections per node. This is a maximum per server, so a 3-node cluster will have a default of 900 available connections, globally. Any active, idle in transaction, or idle in session connection counts toward the connection limit. Some connections are reserved for superusers. The total number of superuser connections is determined by the `superuser_reserved_connections` [configuration parameter](/stable/reference/configuration/yb-tserver/#postgresql-configuration-parameters "configuration parameter"). Connections available to non-superusers is equal to `ysql_max_connections` - `superuser_reserved_connections`. ##### --ysql\_default\_transaction\_isolation Restart Needed Changes to this flag require a restart Default: `'read committed'` Specifies the default transaction isolation level. Valid values: `serializable`, `'repeatable read'`, `'read committed'`, and `'read uncommitted'`. [Read Committed isolation](/stable/explore/transactions/isolation-levels/ "Read Committed isolation") is supported only if the YB-Master flag `yb_enable_read_committed_isolation` is set to `true`. For new universes running v2025.2 or later, `yb_enable_read_committed_isolation` is set to `true` by default when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. If `yb_enable_read_committed_isolation` is `false`, the Read Committed isolation level of the YugabyteDB transactional layer falls back to the stricter Snapshot isolation (in which case Read Committed and Read Uncommitted of YSQL also in turn use Snapshot isolation). ##### --yb\_enable\_read\_committed\_isolation Restart Needed Changes to this flag require a restart Default: `false` Enables Read Committed isolation. For new universes running v2025.2 or later, `yb_enable_read_committed_isolation` is set to `true` by default when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. When set to false, Read Committed (and Read Uncommitted) isolation level of YSQL fall back to the stricter [Snapshot isolation](/stable/explore/transactions/isolation-levels/ "Snapshot isolation"). See also the [--ysql\_default\_transaction\_isolation](#ysql-default-transaction-isolation "--ysql_default_transaction_isolation") flag. ##### --pg\_client\_use\_shared\_memory Default: `true` Enables the use of shared memory between PostgreSQL and the YB-TServer. Using shared memory can potentially improve the performance of your database operations. ##### --ysql\_sequence\_cache\_method Restart Needed Changes to this flag require a restart Default: `connection` Specifies where to cache sequence values. Valid values are `connection` and `server`. This flag requires the YB-TServer `yb_enable_sequence_pushdown` flag to be true (the default). Otherwise, the default behavior will occur regardless of this flag's value. For details on caching values on the server and switching between cache methods, see the semantics on the [nextval](/stable/api/ysql/exprs/sequence_functions/func_nextval/ "nextval") page. ##### --ysql\_sequence\_cache\_minval Restart Needed Changes to this flag require a restart Default: `100` Specifies the minimum number of sequence values to cache in the client for every sequence object. To turn off the default size of cache flag, set the flag to `0`. For details on the expected behaviour when used with the sequence cache clause, see the semantics under [CREATE SEQUENCE](/stable/api/ysql/the-sql-language/statements/ddl_create_sequence/#cache-cache "CREATE SEQUENCE") and [ALTER SEQUENCE](/stable/api/ysql/the-sql-language/statements/ddl_alter_sequence/#cache-cache "ALTER SEQUENCE") pages. ##### --ysql\_yb\_fetch\_size\_limit Default: `0` Specifies the maximum size (in bytes) of total data returned in one response when the query layer fetches rows of a table from DocDB. Used to bound how many rows can be returned in one request. Set to 0 to have no size limit. You can also specify the value as a string. For example, you can set it to `'10MB'`. You should have at least one of row limit or size limit set. If both `--ysql_yb_fetch_row_limit` and `--ysql_yb_fetch_size_limit` are greater than zero, then limit is taken as the lower bound of the two values. See also the [yb\_fetch\_size\_limit](/stable/reference/configuration/yb-tserver/#yb-fetch-size-limit "yb_fetch_size_limit") configuration parameter. If both flag and parameter are set, the parameter takes precedence. ##### --ysql\_yb\_fetch\_row\_limit Default: `1024` Specifies the maximum number of rows returned in one response when the query layer fetches rows of a table from DocDB. Used to bound how many rows can be returned in one request. Set to 0 to have no row limit. You should have at least one of row limit or size limit set. If both `--ysql_yb_fetch_row_limit` and `--ysql_yb_fetch_size_limit` are greater than zero, then limit is taken as the lower bound of the two values. See also the [yb\_fetch\_row\_limit](/stable/reference/configuration/yb-tserver/#yb-fetch-row-limit "yb_fetch_row_limit") configuration parameter. If both flag and parameter are set, the parameter takes precedence. ##### --ysql\_log\_statement Restart Needed Changes to this flag require a restart Default: `none` Specifies the types of YSQL statements that should be logged. Valid values: `none` (off), `ddl` (only data definition queries, such as create/alter/drop), `mod` (all modifying/write statements, includes DDLs plus insert/update/delete/truncate, etc), and `all` (all statements). ##### --ysql\_log\_min\_duration\_statement Restart Needed Changes to this flag require a restart Default: `-1` (disables logging statement durations) Logs the duration of each completed SQL statement that runs the specified duration (in milliseconds) or longer. Setting the value to `0` prints all statement durations. You can use this flag to help track down unoptimized (or "slow") queries. ##### --ysql\_log\_min\_messages Restart Needed Changes to this flag require a restart Default: `WARNING` Specifies the [severity level](https://www.postgresql.org/docs/15/runtime-config-logging.html#RUNTIME-CONFIG-SEVERITY-LEVELS "severity level") of messages to log. ##### --enable\_pg\_cron T-Server / Master Match Flag value must match across all Masters and TServers Restart Needed Changes to this flag require a restart Default: `false` Set this flag to true on all YB-Masters and YB-TServers to add the [pg\_cron extension](/stable/additional-features/pg-extensions/extension-pgcron/ "pg_cron extension"). ##### --ysql\_cron\_database\_name Default: `yugabyte` Specifies the database where pg\_cron is to be installed. You can create the database after setting the flag. The [pg\_cron extension](/stable/additional-features/pg-extensions/extension-pgcron/ "pg_cron extension") is installed on only one database (by default, `yugabyte`). To change the database after the extension is created, you must first drop the extension and then change the flag value. ##### --ysql\_output\_buffer\_size Restart Needed Changes to this flag require a restart Default: `1048576` Size of YSQL layer output buffer, in bytes. YSQL buffers query responses in this output buffer until either a buffer flush is requested by the client or the buffer overflows. As long as no data has been flushed from the buffer, the database can retry queries on retryable errors. For example, you can increase the size of the buffer so that YSQL can retry [read restart errors](/stable/architecture/transactions/read-restart-error/ "read restart errors"). ##### --ysql\_yb\_bnl\_batch\_size Default: `1024` Sets the size of a tuple batch that's taken from the outer side of a [batched nested loop (BNL) join](/stable/architecture/query-layer/join-strategies/#batched-nested-loop-join-bnl "batched nested loop (BNL) join"). When set to 1, BNLs are effectively turned off and won't be considered as a query plan candidate. See also the [yb\_bnl\_batch\_size](/stable/reference/configuration/yb-tserver/#yb-bnl-batch-size "yb_bnl_batch_size") configuration parameter. If both flag and parameter are set, the parameter takes precedence. ##### --ysql\_follower\_reads\_avoid\_waiting\_for\_safe\_time Default: `true` Controls whether YSQL follower reads that specify a not-yet-safe read time should be rejected. This will force them to go to the leader, which will likely be faster than waiting for safe time to catch up. ##### --enable\_ysql\_operation\_lease Default: `true` Enables the [YSQL lease mechanism](/stable/architecture/transactions/concurrency-control/#ysql-lease-mechanism "YSQL lease mechanism"). On YB-TServers, a new PostgreSQL process is spawned only after establishing a lease with the YB-Master leader. The flag also controls whether the background YB-TServer task makes lease refresh requests. ##### --ysql\_lease\_refresher\_interval\_ms Default: `1000` (1 second) Determines the interval a YB-TServer waits before initiating another YSQL lease refresh RPC. Refer to [YSQL lease mechanism](/stable/architecture/transactions/concurrency-control/#ysql-lease-refresher-interval-ms "YSQL lease mechanism") for more details. ##### --master\_ysql\_operation\_lease\_ttl\_ms Default: `5 * 60 * 1000` (5 minutes) Specifies base YSQL lease Time-To-Live (TTL). The YB-Master leader uses this value to determine the validity of a YB-TServer's YSQL lease. Refer to [YSQL lease mechanism](/stable/architecture/transactions/concurrency-control/#master-ysql-operation-lease-ttl-ms "YSQL lease mechanism") for more details. ##### --ysql\_operation\_lease\_ttl\_client\_buffer\_ms Default: 2000 (2 seconds) Specifies a client-side buffer for the YSQL operation lease TTL. Refer to [YSQL lease mechanism](/stable/architecture/transactions/concurrency-control/#ysql-operation-lease-ttl-client-buffer-ms "YSQL lease mechanism") for more details.