[Kiran01bm]

docs/session-affinity.md now explains how a client connection maps to a PostgreSQL session and backend, directly and behind each pooler mode.

Why

The page says session state lives "per server session, not per client connection" without saying what a session is. A reader new to PostgreSQL can't tell why a pooler changes anything, which is the whole reason pg-sprite needs session affinity.

What

• New subsection "Connection, session and backend": one backend per accepted connection, and that backend is the session; a table of how long a client connection keeps its backend for direct, session, transaction and statement mode; a short diagram.
• The existing state table moves under "What pg-sprite keeps in the session", and its lead-in now says "per backend".
• Contents updated.

Before / after

A reader asks why a transaction-mode pooler loses pg-sprite's lock_timeout.

Before
  "state PostgreSQL keeps per server session, not per client connection"
  reader: what is a session, and why would a pooler change it?

After
  client conn ── tx 1 ──▶ backend A   (SET lock_timeout lives in A)
              ── tx 2 ──▶ backend B   (transaction mode: B never saw it)
  reader: the session is the backend; only direct and session mode keep it

🤖 Generated with Amp (Claude Opus 4.6)