Database Migration در فریمورک Yii

در طول توسعه یک برنامه مبتنی بر پایگاه داده (database-driven)، ساختار پایگاه داده همراه با source code رشد می کند و تکامل می یابد. فریمورک Yii ویژگی ای به نام database migration را ارائه می دهد که اجازه می دهد به شما تا تغییرات database را نگهداری و پیگیری کنید.

فریمورک Yii دستورات migration زیر را ارائه می دهد:

• Create new migrations
• Revert migrations
• Apply migrations
• Re-apply migrations
• Show migration status and history

می خواهیم یک database migration ایجاد کنیم، پس بدین صورت عمل می کنیم.

مرحله 1 - داخل پوشه ی ریشه ی پروژه، پنجره console را باز کنید و دستورات زیر را اجرا کنید.

./yii migrate/create add_news_table

دستور بالا یک فایل migration جدید (m160113_102634_add_news_table.php در مثال ما) در پوشه migrations ایجاد می کند.

فایل مورد نظر، حاوی کد زیر است :

<?php
   use yii\db\Schema;
   use yii\db\Migration;
   class m160113_102634_add_news_table extends Migration {
      public function up() {
   
      }
      public function down() {
         echo "m160113_102634_add_news_table cannot be reverted.\n";
         return false;
      }
      /*
      // Use safeUp/safeDown to run migration code within a transaction
      public function safeUp() {
 
      }
      public function safeDown() {
   
      }
      */
   }
?>

هر DB migration ی یک کلاس PHP است که کلاس yii\db\Migration را توسعه می دهد. نام کلاس با فرمت زیر ساخته می شود :

m<YYMMDD_HHMMSS>_<Name>

بخش <YYMMDD_HMMSS> تاریخ و زمانی است که در آن migration اجرا شده است و <Name> ارگومانی است که در فرمان console ارائه شده است.

متد up() هنگام upgrade پایگاه داده تان، فراخوانی می شود، در حالی که متد  down() هنگام downgrade فراخوانی می شود.

مرحله 2 - برای اضافه کردن یک جدول جدید به پایگاه داده، فایل migration را به صورت زیر تغییر دهید.

<?php
   use yii\db\Schema;
   use yii\db\Migration;
   class m160113_102634_add_news_table extends Migration {
      public function up() {
         $this->createTable("news", [
            "id" => Schema::TYPE_PK,
            "title" => Schema::TYPE_STRING,
            "content" => Schema::TYPE_TEXT,
         ]);
      }
      public function down() {
         $this->dropTable('news');
      }
      /*
      // Use safeUp/safeDown to run migration code within a transaction
      public function safeUp() {
            
      }
      public function safeDown() {

 
      }
      */
   }
?>

در کد بالا ما یک جدول جدید به نام news در متد up() ایجاد کردیم و این جدول را در متد down() حذف نمودیم.

جدول news شامل سه فیلد است: id، title و content. هنگام ایجاد یک جدول یا ستون، باید از انواع abstract یا انتزاعی استفاده کنیم تا migration مستقل از نوع پایگاه داده ای باشد که استفاده می کنیم. برای مثال، در پایگاه داده از نوع  MySQL می تواند TYPE_PK تبدیل می شود به  int(11) NOT NUL AUTO_INCREMETN PRIMARY KEY  .

مرحله 3 - برای upgrade یک پایگاه داده، این دستور را اجرا کنید.

./yii migrate

فرمان بالا تمام migration های موجود، که هنوز اعمال نشده اند را لیست می کند. حال اگر migration ها را اعمال کنید ، در تمامی کلاسهای migration، safeUp() یا up() اجرا خواهد شد.

مرحله 4 - برای اعمال تنها سه migration موجود، کد زیر را اجرا کنید.

./yii migrate 3

مرحله 5 - شما همچنین می توانید یک migration خاص را تعریف کنید که پایگاه داده به آن منتقل شود.

# استفاده از timestamp برای مشخص کردن migration

yii migrate/to 160202_195501

# با استفاده از یک رشته که می تواند توسط strtotime() تجزیه شود

yii migrate/to "2016-01-01 19:55:01"

# با استفاده از نام کامل

yii migrate/to m160202_195501_create_news_table

# با استفاده از UNIX timestamp

yii migrate/to 1393964718

مرحله 6 - برای برگرداندن migration، متدهای down() و safeDown() را اجرا کنید.

./yii migrate/down

گام 7 - برای بازگرداندن پنج migration اعمال شده ی اخیر، کد زیر را اجرا کنید.

./yii migrate/down 5

گام 8 - برای دوباره انجام دادن migration ها (بازگرداندن و سپس اعمال دوباره) کد زیر را اجرا کنید.

./yii migrate/redo

برای لیست کردن migrationهایی که قبلا اعمال شده است، از این دستورات استفاده کنید :

• yii migrate/new

# 10 تا از اولین migration های جدید را نشان می دهد.

• yii migrate/new 3 

# 3 تا از اولین migration های جدید را نشان می دهد.

• yii migrate/new all 

# همه ی migration های جدید را نشان می دهد.

• yii migrate/history

# 10 تا از اخرین migration های اعمال شده را نشان می دهد.

• yii migrate/history 20 

# 20 تا از اخرین migration های اعمال شده را نشان می دهد.

• yii migrate/history all 

# همه ی migration های اعمال شده را نشان می دهد.

گاهی اوقات شما نیاز دارید ستونی از یک جدول خاص را اضافه یا حذف کنید. شما می توانید از متدهای addColumn() و dropColumn() استفاده کنید.

مرحله 1 - یک  migrationجدید ایجاد کنید.

./yii migrate/create add_category_to_news

مرحله 2 - فایل migration جدیدمان را به صورت زیر ویرایش کنید.

<?php
   use yii\db\Schema;
   use yii\db\Migration;
   class m160113_110909_add_category_to_news extends Migration {
      public function up() {
         $this->addColumn('news', 'category', $this->integer());
      }
      public function down() {
         $this->dropColumn('news', 'category');
      }
   }
?>

اکنون دستور ./yii migrate را اجرا کنید، ستون category به جدول news اضافه می شود. برعکس، اگر شما دستور ./yii migrate/down 1 را اجرا کنید، ستون category  حذف می شود.

هنگام انجام DB migration ها، حصول اطمینان از اینکه migration موفقیت آمیز بوده یا به شکست خوده است، مهم است. توصیه می شود که عملیات DB در یک  transaction محصور شود. برای اجرای transactional migration، شما فقط باید کد migration را در متد safeUp() و safeDown()  قرار دهید. اگر انجام عملیات در این متد ها به هردلیلی موفقیت آمیز نباشد، تمام عملیات قبلی بازگردانده می شود.

مثال قبلی با روش  “transactional way”انجام می دهیم :

<?php
   use yii\db\Schema;
   use yii\db\Migration;
   class m160113_110909_add_category_to_news extends Migration {
      public function safeUp() {
         $this->addColumn('news', 'category', $this->integer());
      }
      public function safeDown() {
         $this->dropColumn('news', 'category');
      }
   }
?>

کلاس yii\db\Migration متد های زیر را برای کار با پایگاه های داده فراهم می کند :