Rebuild the same connection on a reset, not a weaker one

[roed-math]

Third of five PRs from the August 3 security audit.

Stacked on #133 and #134, so the diff here contains their commits too;
merge those first and this one shrinks to its own commit. (GitHub will not take
a base branch that lives in the fork, hence the main base.)

The problem

PostgresDatabase.__init__ saves the connection overrides it is given in
_connect_kwargs and uses them for the first connection. reset_connection
then calls _new_connection() with no arguments, so the replacement is built
from the configuration alone. Everything the caller passed explicitly is
dropped:

• sslmode, sslrootcert, sslcert, sslkey;
• an alternate host, port, database or user;
• libpq options;
• connect_timeout and keepalive settings.

A connection that drops mid-session can therefore come back without TLS, or
pointed at a different server or database than the one whose schema psycodict
has cached. The 25 second statement_timeout for the webserver role had the
same shape of problem: it was set once, in the constructor, with a SET on the
connection it was replacing later. The read-only, superuser, knowls and userdb
capability flags were computed once and never rechecked.

The fix

• _connection_options() is the single place where configuration and explicit
  overrides are merged, and _new_connection() takes no arguments — there is no
  longer a call shape that can forget the overrides.
• _configure_session(conn) holds the per-session setup (adapters, encoding,
  session settings) and runs for every connection, first or replacement. It
  works directly on the connection rather than through _execute, since it runs
  while recovering from a failure in _execute.
• PostgresDatabase(session_settings={...}) sets statement_timeout,
  lock_timeout, idle_in_transaction_session_timeout or application_name.
  The webserver's 25s timeout is now this setting's default for that role. The
  names are a closed set and the values go through set_config, which takes
  both as bound parameters.
• _detect_capabilities(conn) is factored out of the constructor and rerun for
  every replacement: a reconnect can land on a standby or as a role with
  different grants, and a stale _read_only = False is wrong in the unsafe
  direction. It stays where it was in the constructor's order, after
  create/upgrade, since the read-only check concludes read-only when it can
  see no writable table.
• A replacement is adopted only after _verify_identity confirms it reached the
  same database as the same role. The host is deliberately not checked, so a
  failover to a standby still works, and the TLS and endpoint options are
  preserved either way. On rejection the new connection is closed and the object
  keeps the old one.
• The replaced connection is closed rather than left to the garbage collector.

Retry semantics are untouched: a standalone statement reconnects and retries
once, and a statement inside DelayCommit still raises rather than replaying a
transaction whose earlier statements went down with the connection.

listener() already passed _connect_kwargs to NotificationListener, which
merges them over the configured options the same way; its autocommit behavior
is unchanged. I did not apply session_settings to the listener's connection —
a statement_timeout on a connection that exists to wait for notifications
seemed more likely to be wrong than right, but say the word if you would rather
it inherited them.

Tests

New tests/test_reconnect.py (11 cases): the merged options carry
sslmode/sslrootcert/sslcert/sslkey/connect_timeout/options/keepalives
(checked on the merge, so no TLS server or certificate files are needed); a
forced reset and a reset triggered by a dropped connection each record exactly
the same options as the initial connect; session settings are present before and
after a reconnect, including the webserver default; an unknown session setting is
refused; a replacement reaching a different database is refused and the object
keeps its old connection; capability flags are recomputed; a standalone statement
is retried exactly once; a DelayCommit transaction is not replayed; and an
unreachable server does not loop.

Full suite: 1017 passed, 36 skipped against PostgreSQL 18.

---

Review round (2026-08-03)

• Capability detection is atomic. _detect_capabilities now returns a
  _ConnectionCapabilities snapshot built from local variables and writes
  nothing to the database object; _apply_capabilities is the single mutation
  point. A candidate that fails a later probe — or at the commit — leaves the
  old connection, the registered objects and all four flags exactly as they
  were, and is closed.
• Registered objects get a _connection_reset() hook, a no-op by default,
  called after the replacement connection and its capabilities are in place,
  so an override can just read them. The replaced connection is closed even if
  a hook raises, and a hook's failure is not swallowed. This is for consumers
  that cache what the old session was allowed to do; the LMFDB's
  KnowlBackend._rw_knowldb and PostgresUserTable._rw_userdb/_cols are the
  known cases, and they need a downstream change to use it — written up at
  ~/claude/handoffs/lmfdb-psycodict-security-upgrade.md rather than done here.
• A connection whose per-session setup fails is closed instead of being left
  to the garbage collector holding a server slot; a failure in that close does
  not mask the original error.
• Documentation corrected: session_settings apply to the main connection
  and its replacements, not to "every connection this database opens" — a
  notification listener deliberately does not inherit them (it does inherit the
  overrides that decide which server it reaches). And _verify_identity
  compares the database name and the role, which two different clusters can
  agree on; it is not proof of reaching the same server.
• The webserver-default test now exercises the real resolver instead of
  monkeypatching it.

Full suite: 1128 passed, 36 skipped. Docs build clean under -W.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 psycodict | 🛠️ Build #33893110 | 📁 Comparing 9c17b7c against latest (85283b7)

  🔍 Preview build  

10 files changed · + 1 added · ± 9 modified

+ Added

• _modules/collections.html

± Modified

• DataManagement.html
• SECURITY.html
• genindex.html
• _modules/index.html
• api/base.html
• api/database.html
• _modules/psycodict/base.html
• _modules/psycodict/database.html
• _modules/psycodict/table.html