From aff62308346f18838fefe512408255396a2fb3ae Mon Sep 17 00:00:00 2001 From: Rahul Barigidad Date: Wed, 19 Feb 2025 16:39:28 +0000 Subject: [PATCH] Added sticky connections section --- .../going-beyond-sql/connection-mgr-ysql.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/content/stable/explore/going-beyond-sql/connection-mgr-ysql.md b/docs/content/stable/explore/going-beyond-sql/connection-mgr-ysql.md index 7724d5c34677..b992faa6c7f7 100644 --- a/docs/content/stable/explore/going-beyond-sql/connection-mgr-ysql.md +++ b/docs/content/stable/explore/going-beyond-sql/connection-mgr-ysql.md @@ -105,6 +105,30 @@ The following table describes YB-TServer flags related to YSQL Connection Manage | ysql_conn_mgr_sequence_support_mode | Sequence support mode when YSQL connection manager is enabled. When set to 'pooled_without_curval_lastval', the currval() and lastval() functions are not supported. When set to 'pooled_with_curval_lastval', the currval() and lastval() functions are supported. For both settings, monotonic sequence order is not guaranteed if `ysql_sequence_cache_method` is set to `connection`. To also support monotonic order, set this flag to `session`. | pooled_without_curval_lastval | | ysql_conn_mgr_optimized_extended_query_protocol | Enables optimization of [extended-query protocol](https://www.postgresql.org/docs/current/protocol-overview.html#PROTOCOL-QUERY-CONCEPTS) to provide better performance; note that while optimization is enabled, you may have correctness issues if you alter the schema of objects used in prepared statements. If set to false, extended-query protocol handling is always fully correct but unoptimized. | true | +## Sticky Connections + +YSQL Connection Manager enables a larger number of client connections to efficiently share a smaller pool of backend processes using a many-to-one multiplexing model. However, in certain cases, a backend process may enter a state that prevents connection multiplexing between transactions. When this occurs, the backend process remains dedicated to a single logical connection (hence the term “sticky connection”) for the entire session rather than just a single transaction. This behavior deviates from the typical use case, where backend processes are reassigned after each transaction. + +Some other characteristics of sticky connections: +- Backend processes corresponding to sticky connections are destroyed at the end of the session, and so, sticky connections do not return to the pool once used. +- As of now, sticky connections cannot be reverted back to an "un"-sticky connection; once a sticky connection is formed, it will remain sticky until the end of the session. + +This section outlines the various scenarios where the user can expect a logical connection to be converted into a sticky connection while using YSQL Connection Manager. + +- Creation of `TEMP` tables +- Declaration of a `CURSOR` using the `WITH HOLD` attribute +- Using a `PREPARE` query (Not to be confused with protocol-level preparation of statements) +- Superuser connections (This can be disabled using the `ysql_conn_mgr_superuser_sticky` flag) +- Using a `SEQUENCE` can make the connection sticky (Refer to `ysql_conn_mgr_sequence_support_mode` for support without stickiness) +- Replication connections +- Usage of specific session parameters (GUC variables) during the session: + - `session_authorization` + - `role` + - `default_tablespace` + - `temp_tablespaces` + - Any string-type variables of extensions + - `yb_read_after_commit_visibility` + ## Limitations - Changes to [configuration parameters](../../../reference/configuration/yb-tserver/#postgresql-server-options) 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.