pgschema - Terraform のように PostgreSQL schema を管理する CLI
Database migration tool は、team を二つの方向に寄せがちです。ひとつは番号付き SQL migration を毎回手で書く方法。もうひとつは schema change を ORM の abstraction に寄せる方法です。前者は透明ですが順序管理と rollback が重くなりやすい。後者は便利ですが、database-specific feature に触れた瞬間、結局 hand-written SQL に戻ることがあります。
今日紹介する pgplex/pgschema は、PostgreSQL に別の選択肢を与えます。Infrastructure を Terraform で管理するように、declarative schema file で「database がどうあるべきか」を書き、CLI が current database と比較して plan を生成し、apply します。
公開時点の GitHub page では、およそ 939 stars、55 forks。主な言語は Go、license は Apache-2.0 です。Repository は 2025-06-08 に作成され、現在も active に更新されています。GitHub releases page では、latest release は v1.10.0、公開日は 2026-05-30 です。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| Repository | pgplex/pgschema |
| 位置づけ | PostgreSQL declarative schema migration CLI |
| Stars | 約 939 |
| Forks | 55 |
| 主な言語 | Go |
| License | Apache-2.0 |
| Latest release | v1.10.0 |
Core workflow は Terraform に近い
pgschema の基本 flow は次の四段階です。
- 既存の PostgreSQL instance から schema を dump する。
- 普通の SQL file で target structure を編集する。
- plan を実行し、予定される DDL を確認する。
- 確認後に apply し、変更を database に反映する。
Traditional migration file との大きな違いは、developer が最初に「042 番目の migration file に何を書くか」を決めなくてよいことです。管理するのは target state であり、tool が current state から target state への path を計算します。
もちろん、migration risk が消えるわけではありません。DDL は table lock、failure、production write path への影響を持ちます。ただし plan phase で変更が readable な形で出るため、team はそれを pull request、CI、release process に載せて review できます。Production に直接 hand-written SQL を流すより、議論しやすい状態になります。
PostgreSQL 専用であることが強み
多くの migration tool は複数 database を扱うため、database-specific feature の一部を犠牲にします。pgschema は反対に PostgreSQL 専用を選んでいるため、より細かい object type を扱えます。
README で挙げられている範囲には、tables、constraints、indexes、views、materialized views、functions、procedures、triggers、sequences、enum / composite types、domains、row-level security policies、privileges、default privileges、comments などがあります。PostgreSQL 14 から 18 までを対象にしている点も明記されています。
これは real-world system では重要です。多くの database は CREATE TABLE と普通の index だけではありません。RLS、partial index、partitioned table、constraint trigger、column-level grant を使うと、generic tool では結局手書き SQL に戻ることがあります。pgschema の価値は、こうした PostgreSQL-native capability を同じ diff / plan workflow に入れようとしている点です。
DSL ではなく plain SQL を使う
pgschema は新しい schema DSL を覚えさせるのではなく、SQL file で target structure を表現します。この判断は実務的です。
Database schema は多くの role が読むものです。Backend engineer、DBA、SRE、data engineer、security reviewer が同じ file を見ることがあります。SQL は冗長ですが、共通言語として review しやすい。Target schema を Git に置けることも、change history を分かりやすくします。
すでに schema.sql、database dump、hand-written DDL の習慣がある team なら、pgschema の導入負荷は proprietary DSL より小さいはずです。まず plan と review に使い、workflow 全体を一度に置き換えない始め方もできます。
Plan phase は CI に置きやすい
Declarative migration の要点は「SQL を自動生成する」ことだけではありません。Risk を apply 前に見えるようにすることです。pgschema の plan output は人間向けにも読め、JSON としても出せます。そのため CI に載せやすいです。
- Pull request で schema file が変更される。
- CI が test database または controlled environment に接続する。
- pgschema が plan を生成する。
- Reviewer が column、index、privilege、policy の変更を確認する。
- Plan が受け入れられてから apply に進む。
この pattern は small / mid-sized team に特に向いています。最初から大規模な database release platform を作らなくても、schema change を「誰かが local で SQL を実行した」状態から「preview でき、記録でき、議論できる」状態へ進められます。
AI coding workflow での意味
pgschema の README は AI-assisted workflow に触れ、LLM context 向けの documentation entry も用意しています。これは単なる buzzword ではありません。Agent は application code を書けても、database schema change が実際にどの DDL になるかを正確に判断できるとは限らないからです。
Schema change が natural language requirement と ORM model diff の間だけにあると、agent は constraint、privilege、index impact を見落としやすい。pgschema は target schema、plan、JSON output をひとつの flow に置くため、agent により verify しやすい boundary を与えます。
- Agent が SQL schema file を編集する。
- Agent が plan を読み、実際の DDL を把握する。
- Agent が plan summary を PR に書く。
- Failure が起きたとき、ORM の挙動を推測するのではなく、具体的な DDL を見て修正する。
これは agent に production database を自動変更させるという意味ではありません。より安全なのは、agent に draft と explanation を任せ、apply の timing と permission は人間が持つ使い方です。
使う前に見るべき境界
pgschema は PostgreSQL 向けです。Cross-database migration layer ではありません。System が MySQL、SQLite、Postgres を同時に対象にするなら、唯一の標準 tool にはしにくいでしょう。
README では Windows が直接サポートされておらず、WSL または Linux VM が必要だと説明されています。Local が完全に Windows 中心の team には現実的な friction になります。ただし、多くの CI や server environment では大きな問題にならないはずです。
また、declarative schema tool は data migration design を置き換えません。Column split、backfill、phased rollout、non-blocking index、blue-green deployment などは、引き続き engineering judgment が必要です。pgschema は structure state と DDL plan の管理に向いていますが、すべての database release を自動化する button ではありません。
向いている team
私は pgschema をまず次の場面で試します。
- Main database が PostgreSQL で、schema を Git で管理したい。
- Numbered migration を手で書く負担を減らしたいが、schema を ORM に完全には任せたくない。
- RLS、partition、partial index、trigger、grant など PostgreSQL feature を使う。
- PR や CI で
terraform planに近い database change preview が欲しい。 - AI coding agent を backend development に入れており、reviewable な database evidence が必要。
すでに Flyway、Liquibase、Atlas が安定している team が、無理に移行する必要はありません。pgschema は、SQL の読みやすさを保ちながら、hand-written migration sequence の負担を下げたい team に向いています。
まとめ
pgplex/pgschema の価値は、PostgreSQL schema migration を明確な loop に戻すことです。Target state は SQL にあり、change plan は preview でき、apply は確認でき、結果を Git と CI に載せられます。
もっとも generic な database tool ではありません。むしろ、かなり明確な PostgreSQL tool です。Postgres-native feature を使いながら migration review experience を良くしたい team にとって、その specialization は強みになります。