feat(server,graphile): opt-in blueprint pooling integration — GRAPHILE_BLUEPRINT_POOLING (5/6)

[yyyyaaa]

Summary

PR 5/6 of the #1325 split. Turns the seam from PR 4 on, opt-in via GRAPHILE_BLUEPRINT_POOLING=1. Default off — with the flag unset the dispatcher takes exactly the pre-existing path: key = svc_key, no decision, no extra queries, no pool wrapping.

This is deliberately the smallest code PR of the stack (+425/−24): all mechanism was reviewed in PRs 2–4; this is just the wiring that connects them.

Dispatcher (graphile.ts)

• Resolves the memoized pooling decision per svc_key; pooled services share a bp:-keyed instance built fully qualified against the canonical tenant.
• Per-request routing: the requesting tenant's physical schema list travels in pgSettings via the transaction-local GUC constructive.pool_schemas, where the rewriting pool maps canonical→tenant identifiers.
• Role names de-closured: read from the request's resolved API so a shared instance uses the requesting tenant's roles, not whichever tenant happened to build it.
• (preset).schema.constructivePooled marks shared instances so plugins report logical (hash-stripped) schema names instead of leaking the canonical tenant's physical names through _meta.

Flush (flush.ts) — per-database invalidation

A schema:update flush clears only the changed database's decisions and the blueprint it was attached to. The fleet-wide alternative turned every tenant provision into a cold restart of every pooled instance — and the immediate rebuilds raced the evicted instances' drain (their ~GB stays live until in-flight requests finish), which was the measured 24h-soak OOM in #1325. New tenants have no memoized decisions, so provisioning is a no-op here (instances are shape-generic; a same-shape tenant attaches with no rebuild). The admin /flush route still clears all bp: entries.

Plugin pooling-compat (inert while the flag is off)

• meta-schema: report logical schema names when constructivePooled is set.
• presigned-url: two-tier storage-module matching — exact physical schema first (existing behavior, always wins when not pooled), logical-suffix match only as the pooled fallback; safe because configs are already filtered to one databaseId.
• bm25-codec: documents the store's concurrency contract (serialized by PR 2's build semaphore) and why bm25 shapes are excluded from pooling (bind-value index name — see PR 4).

Measured end-state (from #1325, production-shaped rig: 48 tenant DBs, 61k pg_class rows)

47 tenants pooled onto ONE 2048MB node — 30min authenticated zipf @50rps: 104,818/104,818 OK, error rate 0, p99 21ms, heap peak 195.7MB (9.6% of budget), zero cross-tenant bleed, fail-closed counter 0. Same-tenant SDL byte-identical (MD5) pooled vs dedicated. Capacity/ops guidance (heap floor 1024MB, sizing law) lands with PR 6's docs.

Testing

graphql/server 205/205 · graphile-settings 158/158 · graphile-presigned-url-plugin 25/25 (incl. new two-tier matching suite) · graphile-search 78/78.

Stack

Stacked on #1333 (feat/scale-s4-pooling-core); merge after it. Full stack map in #1330. Extracted from #1325 (kept open as the validated reference).

🤖 Generated with Claude Code

https://claude.ai/code/session_0122xqM2VkNbuAmZshK1YNSb