 _____  _          _
|  __ \| |_   __ _| |__
| |__) | __| / _` | '_ \
|  ___/| |_ | (_| | | | |
|_|     \__| \__,_|_| |_|

オープンソースのデータベース DevOps

驚きのないデータベースマイグレーション

Ptah（プタハ）は、目標スキーマと稼働中のデータベースを比較し、バージョン管理型マイグレーションを書くか、承認済みの計画を適用する。pgvector テーブルの再埋め込みのような、永続的な推論状態の移行も扱う。PostgreSQL、MySQL、MariaDB、SQLite ほか。オープンソース、MIT ライセンス、導入すべきツールチェーンはない。

$ curl -fsSL https://ptah.run/install.sh | sh

v0.13.0 · pre-GA · MITWindows: irm https://ptah.run/install.ps1 | iex

はじめるプレイグラウンド GitHub で見る

完全なオープンソース、MIT
テレメトリーなし
エアギャップ環境で動く
それが重要な理由 →

プレイグラウンドで開く →

変更

sh · ptah-quick-start 49 / 49

# データベース自身のスキーマをファイルに書き出す。$ ptah db read --db-url sqlite://app.db | tee schema.sqlCREATE TABLE "users" (  "id" INTEGER PRIMARY KEY,  "email" TEXT NOT NULL); # ドリフト検査は、そのファイルと取得元のデータベースを比べる。$ ptah schema drift --schema-file schema.sql \    --db-url sqlite://app.dbNo schema drift detected. # 目標スキーマを書き換えて、列を 1 つ要求する。$ cat > schema.sql <<'SQL'CREATE TABLE "users" (  "id" INTEGER PRIMARY KEY,  "email" TEXT NOT NULL,  "created_at" TEXT);SQL # 今度は同じ検査が報告を返す。$ ptah schema drift --schema-file schema.sql \    --db-url sqlite://app.dbSchema drift detected (highest severity: warning).Failure threshold: all. Failing: true.Database: sqlite://app.db Findings:- columns_added: 1 (warning) # 差を埋めるのに何が要るかを尋ねる。ドライランは何も実行しない。$ ptah schema apply --schema-file schema.sql \    --db-url sqlite://app.db --dry-runPlanned schema changes:ALTER TABLE "users" ADD COLUMN "created_at" TEXT; # レビュー済みの計画を実行する。使い捨てのファイルなら --auto-approve でよい。$ ptah schema apply --schema-file schema.sql \    --db-url sqlite://app.db --auto-approvePlanned schema changes:ALTER TABLE "users" ADD COLUMN "created_at" TEXT;Auto-approval enabled; applying schema changes.Schema apply completed successfully. # そして同じ検査を、3 度目に。$ ptah schema drift --schema-file schema.sql \    --db-url sqlite://app.dbNo schema drift detected.

schema.sql データベースと一致+1 行−1 行+7 行

CREATE TABLE users (  id INTEGER PRIMARY KEY,  email TEXT NOT NULL);

CREATE TABLE users (  id INTEGER PRIMARY KEY,  email TEXT NOT NULL,+  created_at TEXT);

CREATE TABLE users (  id INTEGER PRIMARY KEY−  email TEXT NOT NULL);

CREATE TABLE users (  id INTEGER PRIMARY KEY,  email TEXT NOT NULL);+ +CREATE TABLE sessions (+  id INTEGER PRIMARY KEY,+  user_id INTEGER NOT NULL,+  token TEXT NOT NULL,+  FOREIGN KEY (user_id) REFERENCES users(id)+);

--db-url

$ ptah schema drift --schema-file schema.sql \    --db-url sqlite://app.dbNo schema drift detected.exit 0 $ ptah schema apply --schema-file schema.sql \    --db-url sqlite://app.db --dry-runSchema is synced, no changes to be made.exit 0

$ ptah schema drift --schema-file schema.sql \    --db-url sqlite://app.dbSchema drift detected (highest severity: warning).Failure threshold: all. Failing: true.Database: sqlite://app.db Findings:- columns_added: 1 (warning)exit 1 $ ptah schema apply --schema-file schema.sql \    --db-url sqlite://app.db --dry-runPlanned schema changes:ALTER TABLE "users" ADD COLUMN "created_at" TEXT;exit 0

$ ptah schema drift --schema-file schema.sql \    --db-url sqlite://app.dbSchema drift detected (highest severity: destructive).Failure threshold: all. Failing: true.Database: sqlite://app.db Findings:- columns_removed: 1 (destructive)exit 1 $ ptah schema apply --schema-file schema.sql \    --db-url sqlite://app.db --dry-runPlanned schema changes:-- Disable foreign-key enforcement for the table rebuild belowPRAGMA foreign_keys = off;-- SQLite table rebuild for changes ALTER TABLE cannot express on usersCREATE TABLE "__ptah_rebuild_users" (  "id" INTEGER PRIMARY KEY);INSERT INTO "__ptah_rebuild_users" ("id") SELECT "id" FROM "users";DROP TABLE "users";ALTER TABLE "__ptah_rebuild_users" RENAME TO "users";-- Restore foreign-key enforcement after the table rebuildPRAGMA foreign_keys = on;exit 0

$ ptah schema drift --schema-file schema.sql \    --db-url sqlite://app.dbSchema drift detected (highest severity: warning).Failure threshold: all. Failing: true.Database: sqlite://app.db Findings:- constraints_added: 1 (warning)- tables_added: 1 (safe)exit 1 $ ptah schema apply --schema-file schema.sql \    --db-url sqlite://app.db --dry-runPlanned schema changes:CREATE TABLE "sessions" (  "id" INTEGER PRIMARY KEY,  "user_id" INTEGER NOT NULL,  "token" TEXT NOT NULL,  CONSTRAINT "fk_sessions_user_id" FOREIGN KEY ("user_id") REFERENCES "users" ("id"));exit 0

$ ptah schema drift --schema-file schema.sql \    --db-url postgres://app@db/appNo schema drift detected.exit 0 $ ptah schema apply --schema-file schema.sql \    --db-url postgres://app@db/app --dry-runSchema is synced, no changes to be made.exit 0

$ ptah schema drift --schema-file schema.sql \    --db-url postgres://app@db/appSchema drift detected (highest severity: warning).Failure threshold: all. Failing: true.Database: postgres://app@db/app Findings:- columns_added: 1 (warning)exit 1 $ ptah schema apply --schema-file schema.sql \    --db-url postgres://app@db/app --dry-runPlanned schema changes:-- Add/modify columns for table: users ---- ALTER statements: --ALTER TABLE "users" ADD COLUMN "created_at" TEXT;exit 0

$ ptah schema drift --schema-file schema.sql \    --db-url postgres://app@db/appSchema drift detected (highest severity: destructive).Failure threshold: all. Failing: true.Database: postgres://app@db/app Findings:- columns_removed: 1 (destructive)exit 1 $ ptah schema apply --schema-file schema.sql \    --db-url postgres://app@db/app --dry-runPlanned schema changes:-- Remove columns from table: users ---- ALTER statements: --ALTER TABLE "users" DROP COLUMN "email" CASCADE;-- WARNING: Dropping column users.email with CASCADE - This will delete data and dependent objects! --;exit 0

$ ptah schema drift --schema-file schema.sql \    --db-url postgres://app@db/appSchema drift detected (highest severity: warning).Failure threshold: all. Failing: true.Database: postgres://app@db/app Findings:- constraints_added: 1 (warning)- tables_added: 1 (safe)exit 1 $ ptah schema apply --schema-file schema.sql \    --db-url postgres://app@db/app --dry-runPlanned schema changes:-- POSTGRES TABLE: sessions --CREATE TABLE "sessions" (  "id" INTEGER PRIMARY KEY NOT NULL,  "user_id" INTEGER NOT NULL,  "token" TEXT NOT NULL);-- ALTER statements: --ALTER TABLE "sessions" ADD CONSTRAINT "fk_sessions_user_id" FOREIGN KEY ("user_id") REFERENCES "users"("id");exit 0

$ ptah schema drift --schema-file schema.sql \    --db-url mysql://app@db/appNo schema drift detected.exit 0 $ ptah schema apply --schema-file schema.sql \    --db-url mysql://app@db/app --dry-runSchema is synced, no changes to be made.exit 0

$ ptah schema drift --schema-file schema.sql \    --db-url mysql://app@db/appSchema drift detected (highest severity: warning).Failure threshold: all. Failing: true.Database: mysql://app@db/app Findings:- columns_added: 1 (warning)exit 1 $ ptah schema apply --schema-file schema.sql \    --db-url mysql://app@db/app --dry-runPlanned schema changes:-- Modify table: users ---- ALTER statements: --ALTER TABLE `users` ADD COLUMN `created_at` TEXT;exit 0

$ ptah schema drift --schema-file schema.sql \    --db-url mysql://app@db/appSchema drift detected (highest severity: destructive).Failure threshold: all. Failing: true.Database: mysql://app@db/app Findings:- columns_removed: 1 (destructive)exit 1 $ ptah schema apply --schema-file schema.sql \    --db-url mysql://app@db/app --dry-runPlanned schema changes:-- Modify table: users ---- ALTER statements: --ALTER TABLE `users` DROP COLUMN `email`;-- WARNING: Dropping column users.email - This will delete data! --;exit 0

$ ptah schema drift --schema-file schema.sql \    --db-url mysql://app@db/appSchema drift detected (highest severity: warning).Failure threshold: all. Failing: true.Database: mysql://app@db/app Findings:- constraints_added: 1 (warning)- tables_added: 1 (safe)exit 1 $ ptah schema apply --schema-file schema.sql \    --db-url mysql://app@db/app --dry-runPlanned schema changes:-- MYSQL TABLE: sessions --CREATE TABLE `sessions` (  `id` INTEGER PRIMARY KEY,  `user_id` INTEGER NOT NULL,  `token` TEXT NOT NULL);-- ALTER statements: --ALTER TABLE `sessions` ADD CONSTRAINT `fk_sessions_user_id` FOREIGN KEY (`user_id`) REFERENCES `users`(`id`);exit 0

目標スキーマを書く。実行前に何が起きるかを Ptah が示し、実行後はドリフト検査がデータベースとの一致を確かめる。記録したワークフローをもっと見る →

仕組み

比較は 1 つ、どのワークフローもそれを読む

スキーマを何で書いても、Ptah はそれを 1 つの目標スキーマに解析し、データベースとの差分を取る。ドリフト、計画、lint、適用は、その 1 つの差分を 4 通りに読んだものだ。どの検査も 0、1、2 のいずれかで終了するので、CI が接続の失敗をクリーンなスキーマと取り違えることはない。

schema.sqlschema.yamlschema.hclschema.dbmlmodels/*.goorm loader · stdout
↓
目標スキーマ稼働中のデータベース
↓
比較
↓
schema drift裏づけ 0 1 2
schema plan · --dry-runレビューの対象
migrations lint関門
schema apply · migrations up承認のあと → 稼働中のデータベース

ふつうの一週間にやること、3 つ

実際のコマンドと、実際の出力。終了コードはどれでも同じ意味を持つ。0 は成功、1 は検査結果が否定的だったこと、2 は使い方か接続の失敗。

安全でない、または破壊的なマイグレーションを main に入れない

$ CI で.github/workflows/ptah.yml

- uses: stokaro/ptah-action@v1
  with:
    dir: ./internal/models
    db-url: ${{ secrets.PTAH_DATABASE_URL }}
    dialect: postgres
    migration-dir: ./migrations

$ ptah migrations lint --dir ./migrations \
    --dialect postgres
migrations/1790114595_drop_bio.up.sql:1 [warning] BC104: dropping a column retires a name application versions already deployed against the old schema still select and insert, so each of them starts failing the moment this migration commits, whether or not the column held any rows; deploy readers that no longer use the column first, then drop it in a later release (dropped column breaks deployed code)
migrations/1790114595_drop_bio.up.sql:1 [error] DS102: DROP COLUMN permanently deletes the column's data; deploy readers that no longer use the column first, then drop it in a later release (column dropped)

2 finding(s).

チェック · プルリクエストstokaro/ptah-action@v1

Ptah destructive-change verdictfailure

Ptah found destructive migration statements
Safety verdict: destructive.
Destructive changes: yes.

ptah-action が投稿したコメント

## Ptah migration plan

-- Remove columns from table: users --
-- ALTER statements: --
ALTER TABLE "users" DROP COLUMN "bio" CASCADE;

このアクションは対象データベースに対してマイグレーションを計画し、計画をコメントとして投稿し、データを破壊するステートメントがあれば失敗するチェック実行を 1 件書き込む。ptah migrations lint は指摘があれば 1 で、実行できなければ 2 で終了する。だから接続の失敗がクリーンなディレクトリに見えることはない。

レビューされていないマイグレーションをデータベースに近づけない

sh封じる

$ ptah migrations hash --dir ./migrations
Wrote ./migrations/ptah.sum
4 migration file(s) hashed
$ cat ./migrations/ptah.sum
h1:wmq3WUjBVQT+Ll4SPPan7wJGghKMtqi2yDc2Tc4AKnM=
1790114505_create_users.down.sql h1:3hAVcH5B1mghhsNEDFiyIlGOdernvs+6dDRkaO79/F0=
1790114505_create_users.up.sql h1:WJmUNv9ET7Qaypt2hpFNHHrqSQ5XGu0Yi0gMV0gLEMo=
1790114510_add_created_at.down.sql h1:3E0vyUoTX+11C374nPdXruUtJycoXTRoGvl8XsHLLIk=
1790114510_add_created_at.up.sql h1:9wID/+fArtJnyBz/JvM/NDDd1Ovm5SvkaJYcygIXLc4=

sh後日、適用済みのファイルが編集されたあと

$ ptah migrations up \
    --db-url sqlite://app.db \
    --migrations-dir ./migrations
error: migration sum verification failed:
migration directory does not match ptah.sum:
  changed: 1790114505_create_users.up.sql
$ echo $?
2

ptah.sum はファイルごとにチェックサムを記録する。up、validate、lint は何かを行う前にそれを検査し、status も --verify-sum を付ければ検査する。CI がレビューしたものが、そのまま本番で実行される。