マイグレーションとコード生成#

スキーマが先、コードが後です。SQL を書いて当てると、テーブル定義のクラスがそこから作られます。

マイグレーション#

conf/migration/<スキーマ名>/ に SQL を置きます。

# --- !Ups

CREATE TABLE `note` (
	`id`         BIGINT UNSIGNED AUTO_INCREMENT COMMENT 'ID' PRIMARY KEY,
	`title`      VARCHAR(200) NOT NULL COMMENT 'タイトル',
	`created_at` DATETIME     NOT NULL COMMENT '作成日時'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='メモ';

# --- !Downs

DROP TABLE `note`;

./gradlew migrate

• ファイル名は自由。名前の自然順に当たります（001_ を付けるのが分かりやすい）
• <スキーマ名> は設定の scheme（無ければデータソース名）
• クラスパスから探します。conf/ をリソースに足しておいてください（設定）

1文ずつの切り分け#

1つのファイルに複数の文を書けます。「;」で切りますが、 文字列・識別子・コメントの中の「;」では切りません。

どこからどこまでがそれなのかは製品で違うので、繋いでいる製品の決まりで読みます。

コメントだけになった断片は捨てます（MySQL では「Query was empty」で落ちるためです）。 ただし MySQL / MariaDB の /*!40101 ... */ /*M!100301 ... */ は 実行されるコメントなので捨てません。

記録と失敗#

失敗すると**そこで止まり、アプリは起動しません。**中途半端な状態でリクエストを受けないためです。 失敗したことは migration に up_error として残り、次回は down → up をやり直します。

当て終わった SQL を書き換えない#

ハッシュを見ているので、当たったあとに書き換えると失敗します。

適用済みのマイグレーションが書き換えられています: 003_xxx.sql
（down が無効なため巻き戻せません。新しい SQL ファイルを追加してください）

migration.down = true（既定は false）にすると、down → 新しい up でやり直します。 **手で戻すコマンドはありません。**down が動くのは「ファイルが消えた」「ハッシュが変わった」の2つだけです。

製品ごとに SQL を分ける#

MySQL と PostgreSQL で同じ DDL は書けません（AUTO_INCREMENT と bigserial、 ENGINE=InnoDB、列コメントの書き方）。ファイル名の接尾辞で分けます。

conf/migration/blog_example/
	001_create_post.mysql.sql        ← mysql / mariadb のときだけ
	001_create_post.postgresql.sql   ← postgresql のときだけ
	002_add_status.sql               ← 接尾辞なし = どちらでも

• 接尾辞は db.<名前>.product に書ける名前と同じものです（mariadb は mysql と同じ扱い）
• **接尾辞の無いファイルはどの製品でも当たります。**両方で通る SQL は分けなくていいです
• 飛ばしたファイルは起動ログに出ます

マイグレーション: 他の製品向けを飛ばしました（いまは postgresql）: 001_create_post.mysql.sql

適用済みはファイル名で覚えているので、001_create_post.mysql.sql と 001_create_post.postgresql.sql は別の記録になります。 置いてあるファイルは、他の製品向けでも「消えた」とは見ません（down しません）。

同じ版に、いまの製品で流れるファイルを2つ置くと落ちます （001_x.mariadb.sql と 001_x.mysql.sql はどちらも MySQL で流れます）。

マイグレーション SQL の名前が変わったようです（いまは mysql）:
  001_create_post.sql → 001_create_post.mysql.sql
履歴の名前も変えてください。
  UPDATE migration SET name = '001_create_post.mysql.sql' WHERE name = '001_create_post.sql';
  UPDATE migration_history SET name = '001_create_post.mysql.sql' WHERE name = '001_create_post.sql';

複数のサーバーが同時に起動しても#

db_lock の行を FOR UPDATE で取ってから当てるので、1台しか流れません。 待ちきれなかった側は起動に失敗します（migration.lock_timeout_seconds、既定 60 秒）。

Java で書くマイグレーション#

SQL では書けない移行（既存データの詰め替えなど）はクラスで書きます。

CodeMigration.add(new V20260901FillUserKana());
Migration.install();

versionYyyyMmDd() の順に1回だけ走り、結果は migration_code に残ります。 クラスパスは走査しません（原則2）。書いたら add してください。

コード生成#

./gradlew codegen

DB のスキーマから、データソースごとに3種類を作ります。

public class Post extends Table {

	/* 記事ID */
	public static final Column id = new Column(instance(), "id", long.class, false, null, true);

	private static final List<Column> COLUMNS = List.of(id, title, body, published, created_at);
}

列の一覧は生成時に確定します（実行時にリフレクションしません）。

/*
 * このファイルは jimble が作りました（codegen）。手で直さないでください。
 * 直しても次の codegen で消えます。
 */

型の対応#

PostgreSQL では次も同じ扱いになります。

PostgreSQL のとき#

db.xxx.product = postgresql を書いておけば、同じ ./gradlew codegen が動きます （DB を使う）。読み方だけが変わり、生成されるクラスの形は同じです。

いくつか、MySQL と揃わないところがあります。

生成しないテーブル#

jimble が自分で作るテーブル（migration / db_cache / session / batch_* など）は自動で外れます。 MQ のキュー表は名前をアプリが決めるので、自分で書いてください。

codegen {
	package        = "db"
	exclude_tables = ["mq_blog", "mq_scheduler"]
}

設定#

migration {
	on_startup            = "auto"   # auto | true | false。auto はローカル以外で当てる
	down                  = false    # 巻き戻すか
	lock_timeout_seconds  = 60
	resource_dir          = "migration"
}

codegen {
	package        = "db"
	exclude_tables = []
}

CLI から#

Gradle が使えないところ（CI・本番）では CLI で同じことができます。

java -cp app.jar io.jimble.db.cli.JimbleDbCli migrate
java -cp app.jar io.jimble.db.cli.JimbleDbCli codegen src/main/java

設定も SQL もクラスパスから探します。 Gradle のタスクは Gradle プラグイン にまとめてあります。