[elcritch]

Problem and behavior

PR #87 stops raw PostgreSQL connections from creating a new named statement for every parameterized call. This draft adds an opt-in ManagedDbConn for callers that own a stable libpq session and want bounded prepared-plan reuse. It prepares each distinct SQL string once on that session, up to 64 plans by default. Additional distinct SQL executes directly. maxPlans = 0 disables caching.

The connection is move-only under ARC/ORC. Scope exit or explicit close() releases its session and plans; reset() reconnects and invalidates the cache. Inline query:/query(T): and generated createProc/createIter calls accept the owned connection. Single-row and INSERT ... RETURNING paths now compile and preserve the existing raw PostgreSQL error behavior. A closed managed connection raises a clear DbError.

Safety contract

Stacked on #87: review the managed-connection commits on top of that PR until it merges. Raw DbConn calls retain their API and, through #87, use direct execution. The owned connection must be used from one thread at a time with a direct PostgreSQL connection or session pooler. Transaction pooling cannot preserve session-local plans. borrowRaw is for temporary interop; callers must not finish or reset that borrowed handle.

A missing plan, schema-induced plan error, or connection failure is returned to the caller without replaying the query, since side effects may be uncertain. After a missing or stale plan, that session switches to direct execution. The caller can explicitly reset and retry if appropriate.

Validation

• nim test passed (SQLite and compile-time suites).
• nim test_postgres passed against PostgreSQL 14, including the managed-copy compile-fail check.
• Managed PostgreSQL suite passed with debug ORC and release ARC.
• Tests cover plan reuse and cap, generated queries, move/close/reset, killed backend recovery, server plan loss, schema changes, transaction behavior, successful and empty typed/untyped single-row queries, tryQuery, and INSERT ... RETURNING success/failure.
• A libpq result-event test verifies results are released after success, no-row errors, server errors, conversion exceptions, and early iterator exits.

This remains a draft for API and lifecycle review; do not merge it before #87.

[elcritch]

This is a bigger change. In theory it should be worthwhile but I'll need to review it before it's ready to consider.