バックエンドの DB スキーマとエンティティはスキーマファーストで運用する。
- スキーマの定義元は
apps/backend/migrationcrate(SQL マイグレーション)である。 - エンティティ(
apps/backend/crates/entity/src/_generated/)は手書きせず、稼働中の DB からsea-orm-cliで生成する。 - マイグレーション crate は backend のワークスペースから除外した独立 crate である(
apps/backend/Cargo.tomlのexclude)。そのため、backend がコンパイルエラーでもマイグレーションを実行できる。
初期スキーマは migration/src/m20260520000000_initial_schema.rs にまとまっており、以降の変更は増分マイグレーションとして同じディレクトリに並ぶ。
マイグレーションの実行
apps/backend/migration で実行する。接続先は環境変数 DATABASE_URL で渡す。apps/backend/.env の database_url(小文字)は backend と再生成スクリプトが読むもので、この CLI には渡らない。
cd apps/backend/migration
export DATABASE_URL=postgresql://task:task@localhost:5432/task
# 未適用のマイグレーションを全適用
cargo run -- up
# 全テーブルを DROP してから再適用(開発 DB 専用)
cargo run -- fresh
# 直近のマイグレーションをロールバック
cargo run -- down
# 適用状況を確認
cargo run -- statusDocker Compose では migration サービスが /app/run-migration.sh を実行し、up と起動時の schema sync と UNIQUE インデックスの節のインデックス削除を行う。
[!WARNING]
freshは全テーブルを DROP し、refreshとresetは全マイグレーションをロールバックする。どれもデータを失う操作なので、本番や共有の DB には流さず、捨ててよい DB に向けて実行する。freshはapalisスキーマ(ジョブの表と、apalis の適用記録apalis._sqlx_migrations)には触れない。apalis-postgres 1.0.0-rc.8 以前では、適用記録がpublicにあったのでfreshで消え、backend が42P06(schema “apalis” already exists)で起動できなくなったが、1.0.0-rc.9 以降では起きない。Compose で初期化するときはdocker compose run --rm migration /app/migration freshを手動で実行する。
apalis の表
ジョブの表(apalis スキーマ)は、backend の起動時に apalis-postgres が自分の移行で作る。SeaORM のマイグレーションには入れない。
apalis-postgres 1.0.0-rc.9 から、その適用記録は public._sqlx_migrations ではなく apalis._sqlx_migrations に置く。1.0.0-rc.8 以前の版で作った DB は、新しい版の backend を起動する前に、記録の移動と、最初の移行のチェックサムの付け替えが要る。これは SeaORM のマイグレーション m20261117000000_apalis_migration_history_schema が行う。migration サービスが up を終えてから backend を起動する Compose の順序では、手で何もしなくてよい。
public._sqlx_migrationsに apalis の最初の移行(version 20220530084123)の記録が在る DB だけを対象にする。他の物が同じ名前の表を使っていても、その version が無ければ触らない。- 新しい DB と、既に移し終えた DB では何もしない。
- 移す前に新しい版の backend を起動して、空の
apalis._sqlx_migrationsができてしまった DB も、その表を捨ててから移す。両方に記録の行が在る時は、どちらも壊さずに失敗する。 downは元へ戻さない。apalis-postgres を 1.0.0-rc.8 以前へ戻す時は、apalis-postgres の README の「Upgrading to 1.0」の逆の手順を手で行う。
新しい版の apalis-postgres の移行は、hstore 拡張(CREATE EXTENSION IF NOT EXISTS hstore)を作る。DB の利用者に、その権限が要る。
エンティティの再生成
スキーマを変更したら、対象テーブルのエンティティを再生成する。
# カンマ区切りでテーブル名を渡す
scripts/seaorm_generate.sh tasks,sprintsこのスクリプトは内部で次の二つを行う。
sea-orm-cli generate entityでapps/backend/crates/entity/src/_generated/に生成物を出力するscripts/seaorm_postprocess.shを実行して、生成物に型を付け直す
接続先はスクリプトが apps/backend/.env の database_url から読み込む。
postprocess が再適用する内容
sea-orm-cli は varchar 列を String、json 列を Json として出力するので、ドメイン型へ戻す処理を後から当てる。処理は冪等で、再実行しても変わらない。
| テーブル | 列 | 付け直す型 |
|---|---|---|
tasks |
priority |
TaskPriority |
project_custom_fields |
field_type |
CustomFieldType |
sprints |
status |
SprintStatus |
project_members |
role |
ProjectRole |
tenant_members |
role |
TenantRole |
drive_files |
storage_type |
StorageType |
drive_folder_shares |
permission |
SharePermission |
personal_tokens |
scopes |
ScopeList |
型の付け直しのほかに、次の二つの修正も行う。
drive_files/drive_folder_sharesは独自のActiveModelBehavior(CHECK 制約の検証)を持つので、生成された既定の実装を削除して impl の衝突を避ける。sprints.project_idは、sea-orm-cliが誤検出する単一列 unique を除去する。単一列の unique にすると、1 プロジェクトに 1 スプリントしか作れなくなるためである。
varchar の enum 列や JSON のドメイン型列を新しく追加したら、scripts/seaorm_postprocess.sh に対応する replace 行を追記する。追記しないと、再生成のたびに String / Json へ戻る。
スキーマ変更の手順
apps/backend/migration/src/に増分マイグレーションを追加する。CHECK 制約、UNIQUE、インデックス、FK のON DELETEまで漏れなく書く。適用済みのマイグレーションはupで再実行されないので、初期スキーマを編集しても既存の DB には反映されない。- ファイル名は
m<YYYYMMDDhhmmss>_<name>.rsとする。時刻は既存の最大値より後ろで、main と他のオープン PR のマイグレーションと重ならない値にする。lib.rsのmodとBox::new(...)は時刻順の末尾に足す。 - 捨ててよい DB で
cargo run -- freshを実行し、SQL が通ることを確認する。 scripts/seaorm_generate.sh <変更したテーブル>でエンティティを再生成する。_generated/の差分と、必要ならscripts/seaorm_postprocess.shのマッピングを確認する。cargo check --workspace --all-targets(apps/backend)で、エンティティとアプリケーションコードの整合を確認する。
全文検索インデックス(USE_PG_BIGM)
tasks の全文検索インデックスは環境変数 USE_PG_BIGM で切り替わる。値が 1、true、True、TRUE のいずれかなら有効である。
- 有効なときは
pg_bigmの GIN インデックス(idx_tasks_title_bigm/idx_tasks_description_bigm)を作成し、search_vector生成列は作らない。マイグレーションはpg_bigmのCREATE EXTENSIONを行わないので、拡張は先に DB へ入れておく。 - それ以外(既定)は、生成列
search_vector(tsvector)とidx_tasks_search_vector(GIN)を作成する。
初期スキーマの適用時の値で生成されるスキーマが変わるので、fresh の実行時には USE_PG_BIGM の値に注意する。検索ハンドラーも同じ環境変数で検索方法を切り替えるので、マイグレーションと backend で値を揃える。
これとは別に、m20261020000000_tasks_title_trgm は USE_PG_BIGM に関係なく pg_trgm と idx_tasks_title_trgm を作成する。DB の lc_ctype が C だと日本語の trigram が作られないので、このマイグレーションはエラーで止まる。UTF-8 のロケールで作った DB を使う。
起動時の schema sync と UNIQUE インデックス
backend は起動時に SeaORM の schema sync(get_schema_registry("entity::*").sync)を無条件に実行する。sync は、エンティティの unique / unique_key と列の組が一致しない UNIQUE インデックスを DROP CONSTRAINT で消そうとする。実体がインデックスだと Postgres が 42704 を返し、backend は起動しない。
この衝突を避けるため、マイグレーション適用後、sync の前に次の二つのインデックスを削除する。
labels_project_name_uniqueidx_sprints_active_per_project
削除は apps/backend/docker/run-migration.sh と e2e/scripts/start-backend.sh で行う。統合テストのハーネスは idx_sprints_active_per_project だけを削除し、sync の後に作り直す。
idx_sprints_active_per_project(sprints(project_id) WHERE status = 'active')は、エンティティに対応する unique_key が無いので sync でも作られない。したがって Compose で動かす環境にこの部分 UNIQUE インデックスは残らず、「プロジェクトで有効なスプリントは一つ」という規則はスプリント開始のハンドラーの確認だけで守っている。
エンティティの 1 列に付けられる unique_key は 1 つだけなので、同じ列を含む複合 UNIQUE を二つは表せない。複合の列の一部にだけ unique_key を付けると、sync はその列だけの狭い UNIQUE を作る。projects はエンティティで (tenant_id, key)(projects_key_tenant_unique)を表し、「テナントと利用者ごとに個人プロジェクトは一つ」という規則は get_or_create_personal_project のアドバイザリロックで守っている。
これらの理由から、部分 UNIQUE インデックス(CREATE UNIQUE INDEX ... WHERE)をマイグレーションに足さない。NULL を除外したいだけなら列の UNIQUE 制約で足りる(NULL 同士は重複扱いされない)ので、エンティティにも #[sea_orm(unique)] を付けて揃える。
