# PostgreSQL Resources

Curated, high-trust sources for this workspace. Explainers in the lessons draw from here —
not from memory. Grouped **Knowledge** (learn the ideas), **Wisdom** (communities), and
**Repo** (our own code, the ground truth for this mission).

## Knowledge

### Start here (SQL foundations — you're newer to SQL)
- [PostgreSQL Tutorial — Part I of the official docs](https://www.postgresql.org/docs/current/tutorial.html)
  The official gentle intro to relational concepts + SQL. **Use for:** the first pass on
  tables, queries, and basic SQL.
- [PostgreSQL Tutorial (postgresqltutorial.com)](https://www.postgresqltutorial.com/)
  Task-oriented, example-heavy SQL tutorial the learner named. **Use for:** "show me the
  smallest working example of X" — SELECT/JOIN/aggregate/UPSERT. (Also mirrored at
  [neon.com/postgresql/tutorial](https://neon.com/postgresql/tutorial).)

### The authoritative reference
- [PostgreSQL Documentation (current)](https://www.postgresql.org/docs/current/)
  The canonical source. Key chapters we lean on:
  [Ch.11 Indexes](https://www.postgresql.org/docs/current/indexes.html) ·
  [Ch.13 Concurrency Control (MVCC)](https://www.postgresql.org/docs/current/mvcc.html) ·
  [Ch.14 Performance Tips / Using EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html) ·
  [Ch.73 Database Physical Storage](https://www.postgresql.org/docs/current/storage.html) ·
  [CREATE INDEX](https://www.postgresql.org/docs/current/sql-createindex.html).
  **Use for:** the exact definition behind any claim.

### Indexing & query performance (a pillar — the best single source)
- [_Use The Index, Luke!_ — Markus Winand (free web edition)](https://use-the-index-luke.com/)
  The developer's guide to SQL indexing and tuning — how the B-tree works, why an index
  isn't used, and how to read the WHERE clause. **Use for:** the indexes and query-perf
  parts. The single best resource for this mission.

### Internals & data structures (a pillar — the deep dive)
- [_PostgreSQL 14 Internals_ — Egor Rogov (free PDF, PostgresPro)](https://postgrespro.com/community/books/internals)
  548 pages: MVCC & isolation, buffer cache & WAL, locks, query execution, index types.
  [Direct PDF](https://edu.postgrespro.com/postgresql_internals-14_en.pdf). **Use for:** the
  internals part (pages/tuples/MVCC/VACUUM/WAL) — the authoritative deep source.
- [_The Internals of PostgreSQL_ — Hironobu Suzuki (interdb.jp)](https://www.interdb.jp/pg/)
  Free, diagram-rich walkthrough of storage, MVCC, buffer manager, and the planner. **Use
  for:** visual intuition to complement Rogov.

### Go implementation (matches our stack)
- [`jackc/pgx` — GitHub](https://github.com/jackc/pgx) ·
  [pkg.go.dev/github.com/jackc/pgx/v5](https://pkg.go.dev/github.com/jackc/pgx/v5)
  The driver our repo uses. **Use for:** the connection pool, `pgtype`, batch, and how our
  `database` layer wraps it. *(Confirm the major version in the repo map.)*

### EXPLAIN tooling
- [explain.depesz.com](https://explain.depesz.com/) — paste a plan, get it annotated
  (slowest nodes highlighted). **Use for:** the query-performance lessons.

## Wisdom (Communities)
- [r/PostgreSQL](https://www.reddit.com/r/PostgreSQL/) — active, high-signal. **Use for:**
  "is this schema/index sane?", slow-query threads, interview experiences.
- [PostgreSQL mailing lists](https://www.postgresql.org/list/) (esp. pgsql-general) — the
  upstream community. **Use for:** authoritative answers on behaviour.
- [DBA Stack Exchange](https://dba.stackexchange.com/questions/tagged/postgresql) — deep,
  searchable Q&A on tuning and internals.

## Repo (ground truth for this mission)
Our own Postgres usage — the pgx layer, entities, migrations, indexes, transactions, and
RLS multi-tenancy — is captured in
[reference/repo-postgres-map.md](./reference/repo-postgres-map.md) (generated from a scan of
`internal/golibs/database`, `internal/notification`, `internal/spike`, conversationmgmt, and
`migrations/`). The repo also has a DB primer under `docs/tech-stack-learning/` and a
`/query-db` skill for inspecting live data.

## Gaps
- No single trusted Postgres interview-question bank listed — the lessons build their own
  recall quizzes from the sources above.
- If the mission grows toward ops (replication, backups, tuning `postgresql.conf`), add an
  administration source (the official docs' Server Administration part) then.