migration guide improved

docs/guide/migration.md

@@ -73,21 +73,25 @@ method returns `false` to indicate that the migration cannot be reverted.
 As an example, let's show the migration about creating a news table.
 
 ```php
+
+use yii\db\Schema;
+
 class m101129_185401_create_news_table extends \yii\db\Migration
 {
 	public function up()
 	{
-		$this->db->createCommand()->createTable('tbl_news', [
+		$this->createTable('tbl_news', [
 			'id' => 'pk',
-			'title' => 'string(128) NOT NULL',
+			'title' => Schema::TYPE_STRING . ' NOT NULL',
-			'content' => 'text',
+			'content' => Schema::TYPE_TEXT,
-		])->execute();
+		]);
 	}
 
 	public function down()
 	{
-		$this->db->createCommand()->dropTable('tbl_news')->execute();
+		$this->dropTable('tbl_news');
 	}
+
 }
 ```
 
@@ -110,38 +114,40 @@ Transactional Migrations
 While performing complex DB migrations, we usually want to make sure that each
 migration succeed or fail as a whole so that the database maintains the
 consistency and integrity. In order to achieve this goal, we can exploit
-DB transactions.
+DB transactions. We could use special methods `safeUp` and `safeDown` for these purposes.
-
-We could explicitly start a DB transaction and enclose the rest of the DB-related
-code within the transaction, like the following:
 
 ```php
+
+use yii\db\Schema;
+
 class m101129_185401_create_news_table extends \yii\db\Migration
 {
-	public function up()
+	public function safeUp()
-	{
-		$transaction=$this->getDbConnection()->beginTransaction();
-		try
 	{
-			$this->db->createCommand()->createTable('tbl_news', [
+		$this->createTable('tbl_news', [
+			'id' => 'pk',
+			'title' => Schema::TYPE_STRING . ' NOT NULL',
+			'content' => Schema::TYPE_TEXT,
+		]);
+
+		$this->createTable('tbl_user', [
 			'id' => 'pk',
-				'title' => 'string NOT NULL',
+			'login' => Schema::TYPE_STRING . ' NOT NULL',
-				'content' => 'text',
+			'password' => Schema::TYPE_STRING . ' NOT NULL',
-			])->execute();
+		]);
-			$transaction->commit();
 	}
-		catch(Exception $e)
+
+	public function safeDown()
 	{
-			echo "Exception: ".$e->getMessage()."\n";
+		$this->dropTable('tbl_news);
-			$transaction->rollback();
+		$this->dropTable('tbl_user');
-			return false;
-		}
 	}
 
-	// ...similar code for down()
 }
 ```
 
+When your code uses more then one query it is recommended to use `safeUp` and `safeDown`.
+
 > Note: Not all DBMS support transactions. And some DB queries cannot be put
 > into a transaction. In this case, you will have to implement `up()` and
 > `down()`, instead. And for MySQL, some SQL statements may cause
@@ -301,7 +307,7 @@ are located within the module's `migrations` directory, we can use the following
 command:
 
 ```
-yii migrate/up --migrationPath=ext.forum.migrations
+yii migrate/up --migrationPath=@app.modules.forum.migrations
 ```
 
 
@@ -314,8 +320,14 @@ or we may want to use a customized migration template. We can do so by modifying
 the console application's configuration file like the following,
 
 ```php
-TBD
+'controllerMap' => [
+    'migrate' => [
+        'class' => 'yii\console\MigrateController',
+        'migrationTable' => 'my_custom_migrate_table',
+    ],
+]
 ```
 
 Now if we run the `migrate` command, the above configurations will take effect
-without requiring us to enter the command line options every time.
+without requiring us to enter the command line options every time. Other command options
+can be also configured this way.