v0.21

マイグレーション

はじめに

マイグレーションはデータベースのバージョン管理のようなものでありチームがアプリケーションのデータベーススキーマ定義を定義および共有できるようにします。同僚にローカルデータベーススキーマへ手動でカラムを追加するよう依頼した経験があるならマイグレーションが解決する問題に直面したことがあるはずです。

各マイグレーションファイルは非同期のup関数をエクスポートする必要がありオプションでdown関数もエクスポートできるESモジュールです。フレームワークはSchemaサービス、tableクエリビルダー、生のdb接続、queryヘルパーを含むコンテキストオブジェクトを自動的に注入します。これらのプロパティはマイグレーションの実行中グローバルでも利用可能です。

マイグレーションの生成

新しいマイグレーションを作成するにはマイグレーション名を指定してmigrate:make CLIコマンドを使用します:

1dstrn migrate:make create_users_table
2dstrn migrate:make add_role_to_users_table

これによりタイムスタンプ付きのマイグレーションファイルがdatabase/migrations/にスキャフォールドされスタブ化されたup関数とdown関数が含まれます。ジェネレーターは一般的な命名パターン(create_<table>_tableやadd_<col>_to_<table>_tableなど)から対象テーブル名を自動的に推論します(usersのようなテーブル名単体も指定できます)。

テーブルの作成

新しいデータベーステーブルを作成するにはSchemaファサードのcreateメソッドを使用します。createメソッドは2つの引数を受け取ります。テーブル名と新しいテーブルを定義するために使用されるTableBuilderオブジェクトを受け取るクロージャです。

1export async function up({ Schema }) {
2 await Schema.create('users', table => {
3 table.increments('id');
4 table.string('name');
5 table.string('email').unique();
6 table.timestamps();
7 });
8}
9
10export async function down({ Schema }) {
11 await Schema.dropIfExists('users');
12}

カラムタイプ

テーブルビルダーにはテーブル構築時に使用できるさまざまなカラムタイプが用意されています。

タイプ 説明
table.id('id'); 自動インクリメントのbig integer主キー
table.increments('id'); 自動インクリメントのinteger主キー
table.bigIncrements('id'); 自動インクリメントのbig integer主キー
table.integer('votes'); integerカラム
table.bigInteger('views'); big integerカラム
table.float('amount'); floatカラム
table.decimal('balance', '10,2'); 精度指定付きdecimalカラム
table.boolean('confirmed'); tinyint booleanカラム
table.string('name', 100); 長さ指定可能なvarcharカラム
table.text('description'); textカラム
table.json('options'); jsonカラム
table.enum('status', ['active', 'inactive']); enumカラム
table.datetime('created_at'); datetimeカラム
table.date('birthday'); dateカラム
table.time('sunrise'); timeカラム
table.timestamps(); created_atおよびupdated_atのdatetimeカラムを追加

カラム修飾子

上記のカラムタイプに加えてデータベーステーブルにカラムを追加する際に使用できるいくつかのカラム修飾子があります。

タイプ 説明
table.string('email').nullable(); null値を許可
table.string('title').notNullable(); null値を禁止
table.integer('votes').unsigned(); integerをunsignedに設定
table.integer('status').defaultTo(1); デフォルト値を設定
table.string('email').unique(); ユニークインデックスを追加
table.unique('email', 'uniq_email'); カラムにユニークインデックスを追加
table.unique(['org_id', 'slug'], 'uniq_org_slug'); 複合ユニークインデックスを追加
table.string('slug').index(); 基本インデックスを追加
table.index(['user_id', 'status'], 'idx_user_stat'); 複合名前付きインデックスを追加
table.integer('id').primary(); 明示的に主キーを追加
table.string('status').comment('the user status'); カラムコメントを追加

外部キー

dframeworkはテーブルへの外部キー制約の追加をサポートしています。foreignメソッドでローカルカラムを定義しreferencesメソッドで参照先カラムとテーブルを指定しオプションでカスケードルールを定義します。

1export async function up({ Schema }) {
2 await Schema.create('posts', table => {
3 table.increments('id');
4 table.integer('user_id').unsigned();
5
6 table.foreign('user_id')
7 .references('id', 'users')
8 .onDelete('cascade')
9 .onUpdate('cascade');
10 });
11}

テーブルの変更

Schemaファサードのtableメソッドを使用すると既存のテーブルを更新できます(カラムの追加、カラム定義の変更、カラムの名前変更、カラムの削除、インデックスや外部キーの管理)。

1export async function up({ Schema }) {
2 await Schema.table('users', table => {
3 // add a new column
4 table.string('phone').nullable();
5
6 // modify an existing column definition (fluent syntax)
7 table.string('email', 150).nullable().modify();
8
9 // modify an existing column definition (direct syntax)
10 table.modify('bio', 'TEXT', { nullable: true });
11
12 // rename a column
13 table.renameColumn('username', 'handle');
14
15 // drop a single column or multiple columns
16 table.dropColumn('temp_token');
17 table.dropColumns('old_field_a', 'old_field_b');
18
19 // add indexes
20 table.index('phone');
21 table.index(['organization_id', 'role'], 'idx_users_org_role');
22 });
23}
24
25export async function down({ Schema }) {
26 await Schema.table('users', table => {
27 table.dropForeign('fk_users_org_id');
28 table.dropIndex('idx_users_org_role');
29 table.renameColumn('handle', 'username');
30 });
31}

またrenameメソッドを使用して既存のテーブル名を変更することもできます。

1await Schema.rename('old_table', 'new_table');
NOTE

mysqlおよびpostgresqlは既存のカラムタイプの変更(`table.modify()`)や外部キーの変更をサポートしていますがsqliteは既存テーブルに対するカラム定義の変更、外部キーの追加または削除、主キーの変更をネイティブではサポートしていません。sqliteでこれらの操作を実行しようとするとテーブルを再作成して既存レコードを移行するための具体的なガイダンスを含む診断エラーが即座にスローされます。

テーブルの削除

既存のテーブルを削除するにはdropまたはdropIfExistsメソッドを使用します。

1await Schema.drop('users');
2await Schema.dropIfExists('users');

マイグレーションの実行

保留中のマイグレーションを実行するにはmigrateコマンドを実行します:

1dstrn migrate

フレームワークはmigrationsディレクトリ内のファイル名に基づきアルファベット順にマイグレーションを順番に実行します。どのマイグレーションがすでに実行されたかを追跡しバッチごとに整理するためのmigrationsというデータベーステーブルが自動的に生成されます。

本番環境(APP_ENV=production)で実行する場合このコマンドは変更を適用する前に確認を求めます。自動デプロイパイプラインで非対話的にマイグレーションを実行するには--forceフラグを渡します:

1dstrn migrate --force

マイグレーションステータス

どのマイグレーションが適用済みでどれが保留中かを確認するには以下を実行します:

1dstrn migrate:status

これによりすべてのマイグレーションファイルと適用されたバッチ番号を一覧表示するステータステーブルが出力されます。

ロールバック

最新のデータベース変更を取り消す必要がある場合は以下を実行します:

1dstrn migrate:rollback

フレームワークはmigrationsテーブルを照会して最新のバッチ番号を特定しそれらのファイルのdown関数を逆時系列順に実行します。

本番環境(APP_ENV=production)で実行する場合このコマンドはロールバックを適用する前に確認を求めます。自動パイプラインで非対話的に実行するには--forceを渡します:

1dstrn migrate:rollback --force

トランザクションマイグレーションとDDL文

マイグレーションはエラー発生時に変更がロールバックされるようデータベーストランザクション内で実行されます。ただしmysqlはDDL文(create table、alter table、drop tableなど)を暗黙的にコミットします。マイグレーションに複数のDDL文が含まれており途中で失敗した場合失敗前に実行された文はmysqlでコミットされたままとなりマイグレーションのエントリはmigrationsテーブルに記録されません。マイグレーションは単一の責務に集中させDDLマイグレーションが失敗した場合はデータベーススキーマを確認してください。