From e02f6ac63ff3b2e14d92314b4e4ab7cc3adcdf49 Mon Sep 17 00:00:00 2001 From: Alex Shapalov Date: Mon, 7 Sep 2026 12:04:51 -0700 Subject: [PATCH] README: mark Indexes finished, other written topics in review Only the indexes chapter has the hands-on treatment, so the table of contents now shows it as the single finished chapter, the seven other written topics as "in review" drafts that still open with pgbook read, and the rest as in progress. Also documents how to update an install, the PGBOOK_INSTALL_DIR variable, the two-tab tutorial workflow with the step tracker, the chapter-writing conventions the renderer understands, and the two shipping paths (wrangler for chapter text, a v* tag plus the Homebrew formula for the CLI). Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017j8szNM4ep76fVKgpoHa6A --- README.md | 63 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 49 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 3ad1b1a..ed0fb0d 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ No 1,000-page manual. Pick a topic, understand how it works, try the examples yourself. ```console -$ pgbook read locks +$ pgbook read indexes ``` Free and open source · No signup required @@ -28,6 +28,14 @@ Or grab a binary from the [latest release](https://github.com/pgrundev/pgbook/re go install github.com/pgrundev/pgbook@latest ``` +To update, run the same command again: the installer always fetches the latest release, and Homebrew users can `brew update && brew upgrade pgbook`. The installer puts the binary in `/usr/local/bin` (asking for sudo if needed); set `PGBOOK_INSTALL_DIR` to install somewhere else: + +```bash +curl -fsSL https://pgbook.dev/install.sh | PGBOOK_INSTALL_DIR=~/.local/bin sh +``` + +Chapter text is fetched from pgbook.dev when you open it, so new and revised chapters arrive without reinstalling anything. + ## Table of contents ### Beginner @@ -45,12 +53,12 @@ go install github.com/pgrundev/pgbook@latest | # | Topic | | |---|-------|---| -| 07 | **Locks** — why a query is stuck, not slow | ✅ `pgbook read locks` | -| 08 | **Transactions and isolation** — what one query can see of another | ✅ `pgbook read transactions` | -| 09 | **JSONB** — semi-structured data, indexed | ✅ `pgbook read jsonb` | -| 10 | **Window functions** — running totals without collapsing rows | ✅ `pgbook read window-functions` | -| 11 | **Row-level security** — access control inside the database | ✅ `pgbook read row-level-security` | -| 12 | **Vacuum and autovacuum** — why deleted rows still take space | ✅ `pgbook read vacuum` | +| 07 | **Locks** — why a query is stuck, not slow | 🔍 in review · `pgbook read locks` | +| 08 | **Transactions and isolation** — what one query can see of another | 🔍 in review · `pgbook read transactions` | +| 09 | **JSONB** — semi-structured data, indexed | 🔍 in review · `pgbook read jsonb` | +| 10 | **Window functions** — running totals without collapsing rows | 🔍 in review · `pgbook read window-functions` | +| 11 | **Row-level security** — access control inside the database | 🔍 in review · `pgbook read row-level-security` | +| 12 | **Vacuum and autovacuum** — why deleted rows still take space | 🔍 in review · `pgbook read vacuum` | | 13 | Connection pooling | _in progress_ | | 14 | Finding slow queries | _in progress_ | @@ -63,11 +71,13 @@ go install github.com/pgrundev/pgbook@latest | 17 | Index internals | _in progress_ | | 18 | Deadlocks | _in progress_ | | 19 | WAL and checkpoints | _in progress_ | -| 20 | Replication — read replicas and failover | ✅ `pgbook read replication` | +| 20 | Replication — read replicas and failover | 🔍 in review · `pgbook read replication` | | 21 | Partitioning | _in progress_ | | 22 | Query-plan optimization | _in progress_ | -Eight topics are written so far, more in progress. Every example runs against a real Postgres — copy it straight into your own database. +✅ finished · 🔍 in review: readable now as a draft, being reworked into the hands-on format below · _in progress_: not yet written. + +Every example runs against a real Postgres — copy it straight into your own database. ## Built to be read, not searched @@ -82,15 +92,29 @@ Postgres docs are exhaustive but hard to start in. pgbook picks the topics that ## Read it from the terminal ```console +$ pgbook # greeting and where to start $ pgbook list -$ pgbook read locks -$ pgbook search indexes -$ pgbook next +$ pgbook read indexes +$ pgbook search locks +$ pgbook next # continue where you left off $ pgbook pdf ``` Or just read it at [pgbook.dev](https://pgbook.dev) — no install required. +### Hands-on chapters + +Finished chapters are tutorials, not reference pages. Keep `pgbook read` open in one terminal tab and `psql` in another, paste each SQL block as you reach it, and tick off the **Your turn** checklist at the end of every step. The terminal shows where you are: + +```text +──────────────────────────────────────────────────────── + 1 ─ [2] ─ 3 ─ 4 ─ 5 STEP 2 OF 5 + WATCH A QUERY CRAWL +──────────────────────────────────────────────────────── +``` + +SQL blocks are syntax-colored, and every chapter starts with a one-line Docker command for a throwaway Postgres, so you need nothing installed but Docker (or a database you already have). Nothing in a chapter touches real data. + Topics are fetched from pgbook.dev, so the book updates without a new CLI release, and every topic you open is cached for offline reading. The CLI only displays lessons — it never connects to a database and never executes SQL. A single static binary — no signup, no Node, no Postgres required to read. See [Install](#install). @@ -182,9 +206,20 @@ make site # regenerate site/api from topics/*.md make serve # preview pgbook.dev locally on :8391 ``` -Lessons live in `topics/*.md` — front matter plus markdown. Edit one, run `make site`, and the CLI, website, and API all pick it up. `PGBOOK_BASE_URL=http://127.0.0.1:8391 pgbook list` points the CLI at your local preview. +Lessons live in `topics/*.md` — front matter plus markdown. Edit one, run `make site`, and the CLI, website, and API all pick it up. `PGBOOK_BASE_URL=http://127.0.0.1:8391 pgbook read indexes` points the CLI at your local preview. + +### Writing a chapter + +- `## Step N: Title` headings become the step tracker; number them from 1 with no gaps. +- End each step with `### Your turn` and a `- [ ]` checklist. The terminal renders the boxes as ☐. +- Fence SQL as ```` ```sql ```` to get syntax colors; use ```` ```bash ```` and ```` ```text ```` for everything else. +- Keep source lines at 76 characters or fewer so nothing wraps in an 80-column terminal (code blocks are indented four spaces). +- Run every SQL block, in order, against a throwaway `postgres:17` container and paste the real plans into the text. Add `ANALYZE ;` after bulk loads, or the planner's guesses will not match what you wrote. + +### Shipping -Releases are cut by pushing a `v*` tag: CI tests, cross-builds for macOS/Linux (arm64 + amd64), checksums, and publishes the binaries as a GitHub release. +- **Chapter text**: `make site`, commit, then `cd deploy/cloudflare && npx wrangler deploy`. Readers get it on their next `pgbook read`; no CLI release needed. +- **The CLI**: push a `v*` tag. CI tests, cross-builds for macOS/Linux (arm64 + amd64), publishes the binaries and `checksums.txt` as a GitHub release. Then copy the version and the four sha256 values into `packaging/homebrew/pgbook.rb` and push the same file to `pgrundev/homebrew-tap` as `Formula/pgbook.rb`. ---