[sdogruyol]

Closes #1.

What

A per-connection prepared-statement cache. A statement's first run on a connection sends Parse under a generated name and Describe statement, together with Bind/Execute/Sync, in one round trip. Later runs send only Bind, Execute and Sync.

• Key: the SQL text. Parse sends no parameter types, so the server infers them from the text.
• Bound: an LRU of statement_cache_capacity entries, default 512 as in pgx. An evicted statement is closed at the start of the next exchange.
• Off switch: statement_cache_capacity=0, or iyi-db's prepared_statements_cache=false. Unprepared statements, BEGIN and COMMIT keep the unnamed Parse.
• Out-of-date statements: a statement the server refuses as out of date (26000, 0A000, class 42, or class 22 with parameters) is dropped and prepared again. Outside a transaction block the query is retried once. Inside one the error is returned, and the statement is prepared again after the transaction.
• Invalidation: DISCARD ALL and DEALLOCATE ALL empty the cache, and so does any CREATE, ALTER or DROP on the same connection.

Constants are now Share, for parallel code on iyi's multi-core scheduler:

• ConnInfo's tables and QUOTED are Lists.
• LOG and the replication logger sit behind a Mutex.
• DECODERS is a registry that builds a frozen, Share table. Each connection keeps a table, so reading a column takes no lock.
• @[SafeReach] is not used, so pg still builds on iyi 0.18.0.

Compatibility

• User-defined decoders must now be Share.
• ArrayDecoder, RecordDecoder, RangeDecoder and MultirangeDecoder return a copy of their OIDs.

Measured

• Messages per query (1000 queries on one connection, counted through a proxy): Parse, Bind, Describe, Execute and Sync before. After: Bind, Execute and Sync, plus one Parse and one Describe statement in total.
• Postgres CPU per query: 40–49 % lower. PostgreSQL 14.19 on macOS 26.6, Apple M2 Pro.
• A real web app on Windows 11 with 12 logical processors and 12 workers, over 11 database-bound GET endpoints, against its Go port (pgx):
  • throughput went from 0.60 to 0.96 of Go's;
  • postgres CPU per request went from 26.2 ms to 14.9 ms, against Go's 14.1.

Tests

• iyi test pg: 20 of 21 files pass. pg/pq/authentication_methods_test.iyi fails on master too: it needs PGPORT and scram lines in pg_hba.conf.
• New pg/statement_cache_test.iyi:
  • a hit after first use, counted in Parse messages;
  • LRU eviction, checked in pg_prepared_statements;
  • an ALTER TABLE from another session, in and out of a transaction;
  • a column type changed under a parameter;
  • an error inside a transaction;
  • DEALLOCATE and DISCARD;
  • reuse across pool checkouts;
  • the off switches.

Known limit

A migration from another session that changes a column to a type the value still converts to without error is not detected (e.g. timestamp → timestamptz on a server not in UTC). pgx has the same limit. The README says to run such migrations with the cache off, or to reconnect after them.