liquibase-migration

FOLIO Liquibase 移行ガイドライン

1. フォルダー構成

推奨レイアウト

推奨する構成はバージョン管理方式です。各リリースに専用のフォルダーとアグリゲーターファイルを用意します。

src/main/resources/db/changelog/
├── changelog-master.xml
└── changes/
    ├── changelog-v1.0.xml
    ├── v1.0/
    │   ├── create-table-foo.xml
    │   └── add-index-foo-bar.xml
    ├── changelog-v2.0.xml
    └── v2.0/
        └── alter-table-foo-add-column-baz.xml

推奨する構成のルール：

• changelog-master.xml にはバージョンアグリゲーター（changes/changelog-vX.Y.xml）のみを記述します
• 各 changelog-vX.Y.xml には changes/vX.Y/ 内のファイルのみを記述します
• モジュールのリリースごとに、新しい vX.Y/ ディレクトリと changelog-vX.Y.xml を作成します
• すべての <include> 要素で relativeToChangelogFile="true" を使用します

changelog-master.xml の例：

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                   https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

  <include file="/changes/changelog-v1.0.xml" relativeToChangelogFile="true"/>
  <include file="/changes/changelog-v2.0.xml" relativeToChangelogFile="true"/>
</databaseChangeLog>

changes/changelog-v2.0.xml の例：

<databaseChangeLog ...>
  <include file="/changes/v2.0/create-table-foo.xml" relativeToChangelogFile="true"/>
  <include file="/changes/v2.0/alter-table-foo-add-column-bar.xml" relativeToChangelogFile="true"/>
</databaseChangeLog>

既存モジュールでの作業

新しいファイルを作成する前に、モジュール内の既存の変更ログ構成を確認してください。必ず現在使われているレイアウトに従ってください。プロジェクトの途中で構成を変更したり、別の構成を導入したりしないでください。

• モジュールがバージョンごとのアグリゲーターを含む changelog-master.xml を使用している場合 → そのパターンに従います
• モジュールが <include> を直接記述したフラットな changelog-master.xml を使用している場合 → そこに項目を直接追加し続けます
• モジュールが異なる命名規則や階層構造を使用している場合 → 既存の構成に合わせます

既存の移行ファイルがない新しいモジュールを開始する場合は、上記の推奨構成を使用してください。

---

2. 変更セット ID の命名規則

形式

<JIRA-TICKET>@@<scope>-<action>-<target>[-<detail>]

許可される値

部分	値
scope	schema、data、refactor、fix
action	create、alter、drop、rename、migrate、backfill、seed、cleanup、enforce
target	table-<name>、column-<table>-<col>、index-<name>、fk-<from>-to-<to>、type-<name>
detail	(省略可能) 具体的な意図。例：add-not-null、add-metadata-fields

スタイル規則

• 小文字のみを使用します
• ケバブケースのみを使用します（アンダースコアや空白は使用しません）
• ASCII 文字のみを使用します（: は使用しません）
• 命令形の動詞を使用します（動名詞や過去形は使用しません）
• ID はリリース後に変更できません。リリース済みの変更セット ID の名前は変更しないでください

✅ 良い例

MYMOD-101@@schema-create-table-item
MYMOD-102@@schema-alter-table-item-add-column-status
MYMOD-103@@schema-create-index-item-status
MYMOD-104@@schema-create-fk-item-to-location
MYMOD-105@@data-seed-item-default-status
MYMOD-106@@data-migrate-rule-to-specification-rule-metadata-fields
MYMOD-107@@schema-enforce-column-item-id-not-null
MYMOD-108@@schema-create-type-status-enum

❌ 悪い例

MYMOD-101@@CreateItemTable          # PascalCase, no scope/action
MYMOD-101@@schema:create:table      # colons not allowed
MYMOD-101@@schema-creating-table    # gerund
MYMOD-101@@schema-created-table     # past tense
item-table                          # missing JIRA ticket and @@

---

3. 変更セットの構造

すべての変更セットには、次のものを必ず含めてください。

1. <comment> — 変更セットの内容と理由を記述します

<changeSet id="MYMOD-42@@schema-create-table-item" author="john_doe">
  <comment>Create item table for inventory storage</comment>

  <createTable tableName="item">
    ...
  </createTable>
</changeSet>

---

4. FOLIO 標準カラム型

すべての FOLIO モジュールで、これらの型を一貫して使用してください。

用途	型
主キー／外部キー（UUID）	uuid
短い文字列	varchar(36) – varchar(250)
長い文字列	varchar(2500) または text
JSON ブロブ	jsonb
タイムスタンプ	datetime
ブール値フラグ	bool
バージョンカウンター（楽観的ロック）	integer
1 文字のコード	char

メタデータカラム

新しいテーブルにメタデータカラムを追加する前に、必要かどうかをユーザーに確認してください。すべてのテーブルで監査トラッキングが必要なわけではありません。

ユーザーが必要と確認した場合は、次を含めてください。

<column name="created_date" type="DATETIME">
  <constraints nullable="false"/>
</column>
<column name="updated_date" type="DATETIME">
  <constraints nullable="false"/>
</column>
<column name="created_by_user_id" type="uuid">
  <constraints nullable="false"/>
</column>
<column name="updated_by_user_id" type="uuid">
  <constraints nullable="false"/>
</column>

---

5. よくある変更パターン

テーブルの作成

<changeSet id="MYMOD-10@@schema-create-table-item" author="jane_doe">
  <comment>Create item table</comment>

  <createTable tableName="item">
    <column name="id" type="UUID">
      <constraints nullable="false" primaryKey="true" primaryKeyName="pk_item"/>
    </column>
    <column name="barcode" type="varchar(250)"/>
    <column name="status" type="varchar(36)">
      <constraints nullable="false"/>
    </column>
    <column name="data" type="jsonb"/>
    <column name="_version" type="integer"/>
    <column name="created_date" type="DATETIME"><constraints nullable="false"/></column>
    <column name="updated_date" type="DATETIME"><constraints nullable="false"/></column>
    <column name="created_by_user_id" type="uuid"><constraints nullable="false"/></column>
    <column name="updated_by_user_id" type="uuid"><constraints nullable="false"/></column>
  </createTable>
</changeSet>

外部キーの追加

<changeSet id="MYMOD-10@@schema-create-fk-item-to-location" author="jane_doe">
  <comment>Add FK from item to location</comment>

  <addForeignKeyConstraint
    baseTableName="item"
    baseColumnNames="location_id"
    referencedTableName="location"
    referencedColumnNames="id"
    constraintName="fk_item_location_id"/>
</changeSet>

インデックスの作成

<changeSet id="MYMOD-11@@schema-create-index-item-status" author="jane_doe">
  <comment>Create B-tree index on item.status for lookup performance</comment>

  <createIndex tableName="item" indexName="idx_item_status">
    <column name="status"/>
  </createIndex>
</changeSet>

カラムの追加

<changeSet id="MYMOD-15@@schema-alter-table-item-add-column-effective-location-id" author="jane_doe">
  <comment>Add effective_location_id column to item table</comment>

  <addColumn tableName="item">
    <column name="effective_location_id" type="UUID"/>
  </addColumn>
</changeSet>

データ移行／シード

<changeSet id="MYMOD-20@@data-seed-item-default-status" author="jane_doe">
  <comment>Set default status 'Available' for items with null status</comment>

  <sql>
    UPDATE item
    SET status = 'Available'
    WHERE status IS NULL;
  </sql>
</changeSet>

---

6. 避けるべきアンチパターン

❌ コメントがない — レビュアーや今後の開発者が状況を把握できません

<changeSet id="MYMOD-2@@schema-alter-table-item-add-column-bar" author="foo">
  <addColumn tableName="item">...</addColumn>
</changeSet>

❌ リリース済みの変更セット ID を変更する — デプロイ済みのすべての環境で Liquibase のチェックサム検証が失敗します

❌ 関連のない複数の変更を 1 つの変更セットにまとめる — ロールバックやデバッグが難しくなります。1 つの変更セットには 1 つの論理的な変更を含めてください

❌ スキーマ変更セットで runOnChange="true" を使用する — ストアドプロシージャやビューでのみ許容され、DDL では決して使用しません