On this page
マイグレーション
はじめに
マイグレーションはデータベースのバージョン管理のようなものでありチームがアプリケーションのデータベーススキーマ定義を定義および共有できるようにします。同僚にローカルデータベーススキーマへ手動でカラムを追加するよう依頼した経験があるならマイグレーションが解決する問題に直面したことがあるはずです。
各マイグレーションファイルは非同期のup関数をエクスポートする必要がありオプションでdown関数もエクスポートできるESモジュールです。フレームワークはSchemaサービス、tableクエリビルダー、生のdb接続、queryヘルパーを含むコンテキストオブジェクトを自動的に注入します。これらのプロパティはマイグレーションの実行中グローバルでも利用可能です。
マイグレーションの生成
新しいマイグレーションを作成するにはマイグレーション名を指定してmigrate:make CLIコマンドを使用します:
1dstrn migrate:make create_users_table2dstrn 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 column4 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 column13 table.renameColumn('username', 'handle');14 15 // drop a single column or multiple columns16 table.dropColumn('temp_token');17 table.dropColumns('old_field_a', 'old_field_b');18 19 // add indexes20 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');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マイグレーションが失敗した場合はデータベーススキーマを確認してください。

