From 73a4669d99ba2499e8a13063ddde54cb39b70c36 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Tue, 25 Nov 2025 01:39:18 -0500 Subject: [PATCH 1/8] Updated defaults for EPCM flags --- .../additional-features/parallel-query.md | 2 +- .../stable/architecture/design-goals.md | 2 +- .../architecture/transactions/_index.md | 4 +- .../transactions/isolation-levels.md | 6 +- .../transactions/read-committed.md | 8 +- .../ysql-yb-enable-cbo.md | 12 +-- .../explore/transactions/isolation-levels.md | 74 +++---------------- .../reference/configuration/yb-master.md | 2 +- .../reference/configuration/yb-tserver.md | 18 +++-- 9 files changed, 38 insertions(+), 90 deletions(-) diff --git a/docs/content/stable/additional-features/parallel-query.md b/docs/content/stable/additional-features/parallel-query.md index a84630c01f79..214c096f650c 100644 --- a/docs/content/stable/additional-features/parallel-query.md +++ b/docs/content/stable/additional-features/parallel-query.md @@ -22,7 +22,7 @@ To enable and configure parallel queries, set the following configuration parame | Parameter | Description | Default | | :--- | :--- | :--- | -| yb_enable_parallel_append | Enables the planner's use of parallel append plans. To enable parallel query, set this to true. | false | +| yb_enable_parallel_append | Enables the planner's use of parallel append plans. To enable parallel query, set this to true. | true | | yb_parallel_range_rows | The number of rows to plan per parallel worker. To enable parallel query, set this to a value other than 0. (Recommended: 10000) | 0 | | yb_parallel_range_size | Approximate size of parallel range for DocDB relation scans. | 1MB | diff --git a/docs/content/stable/architecture/design-goals.md b/docs/content/stable/architecture/design-goals.md index f443a33a2d9b..272d747db614 100644 --- a/docs/content/stable/architecture/design-goals.md +++ b/docs/content/stable/architecture/design-goals.md @@ -56,7 +56,7 @@ YugabyteDB supports single-row linearizable writes. Linearizability is one of th YugabyteDB supports multi-row transactions with three isolation levels: Serializable, Snapshot (also known as repeatable read), and Read Committed isolation. -- The [YSQL API](../../api/ysql/) supports Serializable, Snapshot (default), and Read Committed isolation using the PostgreSQL isolation level syntax of `SERIALIZABLE`, `REPEATABLE READ`, and `READ COMMITTED` respectively. For more details, see [Isolation levels](#transaction-isolation-levels). +- The [YSQL API](../../api/ysql/) supports Serializable, Snapshot, and Read Committed (default) isolation using the PostgreSQL isolation level syntax of `SERIALIZABLE`, `REPEATABLE READ`, and `READ COMMITTED` respectively. For more details, see [Isolation levels](#transaction-isolation-levels). - The [YCQL API](../../api/ycql/) supports only Snapshot isolation (default) using the [BEGIN TRANSACTION](../../api/ycql/dml_transaction/) syntax. ## Partition Tolerance - CAP diff --git a/docs/content/stable/architecture/transactions/_index.md b/docs/content/stable/architecture/transactions/_index.md index 05512c8362bc..bb948a8c4123 100644 --- a/docs/content/stable/architecture/transactions/_index.md +++ b/docs/content/stable/architecture/transactions/_index.md @@ -82,10 +82,10 @@ To learn how YugabyteDB decides which transactions should be aborted in case of ## Read committed -Read Committed is the isolation level in which, clients do not need to retry or handle serialization errors (40001) in application logic. +Read Committed is the isolation level in which clients do not need to retry or handle serialization errors (40001) in application logic. {{}} -To understand how Read committed is implement and how to use it, see [Read committed](read-committed/). +To understand how Read committed is implemented and how to use it, see [Read committed](read-committed/). {{}} ## Read restart error diff --git a/docs/content/stable/architecture/transactions/isolation-levels.md b/docs/content/stable/architecture/transactions/isolation-levels.md index 29cd983eae50..b22d99d4e774 100644 --- a/docs/content/stable/architecture/transactions/isolation-levels.md +++ b/docs/content/stable/architecture/transactions/isolation-levels.md @@ -15,7 +15,7 @@ Transaction isolation is foundational to handling concurrent transactions in dat YugabyteDB supports the following three strictest transaction isolation levels: -1. Read Committed, which maps to the SQL isolation level of the same name. This isolation level guarantees that each statement sees all data that has been committed before it is issued (this implicitly also means that the statement sees a consistent snapshot). In addition, this isolation level internally handles read restart and conflict errors. In other words, the client does not see read restart and conflict errors (barring an exception). +1. Read Committed (the default for new universes), which maps to the SQL isolation level of the same name. This isolation level guarantees that each statement sees all data that has been committed before it is issued (this implicitly also means that the statement sees a consistent snapshot). In addition, this isolation level internally handles read restart and conflict errors. In other words, the client does not see read restart and conflict errors (barring an exception). 2. Serializable, which maps to the SQL isolation level of the same name. This isolation level guarantees that transactions run in a way equivalent to a serial (sequential) schedule. 3. Snapshot, which maps to the SQL Repeatable Read isolation level. This isolation level guarantees that all reads made in a transaction see a consistent snapshot of the database, and the transaction itself can successfully commit only if no updates it has made conflict with any concurrent updates made by transactions that committed after that snapshot. @@ -26,7 +26,9 @@ Transaction isolation level support differs between the YSQL and YCQL APIs: Similarly to PostgreSQL, you can specify Read Uncommitted for YSQL, but it behaves the same as Read Committed. -Read Committed is supported only if the YB-TServer flag `yb_enable_read_committed_isolation` is set to `true`. By default, this flag is `false`, in which case the Read Committed isolation level of YugabyteDB's transactional layer falls back to the stricter Snapshot isolation. The default isolation level for the YSQL API is essentially Snapshot because Read Committed, which is the YSQL API and PostgreSQL syntactic default, maps to Snapshot isolation. +Read Committed is supported only if the YB-TServer flag `yb_enable_read_committed_isolation` is set to `true` (the default for new universes in v2025.2 and later). + +In versions of YugabyteDB prior to v2025.2, `yb_enable_read_committed_isolation` is `false` by default; in this case, the Read Committed isolation level of YugabyteDB's transactional layer falls back to the stricter Snapshot isolation, making the default isolation level for the YSQL API essentially Snapshot because Read Committed, which is the YSQL API and PostgreSQL syntactic default, maps to Snapshot isolation. ## Internal locking in DocDB diff --git a/docs/content/stable/architecture/transactions/read-committed.md b/docs/content/stable/architecture/transactions/read-committed.md index 8d21cdc9b96e..62b3f4e8dbc3 100644 --- a/docs/content/stable/architecture/transactions/read-committed.md +++ b/docs/content/stable/architecture/transactions/read-committed.md @@ -23,7 +23,9 @@ Note that retries for the statement in YugabyteDB's Read Committed isolation are {{< tip title="Enable Read Committed" >}} -To enable Read Committed isolation, set the YB-TServer flag [yb_enable_read_committed_isolation](../../../reference/configuration/yb-tserver/#yb-enable-read-committed-isolation) to `true`. By default this flag is `false` and in this case 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). +Read Committed is supported only if the YB-TServer flag `yb_enable_read_committed_isolation` is set to `true` (the default for new universes in v2025.2 and later). + +In versions of YugabyteDB prior to v2025.2, `yb_enable_read_committed_isolation` is `false` by default; in this case, the Read Committed isolation level of YugabyteDB's transactional layer falls back to the stricter Snapshot isolation, making the default isolation level for the YSQL API essentially Snapshot because Read Committed, which is the YSQL API and PostgreSQL syntactic default, maps to Snapshot isolation. Refer to [Usage](#usage) to start a Read Committed transaction after enabling the flag. {{< /tip >}} @@ -342,7 +344,7 @@ The retries for serialization errors are done at the statement level. Each retry ## Usage -To use Read Committed isolation, first set the YB-TServer flag `yb_enable_read_committed_isolation=true`; this maps the syntactic Read Committed isolation in YSQL to the Read Committed implementation in DocDB. (When set to `false`, syntactic Read Committed in YSQL is mapped to Snapshot isolation in DocDB, meaning it behaves as Repeatable Read.) +To use Read Committed isolation, ensure the YB-TServer flag `yb_enable_read_committed_isolation=true` (the default for new universes in v2025.2 and later); this maps the syntactic Read Committed isolation in YSQL to the Read Committed implementation in DocDB. (When set to `false`, syntactic Read Committed in YSQL is mapped to Snapshot isolation in DocDB, meaning it behaves as Repeatable Read.) Assuming the flag has been set, you can start a Read Committed transaction in the following ways: @@ -1409,7 +1411,7 @@ Read Committed interacts with the following feature: ## Limitations -* A `SET TRANSACTION ISOLATION LEVEL ...` statement immediately issued after `BEGIN;` or `BEGIN TRANSACTION ISOLATION LEVEL READ COMMITTED;` will fail if the YB-TServer GFlag `yb_enable_read_committed_isolation=true`, and the following error will be issued: +* A `SET TRANSACTION ISOLATION LEVEL ...` statement immediately issued after `BEGIN;` or `BEGIN TRANSACTION ISOLATION LEVEL READ COMMITTED;` will fail if the YB-TServer flag `yb_enable_read_committed_isolation=true`, and the following error will be issued: ```output ERROR: SET TRANSACTION ISOLATION LEVEL must not be called in a subtransaction diff --git a/docs/content/stable/best-practices-operations/ysql-yb-enable-cbo.md b/docs/content/stable/best-practices-operations/ysql-yb-enable-cbo.md index f15b271c927f..ba8dc598a0a8 100644 --- a/docs/content/stable/best-practices-operations/ysql-yb-enable-cbo.md +++ b/docs/content/stable/best-practices-operations/ysql-yb-enable-cbo.md @@ -26,17 +26,7 @@ You configure CBO using the [yb_enable_cbo](../../reference/configuration/yb-tse ## New deployments -For new YSQL deployments, or when migrating from another system, to enable CBO, add the parameter to [ysql_pg_conf_csv](../../reference/configuration/yb-tserver/#ysql-pg-conf-csv) as follows: - -```sh ---ysql_pg_conf_csv=yb_enable_cbo=on -``` - -Alternatively, set the following YB-TServer flag: - -```sh ---ysql_yb_enable_cbo=on -``` +For new YSQL deployments, or when migrating from another system, CBO is enabled by default. ## Existing deployments diff --git a/docs/content/stable/explore/transactions/isolation-levels.md b/docs/content/stable/explore/transactions/isolation-levels.md index de59c2d0ef28..5b3a70f6073a 100644 --- a/docs/content/stable/explore/transactions/isolation-levels.md +++ b/docs/content/stable/explore/transactions/isolation-levels.md @@ -37,13 +37,15 @@ YugabyteDB supports three isolation levels in the transactional layer: - Snapshot - Read committed -The default isolation level for the YSQL API is effectively Snapshot (that is, the same as PostgreSQL's `REPEATABLE READ`) because, by default, Read committed, which is the YSQL API and PostgreSQL _syntactic_ default, maps to Snapshot isolation. +The default isolation level for the YSQL API on new universes in v2025.2 and later is Read Committed. -To enable Read committed, you must set the YB-TServer flag `yb_enable_read_committed_isolation` to `true`. By default this flag is `false` and 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). +To enable Read committed, the YB-TServer flag `yb_enable_read_committed_isolation` must be set to `true` (the default on new universes in v2025.2 and later). + +In versions of YugabyteDB prior to v2025.2, `yb_enable_read_committed_isolation` is `false` by default; in this case, the Read Committed isolation level of YugabyteDB's transactional layer falls back to the stricter Snapshot isolation, making the default isolation level for the YSQL API essentially Snapshot because Read Committed, which is the YSQL API and PostgreSQL syntactic default, maps to Snapshot isolation. {{< tip title="Tip" >}} -To avoid serializable errors, that is, to run applications with no retry logic, keep the default `READ COMMITTED` isolation (`--ysql_default_transaction_isolation`), and set the YB-TServer `--yb_enable_read_committed_isolation` flag to true. This enables read committed isolation. +To avoid serializable errors on universes earlier than v2025.2 (that is, to run applications with no retry logic), keep the default `READ COMMITTED` isolation (`--ysql_default_transaction_isolation`), and set the YB-TServer `--yb_enable_read_committed_isolation` flag to true. This enables read committed isolation. {{< /tip >}} @@ -229,7 +231,7 @@ Snapshot isolation detects only write-write conflicts; it does not detect read-w Applications using this level must be prepared to retry transactions due to serialization failures. -Consider an example of transactions' behavior under the Snapshot isolation level (mapped to PostgreSQL's Repeatable Read level). +Consider an example of transactions' behavior under the Snapshot isolation level. Create a table with sample data, as follows: @@ -249,10 +251,10 @@ Next, connect to the universe using two independent ysqlsh instances, referred t -Begin a transaction in session #1. This is Snapshot isolation by default, meaning it will work against a snapshot of the database as of this point: +Begin a transaction in session #1 with the Serializable isolation level, meaning it will work against a snapshot of the database as of this point: ```sql -BEGIN TRANSACTION; +BEGIN TRANSACTION ISOLATION LEVEL SNAPSHOT; ``` @@ -290,6 +292,7 @@ SELECT * FROM example; Insert a different row. Verify that the row inserted in the transaction in session #1 is not visible in this session, as follows: ```sql +BEGIN TRANSACTION ISOLATION LEVEL SNAPSHOT; INSERT INTO example VALUES (2); SELECT * FROM example; ``` @@ -374,10 +377,10 @@ Connect to the universe using two independent ysqlsh instances, referred to as s -By default, the YB-TServer flag `yb_enable_read_committed_isolation` is false. In this case, Read committed maps to Snapshot isolation at the transactional layer. So, `READ COMMITTED` of YSQL API in turn maps to Snapshot Isolation: +Begin a transaction in session #1 (Read Committed is the default isolation level). ```sql -BEGIN TRANSACTION ISOLATION LEVEL READ COMMITTED; +BEGIN TRANSACTION; SELECT * FROM test; ``` @@ -417,22 +420,6 @@ SELECT * FROM test; COMMIT; ``` -```output - k | v ----+--- - 1 | 2 -(1 row) -``` - -The inserted row (2, 3) is not visible because Read committed is disabled at the transactional layer and maps to Snapshot in which the whole transaction sees a consistent snapshot of the database. - -Set the YB-TServer flag `yb_enable_read_committed_isolation` to `true`: - -```sql -BEGIN TRANSACTION ISOLATION LEVEL READ COMMITTED; -SELECT * FROM test; -``` - ```output k | v ---+--- @@ -441,44 +428,7 @@ SELECT * FROM test; (2 rows) ``` - - - - - - - - - - -Insert a new row, as follows: - -```sql -INSERT INTO test VALUES (3, 4); -``` - - - - - - - -Perform the read again in the same transaction, as follows: - -```sql -SELECT * FROM test; -``` - -```output - k | v ----+--- - 1 | 2 - 2 | 3 - 3 | 4 -(3 rows) -``` - -This time, the statement can see the row (3, 4) that was committed after this transaction had been started but before the statement has been issued. +Unlike snapshot isolation, the statement can see the row (2, 3) that was committed after this transaction had been started but before the statement has been issued. diff --git a/docs/content/stable/reference/configuration/yb-master.md b/docs/content/stable/reference/configuration/yb-master.md index 5edc06ec011c..3deef37123aa 100644 --- a/docs/content/stable/reference/configuration/yb-master.md +++ b/docs/content/stable/reference/configuration/yb-master.md @@ -1066,7 +1066,7 @@ See also [Auto Analyze Service TServer flags](../yb-tserver/#auto-analyze-servic {{}}Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. -Default: false +Default: true ## Advisory lock flags diff --git a/docs/content/stable/reference/configuration/yb-tserver.md b/docs/content/stable/reference/configuration/yb-tserver.md index e3ccc7186497..d966df360cbd 100644 --- a/docs/content/stable/reference/configuration/yb-tserver.md +++ b/docs/content/stable/reference/configuration/yb-tserver.md @@ -392,7 +392,7 @@ Bitmap scans are only supported for LSM indexes. {{% tags/wrap %}} -Default: `false` +Default: `true` {{% /tags/wrap %}} @@ -431,7 +431,7 @@ Enable or disable the query planner's use of batched nested loop join. {{% tags/wrap %}} -Default: `legacy_mode` +Default: `on` {{% /tags/wrap %}} Enables the YugabyteDB [cost-based optimizer](../../../architecture/query-layer/planner-optimizer/) (CBO). Options are `on`, `off`, `legacy_mode`, and `legacy_stats_mode`. @@ -2126,7 +2126,7 @@ See also the [yb_enable_cbo](#yb-enable-cbo) configuration parameter. If this fl {{% tags/wrap %}} {{}} -Default: `legacy_mode` +Default: `on` {{% /tags/wrap %}} Enables the YugabyteDB [cost-based optimizer](../../../architecture/query-layer/planner-optimizer/) (CBO). Options are `on`, `off`, `legacy_mode`, and `legacy_stats_mode`. @@ -2153,7 +2153,7 @@ See also [Auto Analyze Service Master flags](../yb-master/#auto-analyze-service- {{}} {{}} {{}} -Default: `false` +Default: `true` {{% /tags/wrap %}} Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. @@ -2649,16 +2649,20 @@ Specifies the default transaction isolation level. Valid values: `SERIALIZABLE`, `REPEATABLE READ`, `READ COMMITTED`, and `READ UNCOMMITTED`. -[Read Committed Isolation](../../../explore/transactions/isolation-levels/) is supported only if the YB-TServer flag `yb_enable_read_committed_isolation` is set to `true`. By default this flag is `false` and in this case 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). +[Read Committed Isolation](../../../explore/transactions/isolation-levels/) is supported only if the YB-TServer flag `yb_enable_read_committed_isolation` is set to `true` (the default). + +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 {{% tags/wrap %}} {{}} -Default: `false` +Default: `true` {{% /tags/wrap %}} -Enables Read Committed Isolation. By default this flag is false and in this case `READ COMMITTED` (and `READ UNCOMMITTED`) isolation level of YSQL fall back to the stricter [Snapshot Isolation](../../../explore/transactions/isolation-levels/). See [--ysql_default_transaction_isolation](#ysql-default-transaction-isolation) flag for more details. +Enables Read Committed Isolation. + +When set to false, `READ COMMITTED` (and `READ UNCOMMITTED`) isolation level of YSQL fall back to the stricter [Snapshot Isolation](../../../explore/transactions/isolation-levels/). See [--ysql_default_transaction_isolation](#ysql-default-transaction-isolation) flag for more details. ##### --pg_client_use_shared_memory From 83dc70a7239e695a70a230b0eb437d5aaab608d9 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Tue, 25 Nov 2025 09:59:41 -0500 Subject: [PATCH 2/8] Update EPCM page --- .../configuration/postgresql-compatibility.md | 22 ++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/content/stable/reference/configuration/postgresql-compatibility.md b/docs/content/stable/reference/configuration/postgresql-compatibility.md index c69ee8655ef7..cd997f7cc022 100644 --- a/docs/content/stable/reference/configuration/postgresql-compatibility.md +++ b/docs/content/stable/reference/configuration/postgresql-compatibility.md @@ -18,7 +18,11 @@ rightNav: YugabyteDB is a [PostgreSQL-compatible](https://www.yugabyte.com/tech/postgres-compatibility/) distributed database that supports the majority of PostgreSQL syntax. YugabyteDB is methodically expanding its features to deliver PostgreSQL-compatible performance that can substantially improve your application's efficiency. -To test and take advantage of features developed for enhanced PostgreSQL compatibility in YugabyteDB that are currently in {{}}, you can enable Enhanced PostgreSQL Compatibility Mode (EPCM). When this mode is turned on, YugabyteDB is configured to use all the latest features developed for feature and performance parity. EPCM is available in [v2024.1](/stable/releases/ybdb-releases/v2024.1/) and later. The following features are part of EPCM. +To test and take advantage of features developed for enhanced PostgreSQL compatibility in YugabyteDB that are in {{}}, you can enable Enhanced PostgreSQL Compatibility Mode (EPCM). When this mode is turned on, YugabyteDB is configured to use all the latest features developed for feature and performance parity. EPCM is available in [v2024.1](/stable/releases/ybdb-releases/v2024.1/) and later. + +Note that from v2025.2, all the features in EPCM are enabled by default in new universes. Use individual flags to set features. + +The following features are part of EPCM. | Feature | Flag/Configuration Parameter | EA | GA | | :--- | :--- | :--- | :--- | @@ -37,12 +41,24 @@ After turning this mode on, as you upgrade universes, YugabyteDB will automatica As features included in the PostgreSQL compatibility mode transition from {{}} to {{}} in subsequent versions of YugabyteDB, they become enabled by default on new universes, and are no longer managed under EPCM on your existing universes after the upgrade. +From v2025.2, all the features in EPCM are enabled by default in new universes. Use individual flags to set features. + {{}} If you have set these features independent of EPCM, you cannot use EPCM. Conversely, if you are using EPCM on a universe, you cannot set any of the features independently. {{}} +### Upgrading + +If you upgrade a universe with EPCM to v2025.2 or later, YugabyteDB will automatically enable all EPCM features. Going forward, use individual flags to set features. + +When upgrading a universe that does not have EPCM, YugabyteDB does not enable features automatically. If the universe has the [cost based optimizer](#cost-based-optimizer) enabled, however, YugabyteDB will enable the following features: + +- Auto Analyze: ysql_enable_auto_analyze is set to true. +- Bitmap scans: yb_enable_bitmapscan is set to true. +- Parallel append: yb_enable_parallel_append is set to true. + ## Released features The following features are currently available in EPCM. @@ -131,6 +147,10 @@ To learn about parallel queries, see [Parallel queries](../../../additional-feat ## Enable EPCM +From v2025.2, all the features in EPCM are enabled by default in new universes. Use individual flags to set features. + +For versions prior to v2025.2, you can enable EPCM as follows. + ### YugabyteDB To enable EPCM in YugabyteDB: From 2ddd68d7d9fcc62cc9f6d40cefdeb4d9ac1bedab Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Tue, 25 Nov 2025 10:13:31 -0500 Subject: [PATCH 3/8] fix --- docs/content/stable/explore/transactions/isolation-levels.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/stable/explore/transactions/isolation-levels.md b/docs/content/stable/explore/transactions/isolation-levels.md index 5b3a70f6073a..4ccafad3ca26 100644 --- a/docs/content/stable/explore/transactions/isolation-levels.md +++ b/docs/content/stable/explore/transactions/isolation-levels.md @@ -251,7 +251,7 @@ Next, connect to the universe using two independent ysqlsh instances, referred t -Begin a transaction in session #1 with the Serializable isolation level, meaning it will work against a snapshot of the database as of this point: +Begin a transaction in session #1 with the Snapshot isolation level, meaning it will work against a snapshot of the database as of this point: ```sql BEGIN TRANSACTION ISOLATION LEVEL SNAPSHOT; From 6bc0c377bc49e0ebaea7f8a8aa54c21bc4165dac Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Tue, 25 Nov 2025 15:58:35 -0500 Subject: [PATCH 4/8] Clarify defaults --- .../additional-features/parallel-query.md | 4 ++- .../stable/architecture/design-goals.md | 2 +- .../transactions/isolation-levels.md | 8 +++--- .../transactions/read-committed.md | 8 +++--- .../ysql-yb-enable-cbo.md | 14 +++++++++- .../explore/transactions/isolation-levels.md | 10 +++---- .../configuration/postgresql-compatibility.md | 8 +++--- .../reference/configuration/yb-master.md | 4 ++- .../reference/configuration/yb-tserver.md | 26 ++++++++++++++----- 9 files changed, 58 insertions(+), 26 deletions(-) diff --git a/docs/content/stable/additional-features/parallel-query.md b/docs/content/stable/additional-features/parallel-query.md index 214c096f650c..0996fdfad816 100644 --- a/docs/content/stable/additional-features/parallel-query.md +++ b/docs/content/stable/additional-features/parallel-query.md @@ -18,11 +18,13 @@ YugabyteDB supports the use of [PostgreSQL parallel queries](https://www.postgre Currently, YugabyteDB supports parallel queries for [colocated tables](../colocation/); support for hash- and range-sharded tables is planned. +For new universes running v2025.2 or later, Parallel queries is enabled by default when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. + To enable and configure parallel queries, set the following configuration parameters. | Parameter | Description | Default | | :--- | :--- | :--- | -| yb_enable_parallel_append | Enables the planner's use of parallel append plans. To enable parallel query, set this to true. | true | +| yb_enable_parallel_append | Enables the planner's use of parallel append plans. To enable parallel query, set this to true. | false | | yb_parallel_range_rows | The number of rows to plan per parallel worker. To enable parallel query, set this to a value other than 0. (Recommended: 10000) | 0 | | yb_parallel_range_size | Approximate size of parallel range for DocDB relation scans. | 1MB | diff --git a/docs/content/stable/architecture/design-goals.md b/docs/content/stable/architecture/design-goals.md index 272d747db614..3b8a7145dc5c 100644 --- a/docs/content/stable/architecture/design-goals.md +++ b/docs/content/stable/architecture/design-goals.md @@ -56,7 +56,7 @@ YugabyteDB supports single-row linearizable writes. Linearizability is one of th YugabyteDB supports multi-row transactions with three isolation levels: Serializable, Snapshot (also known as repeatable read), and Read Committed isolation. -- The [YSQL API](../../api/ysql/) supports Serializable, Snapshot, and Read Committed (default) isolation using the PostgreSQL isolation level syntax of `SERIALIZABLE`, `REPEATABLE READ`, and `READ COMMITTED` respectively. For more details, see [Isolation levels](#transaction-isolation-levels). +- The [YSQL API](../../api/ysql/) supports Serializable, Snapshot, and Read Committed isolation using the PostgreSQL isolation level syntax of `SERIALIZABLE`, `REPEATABLE READ`, and `READ COMMITTED` respectively. For more details, see [Isolation levels](#transaction-isolation-levels). - The [YCQL API](../../api/ycql/) supports only Snapshot isolation (default) using the [BEGIN TRANSACTION](../../api/ycql/dml_transaction/) syntax. ## Partition Tolerance - CAP diff --git a/docs/content/stable/architecture/transactions/isolation-levels.md b/docs/content/stable/architecture/transactions/isolation-levels.md index b22d99d4e774..1ffe7c6669bc 100644 --- a/docs/content/stable/architecture/transactions/isolation-levels.md +++ b/docs/content/stable/architecture/transactions/isolation-levels.md @@ -15,7 +15,7 @@ Transaction isolation is foundational to handling concurrent transactions in dat YugabyteDB supports the following three strictest transaction isolation levels: -1. Read Committed (the default for new universes), which maps to the SQL isolation level of the same name. This isolation level guarantees that each statement sees all data that has been committed before it is issued (this implicitly also means that the statement sees a consistent snapshot). In addition, this isolation level internally handles read restart and conflict errors. In other words, the client does not see read restart and conflict errors (barring an exception). +1. Read Committed, which maps to the SQL isolation level of the same name. This isolation level guarantees that each statement sees all data that has been committed before it is issued (this implicitly also means that the statement sees a consistent snapshot). In addition, this isolation level internally handles read restart and conflict errors. In other words, the client does not see read restart and conflict errors (barring an exception). 2. Serializable, which maps to the SQL isolation level of the same name. This isolation level guarantees that transactions run in a way equivalent to a serial (sequential) schedule. 3. Snapshot, which maps to the SQL Repeatable Read isolation level. This isolation level guarantees that all reads made in a transaction see a consistent snapshot of the database, and the transaction itself can successfully commit only if no updates it has made conflict with any concurrent updates made by transactions that committed after that snapshot. @@ -26,9 +26,11 @@ Transaction isolation level support differs between the YSQL and YCQL APIs: Similarly to PostgreSQL, you can specify Read Uncommitted for YSQL, but it behaves the same as Read Committed. -Read Committed is supported only if the YB-TServer flag `yb_enable_read_committed_isolation` is set to `true` (the default for new universes in v2025.2 and later). +Read Committed is supported only if the YB-TServer flag `yb_enable_read_committed_isolation` is set to `true`. -In versions of YugabyteDB prior to v2025.2, `yb_enable_read_committed_isolation` is `false` by default; in this case, the Read Committed isolation level of YugabyteDB's transactional layer falls back to the stricter Snapshot isolation, making the default isolation level for the YSQL API essentially Snapshot because Read Committed, which is the YSQL API and PostgreSQL syntactic default, maps to Snapshot isolation. +For new universes running v2025.2 or later, Read Committed is enabled by default when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. + +In versions of YugabyteDB prior to v2025.2, or for manually deployed universes, `yb_enable_read_committed_isolation` is `false` (the default), and the Read Committed isolation level of YugabyteDB's transactional layer falls back to the stricter Snapshot isolation. This makes the default isolation level for the YSQL API effectively Snapshot because Read Committed, which is the YSQL API and PostgreSQL syntactic default, maps to Snapshot isolation. ## Internal locking in DocDB diff --git a/docs/content/stable/architecture/transactions/read-committed.md b/docs/content/stable/architecture/transactions/read-committed.md index 62b3f4e8dbc3..300c7259c329 100644 --- a/docs/content/stable/architecture/transactions/read-committed.md +++ b/docs/content/stable/architecture/transactions/read-committed.md @@ -23,9 +23,11 @@ Note that retries for the statement in YugabyteDB's Read Committed isolation are {{< tip title="Enable Read Committed" >}} -Read Committed is supported only if the YB-TServer flag `yb_enable_read_committed_isolation` is set to `true` (the default for new universes in v2025.2 and later). +Read Committed is supported only if the YB-TServer flag `yb_enable_read_committed_isolation` is set to `true`. -In versions of YugabyteDB prior to v2025.2, `yb_enable_read_committed_isolation` is `false` by default; in this case, the Read Committed isolation level of YugabyteDB's transactional layer falls back to the stricter Snapshot isolation, making the default isolation level for the YSQL API essentially Snapshot because Read Committed, which is the YSQL API and PostgreSQL syntactic default, maps to Snapshot isolation. +For new universes running v2025.2 or later, Read Committed is enabled by default when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. + +In versions of YugabyteDB prior to v2025.2, or for manually deployed universes, `yb_enable_read_committed_isolation` is `false` (the default), and the Read Committed isolation level of YugabyteDB's transactional layer falls back to the stricter Snapshot isolation. This makes the default isolation level for the YSQL API effectively Snapshot because Read Committed, which is the YSQL API and PostgreSQL syntactic default, maps to Snapshot isolation. Refer to [Usage](#usage) to start a Read Committed transaction after enabling the flag. {{< /tip >}} @@ -344,7 +346,7 @@ The retries for serialization errors are done at the statement level. Each retry ## Usage -To use Read Committed isolation, ensure the YB-TServer flag `yb_enable_read_committed_isolation=true` (the default for new universes in v2025.2 and later); this maps the syntactic Read Committed isolation in YSQL to the Read Committed implementation in DocDB. (When set to `false`, syntactic Read Committed in YSQL is mapped to Snapshot isolation in DocDB, meaning it behaves as Repeatable Read.) +To use Read Committed isolation, ensure the YB-TServer flag `yb_enable_read_committed_isolation=true`; this maps the syntactic Read Committed isolation in YSQL to the Read Committed implementation in DocDB. (When set to `false`, syntactic Read Committed in YSQL is mapped to Snapshot isolation in DocDB, meaning it behaves as Repeatable Read.) Assuming the flag has been set, you can start a Read Committed transaction in the following ways: diff --git a/docs/content/stable/best-practices-operations/ysql-yb-enable-cbo.md b/docs/content/stable/best-practices-operations/ysql-yb-enable-cbo.md index ba8dc598a0a8..6c9d32d5d428 100644 --- a/docs/content/stable/best-practices-operations/ysql-yb-enable-cbo.md +++ b/docs/content/stable/best-practices-operations/ysql-yb-enable-cbo.md @@ -26,7 +26,19 @@ You configure CBO using the [yb_enable_cbo](../../reference/configuration/yb-tse ## New deployments -For new YSQL deployments, or when migrating from another system, CBO is enabled by default. +For new universes running v2025.2 or later, CBO is enabled by default when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. + +For older YSQL deployments, or when deploying manually, to enable CBO, add the parameter to [ysql_pg_conf_csv](../../reference/configuration/yb-tserver/#ysql-pg-conf-csv) as follows: + +```sh +--ysql_pg_conf_csv=yb_enable_cbo=on +``` + +Alternatively, set the following YB-TServer flag: + +```sh +--ysql_yb_enable_cbo=on +``` ## Existing deployments diff --git a/docs/content/stable/explore/transactions/isolation-levels.md b/docs/content/stable/explore/transactions/isolation-levels.md index 4ccafad3ca26..494c27a9e143 100644 --- a/docs/content/stable/explore/transactions/isolation-levels.md +++ b/docs/content/stable/explore/transactions/isolation-levels.md @@ -37,15 +37,15 @@ YugabyteDB supports three isolation levels in the transactional layer: - Snapshot - Read committed -The default isolation level for the YSQL API on new universes in v2025.2 and later is Read Committed. +The default isolation level for the YSQL API is effectively Snapshot (that is, the same as PostgreSQL's `REPEATABLE READ`) because, by default, Read committed, which is the YSQL API and PostgreSQL _syntactic_ default, maps to Snapshot isolation. -To enable Read committed, the YB-TServer flag `yb_enable_read_committed_isolation` must be set to `true` (the default on new universes in v2025.2 and later). +However, for new universes running v2025.2 or later, Read Committed is enabled by default when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. -In versions of YugabyteDB prior to v2025.2, `yb_enable_read_committed_isolation` is `false` by default; in this case, the Read Committed isolation level of YugabyteDB's transactional layer falls back to the stricter Snapshot isolation, making the default isolation level for the YSQL API essentially Snapshot because Read Committed, which is the YSQL API and PostgreSQL syntactic default, maps to Snapshot isolation. +In versions of YugabyteDB prior to v2025.2, or for manually deployed universes, to enable Read committed, you must set the YB-TServer flag `yb_enable_read_committed_isolation` to `true`. By default this flag is `false` , and the Read Committed isolation level of YugabyteDB's transactional layer falls back to the stricter Snapshot isolation. This makes the default isolation level for the YSQL API effectively Snapshot because Read Committed, which is the YSQL API and PostgreSQL syntactic default, maps to Snapshot isolation. {{< tip title="Tip" >}} -To avoid serializable errors on universes earlier than v2025.2 (that is, to run applications with no retry logic), keep the default `READ COMMITTED` isolation (`--ysql_default_transaction_isolation`), and set the YB-TServer `--yb_enable_read_committed_isolation` flag to true. This enables read committed isolation. +To avoid serializable errors (that is, to run applications with no retry logic), keep the default `READ COMMITTED` isolation (`--ysql_default_transaction_isolation`), and set the YB-TServer `--yb_enable_read_committed_isolation` flag to true. This enables read committed isolation. {{< /tip >}} @@ -377,7 +377,7 @@ Connect to the universe using two independent ysqlsh instances, referred to as s -Begin a transaction in session #1 (Read Committed is the default isolation level). +Begin a transaction in session #1. (Note that because the universe was deployed using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon, Read Committed is the default isolation level.) ```sql BEGIN TRANSACTION; diff --git a/docs/content/stable/reference/configuration/postgresql-compatibility.md b/docs/content/stable/reference/configuration/postgresql-compatibility.md index cd997f7cc022..30da3a325305 100644 --- a/docs/content/stable/reference/configuration/postgresql-compatibility.md +++ b/docs/content/stable/reference/configuration/postgresql-compatibility.md @@ -20,7 +20,7 @@ YugabyteDB is a [PostgreSQL-compatible](https://www.yugabyte.com/tech/postgres-c To test and take advantage of features developed for enhanced PostgreSQL compatibility in YugabyteDB that are in {{}}, you can enable Enhanced PostgreSQL Compatibility Mode (EPCM). When this mode is turned on, YugabyteDB is configured to use all the latest features developed for feature and performance parity. EPCM is available in [v2024.1](/stable/releases/ybdb-releases/v2024.1/) and later. -Note that from v2025.2, all the features in EPCM are enabled by default in new universes. Use individual flags to set features. +For new universes running v2025.2 or later, all the features in EPCM are enabled by default when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. The following features are part of EPCM. @@ -41,7 +41,7 @@ After turning this mode on, as you upgrade universes, YugabyteDB will automatica As features included in the PostgreSQL compatibility mode transition from {{}} to {{}} in subsequent versions of YugabyteDB, they become enabled by default on new universes, and are no longer managed under EPCM on your existing universes after the upgrade. -From v2025.2, all the features in EPCM are enabled by default in new universes. Use individual flags to set features. +In v2025.2 and later, all the features in EPCM are enabled by default when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. {{}} If you have set these features independent of EPCM, you cannot use EPCM. @@ -147,9 +147,9 @@ To learn about parallel queries, see [Parallel queries](../../../additional-feat ## Enable EPCM -From v2025.2, all the features in EPCM are enabled by default in new universes. Use individual flags to set features. +In v2025.2 and later, all the features in EPCM are enabled by default in new universes when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. -For versions prior to v2025.2, you can enable EPCM as follows. +For versions prior to v2025.2 (or when deploying manually), you can enable EPCM as follows. ### YugabyteDB diff --git a/docs/content/stable/reference/configuration/yb-master.md b/docs/content/stable/reference/configuration/yb-master.md index 3deef37123aa..d6879593f542 100644 --- a/docs/content/stable/reference/configuration/yb-master.md +++ b/docs/content/stable/reference/configuration/yb-master.md @@ -1066,7 +1066,9 @@ See also [Auto Analyze Service TServer flags](../yb-tserver/#auto-analyze-servic {{}}Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. -Default: true +In v2025.2 and later, Auto Analyze is enabled by default in new universes when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. + +Default: false ## Advisory lock flags diff --git a/docs/content/stable/reference/configuration/yb-tserver.md b/docs/content/stable/reference/configuration/yb-tserver.md index d966df360cbd..b5d41ca209d9 100644 --- a/docs/content/stable/reference/configuration/yb-tserver.md +++ b/docs/content/stable/reference/configuration/yb-tserver.md @@ -392,11 +392,15 @@ Bitmap scans are only supported for LSM indexes. {{% tags/wrap %}} -Default: `true` +Default: `false` {{% /tags/wrap %}} -Enables or disables the query planner's use of bitmap scans for YugabyteDB relations. Both [enable_bitmapscan](#enable-bitmapscan) and `yb_enable_bitmapscan` must be set to true for a YugabyteDB relation to use a bitmap scan. If `yb_enable_bitmapscan` is false, the planner never uses a YugabyteDB bitmap scan. +Enables or disables the query planner's use of bitmap scans for YugabyteDB relations. + +In v2025.2 and later, bitmap scan is enabled by default in new universes when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. + +Both [enable_bitmapscan](#enable-bitmapscan) and `yb_enable_bitmapscan` must be set to true for a YugabyteDB relation to use a bitmap scan. If `yb_enable_bitmapscan` is false, the planner never uses a YugabyteDB bitmap scan. | enable_bitmapscan | yb_enable_bitmapscan | Result | | :--- | :--- | :--- | @@ -2126,11 +2130,13 @@ See also the [yb_enable_cbo](#yb-enable-cbo) configuration parameter. If this fl {{% tags/wrap %}} {{}} -Default: `on` +Default: `legacy_mode` {{% /tags/wrap %}} Enables the YugabyteDB [cost-based optimizer](../../../architecture/query-layer/planner-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 enabling CBO, you must run 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](../../../best-practices-operations/ysql-yb-enable-cbo/). @@ -2153,11 +2159,13 @@ See also [Auto Analyze Service Master flags](../yb-master/#auto-analyze-service- {{}} {{}} {{}} -Default: `true` +Default: `false` {{% /tags/wrap %}} Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. +In v2025.2 and later, Auto Analyze is enabled by default in new universes when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. + ##### --ysql_enable_table_mutation_counter {{% tags/wrap %}} @@ -2649,7 +2657,9 @@ Specifies the default transaction isolation level. Valid values: `SERIALIZABLE`, `REPEATABLE READ`, `READ COMMITTED`, and `READ UNCOMMITTED`. -[Read Committed Isolation](../../../explore/transactions/isolation-levels/) is supported only if the YB-TServer flag `yb_enable_read_committed_isolation` is set to `true` (the default). +[Read Committed Isolation](../../../explore/transactions/isolation-levels/) is supported only if the YB-TServer 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). @@ -2657,12 +2667,14 @@ If `yb_enable_read_committed_isolation` is `false`, the Read Committed isolation {{% tags/wrap %}} {{}} -Default: `true` +Default: `false` {{% /tags/wrap %}} Enables Read Committed Isolation. -When set to false, `READ COMMITTED` (and `READ UNCOMMITTED`) isolation level of YSQL fall back to the stricter [Snapshot Isolation](../../../explore/transactions/isolation-levels/). See [--ysql_default_transaction_isolation](#ysql-default-transaction-isolation) flag for more details. +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](../../../explore/transactions/isolation-levels/). See also the [--ysql_default_transaction_isolation](#ysql-default-transaction-isolation) flag. ##### --pg_client_use_shared_memory From ba88111280e56c765b39452bd2c92ab6b6793f1a Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Wed, 26 Nov 2025 11:54:19 -0500 Subject: [PATCH 5/8] added more links/details --- .../best-practices-operations/ysql-yb-enable-cbo.md | 8 ++++++++ .../stable/deploy/manual-deployment/start-masters.md | 2 ++ docs/content/stable/manage/upgrade-deployment.md | 8 +++++++- .../reference/configuration/postgresql-compatibility.md | 2 +- 4 files changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/content/stable/best-practices-operations/ysql-yb-enable-cbo.md b/docs/content/stable/best-practices-operations/ysql-yb-enable-cbo.md index 6c9d32d5d428..135ea8fff0b3 100644 --- a/docs/content/stable/best-practices-operations/ysql-yb-enable-cbo.md +++ b/docs/content/stable/best-practices-operations/ysql-yb-enable-cbo.md @@ -55,6 +55,14 @@ When upgrading a deployment to a version of YugabyteDB that supports the `yb_ena You should migrate existing deployments from using `legacy_mode` or `legacy_stats_mode` to either `on` (recommended) or, if you do not want to use CBO, `off`. +Note that when upgrading a deployment to v2025.2 or later, if the universe has the cost-based optimizer enabled (`on`), YugabyteDB will enable the following features: + +- Auto Analyze: ysql_enable_auto_analyze_service is set to true. +- Bitmap scans: yb_enable_bitmapscan is set to true. +- Parallel append: yb_enable_parallel_append is set to true. + +For more information on these features, see [Enhanced PostgreSQL Compatibility](../../reference/configuration/postgresql-compatibility/). +