From c112eda27dc11acef5648bf7134069e51e493de0 Mon Sep 17 00:00:00 2001 From: Arpit Saxena Date: Thu, 11 Jun 2026 19:21:51 +0530 Subject: [PATCH 1/6] Add sections for ALTER GUC handling in conn mgr --- .../connection-manager-ysql/ycm-setup.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md b/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md index aa4f732dd0ca..4fadd09d6583 100644 --- a/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md +++ b/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md @@ -124,6 +124,8 @@ The following table describes YB-TServer flags related to YSQL Connection Manage | ysql_conn_mgr_optimized_session_parameters | Optimize usage of session parameters in YSQL Connection Manager. If set to false, all applied session parameters are replayed at transaction boundaries for each client connection.
Default: true | | ysql_conn_mgr_max_phy_conn_percent | Deprecated in v2025.2.1.0. Use `ysql_conn_mgr_reserve_internal_conns` instead.
Maximum percentage of `ysql_max_connections` that YSQL Connection Manager can use for its server connections. A value of 85 establishes a soft limit of 0.85 * `ysql_max_connections` on server connections.
Default: 85 | | ysql_conn_mgr_reserve_internal_conns | The number of physical connections to reserve for internal operations, out of the total number of connections (per node) as set using [ysql_max_connections](../../../reference/configuration/yb-tserver/#ysql-max-connections). The reserved connections bypass YSQL Connection Manager; the remaining connections are available for the Connection Manager pool. For example, if `ysql_max_connections` is 300 and this flag is set to 15, YSQL Connection Manager will have a physical connection limit of 285 (300 - 15) per node.
Default: 15. v2025.2.1.0 and later only. | +| ysql_conn_mgr_alter_guc_adoption_strategy | Strategy used by YSQL Connection Manager to adopt configuration parameter (GUC) settings changed by ALTER ROLE and ALTER DATABASE statements. One of `fluctuating`, `gradual`, or `connection_static`. See [Handling ALTER ROLE and ALTER DATABASE](#handling-alter-role-and-alter-database).
Default: gradual | +| ysql_conn_mgr_alter_guc_stale_backend_ttl_ms | Maximum time (in milliseconds) that a backend which doesn't have the latest ALTER GUC settings is allowed to stay alive. When set to a positive value, stale backends are terminated uniformly within the TTL period after the ALTER is executed. `-1` means no action is taken on stale backends; `0` means stale idle backends are destroyed immediately and stale active backends are destroyed when they next become idle. Applies regardless of the `ysql_conn_mgr_alter_guc_adoption_strategy` setting.
Default: 60000 | ## Authentication methods @@ -234,9 +236,21 @@ When using YSQL Connection Manager, sticky connections can form in the following - Any string-type variables of extensions - `yb_read_after_commit_visibility` +## Handling ALTER ROLE and ALTER DATABASE + +`ALTER ROLE ... SET` and `ALTER DATABASE ... SET` statements change the default values of configuration parameters (GUCs) for a role or database. Because YSQL Connection Manager multiplexes many client sessions over a smaller pool of backend processes, a backend that was created before such an ALTER may not have the new settings. The `ysql_conn_mgr_alter_guc_adoption_strategy` flag controls how existing sessions behave after an ALTER: + +- `fluctuating` — No special handling is done. Successive transactions in the same session may run on backends with or without the new settings, so the configuration parameter values observed by the session may fluctuate. +- `gradual` (default) — Existing sessions gradually adopt the new settings. Subsequent transactions are routed to backends that have the latest ALTER settings. +- `connection_static` — Existing sessions retain the configuration parameter settings they had at the time of connection and never observe later ALTER statements. This is closest to the behavior of vanilla PostgreSQL. + +In both the `gradual` and `connection_static` modes, new sessions always observe the effects of ALTER statements that were issued before they were created. + +Independent of the adoption strategy, the `ysql_conn_mgr_alter_guc_stale_backend_ttl_ms` flag bounds how long backends that don't have the latest ALTER settings ("stale" backends) are allowed to stay alive, so that they are eventually recycled. Only _idle_ stale backends are terminated: a stale backend that is currently running a transaction is never interrupted, and is recycled only after it becomes idle. As a result, the effective lifetime of a stale backend can exceed the configured TTL if it stays busy. + ## Limitations -- Changes to [configuration parameters](../../../reference/configuration/yb-tserver/#postgresql-configuration-parameters) for a user or database that are set using ALTER ROLE SET or ALTER DATABASE SET queries may reflect in other pre-existing active sessions. +- The logical client version increment caused by an ALTER ROLE SET or ALTER DATABASE SET query is only observed by the YSQL Connection Manager instance on the node where the ALTER was executed; it is not yet propagated to Connection Manager instances on other nodes. As a result, the stale-backend TTL (`ysql_conn_mgr_alter_guc_stale_backend_ttl_ms`) takes effect only on that node, and stale backends on other nodes do not respect the TTL. New connections on all nodes continue to observe the settings of the latest ALTER. For more information on how ALTER statements are handled, see [Handling ALTER ROLE and ALTER DATABASE](#handling-alter-role-and-alter-database). {{}} - YSQL Connection Manager can route up to 10,000 connection pools. This includes pools corresponding to dropped users and databases. - Prepared statements may be visible to other sessions in the same connection pool. {{}} - Attempting to use DEALLOCATE/DEALLOCATE ALL queries can result in unexpected behavior. {{}} From fe28c7bb08685a8cce2bd9d857df7d173b3b62c2 Mon Sep 17 00:00:00 2001 From: Arpit Saxena Date: Thu, 11 Jun 2026 19:23:27 +0530 Subject: [PATCH 2/6] Mention version from which these flags are available --- .../additional-features/connection-manager-ysql/ycm-setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md b/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md index 4fadd09d6583..571ff2a52644 100644 --- a/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md +++ b/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md @@ -124,8 +124,8 @@ The following table describes YB-TServer flags related to YSQL Connection Manage | ysql_conn_mgr_optimized_session_parameters | Optimize usage of session parameters in YSQL Connection Manager. If set to false, all applied session parameters are replayed at transaction boundaries for each client connection.
Default: true | | ysql_conn_mgr_max_phy_conn_percent | Deprecated in v2025.2.1.0. Use `ysql_conn_mgr_reserve_internal_conns` instead.
Maximum percentage of `ysql_max_connections` that YSQL Connection Manager can use for its server connections. A value of 85 establishes a soft limit of 0.85 * `ysql_max_connections` on server connections.
Default: 85 | | ysql_conn_mgr_reserve_internal_conns | The number of physical connections to reserve for internal operations, out of the total number of connections (per node) as set using [ysql_max_connections](../../../reference/configuration/yb-tserver/#ysql-max-connections). The reserved connections bypass YSQL Connection Manager; the remaining connections are available for the Connection Manager pool. For example, if `ysql_max_connections` is 300 and this flag is set to 15, YSQL Connection Manager will have a physical connection limit of 285 (300 - 15) per node.
Default: 15. v2025.2.1.0 and later only. | -| ysql_conn_mgr_alter_guc_adoption_strategy | Strategy used by YSQL Connection Manager to adopt configuration parameter (GUC) settings changed by ALTER ROLE and ALTER DATABASE statements. One of `fluctuating`, `gradual`, or `connection_static`. See [Handling ALTER ROLE and ALTER DATABASE](#handling-alter-role-and-alter-database).
Default: gradual | -| ysql_conn_mgr_alter_guc_stale_backend_ttl_ms | Maximum time (in milliseconds) that a backend which doesn't have the latest ALTER GUC settings is allowed to stay alive. When set to a positive value, stale backends are terminated uniformly within the TTL period after the ALTER is executed. `-1` means no action is taken on stale backends; `0` means stale idle backends are destroyed immediately and stale active backends are destroyed when they next become idle. Applies regardless of the `ysql_conn_mgr_alter_guc_adoption_strategy` setting.
Default: 60000 | +| ysql_conn_mgr_alter_guc_adoption_strategy | Strategy used by YSQL Connection Manager to adopt configuration parameter (GUC) settings changed by ALTER ROLE and ALTER DATABASE statements. One of `fluctuating`, `gradual`, or `connection_static`. See [Handling ALTER ROLE and ALTER DATABASE](#handling-alter-role-and-alter-database).
Default: gradual. v2025.2.4.0 and later only. | +| ysql_conn_mgr_alter_guc_stale_backend_ttl_ms | Maximum time (in milliseconds) that a backend which doesn't have the latest ALTER GUC settings is allowed to stay alive. When set to a positive value, stale backends are terminated uniformly within the TTL period after the ALTER is executed. `-1` means no action is taken on stale backends; `0` means stale idle backends are destroyed immediately and stale active backends are destroyed when they next become idle. Applies regardless of the `ysql_conn_mgr_alter_guc_adoption_strategy` setting.
Default: 60000. v2025.2.4.0 and later only. | ## Authentication methods From 138fcaac42d4c80accf7d83e92d2b7fd38666d02 Mon Sep 17 00:00:00 2001 From: Arpit Saxena Date: Thu, 11 Jun 2026 19:25:45 +0530 Subject: [PATCH 3/6] Minor moving around of things --- .../additional-features/connection-manager-ysql/ycm-setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md b/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md index 571ff2a52644..0e20768682cc 100644 --- a/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md +++ b/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md @@ -236,7 +236,7 @@ When using YSQL Connection Manager, sticky connections can form in the following - Any string-type variables of extensions - `yb_read_after_commit_visibility` -## Handling ALTER ROLE and ALTER DATABASE +## ALTER ROLE SET / ALTER DATABASE SET commands `ALTER ROLE ... SET` and `ALTER DATABASE ... SET` statements change the default values of configuration parameters (GUCs) for a role or database. Because YSQL Connection Manager multiplexes many client sessions over a smaller pool of backend processes, a backend that was created before such an ALTER may not have the new settings. The `ysql_conn_mgr_alter_guc_adoption_strategy` flag controls how existing sessions behave after an ALTER: @@ -250,7 +250,6 @@ Independent of the adoption strategy, the `ysql_conn_mgr_alter_guc_stale_backend ## Limitations -- The logical client version increment caused by an ALTER ROLE SET or ALTER DATABASE SET query is only observed by the YSQL Connection Manager instance on the node where the ALTER was executed; it is not yet propagated to Connection Manager instances on other nodes. As a result, the stale-backend TTL (`ysql_conn_mgr_alter_guc_stale_backend_ttl_ms`) takes effect only on that node, and stale backends on other nodes do not respect the TTL. New connections on all nodes continue to observe the settings of the latest ALTER. For more information on how ALTER statements are handled, see [Handling ALTER ROLE and ALTER DATABASE](#handling-alter-role-and-alter-database). {{}} - YSQL Connection Manager can route up to 10,000 connection pools. This includes pools corresponding to dropped users and databases. - Prepared statements may be visible to other sessions in the same connection pool. {{}} - Attempting to use DEALLOCATE/DEALLOCATE ALL queries can result in unexpected behavior. {{}} @@ -262,3 +261,4 @@ Independent of the adoption strategy, the `ysql_conn_mgr_alter_guc_stale_backend - The use of auth-backends (`ysql_conn_mgr_use_auth_backend=true`) to authenticate client connections can result in higher connection acquisition latencies. Contact {{% support-general %}} about whether setting `ysql_conn_mgr_use_auth_backend` to false is the recommended setting for your workload. {{}} - Unix socket connections to YSQL Connection Manager are not supported. {{}} - Connection manager is not supported or included in the MacOS YugabyteDB releases, and there are currently no plans to support it. +- The logical client version increment caused by an ALTER ROLE SET or ALTER DATABASE SET query is only observed by the YSQL Connection Manager instance on the node where the ALTER was executed; it is not yet propagated to Connection Manager instances on other nodes. As a result, the stale-backend TTL (`ysql_conn_mgr_alter_guc_stale_backend_ttl_ms`) takes effect only on that node, and stale backends on other nodes do not respect the TTL. New connections on all nodes continue to observe the settings of the latest ALTER. For more information on how ALTER statements are handled, see [Handling ALTER ROLE and ALTER DATABASE](#handling-alter-role-and-alter-database). {{}} From bc3d65d2813ae056f8a7e5e0489517d3e6892c4b Mon Sep 17 00:00:00 2001 From: Arpit Saxena Date: Thu, 11 Jun 2026 19:36:11 +0530 Subject: [PATCH 4/6] Fix cross-reference anchors to renamed ALTER section The section heading was renamed to 'ALTER ROLE SET / ALTER DATABASE SET commands', so update the two in-page links to use the matching blackfriday anchor and link text. Co-Authored-By: Claude Opus 4.8 --- .../additional-features/connection-manager-ysql/ycm-setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md b/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md index 0e20768682cc..e1148cf8bdc3 100644 --- a/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md +++ b/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md @@ -124,7 +124,7 @@ The following table describes YB-TServer flags related to YSQL Connection Manage | ysql_conn_mgr_optimized_session_parameters | Optimize usage of session parameters in YSQL Connection Manager. If set to false, all applied session parameters are replayed at transaction boundaries for each client connection.
Default: true | | ysql_conn_mgr_max_phy_conn_percent | Deprecated in v2025.2.1.0. Use `ysql_conn_mgr_reserve_internal_conns` instead.
Maximum percentage of `ysql_max_connections` that YSQL Connection Manager can use for its server connections. A value of 85 establishes a soft limit of 0.85 * `ysql_max_connections` on server connections.
Default: 85 | | ysql_conn_mgr_reserve_internal_conns | The number of physical connections to reserve for internal operations, out of the total number of connections (per node) as set using [ysql_max_connections](../../../reference/configuration/yb-tserver/#ysql-max-connections). The reserved connections bypass YSQL Connection Manager; the remaining connections are available for the Connection Manager pool. For example, if `ysql_max_connections` is 300 and this flag is set to 15, YSQL Connection Manager will have a physical connection limit of 285 (300 - 15) per node.
Default: 15. v2025.2.1.0 and later only. | -| ysql_conn_mgr_alter_guc_adoption_strategy | Strategy used by YSQL Connection Manager to adopt configuration parameter (GUC) settings changed by ALTER ROLE and ALTER DATABASE statements. One of `fluctuating`, `gradual`, or `connection_static`. See [Handling ALTER ROLE and ALTER DATABASE](#handling-alter-role-and-alter-database).
Default: gradual. v2025.2.4.0 and later only. | +| ysql_conn_mgr_alter_guc_adoption_strategy | Strategy used by YSQL Connection Manager to adopt configuration parameter (GUC) settings changed by ALTER ROLE and ALTER DATABASE statements. One of `fluctuating`, `gradual`, or `connection_static`. See [ALTER ROLE SET / ALTER DATABASE SET commands](#alter-role-set-alter-database-set-commands).
Default: gradual. v2025.2.4.0 and later only. | | ysql_conn_mgr_alter_guc_stale_backend_ttl_ms | Maximum time (in milliseconds) that a backend which doesn't have the latest ALTER GUC settings is allowed to stay alive. When set to a positive value, stale backends are terminated uniformly within the TTL period after the ALTER is executed. `-1` means no action is taken on stale backends; `0` means stale idle backends are destroyed immediately and stale active backends are destroyed when they next become idle. Applies regardless of the `ysql_conn_mgr_alter_guc_adoption_strategy` setting.
Default: 60000. v2025.2.4.0 and later only. | ## Authentication methods @@ -261,4 +261,4 @@ Independent of the adoption strategy, the `ysql_conn_mgr_alter_guc_stale_backend - The use of auth-backends (`ysql_conn_mgr_use_auth_backend=true`) to authenticate client connections can result in higher connection acquisition latencies. Contact {{% support-general %}} about whether setting `ysql_conn_mgr_use_auth_backend` to false is the recommended setting for your workload. {{}} - Unix socket connections to YSQL Connection Manager are not supported. {{}} - Connection manager is not supported or included in the MacOS YugabyteDB releases, and there are currently no plans to support it. -- The logical client version increment caused by an ALTER ROLE SET or ALTER DATABASE SET query is only observed by the YSQL Connection Manager instance on the node where the ALTER was executed; it is not yet propagated to Connection Manager instances on other nodes. As a result, the stale-backend TTL (`ysql_conn_mgr_alter_guc_stale_backend_ttl_ms`) takes effect only on that node, and stale backends on other nodes do not respect the TTL. New connections on all nodes continue to observe the settings of the latest ALTER. For more information on how ALTER statements are handled, see [Handling ALTER ROLE and ALTER DATABASE](#handling-alter-role-and-alter-database). {{}} +- The logical client version increment caused by an ALTER ROLE SET or ALTER DATABASE SET query is only observed by the YSQL Connection Manager instance on the node where the ALTER was executed; it is not yet propagated to Connection Manager instances on other nodes. As a result, the stale-backend TTL (`ysql_conn_mgr_alter_guc_stale_backend_ttl_ms`) takes effect only on that node, and stale backends on other nodes do not respect the TTL. New connections on all nodes continue to observe the settings of the latest ALTER. For more information on how ALTER statements are handled, see [ALTER ROLE SET / ALTER DATABASE SET commands](#alter-role-set-alter-database-set-commands). {{}} From e48585e241471854e94333f1e35b789d2b26b3c2 Mon Sep 17 00:00:00 2001 From: Arpit Saxena Date: Thu, 11 Jun 2026 19:45:19 +0530 Subject: [PATCH 5/6] Replace slash in ALTER section header with 'and' Slashes in markdown headers can produce inconsistent anchors across renderers (GitHub vs. Hugo/Goldmark). Update the header and the two cross-references to use the slash-free anchor. Co-Authored-By: Claude Opus 4.8 --- .../connection-manager-ysql/ycm-setup.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md b/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md index e1148cf8bdc3..931d242d3b4c 100644 --- a/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md +++ b/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md @@ -124,7 +124,7 @@ The following table describes YB-TServer flags related to YSQL Connection Manage | ysql_conn_mgr_optimized_session_parameters | Optimize usage of session parameters in YSQL Connection Manager. If set to false, all applied session parameters are replayed at transaction boundaries for each client connection.
Default: true | | ysql_conn_mgr_max_phy_conn_percent | Deprecated in v2025.2.1.0. Use `ysql_conn_mgr_reserve_internal_conns` instead.
Maximum percentage of `ysql_max_connections` that YSQL Connection Manager can use for its server connections. A value of 85 establishes a soft limit of 0.85 * `ysql_max_connections` on server connections.
Default: 85 | | ysql_conn_mgr_reserve_internal_conns | The number of physical connections to reserve for internal operations, out of the total number of connections (per node) as set using [ysql_max_connections](../../../reference/configuration/yb-tserver/#ysql-max-connections). The reserved connections bypass YSQL Connection Manager; the remaining connections are available for the Connection Manager pool. For example, if `ysql_max_connections` is 300 and this flag is set to 15, YSQL Connection Manager will have a physical connection limit of 285 (300 - 15) per node.
Default: 15. v2025.2.1.0 and later only. | -| ysql_conn_mgr_alter_guc_adoption_strategy | Strategy used by YSQL Connection Manager to adopt configuration parameter (GUC) settings changed by ALTER ROLE and ALTER DATABASE statements. One of `fluctuating`, `gradual`, or `connection_static`. See [ALTER ROLE SET / ALTER DATABASE SET commands](#alter-role-set-alter-database-set-commands).
Default: gradual. v2025.2.4.0 and later only. | +| ysql_conn_mgr_alter_guc_adoption_strategy | Strategy used by YSQL Connection Manager to adopt configuration parameter (GUC) settings changed by ALTER ROLE and ALTER DATABASE statements. One of `fluctuating`, `gradual`, or `connection_static`. See [ALTER ROLE SET and ALTER DATABASE SET commands](#alter-role-set-and-alter-database-set-commands).
Default: gradual. v2025.2.4.0 and later only. | | ysql_conn_mgr_alter_guc_stale_backend_ttl_ms | Maximum time (in milliseconds) that a backend which doesn't have the latest ALTER GUC settings is allowed to stay alive. When set to a positive value, stale backends are terminated uniformly within the TTL period after the ALTER is executed. `-1` means no action is taken on stale backends; `0` means stale idle backends are destroyed immediately and stale active backends are destroyed when they next become idle. Applies regardless of the `ysql_conn_mgr_alter_guc_adoption_strategy` setting.
Default: 60000. v2025.2.4.0 and later only. | ## Authentication methods @@ -236,7 +236,7 @@ When using YSQL Connection Manager, sticky connections can form in the following - Any string-type variables of extensions - `yb_read_after_commit_visibility` -## ALTER ROLE SET / ALTER DATABASE SET commands +## ALTER ROLE SET and ALTER DATABASE SET commands `ALTER ROLE ... SET` and `ALTER DATABASE ... SET` statements change the default values of configuration parameters (GUCs) for a role or database. Because YSQL Connection Manager multiplexes many client sessions over a smaller pool of backend processes, a backend that was created before such an ALTER may not have the new settings. The `ysql_conn_mgr_alter_guc_adoption_strategy` flag controls how existing sessions behave after an ALTER: @@ -261,4 +261,4 @@ Independent of the adoption strategy, the `ysql_conn_mgr_alter_guc_stale_backend - The use of auth-backends (`ysql_conn_mgr_use_auth_backend=true`) to authenticate client connections can result in higher connection acquisition latencies. Contact {{% support-general %}} about whether setting `ysql_conn_mgr_use_auth_backend` to false is the recommended setting for your workload. {{}} - Unix socket connections to YSQL Connection Manager are not supported. {{}} - Connection manager is not supported or included in the MacOS YugabyteDB releases, and there are currently no plans to support it. -- The logical client version increment caused by an ALTER ROLE SET or ALTER DATABASE SET query is only observed by the YSQL Connection Manager instance on the node where the ALTER was executed; it is not yet propagated to Connection Manager instances on other nodes. As a result, the stale-backend TTL (`ysql_conn_mgr_alter_guc_stale_backend_ttl_ms`) takes effect only on that node, and stale backends on other nodes do not respect the TTL. New connections on all nodes continue to observe the settings of the latest ALTER. For more information on how ALTER statements are handled, see [ALTER ROLE SET / ALTER DATABASE SET commands](#alter-role-set-alter-database-set-commands). {{}} +- The logical client version increment caused by an ALTER ROLE SET or ALTER DATABASE SET query is only observed by the YSQL Connection Manager instance on the node where the ALTER was executed; it is not yet propagated to Connection Manager instances on other nodes. As a result, the stale-backend TTL (`ysql_conn_mgr_alter_guc_stale_backend_ttl_ms`) takes effect only on that node, and stale backends on other nodes do not respect the TTL. New connections on all nodes continue to observe the settings of the latest ALTER. For more information on how ALTER statements are handled, see [ALTER ROLE SET and ALTER DATABASE SET commands](#alter-role-set-and-alter-database-set-commands). {{}} From 324eb6d3fa06493652078b3a4891a80cd7c9f7bd Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Thu, 11 Jun 2026 18:55:38 -0400 Subject: [PATCH 6/6] DOC-1301 Add support for close/deallocate in YCM --- .../additional-features/connection-manager-ysql/ycm-setup.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md b/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md index 931d242d3b4c..d4c7417daaa8 100644 --- a/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md +++ b/docs/content/stable/additional-features/connection-manager-ysql/ycm-setup.md @@ -126,6 +126,10 @@ The following table describes YB-TServer flags related to YSQL Connection Manage | ysql_conn_mgr_reserve_internal_conns | The number of physical connections to reserve for internal operations, out of the total number of connections (per node) as set using [ysql_max_connections](../../../reference/configuration/yb-tserver/#ysql-max-connections). The reserved connections bypass YSQL Connection Manager; the remaining connections are available for the Connection Manager pool. For example, if `ysql_max_connections` is 300 and this flag is set to 15, YSQL Connection Manager will have a physical connection limit of 285 (300 - 15) per node.
Default: 15. v2025.2.1.0 and later only. | | ysql_conn_mgr_alter_guc_adoption_strategy | Strategy used by YSQL Connection Manager to adopt configuration parameter (GUC) settings changed by ALTER ROLE and ALTER DATABASE statements. One of `fluctuating`, `gradual`, or `connection_static`. See [ALTER ROLE SET and ALTER DATABASE SET commands](#alter-role-set-and-alter-database-set-commands).
Default: gradual. v2025.2.4.0 and later only. | | ysql_conn_mgr_alter_guc_stale_backend_ttl_ms | Maximum time (in milliseconds) that a backend which doesn't have the latest ALTER GUC settings is allowed to stay alive. When set to a positive value, stale backends are terminated uniformly within the TTL period after the ALTER is executed. `-1` means no action is taken on stale backends; `0` means stale idle backends are destroyed immediately and stale active backends are destroyed when they next become idle. Applies regardless of the `ysql_conn_mgr_alter_guc_adoption_strategy` setting.
Default: 60000. v2025.2.4.0 and later only. | +| ysql_conn_mgr_enable_prep_stmt_close1 | Applies only to named prepared statements. When enabled, YSQL Connection Manager forwards Close messages to the backend, which drops the prepared statement only if its cached plan is invalid or the connection is sticky; valid plans on non-sticky connections are retained for reuse across logical connections. Unnamed prepared statements are not covered; see {{}}. When disabled, Close messages are handled as a no-op by the connection manager and never reach the backend, which can cause errors. Requires `ysql_conn_mgr_optimized_extended_query_protocol` to be enabled.
Default: true. v2025.2.4.0 and later only. | +| ysql_yb_conn_mgr_selective_deallocate | When enabled, DEALLOCATE commands sent via YSQL Connection Manager only drop prepared statements whose cached plans are invalid (for example, stale due to schema changes or `search_path` drift), while preserving valid statements that may be shared across logical connections on the same backend. SQL-level prepared statements (from PREPARE) are always dropped because they make the connection sticky. When disabled, standard PostgreSQL DEALLOCATE behavior applies: `DEALLOCATE ALL` unconditionally drops all statements, and `DEALLOCATE ` fails for protocol-level prepared statements.
Default: true. v2025.2.4.0 and later only. | + +1 In v2025.2.3.0, this flag was named `ysql_conn_mgr_deallocate_if_invalid_prep_stmt`; the old name is deprecated. ## Authentication methods @@ -252,7 +256,6 @@ Independent of the adoption strategy, the `ysql_conn_mgr_alter_guc_stale_backend - YSQL Connection Manager can route up to 10,000 connection pools. This includes pools corresponding to dropped users and databases. - Prepared statements may be visible to other sessions in the same connection pool. {{}} -- Attempting to use DEALLOCATE/DEALLOCATE ALL queries can result in unexpected behavior. {{}} - Currently, you can't apply custom configurations to individual pools. The YSQL Connection Manager configuration applies to all pools. - When YSQL Connection Manager is enabled, the backend PID stored using JDBC drivers may not be accurate. This does not affect backend-specific functionalities (for example, cancel queries), but this PID should not be used to identify the backend process. - By default, `currval` and `lastval` functions do not work when YSQL Connection Manager is enabled. They can be supported with the help of the `ysql_conn_mgr_sequence_support_mode` flag.