diff --git a/docs/en/basics/orm.md b/docs/en/basics/orm.md
index 9638b583..9df2a3cc 100644
--- a/docs/en/basics/orm.md
+++ b/docs/en/basics/orm.md
@@ -129,8 +129,8 @@ return [
```
> **Warning**
-> Please note that using SQLite as the database backend with multiple workers can present significant challenges and
-> limitations. It is important to be aware of these limitations to ensure proper functionality and performance of your
+> Please note that using SQLite as the database backend with multiple workers can present significant challenges and
+> limitations. It is important to be aware of these limitations to ensure proper functionality and performance of your
> application. Rad more about this in the [SQLite limitations](./#sqlite-limitations) section.
> **See more**
@@ -880,9 +880,118 @@ Foreign Keys of default.posts:
## Migrations
-You can create config file `app/config/migration.php` if you want to configure Cycle ORM Migrations:
+When you're working with Cycle ORM and need to adapt your database to changes in your application's entities, the
+`cycle/migrations` package provides a convenient way to generate and manage your migrations. This process compares
+your current database schema with your entity changes and creates the necessary migration files.
+
+### Generating Migrations
+
+After you've made changes to your entities or created new ones, you'll need to generate migration files that reflect \
+those changes. To do this, run the following command in your console:
+
+```terminal
+php app.php cycle:migrate
+```
+
+The new migration files will be created in the app/migrations directory.
+
+> **Warning**
+> Before executing the above command, make sure to apply any existing migrations by running `php app.php migrate`. This
+> ensures your database schema is up-to-date.
+
+### Applying Migrations
+
+After you generate migration files, they need to be applied to your database to make the actual changes.
+
+```terminal
+php app.php migrate
+```
+
+This command applies the latest generated migrations. When you run it, Cycle ORM updates your database schema according
+to the changes described in your migration files.
+
+**Cycle ORM provides several commands to manage migrations at different stages and for different purposes:**
+
+#### Replay
+
+```terminal
+php app.php migrate:replay
+```
+
+This command is useful for re-running migrations. It first rolls back (or "downs") migrations, then runs them again
+(or "ups"). It can be handy when you want to quickly test changes made in your migrations.
+
+**Options:**
+
+- `--all`: This option will replay all migrations, not just the last one.
+
+#### Rollback
+
+```terminal
+php app.php migrate:rollback
+```
+
+If you need to undo migrations, this is the command you'll use. It reverses the changes made by the migrations. By
+default, it rolls back the last migration.
+
+**Options:**
+
+- `--all`: This option will rollback all migrations, not just the last one.
+
+#### Status
+
+```terminal
+php app.php migrate:status
+```
+
+Want to see what's been done and what's pending? This command shows you a list of all migrations along with their
+statuses—whether they've been applied or not.
+
+**Here's an example of the output:**
+
+```output
++-----------------------------------------------------------+---------------------+---------------------+
+| Migration | Created at | Executed at |
++-----------------------------------------------------------+---------------------+---------------------+
+| 0_default_create_auth_tokens | 2023-09-25 16:45:13 | 2023-10-04 10:46:11 |
+| 0_default_create_user_role_create_user_roles_create_users | 2023-09-26 21:22:16 | 2023-10-04 10:46:11 |
+| 0_default_change_user_roles_add_read_only | 2023-09-27 13:53:19 | 2023-10-04 10:46:11 |
++-----------------------------------------------------------+---------------------+---------------------+
+```
+
+#### Init
+
+```terminal
+php app.php migrate:init
+```
+
+Before you can start using migrations, the migrations component needs a place to record which migrations have been run.
+This command sets up that tracking by creating a migrations table in your database.
+
+> **Note**
+> This command is run automatically when you first run `php app.php migrate`.
+
+
+### Configuration
+
+If you want to customize how Cycle ORM handles migrations, you can create a configuration file
+at `app/config/migration.php.` This file allows you to set various options, such as the location of migration files or
+the name of the migrations table in the database.
+
+**Here's what you can set in the configuration file:**
+
+- **Directory**: Choose where to save the migration files.
+- **Table**: Name the table that keeps track of migration statuses.
+- **Strategy**: Determine how migration files are generated.
+- **Name Generator**: Specify how migration filenames are created.
+- **Safe**: Skip confirmation requests during migration runs in production environments.
+
+**Here is an example of config file**
```php app/config/migration.php
+use Cycle\Schema\Generator\Migrations\Strategy\SingleFileStrategy;
+use Cycle\Schema\Generator\Migrations\NameBasedOnChangesGenerator;
+
return [
/**
* Directory to store migration files
@@ -893,6 +1002,16 @@ return [
* Table name to store information about migrations status (per database)
*/
'table' => 'migrations',
+
+ /**
+ * Migration file generator strategy
+ */
+ 'strategy' => SingleFileStrategy::class,
+
+ /**
+ * Migration file name generator
+ */
+ 'nameGenerator' => NameBasedOnChangesGenerator::class,
/**
* When set to true no confirmation will be requested on migration run.
@@ -901,15 +1020,130 @@ return [
];
```
-### Console Commands
+### Migration File Strategies
+
+With version **2.6.0** of `spiral/cycle-bridge`, you can choose how the migration files are generated:
+
+#### 1. Single File Strategy
+
+This strategy combines all changes into a single migration file each time you run the command. This is useful if you
+prefer to group all changes in one place.
+
+```php
+table('user_roles')
+ ->addColumn('created_at', 'datetime', ['nullable' => false, 'default' => 'CURRENT_TIMESTAMP'])
+ // ...
+ ->setPrimaryKeys(['uuid'])
+ ->create();
+
+ $this->table('users')
+ ->addColumn('created_at', 'datetime', ['nullable' => false, 'default' => 'CURRENT_TIMESTAMP'])
+ //...
+ ->setPrimaryKeys(['uuid'])
+ ->create();
+ }
+
+ public function down(): void
+ {
+ $this->table('users')->drop();
+ $this->table('user_roles')->drop();
+ }
+}
+```
+
+#### 2. Multiple Files Strategy
+
+With this approach, changes are separated into different files based on the table name. This means if you have changes
+for different tables, each table's changes go into its own file.
+
+```php
+table('user_roles')
+ ->addColumn('created_at', 'datetime', ['nullable' => false, 'default' => 'CURRENT_TIMESTAMP'])
+ // ...
+ ->setPrimaryKeys(['uuid'])
+ ->create();
+ }
+
+ public function down(): void
+ {
+ $this->table('user_roles')->drop();
+ }
+}
+
+```
+
+```php
+table('users')
+ ->addColumn('created_at', 'datetime', ['nullable' => false, 'default' => 'CURRENT_TIMESTAMP'])
+ //...
+ ->setPrimaryKeys(['uuid'])
+ ->create();
+ }
+
+ public function down(): void
+ {
+ $this->table('users')->drop();
+ }
+}
+```
+
+#### 3. Custom strategy
+
+You also have the option to create a custom migration strategy by implementing
+the `Cycle\Schema\Generator\Migrations\Strategy\GeneratorStrategyInterface`.
+
+### Migration Filename Generation
+
+With version **2.6.0** of `spiral/cycle-bridge`, you can choose configure the default naming strategy for migration
+files.
+
+By default, Spiral uses `Cycle\Schema\Generator\Migrations\NameBasedOnChangesGenerator` that takes into account all the
+changes in the migration file to create a unique name. But you can create a custom filename generation strategy by
+implementing the `Cycle\Schema\Generator\Migrations\NameGeneratorInterface`.
-| Command | Description |
-|--------------------|---------------------------------------------------------------------------------------------------|
-| `migrate` | Performs one or all the outstanding migrations.
`--one` Execute only one (first) migration. |
-| `migrate:replay` | Replays (down, up) one or multiple migrations.
`--all` Replays all the migrations. |
-| `migrate:rollback` | Rolls back (default) or multiple migrations.
`--all` Rolls back all the executed migrations. |
-| `migrate:init` | Initiates the migrations component (create a migrations table). |
-| `migrate:status` | Gets a list of all available migrations and their statuses. |
+---
## SQLite limitations