pgbookとは｜Postgresのロック・VACUUM・JSONBをターミナルで読むGo製CLIを実測

Postgresの公式ドキュメントは網羅的だが、実務で詰まる論点にたどり着くまでが遠い。「クエリが遅いのではなく止まっている」ときに読みたいのはロックの章だけで、そこに行くまでに目次を何度も往復することになる。

pgbook（pgrundev/pgbook・★56・MIT・Go製・2026-09-04時点）は、その論点だけを1ページに切り出してターミナルから1本ずつ読ませるCLIだ。pgbook read locks と打つと、ロックの話だけが端末に出る。リポジトリが作られたのは2026-09-02、v0.1.0のリリースはその翌日で、これを書いている時点で公開から2日しか経っていない。

この記事は紹介ではなく実際に v0.1.0 のバイナリを落として動かした記録である。★56という規模のとおり、できることは多くない。だからこそ「READMEに書いてあることのうち、いま本当に動くのはどこまでか」を確かめる価値がある。

学習コンテンツをCLIに載せる発想そのものは新しくない。むしろpgbookは「AIに要約させる」潮流とは逆を向いていて、人間が読む短い章をそのまま配る側に立っている。開発まわりの作業をどこまで道具に任せるかという全体の見取り図はAI自動化ツール｜ノーコードからコードまで2026年版の比較と選び方にまとめている。

pgbookとは：Postgresの論点を1本ずつ配るGo製CLI

配布はGitHub Releasesのバイナリ、Homebrew、go install、インストールスクリプトの4通りある。バイナリを直接取るのがいちばん素性がはっきりしている。

# 公式リリースのバイナリを取る（macOS Apple Silicon）
curl -sfL -o pgbook.tar.gz \
  https://github.com/pgrundev/pgbook/releases/download/v0.1.0/pgbook_0.1.0_darwin_arm64.tar.gz
tar xzf pgbook.tar.gz
./pgbook --version
# → pgbook 0.1.0

Homebrew（brew install pgrundev/tap/pgbook）と go install github.com/pgrundev/pgbook@latest も用意されている。READMEの先頭は curl -fsSL https://pgbook.dev/install.sh | sh を勧めているが、スクリプトを読まずにシェルへ流し込む形なので、リリース資産を直接取るか go install を使うほうが素直だ。リリースには checksums.txt も付いている。

配布サイズは4プラットフォームで2.0〜2.3MBの範囲、展開後のバイナリは実測 5,080,290バイト（4.8MiB） だった。

配布経路は4つ。サイズは実測2.0〜2.3MB

リリース資産は macOS（amd64 / arm64）と Linux（amd64 / arm64）の4種で、いずれも 2,057,864〜2,274,272 バイトの範囲に収まっている。Windows 向けのバイナリは v0.1.0 時点では配布されていない。

pgbook list が返すのは8本

./pgbook list

実際の出力は次のとおり。

POSTGRES BOOK

01  Indexes                   beginner
02  Transactions & isolation  intermediate
03  JSON & JSONB              intermediate
04  Window functions          intermediate
05  Row-level security        intermediate
06  Vacuum & autovacuum       intermediate
07  Locks                     intermediate
08  Replication               advanced

Read a topic: pgbook read locks

READMEの目次は22項目あるが、pgbook list が返すのは8本だ。READMEは各行に「✅ pgbook read <slug>」か「in progress」を付けており、書き上がっていない14項目はMVCC・クエリプランナ・デッドロック・WALとチェックポイント・パーティショニング・接続プーリングなど、いずれも実務で効く論点が並んでいる。

READMEの番号（Locksは07、Indexesは04）とpgbook listの番号（Locksは07、Indexesは01）が一致しない点にも注意がいる。CLI側は書き上がった8本だけを1から振り直すので、READMEの番号を覚えて打っても意味がない。指定はスラッグ（locks / jsonb など）で行う。

8トピックの中身を APIの実データで確認する

GET /api/topics が返す内容をそのまま表にした（2026-09-04 実測・version: "0.1"）。

合計77分。つまり現時点の「Postgres Book」は、通しで読んでも1時間20分足らずで読み切れる分量である。22項目すべてが埋まれば単純計算で3時間半前後になる計算だ。

内容の重心は明確で、8本中5本がMVCCまわり（transactions / vacuum / locks）と、それを前提にした運用の話に寄っている。タグの分布を見ても concurrency mvcc blocking bloat が繰り返し出てくる。「Postgresの入門書」ではなく「Postgresで実際に事故る場所の解説」という編集方針が、目次より先にこのメタデータから読み取れる。

aliases が効くので、pgbook read rls でも pgbook read row-security でも同じ章に着く。用語のゆれで空振りしないための配慮で、公式ドキュメントを引くときにいちばん困るところを潰しにいっている。

本文の見た目

pgbook read locks の冒頭は次のようになる。

LOCKS
Why a query is stuck, not slow

Intermediate · 10 min

WHAT POSTGRES LOCKS

A query that is "slow" every time has a plan problem. A query that is
usually instant but sometimes hangs has a lock problem.

pgbook search <語>（トピック横断の検索）と pgbook next（次のトピックへ進む）も動く。search index を実行すると4件がヒットし、next は最後に読んだ位置の次を出した。

オフラインで読めるのは「一度開いたトピック」だけ

READMEは「every topic you open is cached for offline reading」と書いている。これを陽性対照つきで確かめた。

# 通信を落とした状態で、まだ開いていないトピックを読む
HTTPS_PROXY=http://127.0.0.1:9 HTTP_PROXY=http://127.0.0.1:9 ./pgbook read jsonb
# → pgbook: cannot load topic "jsonb": Get "https://pgbook.dev/api/topics/jsonb":
#    proxyconnect tcp: dial tcp 127.0.0.1:9: connect: connection refused

キャッシュの実体は ~/.cache/pgbook/ にあり、topics.json（一覧・実測3,119バイト）と topics/<slug>.json（本文）に分かれていた。「オフラインで読める」は、事前に開いておいたトピックに限るということで、飛行機に乗る前に全部落としておくような一括取得コマンドは用意されていない。8本しかないので手で全部開けば済むが、章が増えたときは効いてくる差だ。

READMEに書かれていて、まだ動かない機能：pgbook pdf

READMEには pgbook pdf の節があり、期待される出力まで具体的に書かれている。

Downloading Postgres Book…

✓ Saved to ./postgres-book.pdf
  8 topics · 64 pages · version 0.1

--output / -o での保存先指定、上書き前の確認、一時ファイルへのダウンロードと成功後のリネーム、HTTPレスポンス・content type・ファイルサイズ・公開チェックサムの検証、失敗時の非ゼロ終了コード——挙動の仕様がひととおり列挙されている。実際に叩いてみた結果は次のとおりだった。

./pgbook pdf --output ./pb.pdf --force
# → pgbook: cannot fetch book metadata: https://pgbook.dev/api/book: not found

叩き先を直接確認すると、https://pgbook.dev/api/book は 404（content-type: application/json）を返す。一方 https://pgbook.dev/api/topics は 200 で正常にJSONを返すので、サーバー自体は生きていて、このエンドポイントだけが存在しない。トップページのHTMLにもPDFへのリンクは見当たらなかった。

公開APIの中身：ドキュメントとCLIとPDFが同じ原稿を見ている

pgbook は公開・読み取り専用のJSON APIを持っている。GET /api/topics の実測レスポンスは次の形だった。

{
  "version": "0.1",
  "topics": [
    {
      "slug": "indexes",
      "title": "Indexes",
      "description": "Why some queries are instant",
      "level": "beginner",
      "reading_minutes": 8,
      "order": 1,
      "aliases": ["index", "index-basics", "btree"],
      "tags": ["performance", "btree", "explain"]
    }
  ]
}

aliases があるので pgbook read index でも pgbook read btree でも同じ章に着く。READMEによれば、この API・CLIの本文・（将来の）PDF・Webサイトはすべて同じ topics/*.md から生成される。トピックは pgbook.dev から取得されるため、章が増えてもCLIを入れ直す必要がない——この設計のおかげで「CLIのバージョンと本の版がずれる」問題が起きにくい代わりに、上で見たとおり手元のバイナリだけでは何も読めないという依存が生まれている。

誰に向いていて、誰に向いていないか

★56・公開2日目という前提を踏まえた評価を置いておく。

Postgres本体を触る道具ではない点は繰り返しておきたい。稼働中のDBを覗きたいならsql-tapとは｜アプリを無改修でSQLトラフィックをリアルタイムに覗くGo製プロキシ型TUI/Web監視ツールのようなプロキシ型の監視ツールが役割として近い。Postgres自体に機能を足す方向ならPgsemantic正式公開、PostgreSQLに即座にベクトル検索機能を実装やPostgres LLMで「INSERTするだけでLLM処理」を実現するトリガー型OSSが別の入口になる。pgbookはそのどれとも重ならず、読むだけの道具として独立している。

まとめ：8本の完成度と、22本の約束を分けて読む

pgbookの設計判断は筋が通っている。DBに接続しないと決めたことで権限も設定も要らず、本文をサーバー側に置いたことで章を足すのにリリースが要らない。1章8〜11分という分量も、公式ドキュメントの章とは明確に違う狙いを示している。

一方で、いま手に入るのは22本の目次に対して8本であり、pgbook pdf は動かず、日本語もない。★56・公開2日目のOSSとしてはむしろ健全な状態だが、READMEを読んで期待する内容と、いま pgbook list が返す内容には差がある。

判断としては「Intermediate の6本——ロック・分離レベル・JSONB・ウィンドウ関数・行レベルセキュリティ・VACUUM——が読みたいかどうか」に尽きる。そこが刺さるなら5MBのバイナリを置く価値はあるし、刺さらないなら残り14本が書かれるのを待ってからで遅くない。この記事の数値はすべて2026-09-04時点の実測なので、読む時点では章が増えている可能性が高い。pgbook list を叩けばその場で分かる。

参照ソース

• pgrundev/pgbook — GitHub
• pgbook v0.1.0 Release
• pgbook.dev — 公式サイト
• PostgreSQL 公式ドキュメント — Explicit Locking