はじめに (対象読者・この記事でわかること)

この記事は、PHPフレームワーク「Sabel」を使ってWebアプリケーションを開発している方、あるいはこれから始めようとしている方向けです。特に、データベースのスキーマ変更をチームで安全に管理したい方、または「マイグレーションって何？」という方に読んでいただきたい内容です。

この記事を読むことで、Sabelに付属しているマイグレーションツールの基本的な使い方から、実際の運用でよくあるパターンまでを理解できます。具体的には、マイグレーションファイルの作成方法、ロールバックの仕組み、チーム開発での運用ノウハウについて解説します。これまで手動でSQLを管理していた方も、マイグレーションを使うことで、より安全で追跡可能なデータベース管理ができるようになります。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。 - PHPの基本的な文法とオブジェクト指向の基礎知識 - MySQLやPostgreSQLなどのRDBMSの基本的な操作 - コマンドライン（ターミナル）での作業経験

Sabelマイグレーションの概要となぜ必要なのか

Sabelのマイグレーションツールは、データベースのスキーマ（テーブル構造）をバージョン管理するための仕組みです。これまでの開発で「本番環境でALTER TABLEを実行したら予期せぬエラーが発生した」や、「開発メンバー間でデータベースの構造がずれて動作確認ができない」といった経験はありませんか？

マイグレーションを使うことで、これらの問題を防げます。マイグレーションファイルは、データベースの変更履歴をPHPのコードとして記述したものです。これにより、誰でも同じ手順で環境を構築でき、過去の状態に戻すことも簡単に行えます。特にSabelのマイグレーションは、フレームワークに密接に統合されているため、開発効率が大幅に向上します。

実践的なSabelマイグレーションの使い方

それでは、実際にSabelのマイグレーションツールを使ってみましょう。ここでは、ECサイトのユーザーテーブルを例に、マイグレーションの基本的な使い方から応用的なテクニックまで解説します。

ステップ1：マイグレーションファイルの作成

まず、新しいマイグレーションファイルを作成します。Sabelでは、以下のコマンドで簡単に作成できます。

Bash

$ php sabel migrate:create CreateUsersTable

このコマンドを実行すると、app/migrations/ディレクトリにYYYYMMDDHHMMSS_CreateUsersTable.phpというファイルが生成されます。ファイル名の先頭の数字はタイムスタンプで、マイグレーションの実行順を制御します。

生成されたファイルを開くと、以下のようなテンプレートが表示されます：

Php

<?php
class CreateUsersTable extends Sabel_Migration_Abstract
{
    public function up()
    {
        // マイグレーション処理
    }

    public function down()
    {
        // ロールバック処理
    }
}

up()メソッドには、マイグレーション実行時の処理を記述し、down()メソッドには、ロールバック（元に戻す）時の処理を記述します。それでは、ユーザーテーブルを作成するマイグレーションを実装してみましょう：

Php

<?php
class CreateUsersTable extends Sabel_Migration_Abstract
{
    public function up()
    {
        $this->createTable("users", array(
            "id" => array("type" => "serial", "primary" => true),
            "email" => array("type" => "string", "length" => 255, "null" => false),
            "password" => array("type" => "string", "length" => 255, "null" => false),
            "name" => array("type" => "string", "length" => 100, "null" => false),
            "created_at" => array("type" => "datetime", "null" => false),
            "updated_at" => array("type" => "datetime", "null" => false)
        ));

        $this->addIndex("users", "email", array("unique" => true));
    }

    public function down()
    {
        $this->dropTable("users");
    }
}

ステップ2：マイグレーションの実行とロールバック

マイグレーションファイルを作成したら、実際に実行してみましょう：

Bash

# マイグレーションを実行
$ php sabel migrate:latest

# 特定のバージョンまで実行
$ php sabel migrate:up 20240625000000

# ロールバック（1つ前の状態に戻す）
$ php sabel migrate:rollback

# 全てロールバック
$ php sabel migrate:reset

マイグレーションの実行状況は、データベース内のschema_migrationsテーブルで管理されています。このテーブルには、実行済みのマイグレーションのバージョンが記録されているため、同じマイグレーションを重複して実行することはありません。

ハマった点やエラー解決

実際の開発でよくあるのが、マイグレーション実行中のエラーです。特に、既存のテーブルにカラムを追加する場合や、外部キー制約を設定する場合に注意が必要です。

例えば、以下のようなマイグレーションを考えてみましょう：

Php

<?php
class AddProfileToUsers extends Sabel_Migration_Abstract
{
    public function up()
    {
        $this->addColumn("users", "profile", array("type" => "text"));
    }

    public function down()
    {
        $this->removeColumn("users", "profile");
    }
}

このマイグレーションを実行すると、以下のようなエラーが発生することがあります：

SQLSTATE[42S21]: Column already exists: 1060 Duplicate column name 'profile'

これは、既に同じ名前のカラムが存在している場合に発生します。特に、開発環境で何度かマイグレーションを実行したりロールバックしたりしていると、状態が一致しなくなることがあります。

解決策

このような問題を防ぐためには、マイグレーションの実行前に状態を確認するようにしましょう：

Php

<?php
class AddProfileToUsers extends Sabel_Migration_Abstract
{
    public function up()
    {
        if (!$this->hasColumn("users", "profile")) {
            $this->addColumn("users", "profile", array("type" => "text"));
        }
    }

    public function down()
    {
        if ($this->hasColumn("users", "profile")) {
            $this->removeColumn("users", "profile");
        }
    }
}

また、外部キー制約を設定する場合は、参照先のテーブルが存在することを確認しましょう：

Php

<?php
class AddUserIdToOrders extends Sabel_Migration_Abstract
{
    public function up()
    {
        $this->addColumn("orders", "user_id", array("type" => "integer", "null" => false));

        // 外部キー制約を追加
        $this->addForeignKey("orders", "user_id", "users", "id", array(
            "on_delete" => "CASCADE",
            "on_update" => "CASCADE"
        ));
    }

    public function down()
    {
        $this->removeForeignKey("orders", "user_id");
        $this->removeColumn("orders", "user_id");
    }
}

さらに、チーム開発では以下の運用ルールを設けることをおすすめします：

  1. マイグレーションファイルは必ず小さな単位で作成する
  2. マイグレーション実行前に、必ず現在のデータベースの状態を確認する
  3. 本番環境への適用前に、ステージング環境で必ずテストする
  4. マイグレーションファイルにコメントを残し、意図を明確にする

まとめ

本記事では、Sabelフレームワークのマイグレーションツールの基本的な使い方から、実践的な運用方法まで解説しました。

  • マイグレーションは、データベースのスキーマをバージョン管理する仕組み
  • Sabelのマイグレーションは、PHPコードで記述でき、ロールバックも簡単
  • 実装時は、エラーハンドリングを意識して、安全に実行できるようにする
  • チーム開発では、運用ルールを設けることで、トラブルを未然に防げる

この記事を通して、マイグレーションを使うことで、より安全で追跡可能なデータベース管理ができるようになりました。次回は、Sabelのマイグレーションを使った、より高度なデータベース設計パターンや、大規模システムでの運用事例について紹介したいと思います。

参考資料