0be354a920
Single-commit clean baseline after security scrub of niche-tells, project codenames, internal jargon, and contributor-email leaks. Contents: - 100 Rust crates (_primitives/_rust/) - 37 agent manifests (_manifests/) + generated specs (_generated/) - 67 user-invocable skills (skills/) - 33 hooks (hooks/) - Composition blocks (_blocks/) - Documentation (docs/, README.md) - TS adapter packages (_ts_packages/) - Assembler (_assembler/) - Roles (_roles/) - Templates (_templates/) - Forgejo CI (.forgejo/) Author: Denis Parfionovich <info@greendragon.info> License: see LICENSE.
28 lines
2.2 KiB
Markdown
28 lines
2.2 KiB
Markdown
# DB — PostgreSQL (current major — 17 as of 2026-04) patterns
|
||
|
||
Use when the project needs relational integrity, concurrent writes, or server-side indexing power that SQLite can't match. Default RDBMS for new multi-user services. [E4 — expert assessment]
|
||
|
||
**Version choice:** PostgreSQL 17 for new projects (current GA line, improved vacuum, JSON_TABLE, better parallel index builds). PostgreSQL 16 acceptable if hosting provider pins it. [UNVERIFIED: exact feature matrix — verify on postgresql.org/docs before committing to a minor-version-specific feature]
|
||
|
||
**Schema migrations:** every schema change ships as a numbered `.sql` file, never `ALTER TABLE` on prod. Use `kei-migrate` (this kit) or Atlas/goose/sqlx-cli — see `db-migration-hygiene.md`. One migration per logical change; no mega-migrations.
|
||
|
||
**Indexing:**
|
||
- B-tree default for equality + range. `CREATE INDEX CONCURRENTLY` on prod to avoid table lock.
|
||
- `GIN` for `jsonb` / array / full-text (`tsvector`).
|
||
- `BRIN` only for massive append-only time-series (orders of magnitude smaller than B-tree).
|
||
- Partial indexes (`WHERE active = true`) for sparse predicates.
|
||
- **Verify with `EXPLAIN (ANALYZE, BUFFERS)`** before declaring an index necessary. No blind indexing.
|
||
|
||
**Connection pooling:** app-side connection pool is NOT enough at scale. Use:
|
||
- **PgBouncer** (transaction mode) for most services — battle-tested, low overhead.
|
||
- **Supavisor** if already on Supabase — serverless-friendly, wire-compatible. [E4]
|
||
- Native server pooling (PG 17's improved but still not a substitute). [UNVERIFIED]
|
||
|
||
Sizing rule of thumb: `max_connections` on server × 1 pool layer. Don't stack pools (pool → PgBouncer → PG = deadlock risk).
|
||
|
||
**Backup:**
|
||
- Logical: `pg_dump` nightly for schema + data portability.
|
||
- Physical: `pg_basebackup` + WAL archiving (`archive_command`) for PITR.
|
||
- Managed service (RDS / Supabase / Neon) — verify backup retention in their UI, don't assume.
|
||
|
||
**Forbidden:** `SELECT *` in hot paths (N+1 + column drift); unindexed FK columns (join explosion); `SERIAL` on new tables — prefer `GENERATED ALWAYS AS IDENTITY` (SQL standard, PG 10+); plaintext passwords in `pg_hba.conf`; committing `.env` with DB URL.
|