Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[doc] Added sticky connections section to Connection Manager docs #26114

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+24 −0
Open

[doc] Added sticky connections section to Connection Manager docs #26114

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions docs/content/stable/explore/going-beyond-sql/connection-mgr-ysql.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Sticky Connections
## 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand how the one relates to the other, or what you are saying here. Why don't sticky connections return to pool? Even after related backend process is destroyed at end of session?

- 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This implies the opposite - it will return to pool at end of 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
When using YSQL Connection Manager, sticky connections can form in the following circumstances:


- Creation of `TEMP` tables
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Creation of `TEMP` tables
- Creating TEMP tables

- Declaration of a `CURSOR` using the `WITH HOLD` attribute
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Declaration of a `CURSOR` using the `WITH HOLD` attribute
- Declaring a CURSOR using the WITH HOLD attribute

- Using a `PREPARE` query (Not to be confused with protocol-level preparation of statements)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Using a `PREPARE` query (Not to be confused with protocol-level preparation of statements)
- 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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'This' - what is disabled? superuser connections?

- Using a `SEQUENCE` can make the connection sticky (Refer to `ysql_conn_mgr_sequence_support_mode` for support without stickiness)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Using a `SEQUENCE` can make the connection sticky (Refer to `ysql_conn_mgr_sequence_support_mode` for support without stickiness)
- Using a SEQUENCE. (Refer to `ysql_conn_mgr_sequence_support_mode` for support without stickiness.)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does ysql_conn_mgr_sequence_support_mode do? What do you mean 'support without stickiness'? How? Is the flag documented/link?

- Replication connections
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CDC? xCluster? Any replication?

- Usage of specific session parameters (GUC variables) during the session:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Usage of specific session parameters (GUC variables) during the session:
- Setting the following configuration parameters 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.
Expand Down