Add migration docs yiisoft/db-migration (#200)

guide/en/README.md

@@ -65,13 +65,13 @@ Views -
 * [Template engines](views/template-engines.md) -
 
 
-Working with databases -
+Working with databases +-
 ----------------------
 
 * [Database access objects](db-dao.md): Connecting to a database, basic queries, transactions, and schema manipulation
 * [Query builder](db-query-builder.md): Querying the database using a simple abstraction layer
 * [Active record](db-active-record.md): The Active Record ORM, retrieving and manipulating records, and defining relations
-* [Migrations](db-migrations.md): Apply version control to your databases in a team development environment
+* [Migrations](databases/db-migrations.md): +
 
 Getting data from users -
 -----------------------

guide/en/databases/db-migrations.md

@@ -0,0 +1,102 @@
+# Migrations
+
+To use migrations, install [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package:
+
+```shell
+composer require yiisoft/db-migration
+```
+
+### Example usage
+
+First, configure DI container. Create `config/common/db.php` with the following content:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Yiisoft\Db\Connection\ConnectionInterface;
+use Yiisoft\Db\Sqlite\Connection as SqliteConnection;
+
+return [
+    ConnectionInterface::class => [
+        'class' => SqliteConnection::class,
+        '__construct()' => [
+            'dsn' => 'sqlite:' . __DIR__ . '/Data/yiitest.sq3'
+        ]
+    ]
+];
+```
+
+Add the following to `config/params.php`:
+
+```php
+...
+'yiisoft/db-migration' => [
+    'newMigrationNamespace' => 'App\\Migration',
+    'sourceNamespaces' => ['App\\Migration'],
+],
+...
+```
+
+Now test if it works:
+
+```shell
+./yii list migrate
+```
+
+### Creating a migration
+
+To work with migrations, you can use the provided [view](https://github.com/yiisoft/db-migration/tree/master/resources/views).
+
+```shell
+./yii migrate:create my_first_table --command=table --fields=name,example --table-comment=my_first_table
+```
+
+That would generate the following:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Migration;
+
+use Yiisoft\Db\Migration\MigrationBuilder;
+use Yiisoft\Db\Migration\RevertibleMigrationInterface;
+use Yiisoft\Db\Migration\TransactionalMigrationInterface;
+
+/**
+ * Handles the creation of table `my_first_table`.
+ */
+final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface
+{
+    public function up(MigrationBuilder $b): void
+    {
+        $b->createTable('my_first_table', [
+            'id' => $b->primaryKey(),
+            'name',
+            'example',
+        ]);
+
+        $b->addCommentOnTable('my_first_table', 'dest');
+    }
+
+    public function down(MigrationBuilder $b): void
+    {
+        $b->dropTable('my_first_table');
+    }
+}
+```
+
+For more information [see](https://github.com/yiisoft/db-migration/tree/master/docs/en)
+
+### Upgrading from Yii2
+
+Migrations in Yii2 and the [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package are not compatible,
+and the `migration` table is also not
+compatible.
+A probable solution is to use structure dumps and rename the old `migration` table. Upon the initial execution of
+migrations, a new `migration` table with new fields will be created. All subsequent changes in the database schema are
+applied using the new `migration` component and recorded in the new migration table.
+

guide/en/security/authorization.md

@@ -208,10 +208,10 @@ The command above could be executed from console the following way:
 
 **TODO**: finish it when migrations are implemented.
 
-You can use [migrations](db-migrations.md)
+You can use [migrations](../databases/db-migrations.md)
 to initialize and change hierarchy via APIs offered by `\Yiisoft\Rbac\ManagerInterface`.
 
-Create new migration using `./yii migrate/create init_rbac` then implement creating a hierarchy:
+Create new migration using `./yii migrate:create init_rbac` then implement creating a hierarchy:
 
 ```php
 <?php

guide/es/security/authorization.md

@@ -208,7 +208,7 @@ The command above could be executed from console the following way:
 You can use [migrations](db-migrations.md)
 to initialize and modify hierarchy via APIs offered by `\Yiisoft\Rbac\ManagerInterface`.
 
-Create new migration using `./vendor/bin/yii migrate/create init_rbac` then impement creating a hierarchy:
+Create new migration using `./vendor/bin/yii migrate:create init_rbac` then impement creating a hierarchy:
 
 ```php
 <?php