rsc-universal 0.1.1

package/skills/postgresdb/evals/cases.yaml

@@ -0,0 +1,57 @@
+skill: postgresdb
+
+should_trigger:
+  - prompt: "This query takes 8 seconds and the page won't load. Can you help me figure out why and speed it up?"
+    why: "Slow query / latency complaint is core scope; the skill owns reading the plan and fixing scans even though the user never says SQL or index."
+  - prompt: "We need to add a column to a 40-million-row table that's getting live traffic without taking the app down. What's the safe way?"
+    why: "Zero-downtime migration against a large table with live traffic — expand-contract, lock_timeout, batched backfill — is explicitly in scope."
+  - prompt: "Here's my EXPLAIN ANALYZE output. Why is it doing a Seq Scan on orders when I have an index on user_id?"
+    why: "Reading a plan, diagnosing Seq Scan vs index usage, and stale-stats/predicate issues are the heart of query-optimization."
+  - prompt: "Should I store this as an enum or a separate lookup table with a foreign key? The set of statuses keeps changing."
+    why: "Schema/DDL type decision (enum-vs-lookup) is a named When-to-use case with a decision rule in the skill."
+  - prompt: "Different tenants keep seeing each other's rows in our shared table. I want the database itself to enforce isolation per tenant."
+    why: "This is row-level security (RLS) operational/security scope, even though the user never names RLS or Postgres explicitly."
+  - prompt: "Our background workers keep grabbing the same job and processing it twice. They poll a jobs table. How do I make concurrent workers not collide?"
+    why: "Postgres-as-queue with FOR UPDATE SKIP LOCKED is explicitly the one queue pattern in scope; concurrency/locking is core."
+  - prompt: "I have a list view and every time I load a user's page it fires hundreds of little SELECTs, one per row. How do I fix this?"
+    why: "Classic N+1 described without the term; skill owns fixing it at the SQL boundary with a set-based query / LATERAL join."
+  - prompt: "We're running out of Postgres connections under load on our serverless app. How should we set up pooling?"
+    why: "Connection pooling / PgBouncer is named operations scope (the engine-side answer, not vendor console clicks)."
+
+should_not_trigger:
+  - prompt: "My Prisma updateMany returns the wrong count and isn't updating the rows I expect. What's the ORM doing?"
+    route_to: "none"
+    why: "Explicitly out of scope: ORM-API ergonomics like Prisma's updateMany count trap belong to the ORM's own docs, not this engine-level skill."
+  - prompt: "I need to add a SQLite full-text search index in my Expo mobile app's local database."
+    route_to: "flutter"
+    why: "Non-Postgres engine (SQLite) is explicitly out of scope — different MVCC/planner; mobile-app data lands closer to the app-framework skill, not postgresdb."
+  - prompt: "How do I configure a managed Postgres instance on RDS through the AWS console and set up automated snapshots in the UI?"
+    route_to: "deployment"
+    why: "Cloud-vendor console clicks are explicitly out of scope; provisioning/infra-through-UI is deployment territory, not engine-level SQL."
+  - prompt: "Build a FastAPI endpoint with a Pydantic request model that returns paginated results."
+    route_to: "fastapi"
+    why: "This is API-framework / request-validation work; the SQL it eventually emits could touch postgresdb but the prompt as stated is fastapi's domain."
+  - prompt: "How do I prevent SQL injection in my Node app — is parameterizing enough, and how should I handle untrusted input generally?"
+    route_to: "secure-coding"
+    why: "A general application-security question about untrusted input belongs to secure-coding; postgresdb owns engine behavior, not app-layer input handling."
+  - prompt: "Should I cache these hot query results in Redis to cut database load?"
+    route_to: "none"
+    why: "App-layer caching / Redis as a product is explicitly out of scope; only Postgres-as-queue via SKIP LOCKED is in scope, not caching layers."
+
+capability:
+  - scenario: "User has a query `SELECT * FROM orders WHERE user_id = $1 AND created_at >= $2 ORDER BY created_at DESC LIMIT 20` that is slow on a large orders table, and asks which index to add and how to confirm it helps."
+    must_include:
+      - "Proposes a composite btree index with equality column first, range/sort column second: ON orders (user_id, created_at DESC)"
+      - "Explains the index ORDER BY direction must match the query to avoid a sort, and column order rationale (equality then range)"
+      - "Instructs running EXPLAIN (ANALYZE, BUFFERS) and confirming an Index Cond (not a Filter / Rows Removed by Filter) before declaring success"
+      - "Recommends CREATE INDEX CONCURRENTLY on a live table (cannot run inside a transaction) rather than plain CREATE INDEX"
+      - "Recommends keyset/cursor pagination over large OFFSET, or at least flags OFFSET as O(n) for deep pages"
+      - "Warns against blindly adding an index when selectivity is low or the column is already a left prefix of an existing index"
+  - scenario: "User wants to add a NOT NULL `country` column to a 50M-row table that serves live traffic, with zero downtime, using a generic migration tool."
+    must_include:
+      - "Splits the change into steps (expand-contract): add nullable column first, backfill, then enforce NOT NULL — never ADD COLUMN ... NOT NULL with backfill in one shot on a large table"
+      - "Notes that a constant (non-volatile) default is instant on PG11+, but a volatile default (e.g. now()/uuid) forces a full table rewrite under ACCESS EXCLUSIVE"
+      - "Backfills in batches to avoid a long transaction / lock and bloat, rather than a single UPDATE"
+      - "Adds the NOT NULL via a CHECK ... NOT VALID then VALIDATE CONSTRAINT (or NOT NULL after backfill) to avoid a blocking full-table scan under heavy lock"
+      - "Wraps DDL with SET lock_timeout and SET statement_timeout so a blocked DDL fails fast instead of queueing behind/ahead of traffic"
+      - "States migrations are forward-only in prod and never edit an already-applied migration"

package/skills/postgresdb/references/migrations.md

@@ -0,0 +1,279 @@
+# PostgreSQL zero-downtime migrations
+
+Safe DDL against tables with real data and live traffic, on PostgreSQL 16, across raw SQL,
+golang-migrate, Alembic, and Prisma. Running example: add `avatar_url` to `users`, index it
+concurrently, backfill `display_name`.
+
+> Using Drizzle, Kysely, Django, or another migration runner not shown here? The engine-level rules
+> below (expand–contract, `CONCURRENTLY` outside a txn, `NOT VALID` then `VALIDATE`, batched backfill)
+> are identical regardless of runner — translate the raw-SQL recipes into your tool's directives. The
+> per-tool workflow/wiring of those runners lives in each runner's own upstream documentation (they are
+> external tools, not companion skills); the engine-level recipes here are what those directives must
+> ultimately emit.
+
+## Principles
+
+- **Forward-only in prod.** Roll back with a new forward migration, not by editing history.
+- **DDL and DML in separate migrations.** A schema change and a data backfill have different lock and
+  duration profiles; never mix them.
+- **Immutable once applied.** Editing an applied migration drifts environments (and breaks Prisma's
+  checksum).
+- **Test against prod-sized data.** A migration that is instant on 100 rows can hold ACCESS EXCLUSIVE
+  for minutes on 10M.
+- **Bound every risky DDL** so a wait can never become an outage:
+
+```sql
+SET lock_timeout = '3s';        -- give up acquiring the lock rather than queueing behind it
+SET statement_timeout = '0';    -- or a bounded value per backfill step
+```
+
+A blocked DDL holding ACCESS EXCLUSIVE queues *every* subsequent query behind it; `lock_timeout` makes
+the migration fail fast instead of stalling the whole table.
+
+## Lock-impact reference
+
+| Operation | Lock | Reads | Writes | Safe variant |
+| --- | --- | --- | --- | --- |
+| `ADD COLUMN` (nullable, no default) | ACCESS EXCLUSIVE (brief) | no | no | metadata-only, instant |
+| `ADD COLUMN ... DEFAULT <const>` (PG11+) | ACCESS EXCLUSIVE (brief) | no | no | instant; default stored in catalog |
+| `ADD COLUMN ... DEFAULT <volatile>` | ACCESS EXCLUSIVE (long) | yes | yes | add nullable → batched backfill |
+| `ALTER COLUMN ... TYPE` (rewrite) | ACCESS EXCLUSIVE (long) | yes | yes | expand-contract new column |
+| `ADD CHECK` | ACCESS EXCLUSIVE + full scan | yes | yes | `... NOT VALID` then `VALIDATE` |
+| `ADD FOREIGN KEY` | SHARE ROW EXCLUSIVE + scan | no | yes | `... NOT VALID` then `VALIDATE` |
+| `SET NOT NULL` | ACCESS EXCLUSIVE + full scan | yes | yes | add validated CHECK first (PG12+ skips re-scan) |
+| `CREATE INDEX` | SHARE (blocks writes) | no | yes | `CREATE INDEX CONCURRENTLY` |
+| `CREATE INDEX CONCURRENTLY` | SHARE UPDATE EXCLUSIVE | no | no | the safe one; 2 scans, no txn |
+| `DROP COLUMN` | ACCESS EXCLUSIVE (brief) | no | no | code-first, then drop |
+| `VACUUM FULL` | ACCESS EXCLUSIVE (long) | yes | yes | autovacuum / `pg_repack` |
+
+## Expand–contract (zero-downtime)
+
+The only safe way to rename a column, change its type, or split/merge columns. Each arrow is a
+deployable step; the schema and the app are always compatible.
+
+```text
+1. EXPAND   add the new column/table (nullable or instant-default). Schema-only, no app change.
+2. DUAL-WRITE + BACKFILL   deploy app that writes BOTH old and new; backfill old rows in batches.
+3. MIGRATE READS   deploy app that reads NEW, still writes both; verify parity.
+4. CONTRACT   deploy app that uses only NEW; in a later migration drop the old column.
+```
+
+Never collapse these into one migration. The gap between deploys is where reads and writes stay
+consistent across rolling app instances running mixed versions.
+
+## Safe recipes (raw SQL)
+
+### Add a NOT NULL column safely
+
+```sql
+-- 1. add nullable (instant, metadata-only)
+ALTER TABLE users ADD COLUMN display_name text;
+-- 2. batched backfill (see "Batched backfill" below)
+-- 3. add the NOT NULL invariant as a NOT VALID check, then validate under a light lock
+ALTER TABLE users ADD CONSTRAINT ck_users_display_name_nn
+    CHECK (display_name IS NOT NULL) NOT VALID;
+ALTER TABLE users VALIDATE CONSTRAINT ck_users_display_name_nn;  -- scans, SHARE UPDATE EXCLUSIVE
+-- 4. promote to a real NOT NULL: PG12+ reuses the proven CHECK and skips the full re-scan
+ALTER TABLE users ALTER COLUMN display_name SET NOT NULL;
+ALTER TABLE users DROP CONSTRAINT ck_users_display_name_nn;
+```
+
+### Add an index concurrently (and clean a failed one)
+
+```sql
+CREATE INDEX CONCURRENTLY ix_users_avatar_url ON users (avatar_url);
+-- A failed CONCURRENTLY build leaves an INVALID index that still costs writes:
+SELECT indexrelid::regclass FROM pg_index WHERE NOT indisvalid;
+DROP INDEX CONCURRENTLY ix_users_avatar_url;   -- drop it, then recreate
+```
+
+`CONCURRENTLY` cannot run inside a transaction block (it does two table scans and a wait). It is the
+mandatory form on any live table.
+
+### Add a foreign key without a long lock
+
+```sql
+ALTER TABLE orders ADD CONSTRAINT fk_orders_user
+    FOREIGN KEY (user_id) REFERENCES users (id) NOT VALID;   -- brief lock, checks new rows only
+ALTER TABLE orders VALIDATE CONSTRAINT fk_orders_user;        -- scans existing rows, light lock
+```
+
+### Change a column type via expand-contract
+
+In-place `ALTER COLUMN ... TYPE` rewrites the whole table under ACCESS EXCLUSIVE. When the conversion
+is not assignment-cast-free, expand-contract instead:
+
+```sql
+-- 1. expand: new typed column
+ALTER TABLE orders ADD COLUMN amount_v2 numeric(19,4);
+-- 2. backfill in batches; app dual-writes amount and amount_v2
+-- 3. migrate reads to amount_v2; verify parity
+-- 4. contract: drop the old column in a later migration
+ALTER TABLE orders DROP COLUMN amount;
+ALTER TABLE orders RENAME COLUMN amount_v2 TO amount;   -- brief lock, metadata-only
+```
+
+### Drop a column
+
+```sql
+-- code-first: ship an app release that no longer references the column, THEN:
+ALTER TABLE orders DROP COLUMN legacy_status;   -- brief ACCESS EXCLUSIVE, metadata-only
+```
+
+### Batched backfill
+
+Backfill in bounded, committed batches so no single transaction holds locks or bloats WAL, and
+autovacuum can keep up. Drive the loop from the app/migration tool (primary), or use a `DO` block in
+`psql` (fallback).
+
+```python
+# Primary: psycopg 3, keyset + SKIP LOCKED, commit per batch
+last_id = 0
+while True:
+    rows = conn.execute(
+        "WITH b AS (SELECT id FROM users WHERE id > %s AND display_name IS NULL "
+        "ORDER BY id LIMIT 5000 FOR UPDATE SKIP LOCKED) "
+        "UPDATE users u SET display_name = u.username FROM b WHERE u.id = b.id "
+        "RETURNING u.id", (last_id,)).fetchall()
+    conn.commit()
+    if not rows:
+        break
+    last_id = max(r[0] for r in rows)
+```
+
+```sql
+-- Fallback in psql: a DO block that commits each batch (PG11+ allows COMMIT inside DO)
+DO $$
+DECLARE last_id bigint := 0; max_id bigint;
+BEGIN
+  LOOP
+    WITH batch AS (
+        SELECT id FROM users WHERE id > last_id AND display_name IS NULL
+        ORDER BY id LIMIT 5000 FOR UPDATE SKIP LOCKED
+    ), upd AS (
+        UPDATE users u SET display_name = u.username
+        FROM batch WHERE u.id = batch.id
+        RETURNING u.id
+    )
+    SELECT max(id) INTO max_id FROM upd;
+    EXIT WHEN max_id IS NULL;   -- no rows updated this round
+    last_id := max_id;
+    COMMIT;
+  END LOOP;
+END $$;
+```
+
+## Per-tool concrete examples
+
+### Plain SQL (golang-migrate-style file pair)
+
+```sql
+-- 000003_add_avatar.up.sql
+ALTER TABLE users ADD COLUMN avatar_url text;
+CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_users_avatar_url ON users (avatar_url);
+-- (backfill of display_name runs as a SEPARATE migration / job, not here)
+```
+
+```sql
+-- 000003_add_avatar.down.sql
+DROP INDEX CONCURRENTLY IF EXISTS ix_users_avatar_url;
+ALTER TABLE users DROP COLUMN IF EXISTS avatar_url;
+```
+
+### golang-migrate
+
+golang-migrate wraps each migration file in a single transaction by default, and `CONCURRENTLY` cannot
+run in a transaction. The `postgres`/`pgx` driver exposes only a driver-level `x-multi-statement` /
+`TransactionsEnabled=false` toggle (set when constructing the driver, applied to the whole run) — there
+is no per-file "disable transaction" directive. So the honest, canonical approach is: **put the
+concurrent-index statement in its own migration file and apply that step out-of-band**, or switch to a
+tool that supports a per-file no-transaction directive (`dbmate` `-- migrate:up transaction:false`,
+`atlas`, or `tern`) for that one step.
+
+```bash
+# create the pair
+migrate create -ext sql -dir migrations -seq add_avatar_index
+
+# put ONLY the concurrent index in its own file, apply it (it will fail if wrapped in a txn —
+# run it with psql directly, or via a tool that does not open a transaction):
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 \
+  -c "CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_users_avatar_url ON users (avatar_url);"
+
+# if a previous run left the migration marked dirty, clear it:
+migrate -path migrations -database "$DATABASE_URL" force 3
+```
+
+```sql
+-- migrations/000004_add_avatar_col.up.sql  (this file IS safe inside a txn)
+ALTER TABLE users ADD COLUMN avatar_url text;
+```
+
+### Alembic (SQLAlchemy 2.0, Python 3.12)
+
+```python
+from alembic import op
+import sqlalchemy as sa
+
+def upgrade() -> None:
+    op.add_column("users", sa.Column("avatar_url", sa.Text(), nullable=True))
+    with op.get_context().autocommit_block():     # required for CONCURRENTLY (leaves the txn)
+        op.create_index(
+            "ix_users_avatar_url", "users", ["avatar_url"],
+            postgresql_concurrently=True, if_not_exists=True,
+        )
+    op.execute("UPDATE users SET display_name = username WHERE display_name IS NULL")
+    op.create_check_constraint(
+        "ck_users_display_name_nn", "users", "display_name IS NOT NULL",
+        postgresql_not_valid=True,
+    )
+
+def downgrade() -> None:
+    op.drop_constraint("ck_users_display_name_nn", "users", type_="check")
+    op.drop_index("ix_users_avatar_url", "users", postgresql_concurrently=True, if_exists=True)
+    op.drop_column("users", "avatar_url")
+```
+
+For a large backfill, replace the single `op.execute(...)` with the batched loop from above (run via a
+raw connection inside the migration, committing per batch).
+
+### Prisma
+
+Prisma cannot emit `CONCURRENTLY`; generate an empty migration and hand-edit the SQL.
+
+```bash
+# 1. create the migration WITHOUT applying it
+npx prisma migrate dev --create-only --name add_avatar_url
+
+# 2. hand-edit prisma/migrations/<ts>_add_avatar_url/migration.sql (see below)
+
+# 3. apply in CI/CD with deploy (never migrate dev on shared envs — it can reset the DB)
+npx prisma migrate deploy
+```
+
+```sql
+-- prisma/migrations/<ts>_add_avatar_url/migration.sql
+ALTER TABLE "users" ADD COLUMN "avatar_url" TEXT;
+CREATE INDEX CONCURRENTLY IF NOT EXISTS "ix_users_avatar_url" ON "users" ("avatar_url");
+```
+
+Prisma checksums every migration file: once applied, editing it triggers `P3006` on every environment
+where the original already ran — create a new migration instead. ORM-surface traps
+(`updateMany` returning a count, `@updatedAt` skipped on bulk writes, serverless connection
+exhaustion) are out of scope for this engine-level skill — see Prisma's own documentation.
+
+## Rollback reality
+
+Down-migrations are best-effort. Data-destructive forward changes are not reversible from a
+down-migration:
+
+- `DROP COLUMN` discards the data — only a backup restores it.
+- Type narrowing (`numeric(19,4)` → `int`) loses precision irreversibly.
+- A completed backfill cannot be un-derived if the source was dropped.
+
+Before the **contract** phase, snapshot the affected table:
+
+```bash
+pg_dump -Fc -t orders "$DATABASE_URL" > orders_pre_contract.dump   # restore with pg_restore -t orders
+```
+
+Treat the down-migration as a convenience for local dev; in prod, recover from backup or roll forward.

package/skills/postgresdb/references/operations-and-security.md

@@ -0,0 +1,267 @@
+# PostgreSQL operations & security
+
+Running, securing, and monitoring PostgreSQL 16: least-privilege roles, row-level security,
+connection pooling, vacuum, observability, partitioning, backups, and HA basics. Running example
+tables: `orders`, `users`, `jobs`, `events`.
+
+## Roles & least privilege
+
+A role is a login role when it has `LOGIN`; group roles aggregate grants. The app connects as a role
+that can do exactly its work and nothing more — never as a superuser, never as the schema owner in
+normal traffic.
+
+By default every user can create objects in `public` and execute functions there; lock it down first:
+
+```sql
+-- 1. close the open default on the public schema
+REVOKE ALL ON SCHEMA public FROM PUBLIC;
+
+-- 2. an application read/write role with only DML, no DDL, no superuser
+CREATE ROLE app_rw LOGIN PASSWORD :'app_pw';
+GRANT USAGE ON SCHEMA public TO app_rw;
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO app_rw;
+GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO app_rw;
+
+-- 3. make the grants apply to tables created LATER, too
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+    GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_rw;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+    GRANT USAGE, SELECT ON SEQUENCES TO app_rw;
+
+-- 4. a read-only reporting / replica role (PG14+ predefined role reads every table)
+CREATE ROLE reporter LOGIN PASSWORD :'rep_pw';
+GRANT pg_read_all_data TO reporter;   -- PG14+: SELECT on all current and future tables
+```
+
+`ALTER DEFAULT PRIVILEGES` is keyed to the role that **creates** the object — run it as whichever role
+owns the migrations, or the grants will silently not apply to new tables. The `:'app_pw'` form is a
+`psql` variable; pass it with `psql -v app_pw=...` so the secret never lands in shell history.
+
+## Row-Level Security
+
+RLS filters rows per the connecting role. Two facts that bite everyone: it is **opt-in per table**
+(disabled by default), and the **table owner bypasses every policy** unless you also `FORCE` it.
+
+```sql
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+ALTER TABLE orders FORCE ROW LEVEL SECURITY;   -- owner is subject to policies too
+
+CREATE POLICY tenant_isolation ON orders
+    USING       (tenant_id = (SELECT current_setting('app.tenant_id', true)::bigint))
+    WITH CHECK  (tenant_id = (SELECT current_setting('app.tenant_id', true)::bigint));
+
+-- per request: scope the tenant for the duration of the transaction
+SET LOCAL app.tenant_id = '42';   -- inside a txn; cleared at COMMIT
+```
+
+- `USING` filters which existing rows are **visible** (SELECT/UPDATE/DELETE); `WITH CHECK` constrains
+  what **new/changed** rows may contain (INSERT/UPDATE). Set both or an insert can write a row the role
+  cannot then read.
+- Wrap the setting in `(SELECT current_setting(...))` so it is evaluated **once per statement**, not
+  once per row — the single biggest RLS performance trap.
+- `current_setting('app.tenant_id', true)` — the `true` means "missing → NULL" instead of erroring,
+  so an unscoped connection sees zero rows (fail-closed).
+
+Test as a non-owner role, or the owner bypass will make a broken policy look like it works:
+
+```sql
+SET ROLE app_rw;
+SET app.tenant_id = '42';
+SELECT count(*) FROM orders;   -- must equal only tenant 42's rows
+RESET ROLE;
+```
+
+On Supabase the same pattern uses `auth.uid()`; still wrap it: `USING (user_id = (SELECT auth.uid()))`.
+
+## Connection pooling
+
+A PostgreSQL backend is a forked OS process (~5-10 MB RSS) with its own snapshot and caches, so
+connections are expensive and `max_connections` should stay modest (a few hundred). Funnel the app
+through a pooler.
+
+**PgBouncer transaction mode** assigns a server connection only for the duration of a transaction —
+the highest reuse, but with hard caveats:
+
+- No session state across statements: `SET`/`SET search_path`, session-level `SET TIME ZONE`, and
+  `LISTEN`/`NOTIFY` do not survive. Use `SET LOCAL` inside a transaction instead.
+- **Session** advisory locks (`pg_advisory_lock`) leak across clients — use `pg_advisory_xact_lock`.
+- Prepared statements need a driver using **protocol-level** prepared statements (libpq `PQprepare`,
+  JDBC `PreparedStatement`, etc. — not text `PREPARE`) **and** PgBouncer ≥ 1.21 with
+  `max_prepared_statements > 0`; older combinations error with "prepared statement already exists".
+  (Protocol-level `DEALLOCATE`/close requires PG17+; before that PgBouncer cannot deallocate them.)
+
+```ini
+; pgbouncer.ini
+[databases]
+appdb = host=10.0.0.5 port=5432 dbname=appdb
+
+[pgbouncer]
+pool_mode = transaction
+max_client_conn = 5000
+default_pool_size = 20            ; server conns per (user,db); pool_size ~= cores * 2..4
+max_prepared_statements = 200     ; >=1.21, enables protocol prepared statements in txn mode
+server_idle_timeout = 600
+```
+
+Sizing: `default_pool_size ≈ cores × 2..4`; the **sum** of all app-side pool maxima must stay below the
+server's `max_connections`. Serverless functions should set `connection_limit=1` per instance and rely
+on the external pooler — set the `connection_limit=1` and `pgbouncer=true` `DATABASE_URL` parameters
+per your client's documentation (e.g. Prisma's `?connection_limit=1&pgbouncer=true`).
+
+## VACUUM & autovacuum
+
+`VACUUM` reclaims dead tuples (left by every UPDATE/DELETE under MVCC), updates the visibility map
+(enabling index-only scans), and freezes old transaction IDs to prevent wraparound. Autovacuum does
+this automatically; tune it harder for hot tables instead of disabling it.
+
+```sql
+-- A high-churn table: vacuum sooner and let it work harder
+ALTER TABLE jobs SET (
+    autovacuum_vacuum_scale_factor = 0.02,   -- vacuum at 2% dead tuples, not the 20% default
+    autovacuum_vacuum_cost_limit   = 2000    -- more I/O budget per round
+);
+
+-- Transaction-ID wraparound watch: if age() approaches ~2^31, the DB will force a shutdown to protect data
+SELECT datname, age(datfrozenxid) AS xid_age
+FROM pg_database ORDER BY xid_age DESC;
+```
+
+`VACUUM (ANALYZE) orders;` is the safe manual form — reclaims space and refreshes planner stats while
+allowing reads and writes. `VACUUM FULL` rewrites the entire table under ACCESS EXCLUSIVE — never on a
+live hot table; use `pg_repack` for online compaction.
+
+## Monitoring
+
+Enable `pg_stat_statements` (the single most useful extension) — it requires a preload and a restart:
+
+```sql
+-- postgresql.conf: shared_preload_libraries = 'pg_stat_statements'
+--                  pg_stat_statements.track = top
+-- then, once, after restart:
+CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+```
+
+```sql
+-- Worst total-time queries (where the time actually goes)
+SELECT calls,
+       round(mean_exec_time::numeric, 2)  AS mean_ms,
+       round(total_exec_time::numeric, 2) AS total_ms,
+       query
+FROM pg_stat_statements
+ORDER BY total_exec_time DESC
+LIMIT 20;
+
+-- Table/index activity: seq scans on big tables, dead tuples, unused indexes
+SELECT relname, seq_scan, idx_scan, n_dead_tup, last_autovacuum
+FROM pg_stat_user_tables ORDER BY seq_scan DESC LIMIT 20;
+
+SELECT relname, indexrelname, idx_scan
+FROM pg_stat_user_indexes WHERE idx_scan = 0 ORDER BY relname;
+
+-- Buffer cache hit ratio (aim > 0.99; sustained lower → undersized shared_buffers or cold working set)
+SELECT sum(heap_blks_hit) / nullif(sum(heap_blks_hit + heap_blks_read), 0) AS cache_hit_ratio
+FROM pg_statio_user_tables;
+
+-- Who is blocking whom
+SELECT blocked.pid AS blocked_pid, blocking.pid AS blocking_pid,
+       blocked.query AS blocked_query, blocking.query AS blocking_query
+FROM pg_stat_activity blocked
+JOIN pg_locks bl ON bl.pid = blocked.pid AND NOT bl.granted
+JOIN pg_locks gl ON gl.locktype = bl.locktype
+  AND gl.database IS NOT DISTINCT FROM bl.database
+  AND gl.relation IS NOT DISTINCT FROM bl.relation AND gl.granted
+JOIN pg_stat_activity blocking ON blocking.pid = gl.pid;
+
+-- Replication lag on the primary (seconds behind per standby)
+SELECT client_addr, state, replay_lag FROM pg_stat_replication;
+```
+
+Set guardrails globally so a single runaway query or leaked transaction cannot take the cluster down:
+
+```sql
+ALTER SYSTEM SET statement_timeout = '30s';
+ALTER SYSTEM SET idle_in_transaction_session_timeout = '60s';   -- kill txns that pin snapshots
+SELECT pg_reload_conf();
+```
+
+## Declarative partitioning
+
+Split one logical table into physical partitions by a key — almost always `RANGE` on a timestamp for
+time-series. The win is fast bulk drop of old data (`DETACH` + `DROP`, no row-by-row delete) and
+partition pruning that skips irrelevant partitions at plan time.
+
+```sql
+CREATE TABLE events (
+    id         bigint GENERATED ALWAYS AS IDENTITY,
+    created_at timestamptz NOT NULL,
+    payload    jsonb NOT NULL
+) PARTITION BY RANGE (created_at);
+
+-- one partition per month
+CREATE TABLE events_2026_06 PARTITION OF events
+    FOR VALUES FROM ('2026-06-01') TO ('2026-07-01');
+CREATE TABLE events_2026_07 PARTITION OF events
+    FOR VALUES FROM ('2026-07-01') TO ('2026-08-01');
+
+-- index on the parent propagates to all partitions (PG11+)
+CREATE INDEX ix_events_created ON events (created_at);
+
+-- drop a month of data instantly
+ALTER TABLE events DETACH PARTITION events_2026_06;
+DROP TABLE events_2026_06;
+```
+
+Note: the partition key must be part of the primary key / unique constraints. Automate partition
+creation with `pg_partman` rather than hand-managing months. It **helps** for huge time-series with a
+rolling retention window; it **hurts** small tables (pure overhead), queries that cannot prune (no
+partition-key predicate), and schemas with thousands of partitions (planning slows). Do not partition
+a table under ~10s of millions of rows.
+
+## Backups & PITR
+
+Two independent strategies — run both:
+
+```bash
+# Logical: portable, per-object, restorable to a different major version. Custom format + parallel.
+pg_dump -Fc -j4 -f appdb.dump "$DATABASE_URL"
+pg_restore -j4 -d "$TARGET_URL" appdb.dump          # parallel restore; -t orders for one table
+
+# Physical base backup for point-in-time recovery
+pg_basebackup -D /backups/base -Ft -z -P -h "$PGHOST" -U replicator
+```
+
+```ini
+# postgresql.conf — continuous WAL archiving enables PITR
+wal_level = replica
+archive_mode = on
+# ILLUSTRATIVE ONLY — do NOT ship this archive_command to production. Plain `cp` is not crash-safe:
+# it does not fsync the archived file or its directory, so a crash mid-archive can silently corrupt or
+# lose a WAL segment and break recovery. Use a tool that fsyncs and verifies — pgBackRest or wal-g
+# (referenced below) — as the real archive_command.
+archive_command = 'test ! -f /archive/%f && cp %p /archive/%f'
+```
+
+```ini
+# recovery target on the restored cluster (postgresql.conf + standby.signal)
+restore_command = 'cp /archive/%f %p'
+recovery_target_time = '2026-06-01 09:30:00+00'
+```
+
+Test restores on a schedule — a backup you have never restored is a hypothesis, not a backup. For
+production at scale use a purpose-built tool such as `pgBackRest` or `wal-g` (parallel, incremental,
+encrypted, crash-safe archiving with retention and verify) instead of a hand-rolled `cp`-based
+`archive_command`.
+
+## HA basics
+
+Streaming replication ships WAL from a primary to one or more standbys:
+
+- **Async** (default): low write latency, but a standby may lag and a failover can lose the last few
+  committed transactions.
+- **Sync** (`synchronous_standby_names`): no data loss on failover, at the cost of write latency that
+  depends on the slowest synchronous standby.
+
+Read replicas offload SELECTs but lag behind the primary, so reads that must see a just-committed write
+(read-after-write) must go to the primary; route only lag-tolerant reads to replicas. This is not a
+deep HA guide — use **Patroni** (or a managed equivalent) for automated failover, leader election, and
+fencing; configure it per its docs.