---
title: "マイグレーション"
description: "SeaORM エンティティをスキーマファーストで運用するためのマイグレーション手順とエンティティ再生成の流れ"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.koyori.app/llms.txt
> Use this file to discover all available pages before exploring further.

# マイグレーション

バックエンドの DB スキーマとエンティティはスキーマファーストで運用する。

- スキーマの定義元は `apps/backend/migration` crate（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 には渡らない。

```sh
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 -- status
```

Docker Compose では `migration` サービスが `/app/run-migration.sh` を実行し、`up` と[起動時の schema sync と UNIQUE インデックス](#起動時の-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 の利用者に、その権限が要る。

## エンティティの再生成

スキーマを変更したら、対象テーブルのエンティティを再生成する。

```sh
# カンマ区切りでテーブル名を渡す
scripts/seaorm_generate.sh tasks,sprints
```

このスクリプトは内部で次の二つを行う。

1. `sea-orm-cli generate entity` で `apps/backend/crates/entity/src/_generated/` に生成物を出力する
2. `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` へ戻る。

## スキーマ変更の手順

1. `apps/backend/migration/src/` に増分マイグレーションを追加する。CHECK 制約、UNIQUE、インデックス、FK の `ON DELETE` まで漏れなく書く。適用済みのマイグレーションは `up` で再実行されないので、初期スキーマを編集しても既存の DB には反映されない。
2. ファイル名は `m<YYYYMMDDhhmmss>_<name>.rs` とする。時刻は既存の最大値より後ろで、main と他のオープン PR のマイグレーションと重ならない値にする。`lib.rs` の `mod` と `Box::new(...)` は時刻順の末尾に足す。
3. 捨ててよい DB で `cargo run -- fresh` を実行し、SQL が通ることを確認する。
4. `scripts/seaorm_generate.sh <変更したテーブル>` でエンティティを再生成する。
5. `_generated/` の差分と、必要なら `scripts/seaorm_postprocess.sh` のマッピングを確認する。
6. `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_unique`
- `idx_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)]` を付けて揃える。

Source: https://docs.koyori.app/dev/development/database-migrations/index.mdx
