Enforce prepared statements cache limits at runtime, add memory limit

[IgorOhrimenko]

Problem

The global prepared statements cache is enforced by a 1 Hz maintenance task that calls close_unused(prepared_statements_limit), but three things undermine it:

• The default prepared_statements_limit is i64::MAX, so out of the box every statement a client ever released is kept forever.
• There is no memory-based limit at all: the count says nothing about entry size, and entries carry the full Parse (plus a rewritten copy and a RowDescription when present).
• Enforcement only happens once a second, so a burst of prepare/close cycles can overshoot between ticks.

What this PR does not fix, explicitly: statements a client is still holding can never be evicted — dropping one would break the client using it. A workload that keeps millions of unique statements open (we watched ~6M held statements take a pooler to ~7 GiB RSS until the clients disconnected) is out of reach for any unused-only eviction, including this one and the existing maintenance task. Protecting against that needs a per-client cap or similar — happy to discuss as a follow-up; this PR bounds what released statements can accumulate, immediately rather than at the next tick.

Change

Same shape as the query cache limits in #1266:

• prepared_statements_limit and the new prepared_statements_memory_limit (bytes, 0 = unlimited, env PGDOG_PREPARED_STATEMENTS_MEMORY_LIMIT, settable from the admin console) are enforced at the moment the cache grows or a statement is released, not just at the next maintenance tick.
• Eviction is deterministic — oldest released statement first (unused is a BTreeSet now) — and only ever touches statements nobody holds.
• The byte total is maintained incrementally on insert/remove/rewrite/describe, so enforcement doesn't rescan the maps, and GlobalCache::memory_usage() returns that same number — the prepared_statements_memory_used metric and the budget can't drift apart. A prepared_statements_memory_limit gauge is exported next to it.

Behavior changes

• Admin console SET prepared_statements_limit TO 0 used to wipe the cache; it now means "unlimited" (matching the config semantics) and logs a warning pointing at RESET PREPARED.
• RESET PREPARED now passes 0 explicitly and clears everything not in use regardless of the configured limit — with the default (unlimited) limit it used to be a no-op.
• close_unused(0) no longer resets the name counter: global __pgdog_N names are never reused, so a server connection holding an old name can't be handed a different query under it.

Testing

Unit tests for enforcement (capacity and memory eviction, in-use statements never evicted, 0 = unlimited, immediate enforcement on configure, deterministic oldest-first order, release via both close() and decrement(), counter preserved across RESET PREPARED) and a byte-accounting invariant test that recounts the total from live entries after a mix of inserts, duplicate inserts, insert_anyway, late RowDescription, rewrite() (including replacement), closes and evictions. Config env/default tests; JSON schema regenerated.

Cost note

Eviction runs under the global cache write lock. The maintenance task now goes through configure() once a second too, but when the cache is within its limits that's a couple of integer comparisons — there is nothing to evict, because insert/release enforcement already kept it in budget. The one expensive case is lowering a limit (admin SET, RELOAD) over a cache holding millions of released statements: they are all evicted in one pass and cache users wait for the duration. That's a one-off administrative action; chunked eviction can be added if it matters in practice.

Docs PR to follow once the shape is agreed on.

[codecov]

Codecov Report

❌ Patch coverage is 99.59677% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...g/src/frontend/prepared_statements/global_cache.rs	99.53%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[IgorOhrimenko]

On the Codecov report: the one uncovered line in the patch is the evict_on_close arm in close() (self.remove(name) at global_cache.rs:364). The edit next to it pulled the arm into the patch, but the flag itself is never set to true anywhere in the codebase today, so the branch is unreachable — no test can cover it. Happy to drop the field and the arm here or in a follow-up if it's actually dead, or leave it alone if it's groundwork for something planned.

[IgorOhrimenko]

A note on the ci (complex) failures on the latest commit (three in a row now): it's the shutdown check timing out, not a regression.

• The failing runs stop at waiting on N background tasks and hit shutdown.sh's 10-second budget; the ci-new-parser twin of the same suite on the same SHA passes every time.
• Locally the suite passes 7/7 on this commit unconstrained. Pinned to a single CPU to simulate a busy runner, the shutdown check fails on both this commit and its parent (which passed CI three times) at the same rate — 1/8 each — with the same waiting on N background tasks signature.
• On a healthy runner the drain takes ~5 of the allowed 10 seconds (340 → 304 → 23 tasks over ~5s in the passing log), so there's no headroom when the runner is loaded.

Same class of timing flake as #1303/#1304/#1305. Bumping wait_for_shutdown in integration/complex/shutdown.sh from 100 to ~300 iterations would give the drain the headroom it needs; happy to include that here or send it separately.