diff --git a/_translations/po/es/guide_databases_db-migrations.md.po b/_translations/po/es/guide_databases_db-migrations.md.po index c41ea3c..30b0c95 100644 --- a/_translations/po/es/guide_databases_db-migrations.md.po +++ b/_translations/po/es/guide_databases_db-migrations.md.po @@ -6,7 +6,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2025-12-27 07:40+0000\n" +"POT-Creation-Date: 2025-12-27 10:28+0000\n" "PO-Revision-Date: 2025-09-04 11:19+0500\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -22,26 +22,207 @@ msgstr "" msgid "Migrations" msgstr "" +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "During the course of developing and maintaining a database-driven application, the structure of the database being used evolves just like the source code does. For example, during the development of an application, a new table may be found necessary; after the application is deployed to production, it may be discovered that an index should be created to improve the query performance; and so on. Because a database structure change often requires some source code changes, Yii supports the so-called *database migration* feature that allows you to keep track of database changes in terms of *database migrations* which are version-controlled together with the source code." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "The following steps show how database migration can be used by a team during development:" +msgstr "" + +#. type: Bullet: '1. ' +#: ../src/guide/databases/db-migrations.md +msgid "Tim creates a new migration (e.g. creates a new table, changes a column definition, etc.)." +msgstr "" + +#. type: Bullet: '2. ' +#: ../src/guide/databases/db-migrations.md +msgid "Tim commits the new migration into the source control system (e.g. Git, Mercurial)." +msgstr "" + +#. type: Bullet: '3. ' +#: ../src/guide/databases/db-migrations.md +msgid "Doug updates his repository from the source control system and receives the new migration." +msgstr "" + +#. type: Bullet: '4. ' +#: ../src/guide/databases/db-migrations.md +msgid "Doug applies the migration to his local development database, thereby synchronizing his database to reflect the changes that Tim has made." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "And the following steps show how to deploy a new release with database migrations to production:" +msgstr "" + +#. type: Bullet: '1. ' +#: ../src/guide/databases/db-migrations.md +msgid "Scott creates a release tag for the project repository that contains some new database migrations." +msgstr "" + +#. type: Bullet: '2. ' +#: ../src/guide/databases/db-migrations.md +msgid "Scott updates the source code on the production server to the release tag." +msgstr "" + +#. type: Bullet: '3. ' +#: ../src/guide/databases/db-migrations.md +msgid "Scott applies any accumulated database migrations to the production database." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Yii provides a set of migration command line tools that allow you to:" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "create new migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "apply migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "revert migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "re-apply migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "show migration history and status." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "All these tools are accessible through the command `yii migrate`. In this section we will describe in detail how to accomplish various tasks using these tools." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> [!TIP]\n" +"> Migrations could affect not only database schema but adjust existing data to fit new schema, create RBAC\n" +"hierarchy or clean up cache.\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> [!NOTE]\n" +"> When manipulating data using a migration you may find that using your Active Record or entity classes\n" +"> for this might be useful because some of the logic is already implemented there. Keep in mind however, that in contrast\n" +"> to code written in the migrations, whose nature is to stay constant forever, application logic is subject to change.\n" +"> So when using Active Record or entity classes in migration code, changes to the logic in the source code\n" +"> may accidentally break the existing migrations. For this reason migration code should be kept independent of other\n" +"> application logic such.\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Introduction +" +msgid "Initial configuration" +msgstr "Introducción" + #. type: Plain text #: ../src/guide/databases/db-migrations.md msgid "To use migrations, install [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package:" msgstr "" -#. type: Fenced code block (shell) +#. type: Fenced code block (sh) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, no-wrap +msgid "make composer require yiisoft/db-migration\n" +msgstr "" + +#. type: Plain text #: ../src/guide/databases/db-migrations.md +msgid "Create a directory to store migrations `src/Migration` right in the project root." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Add the following configuration to `config/common/params.php`:" +msgstr "" + +#. type: Fenced code block (php) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md #, no-wrap -msgid "composer require yiisoft/db-migration\n" +msgid "" +"'yiisoft/db-migration' => [\n" +" 'newMigrationNamespace' => 'App\\\\Migration',\n" +" 'sourceNamespaces' => ['App\\\\Migration'],\n" +"],\n" msgstr "" -#. type: Title ### +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "If you want to place migrations elsewhere, you can define the path in `newMigrationPath`. If your migrations to be applied are from multiple sources, such as external modules, `sourcePaths` could be used to define these." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "You need a database connection configured as well. See [Working with databases](../start/databases.md) for an example of configuring it for PostgreSQL." +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "Creating a migration" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, fuzzy +#| msgid "Events are raised like the following:" +msgid "To create a new empty migration, run the following command:" +msgstr "Los eventos se lanzan de la siguiente forma:" + +#. type: Fenced code block (sh) +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"make shell\n" +"./yii migrate:create \n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "The required `name` argument gives a brief description about the new migration. For example, if the migration is about creating a new table named *news*, you may use the name `create_news_table` and run the following command:" +msgstr "" + +#. type: Fenced code block #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "Example usage" +msgid "" +"make shell\n" +"./yii migrate:create create_news_table\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> [!NOTE]\n" +"> Because the `name` argument will be used as part of the generated migration class name,\n" +"> it should only contain letters, digits, and/or underscore characters.\n" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "First, configure a DI container. Create `config/common/db.php` with the following content:" +msgid "The above command will create a new PHP class file named `src/Migration/M251225221906CreateNewsTable.php`. The file contains the following code which mainly declares a migration class with the skeleton code:" msgstr "" #. type: Fenced code block (php) @@ -52,62 +233,460 @@ msgid "" "\n" "declare(strict_types=1);\n" "\n" -"use Yiisoft\\Db\\Connection\\ConnectionInterface;\n" -"use Yiisoft\\Db\\Sqlite\\Connection as SqliteConnection;\n" +"namespace App\\Migration;\n" +"\n" +"use Yiisoft\\Db\\Migration\\MigrationBuilder;\n" +"use Yiisoft\\Db\\Migration\\RevertibleMigrationInterface;\n" "\n" -"return [\n" -" ConnectionInterface::class => [\n" -" 'class' => SqliteConnection::class,\n" -" '__construct()' => [\n" -" 'dsn' => 'sqlite:' . __DIR__ . '/Data/yiitest.sq3'\n" -" ]\n" -" ]\n" -"];\n" +"final class M251225221906CreateNewsTable implements RevertibleMigrationInterface\n" +"{\n" +" public function up(MigrationBuilder $b): void\n" +" {\n" +" // TODO: Implement the logic to apply the migration.\n" +" }\n" +"\n" +" public function down(MigrationBuilder $b): void\n" +" {\n" +" // TODO: Implement the logic to revert the migration.\n" +" }\n" +"}\n" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "Add the following to `config/params.php`:" +msgid "In the migration class, you are expected to write code in the `up()` method that makes changes to the database structure. You may also want to write code in the `down()` method to revert the changes made by `up()`. The `up()` method is invoked when you upgrade the database with this migration, while the `down()` method is invoked when you downgrade the database. The following code shows how you may implement the migration class to create a `news` table:" msgstr "" #. type: Fenced code block (php) #: ../src/guide/databases/db-migrations.md #, no-wrap msgid "" -"...\n" -"'yiisoft/db-migration' => [\n" -" 'newMigrationNamespace' => 'App\\\\Migration',\n" -" 'sourceNamespaces' => ['App\\\\Migration'],\n" -"],\n" -"...\n" +"columnBuilder();\n" +"\n" +" $b->createTable('news', [\n" +" 'id' => $cb::uuidPrimaryKey(),\n" +" 'title' => $cb::string()->notNull(),\n" +" 'content' => $cb::text(),\n" +" ]);\n" +" }\n" +"\n" +" public function down(MigrationBuilder $b): void\n" +" {\n" +" $b->dropTable('news');\n" +" }\n" +"}\n" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "Now test if it works:" +msgid "Migration builder `$b` in the above manages database schema while the column builder `$cb` manages column types. Both allow using *abstract types*. When a migration is applied to a particular database, the abstract types will be translated into the corresponding database physical types and corresponding SQL to define them." msgstr "" -#. type: Fenced code block (shell) +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Methods available in migration builder belong to the following types:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Raw queries" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "getDb — to get database connection instance." +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "execute — to execute raw SQL query." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Data" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "insert / update / delete" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "batchInsert" +msgstr "" + +#. type: Bullet: ' - ' #: ../src/guide/databases/db-migrations.md +msgid "upsert" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Tables and views" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "createTable / renameTable / dropTable" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "truncateTable" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addCommentOnTable / dropCommentFromTable" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "createView / dropView" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Columns" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addColumn / renameColumn / alterColumn / dropColumn" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addCommentOnColumn / dropCommentFromColumn" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Keys and indexes" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addPrimaryKey / dropPrimaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addForeignKey / dropForeignKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "createIndex / dropIndex" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Additionally, there's a `columnBuilder()` which is used to obtain a column builder as in example above. The builder has static methods that define various column types:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Keys" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "primaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "smallPrimaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "bigPrimaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "uuidPrimaryKey" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Boolean" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "boolean" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Numbers" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "bit" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "tinyint" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "smallint" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "integer" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "bigint" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "flat" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "double" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "decimal" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md ../src/internals/010-code-style.md #, no-wrap -msgid "./yii list migrate\n" +msgid "Strings" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "char" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "string" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "text" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Date and time" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "timestamp" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "datetime" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "datetimeWithTimezone" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "time" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "timeWithTimezone" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "date" msgstr "" +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Special types" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "money" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "binary" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "uuid" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "array" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "structured" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "json" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "enum" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "All the above methods create a base type which could be adjusted with additional methods:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "null / notNull" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "defaultValue" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "unique" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "scale / size / unsigned" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "primaryKey / autoIncrement" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "check" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "comment" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "computed" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "extra" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +#, fuzzy +#| msgid "References" +msgid "reference" +msgstr "Referencias" + #. type: Title ### #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "Creating a migration" +msgid "Irreversible migrations" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "To work with migrations, you can use the provided [view](https://github.com/yiisoft/db-migration/tree/master/resources/views)." +msgid "Not all migrations are reversible. For example, if the `up()` method deletes a row of a table, you may not be able to recover this row in the `down()` method. Sometimes, you may be just too lazy to implement the `down()`, because it is not very common to revert database migrations. In this case, you should implement `Yiisoft\\Db\\Migration\\MigrationInterface` that has `up()` only." +msgstr "" + +#. type: Title ### +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Introduction +" +msgid "Transactional migrations" +msgstr "Introducción" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "While performing complex DB migrations, it is important to ensure each migration to either succeed or fail as a whole so that the database can maintain integrity and consistency. To achieve this goal, it is recommended that you may enclose the DB operations of each migration in a transaction automatically by adding `TransactionalMigrationInterface` to `implements` of your migration." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "As a result, if any operation in the `up()` or `down()` method fails, all prior operations will be rolled back automatically." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> Note: Not all DBMS support transactions. And some DB queries cannot be put into a transaction. For some examples,\n" +"please refer to [implicit commit](https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html).\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Generating API documentation" +msgid "Generating a migration" +msgstr "Generación de Documentación de API" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Instead of writing migrations by hand, the command provides a convenient way generate some of the code." msgstr "" #. type: Fenced code block (shell) #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "./yii migrate:create my_first_table --command=table --fields=name,example --table-comment=my_first_table\n" +msgid "" +"make shell\n" +"./yii migrate:create -- my_first_table --command=table --fields=name,example --table-comment=my_first_table\n" msgstr "" #. type: Plain text @@ -130,19 +709,21 @@ msgid "" "use Yiisoft\\Db\\Migration\\TransactionalMigrationInterface;\n" "\n" "/**\n" -" * Handles the creation of a table `my_first_table`.\n" +" * Handles the creation of table `my_first_table`.\n" " */\n" -"final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface\n" +"final class M251227095006CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface\n" "{\n" " public function up(MigrationBuilder $b): void\n" " {\n" +" $columnBuilder = $b->columnBuilder();\n" +"\n" " $b->createTable('my_first_table', [\n" -" 'id' => $b->primaryKey(),\n" +" 'id' => $columnBuilder::primaryKey(),\n" " 'name',\n" " 'example',\n" " ]);\n" -" \n" -" $b->addCommentOnTable('my_first_table', 'dest');\n" +"\n" +" $b->addCommentOnTable('my_first_table', 'my_first_table');\n" " }\n" "\n" " public function down(MigrationBuilder $b): void\n" @@ -154,7 +735,156 @@ msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "For more information [see](https://github.com/yiisoft/db-migration/tree/master/docs/guide/en)" +msgid "Commands available are:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "create - empty migration." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "table - creating a table. Use `--fields` specify a list of fields to use. Types could be specified as well such as `id:primaryKey,name:string:defaultValue(\"Alex\"),user_id:integer:foreignKey,category_id2:integer:foreignKey(category id2)`." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "dropTable - dropping a table." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "addColumn - adding a column." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "dropColumn - dropping a column." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "junction - creating a junction table. Use `--and` specify a second table." +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "Applying Migrations" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "To upgrade a database to its latest structure, you should apply all available new migrations using the following command:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "./yii migrate:up\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "This command will list all migrations that have not been applied so far. If you confirm that you want to apply these migrations, it will run the `up()` method in every new migration class, one after another, in the order of their timestamp values. If any of the migrations fails, the command will quit without applying the rest of the migrations." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "For each migration that has been successfully applied, the command will insert a row into a database table named `migration` to record the successful application of the migration. This will allow the migration tool to identify which migrations have been applied and which have not." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Sometimes, you may only want to apply one or a few new migrations, instead of all available migrations. You can do so by specifying the number of migrations that you want to apply when running the command. For example, the following command will try to apply the next three available migrations:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "./yii migrate:up --limit=3\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Resolving aliases " +msgid "Reverting Migrations " +msgstr "Resolución de Alias " + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "To revert (undo) one or multiple migrations that have been applied before, you can run the following command:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"./yii migrate:down # revert the most recently applied migration\n" +"./yii migrate:down --limit=3 # revert the most 3 recently applied migrations\n" +"./yii migrate:down --all # revert all migrations\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> Note: Not all migrations are reversible. Trying to revert such migrations will cause an error and stop the\n" +"entire reverting process.\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Resolving aliases " +msgid "Redoing Migrations " +msgstr "Resolución de Alias " + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Redoing migrations means first reverting the specified migrations and then applying again. This can be done as follows:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"./yii migrate:redo # redo the last applied migration\n" +"./yii migrate:redo --limit=3 # redo the last 3 applied migrations\n" +"./yii migrate:redo --all # redo all migrations\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "> Note: If a migration is not reversible, you will not be able to redo it.\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Raising events " +msgid "Listing Migrations " +msgstr "Lanzamiento de Eventos " + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "To list which migrations have been applied and which are not, you may use the following commands:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"./yii migrate/history # showing the last 10 applied migrations\n" +"./yii migrate:history --limit=5 # showing the last 5 applied migrations\n" +"./yii migrate:history --all # showing all applied migrations\n" +"\n" +"./yii migrate:new # showing the first 10 new migrations\n" +"./yii migrate:new --limit=5 # showing the first 5 new migrations\n" +"./yii migrate:new --all # showing all new migrations\n" msgstr "" #. type: Title ### @@ -165,5 +895,10 @@ msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "Migrations in Yii 2.0 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 further changes in the database schema are applied using the new `migration` component and recorded in the new migration table." +msgid "Migrations in Yii 2.0 and the [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package are not compatible, and the `migration` table is also not compatible." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "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 further changes in the database schema are applied using the new `migration` component and recorded in the new migration table." msgstr "" diff --git a/_translations/po/es/guide_start_databases.md.po b/_translations/po/es/guide_start_databases.md.po index 7ac96a0..560aede 100644 --- a/_translations/po/es/guide_start_databases.md.po +++ b/_translations/po/es/guide_start_databases.md.po @@ -6,7 +6,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2025-12-27 06:04+0000\n" +"POT-Creation-Date: 2025-12-27 06:16+0000\n" "PO-Revision-Date: 2025-09-04 11:19+0500\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -16,6 +16,22 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=(n != 1);\n" +#. type: Fenced code block (sh) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, no-wrap +msgid "make composer require yiisoft/db-migration\n" +msgstr "" + +#. type: Fenced code block (php) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, no-wrap +msgid "" +"'yiisoft/db-migration' => [\n" +" 'newMigrationNamespace' => 'App\\\\Migration',\n" +" 'sourceNamespaces' => ['App\\\\Migration'],\n" +"],\n" +msgstr "" + #. type: Title # #: ../src/guide/index.md ../src/guide/start/databases.md #, no-wrap @@ -252,27 +268,11 @@ msgstr "" msgid "To use migrations we need another package installed:" msgstr "" -#. type: Fenced code block (sh) -#: ../src/guide/start/databases.md -#, no-wrap -msgid "make composer require yiisoft/db-migration\n" -msgstr "" - #. type: Plain text #: ../src/guide/start/databases.md msgid "Create a directory to store migrations `src/Migration` right in the project root. Add the following configuration to `config/common/params.php`:" msgstr "" -#. type: Fenced code block (php) -#: ../src/guide/start/databases.md -#, no-wrap -msgid "" -"'yiisoft/db-migration' => [\n" -" 'newMigrationNamespace' => 'App\\\\Migration',\n" -" 'sourceNamespaces' => ['App\\\\Migration'],\n" -"],\n" -msgstr "" - #. type: Plain text #: ../src/guide/start/databases.md msgid "Now you can use `make yii migrate:create page` to create a new migration. For our example we need a `page` table with some columns:" diff --git a/_translations/po/es/internals_010-code-style.md.po b/_translations/po/es/internals_010-code-style.md.po index 642bbf8..36a528b 100644 --- a/_translations/po/es/internals_010-code-style.md.po +++ b/_translations/po/es/internals_010-code-style.md.po @@ -6,7 +6,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2025-12-24 08:02+0000\n" +"POT-Creation-Date: 2025-12-27 10:28+0000\n" "PO-Revision-Date: 2025-12-24 08:02+0000\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -16,117 +16,123 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=(n != 1);\n" +#. type: Title ## +#: ../src/guide/databases/db-migrations.md ../src/internals/010-code-style.md +#, no-wrap +msgid "Strings" +msgstr "" + #. type: Title # -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "010 — Code style" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Code formatting used in Yii 3 packages is based on [PSR-1](https://www.php-fig.org/psr/psr-1/) and [PSR-12](https://www.php-fig.org/psr/psr-12/) with extra rules added on top of it." msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md ../src/en/internals/017-tags.md -#: ../src/en/internals/018-widgets.md +#: ../src/internals/010-code-style.md ../src/internals/017-tags.md +#: ../src/internals/018-widgets.md #, no-wrap msgid "Names" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use English only." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use camelCase notation, including abbreviations (e.g., `enableIdn`)." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use the shortest possible, but an explanatory name." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Never trim or abbreviate a name." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Postfix classes, interfaces, traits and variables, which is a [collection](https://en.wikipedia.org/wiki/Collection_(abstract_data_type)), with `Collection`." msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Types" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Declare [argument and return types](https://www.php.net/manual/en/migration70.new-features.php) where possible." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[Use types for properties](https://wiki.php.net/rfc/typed_properties_v2)." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use strict typing. Avoid mixed and union types where possible except compatible types such as `string|Stringable`." msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Comments" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Inline comments are to be avoided unless code couldn't be understood without them. A good example is a workaround for a bug in a certain PHP version." msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Method comment is necessary except it adds nothing to what method name and signature already has." msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Class comment should describe the purpose of the class." msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, fuzzy #| msgid "[Validating input](https://github.com/yiisoft/validator/blob/master/docs/guide/en/README.md) +" msgid "[See PHPDoc](https://github.com/yiisoft/docs/blob/master/014-docs.md#phpdoc)." msgstr "[Validar Datos](https://github.com/yiisoft/validator/blob/master/docs/guide/en/README.md)" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Formatting" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "No alignment" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Property, variable and constant value assignments shouldn't be aligned. The same applies to phpdoc tags. The reason is that aligned statements often cause larger diff and even conflicts." msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "final class X\n" @@ -150,18 +156,18 @@ msgid "" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Chain calls" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Chained calls should be formatted for better readability. If it's a long chain that doesn't fit the line length of 120 characters, then each call should on a new line:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "$object\n" @@ -173,149 +179,143 @@ msgid "" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "If it's a short chain, it's alright for it to be on a single line:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "$object = $object->withName('test');\n" msgstr "" -#. type: Title ## -#: ../src/en/internals/010-code-style.md -#, no-wrap -msgid "Strings" -msgstr "" - #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "When no variables involved, use `'Hello!'`" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "To get variables into string prefer `\"Hello, $username!\"`" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Classes and interfaces" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Final by default" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Classes should be `final` by default." msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Private by default" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Constants, properties and methods should be private by default." msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Composition over inheritance" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, fuzzy #| msgid "[Dependency injection container](concept/di-container.md) +" msgid "Prefer [composition to inheritance](guide/en/concept/di-container.md)." msgstr "[Contenedor de Inyección de Dependencia](concept/di-container.md)" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Property, constant and method order" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, fuzzy #| msgid "The event class itself may look like the following:" msgid "Order should be the following:" msgstr "La clase del evento en sí se podría ver como esto:" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Constants" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Properties" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md ../src/en/internals/017-tags.md -#: ../src/en/internals/018-widgets.md +#: ../src/internals/010-code-style.md ../src/internals/017-tags.md +#: ../src/internals/018-widgets.md #, no-wrap msgid "Methods" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Within each category, items should be sorted by visibility:" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "public" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "protected" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "private" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Abstract classes" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Abstract classes *shouldn't* be prefixed or postfixed with `Abstract`." msgstr "" #. type: Title #### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Immutable methods" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, fuzzy #| msgid "You can attach a handler to an event like the following:" msgid "Immutable method convention is the following:" msgstr "Puedes acoplar un gestor a un evento como se demuestra a continuación:" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "public function withName(string $name): self\n" @@ -327,28 +327,28 @@ msgid "" msgstr "" #. type: Bullet: '1. ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Cloned object name is `$new`." msgstr "" #. type: Bullet: '2. ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Return type is `self`." msgstr "" #. type: Title #### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Boolean check methods" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Methods that are there to check if something is true should be named like the following:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "public function isDeleted(): bool;\n" @@ -357,29 +357,29 @@ msgid "" msgstr "" #. type: Title #### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Flags in methods " msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Boolean flags in methods are better to be avoided. It's a sign the method may be doing too much, and there should be two methods instead of one." msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "public function login(bool $refreshPage = true): void;\n" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "It is better to be two methods:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "public function login(): void;\n" @@ -387,18 +387,18 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Variables" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Add an underscore (`_`) prefix for unused variables. For example:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "foreach ($items as $key => $_value) {\n" @@ -407,18 +407,18 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Imports" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Prefer importing classes and functions to using fully qualified names:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "use Yiisoft\\Arrays\\ArrayHelper;\n" @@ -430,24 +430,24 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Additional conventions" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[Namespaces](004-namespaces.md)" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, fuzzy #| msgid "[Actions](structure/action.md) +" msgid "[Exceptions](007-exceptions.md)" msgstr "[Acciones](structure/action.md)" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[Interfaces](008-interfaces.md)" msgstr "" diff --git a/_translations/po/id/guide_databases_db-migrations.md.po b/_translations/po/id/guide_databases_db-migrations.md.po index cc0892f..bb6bd07 100644 --- a/_translations/po/id/guide_databases_db-migrations.md.po +++ b/_translations/po/id/guide_databases_db-migrations.md.po @@ -6,7 +6,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2025-12-27 07:40+0000\n" +"POT-Creation-Date: 2025-12-27 10:28+0000\n" "PO-Revision-Date: 2025-09-04 11:19+0500\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -21,26 +21,205 @@ msgstr "" msgid "Migrations" msgstr "" +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "During the course of developing and maintaining a database-driven application, the structure of the database being used evolves just like the source code does. For example, during the development of an application, a new table may be found necessary; after the application is deployed to production, it may be discovered that an index should be created to improve the query performance; and so on. Because a database structure change often requires some source code changes, Yii supports the so-called *database migration* feature that allows you to keep track of database changes in terms of *database migrations* which are version-controlled together with the source code." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "The following steps show how database migration can be used by a team during development:" +msgstr "" + +#. type: Bullet: '1. ' +#: ../src/guide/databases/db-migrations.md +msgid "Tim creates a new migration (e.g. creates a new table, changes a column definition, etc.)." +msgstr "" + +#. type: Bullet: '2. ' +#: ../src/guide/databases/db-migrations.md +msgid "Tim commits the new migration into the source control system (e.g. Git, Mercurial)." +msgstr "" + +#. type: Bullet: '3. ' +#: ../src/guide/databases/db-migrations.md +msgid "Doug updates his repository from the source control system and receives the new migration." +msgstr "" + +#. type: Bullet: '4. ' +#: ../src/guide/databases/db-migrations.md +msgid "Doug applies the migration to his local development database, thereby synchronizing his database to reflect the changes that Tim has made." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "And the following steps show how to deploy a new release with database migrations to production:" +msgstr "" + +#. type: Bullet: '1. ' +#: ../src/guide/databases/db-migrations.md +msgid "Scott creates a release tag for the project repository that contains some new database migrations." +msgstr "" + +#. type: Bullet: '2. ' +#: ../src/guide/databases/db-migrations.md +msgid "Scott updates the source code on the production server to the release tag." +msgstr "" + +#. type: Bullet: '3. ' +#: ../src/guide/databases/db-migrations.md +msgid "Scott applies any accumulated database migrations to the production database." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Yii provides a set of migration command line tools that allow you to:" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "create new migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "apply migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "revert migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "re-apply migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "show migration history and status." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "All these tools are accessible through the command `yii migrate`. In this section we will describe in detail how to accomplish various tasks using these tools." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> [!TIP]\n" +"> Migrations could affect not only database schema but adjust existing data to fit new schema, create RBAC\n" +"hierarchy or clean up cache.\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> [!NOTE]\n" +"> When manipulating data using a migration you may find that using your Active Record or entity classes\n" +"> for this might be useful because some of the logic is already implemented there. Keep in mind however, that in contrast\n" +"> to code written in the migrations, whose nature is to stay constant forever, application logic is subject to change.\n" +"> So when using Active Record or entity classes in migration code, changes to the logic in the source code\n" +"> may accidentally break the existing migrations. For this reason migration code should be kept independent of other\n" +"> application logic such.\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Container configuration" +msgid "Initial configuration" +msgstr "Konfigurasi container" + #. type: Plain text #: ../src/guide/databases/db-migrations.md msgid "To use migrations, install [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package:" msgstr "" -#. type: Fenced code block (shell) +#. type: Fenced code block (sh) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, fuzzy, no-wrap +msgid "make composer require yiisoft/db-migration\n" +msgstr "composer require yiisoft/cache\n" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Create a directory to store migrations `src/Migration` right in the project root." +msgstr "" + +#. type: Plain text #: ../src/guide/databases/db-migrations.md +msgid "Add the following configuration to `config/common/params.php`:" +msgstr "" + +#. type: Fenced code block (php) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md #, no-wrap -msgid "composer require yiisoft/db-migration\n" +msgid "" +"'yiisoft/db-migration' => [\n" +" 'newMigrationNamespace' => 'App\\\\Migration',\n" +" 'sourceNamespaces' => ['App\\\\Migration'],\n" +"],\n" msgstr "" -#. type: Title ### +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "If you want to place migrations elsewhere, you can define the path in `newMigrationPath`. If your migrations to be applied are from multiple sources, such as external modules, `sourcePaths` could be used to define these." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "You need a database connection configured as well. See [Working with databases](../start/databases.md) for an example of configuring it for PostgreSQL." +msgstr "" + +#. type: Title ## #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "Example usage" +msgid "Creating a migration" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "To create a new empty migration, run the following command:" +msgstr "" + +#. type: Fenced code block (sh) +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"make shell\n" +"./yii migrate:create \n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "The required `name` argument gives a brief description about the new migration. For example, if the migration is about creating a new table named *news*, you may use the name `create_news_table` and run the following command:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"make shell\n" +"./yii migrate:create create_news_table\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> [!NOTE]\n" +"> Because the `name` argument will be used as part of the generated migration class name,\n" +"> it should only contain letters, digits, and/or underscore characters.\n" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "First, configure a DI container. Create `config/common/db.php` with the following content:" +msgid "The above command will create a new PHP class file named `src/Migration/M251225221906CreateNewsTable.php`. The file contains the following code which mainly declares a migration class with the skeleton code:" msgstr "" #. type: Fenced code block (php) @@ -51,62 +230,460 @@ msgid "" "\n" "declare(strict_types=1);\n" "\n" -"use Yiisoft\\Db\\Connection\\ConnectionInterface;\n" -"use Yiisoft\\Db\\Sqlite\\Connection as SqliteConnection;\n" +"namespace App\\Migration;\n" +"\n" +"use Yiisoft\\Db\\Migration\\MigrationBuilder;\n" +"use Yiisoft\\Db\\Migration\\RevertibleMigrationInterface;\n" "\n" -"return [\n" -" ConnectionInterface::class => [\n" -" 'class' => SqliteConnection::class,\n" -" '__construct()' => [\n" -" 'dsn' => 'sqlite:' . __DIR__ . '/Data/yiitest.sq3'\n" -" ]\n" -" ]\n" -"];\n" +"final class M251225221906CreateNewsTable implements RevertibleMigrationInterface\n" +"{\n" +" public function up(MigrationBuilder $b): void\n" +" {\n" +" // TODO: Implement the logic to apply the migration.\n" +" }\n" +"\n" +" public function down(MigrationBuilder $b): void\n" +" {\n" +" // TODO: Implement the logic to revert the migration.\n" +" }\n" +"}\n" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "Add the following to `config/params.php`:" +msgid "In the migration class, you are expected to write code in the `up()` method that makes changes to the database structure. You may also want to write code in the `down()` method to revert the changes made by `up()`. The `up()` method is invoked when you upgrade the database with this migration, while the `down()` method is invoked when you downgrade the database. The following code shows how you may implement the migration class to create a `news` table:" msgstr "" #. type: Fenced code block (php) #: ../src/guide/databases/db-migrations.md #, no-wrap msgid "" -"...\n" -"'yiisoft/db-migration' => [\n" -" 'newMigrationNamespace' => 'App\\\\Migration',\n" -" 'sourceNamespaces' => ['App\\\\Migration'],\n" -"],\n" -"...\n" +"columnBuilder();\n" +"\n" +" $b->createTable('news', [\n" +" 'id' => $cb::uuidPrimaryKey(),\n" +" 'title' => $cb::string()->notNull(),\n" +" 'content' => $cb::text(),\n" +" ]);\n" +" }\n" +"\n" +" public function down(MigrationBuilder $b): void\n" +" {\n" +" $b->dropTable('news');\n" +" }\n" +"}\n" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "Now test if it works:" +msgid "Migration builder `$b` in the above manages database schema while the column builder `$cb` manages column types. Both allow using *abstract types*. When a migration is applied to a particular database, the abstract types will be translated into the corresponding database physical types and corresponding SQL to define them." msgstr "" -#. type: Fenced code block (shell) +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Methods available in migration builder belong to the following types:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Raw queries" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "getDb — to get database connection instance." +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "execute — to execute raw SQL query." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Data" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "insert / update / delete" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "batchInsert" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "upsert" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Tables and views" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "createTable / renameTable / dropTable" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "truncateTable" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addCommentOnTable / dropCommentFromTable" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "createView / dropView" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Columns" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addColumn / renameColumn / alterColumn / dropColumn" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addCommentOnColumn / dropCommentFromColumn" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Keys and indexes" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addPrimaryKey / dropPrimaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addForeignKey / dropForeignKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "createIndex / dropIndex" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Additionally, there's a `columnBuilder()` which is used to obtain a column builder as in example above. The builder has static methods that define various column types:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Keys" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "primaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "smallPrimaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "bigPrimaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "uuidPrimaryKey" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Boolean" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "boolean" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Numbers" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "bit" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "tinyint" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "smallint" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "integer" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "bigint" +msgstr "" + +#. type: Bullet: ' - ' #: ../src/guide/databases/db-migrations.md +msgid "flat" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "double" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "decimal" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md ../src/internals/010-code-style.md #, no-wrap -msgid "./yii list migrate\n" +msgid "Strings" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "char" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "string" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "text" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Date and time" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "timestamp" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "datetime" msgstr "" +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "datetimeWithTimezone" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "time" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "timeWithTimezone" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "date" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Special types" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "money" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "binary" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "uuid" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "array" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "structured" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "json" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "enum" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "All the above methods create a base type which could be adjusted with additional methods:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "null / notNull" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "defaultValue" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "unique" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "scale / size / unsigned" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "primaryKey / autoIncrement" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "check" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "comment" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "computed" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "extra" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +#, fuzzy +#| msgid "References" +msgid "reference" +msgstr "Referensi" + #. type: Title ### #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "Creating a migration" +msgid "Irreversible migrations" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "To work with migrations, you can use the provided [view](https://github.com/yiisoft/db-migration/tree/master/resources/views)." +msgid "Not all migrations are reversible. For example, if the `up()` method deletes a row of a table, you may not be able to recover this row in the `down()` method. Sometimes, you may be just too lazy to implement the `down()`, because it is not very common to revert database migrations. In this case, you should implement `Yiisoft\\Db\\Migration\\MigrationInterface` that has `up()` only." +msgstr "" + +#. type: Title ### +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Container configuration" +msgid "Transactional migrations" +msgstr "Konfigurasi container" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "While performing complex DB migrations, it is important to ensure each migration to either succeed or fail as a whole so that the database can maintain integrity and consistency. To achieve this goal, it is recommended that you may enclose the DB operations of each migration in a transaction automatically by adding `TransactionalMigrationInterface` to `implements` of your migration." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "As a result, if any operation in the `up()` or `down()` method fails, all prior operations will be rolled back automatically." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> Note: Not all DBMS support transactions. And some DB queries cannot be put into a transaction. For some examples,\n" +"please refer to [implicit commit](https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html).\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Generating API documentation" +msgid "Generating a migration" +msgstr "Membuat Dokumentasi API" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Instead of writing migrations by hand, the command provides a convenient way generate some of the code." msgstr "" #. type: Fenced code block (shell) #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "./yii migrate:create my_first_table --command=table --fields=name,example --table-comment=my_first_table\n" +msgid "" +"make shell\n" +"./yii migrate:create -- my_first_table --command=table --fields=name,example --table-comment=my_first_table\n" msgstr "" #. type: Plain text @@ -129,19 +706,21 @@ msgid "" "use Yiisoft\\Db\\Migration\\TransactionalMigrationInterface;\n" "\n" "/**\n" -" * Handles the creation of a table `my_first_table`.\n" +" * Handles the creation of table `my_first_table`.\n" " */\n" -"final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface\n" +"final class M251227095006CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface\n" "{\n" " public function up(MigrationBuilder $b): void\n" " {\n" +" $columnBuilder = $b->columnBuilder();\n" +"\n" " $b->createTable('my_first_table', [\n" -" 'id' => $b->primaryKey(),\n" +" 'id' => $columnBuilder::primaryKey(),\n" " 'name',\n" " 'example',\n" " ]);\n" -" \n" -" $b->addCommentOnTable('my_first_table', 'dest');\n" +"\n" +" $b->addCommentOnTable('my_first_table', 'my_first_table');\n" " }\n" "\n" " public function down(MigrationBuilder $b): void\n" @@ -153,7 +732,157 @@ msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "For more information [see](https://github.com/yiisoft/db-migration/tree/master/docs/guide/en)" +msgid "Commands available are:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "create - empty migration." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "table - creating a table. Use `--fields` specify a list of fields to use. Types could be specified as well such as `id:primaryKey,name:string:defaultValue(\"Alex\"),user_id:integer:foreignKey,category_id2:integer:foreignKey(category id2)`." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "dropTable - dropping a table." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "addColumn - adding a column." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "dropColumn - dropping a column." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "junction - creating a junction table. Use `--and` specify a second table." +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Configuration" +msgid "Applying Migrations" +msgstr "Konfigurasi" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "To upgrade a database to its latest structure, you should apply all available new migrations using the following command:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "./yii migrate:up\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "This command will list all migrations that have not been applied so far. If you confirm that you want to apply these migrations, it will run the `up()` method in every new migration class, one after another, in the order of their timestamp values. If any of the migrations fails, the command will quit without applying the rest of the migrations." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "For each migration that has been successfully applied, the command will insert a row into a database table named `migration` to record the successful application of the migration. This will allow the migration tool to identify which migrations have been applied and which have not." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Sometimes, you may only want to apply one or a few new migrations, instead of all available migrations. You can do so by specifying the number of migrations that you want to apply when running the command. For example, the following command will try to apply the next three available migrations:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "./yii migrate:up --limit=3\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Resolving aliases " +msgid "Reverting Migrations " +msgstr "Me-resolve alias " + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "To revert (undo) one or multiple migrations that have been applied before, you can run the following command:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"./yii migrate:down # revert the most recently applied migration\n" +"./yii migrate:down --limit=3 # revert the most 3 recently applied migrations\n" +"./yii migrate:down --all # revert all migrations\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> Note: Not all migrations are reversible. Trying to revert such migrations will cause an error and stop the\n" +"entire reverting process.\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Resolving aliases " +msgid "Redoing Migrations " +msgstr "Me-resolve alias " + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Redoing migrations means first reverting the specified migrations and then applying again. This can be done as follows:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"./yii migrate:redo # redo the last applied migration\n" +"./yii migrate:redo --limit=3 # redo the last 3 applied migrations\n" +"./yii migrate:redo --all # redo all migrations\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "> Note: If a migration is not reversible, you will not be able to redo it.\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Using aliases in configuration " +msgid "Listing Migrations " +msgstr "Menggunakan aliases di konfigurasi " + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "To list which migrations have been applied and which are not, you may use the following commands:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"./yii migrate/history # showing the last 10 applied migrations\n" +"./yii migrate:history --limit=5 # showing the last 5 applied migrations\n" +"./yii migrate:history --all # showing all applied migrations\n" +"\n" +"./yii migrate:new # showing the first 10 new migrations\n" +"./yii migrate:new --limit=5 # showing the first 5 new migrations\n" +"./yii migrate:new --all # showing all new migrations\n" msgstr "" #. type: Title ### @@ -164,5 +893,10 @@ msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "Migrations in Yii 2.0 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 further changes in the database schema are applied using the new `migration` component and recorded in the new migration table." +msgid "Migrations in Yii 2.0 and the [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package are not compatible, and the `migration` table is also not compatible." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "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 further changes in the database schema are applied using the new `migration` component and recorded in the new migration table." msgstr "" diff --git a/_translations/po/id/guide_start_databases.md.po b/_translations/po/id/guide_start_databases.md.po index 079b162..e08047e 100644 --- a/_translations/po/id/guide_start_databases.md.po +++ b/_translations/po/id/guide_start_databases.md.po @@ -6,7 +6,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2025-12-27 06:04+0000\n" +"POT-Creation-Date: 2025-12-27 06:16+0000\n" "PO-Revision-Date: 2025-09-04 11:19+0500\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -15,6 +15,22 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" +#. type: Fenced code block (sh) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, fuzzy, no-wrap +msgid "make composer require yiisoft/db-migration\n" +msgstr "composer require yiisoft/cache\n" + +#. type: Fenced code block (php) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, no-wrap +msgid "" +"'yiisoft/db-migration' => [\n" +" 'newMigrationNamespace' => 'App\\\\Migration',\n" +" 'sourceNamespaces' => ['App\\\\Migration'],\n" +"],\n" +msgstr "" + #. type: Title # #: ../src/guide/index.md ../src/guide/start/databases.md #, no-wrap @@ -252,28 +268,11 @@ msgstr "" msgid "To use migrations we need another package installed:" msgstr "" -#. type: Fenced code block (sh) -#: ../src/guide/start/databases.md -#, fuzzy, no-wrap -#| msgid "composer require yiisoft/cache\n" -msgid "make composer require yiisoft/db-migration\n" -msgstr "composer require yiisoft/cache\n" - #. type: Plain text #: ../src/guide/start/databases.md msgid "Create a directory to store migrations `src/Migration` right in the project root. Add the following configuration to `config/common/params.php`:" msgstr "" -#. type: Fenced code block (php) -#: ../src/guide/start/databases.md -#, no-wrap -msgid "" -"'yiisoft/db-migration' => [\n" -" 'newMigrationNamespace' => 'App\\\\Migration',\n" -" 'sourceNamespaces' => ['App\\\\Migration'],\n" -"],\n" -msgstr "" - #. type: Plain text #: ../src/guide/start/databases.md msgid "Now you can use `make yii migrate:create page` to create a new migration. For our example we need a `page` table with some columns:" diff --git a/_translations/po/id/internals_010-code-style.md.po b/_translations/po/id/internals_010-code-style.md.po index e5879f6..983b975 100644 --- a/_translations/po/id/internals_010-code-style.md.po +++ b/_translations/po/id/internals_010-code-style.md.po @@ -6,7 +6,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2025-12-24 08:02+0000\n" +"POT-Creation-Date: 2025-12-27 10:28+0000\n" "PO-Revision-Date: 2025-12-24 08:02+0000\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -15,117 +15,123 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" +#. type: Title ## +#: ../src/guide/databases/db-migrations.md ../src/internals/010-code-style.md +#, no-wrap +msgid "Strings" +msgstr "" + #. type: Title # -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "010 — Code style" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Code formatting used in Yii 3 packages is based on [PSR-1](https://www.php-fig.org/psr/psr-1/) and [PSR-12](https://www.php-fig.org/psr/psr-12/) with extra rules added on top of it." msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md ../src/en/internals/017-tags.md -#: ../src/en/internals/018-widgets.md +#: ../src/internals/010-code-style.md ../src/internals/017-tags.md +#: ../src/internals/018-widgets.md #, no-wrap msgid "Names" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use English only." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use camelCase notation, including abbreviations (e.g., `enableIdn`)." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use the shortest possible, but an explanatory name." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Never trim or abbreviate a name." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Postfix classes, interfaces, traits and variables, which is a [collection](https://en.wikipedia.org/wiki/Collection_(abstract_data_type)), with `Collection`." msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Types" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Declare [argument and return types](https://www.php.net/manual/en/migration70.new-features.php) where possible." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[Use types for properties](https://wiki.php.net/rfc/typed_properties_v2)." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use strict typing. Avoid mixed and union types where possible except compatible types such as `string|Stringable`." msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Comments" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Inline comments are to be avoided unless code couldn't be understood without them. A good example is a workaround for a bug in a certain PHP version." msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Method comment is necessary except it adds nothing to what method name and signature already has." msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Class comment should describe the purpose of the class." msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, fuzzy #| msgid "[Validating input](https://github.com/yiisoft/validator/blob/master/docs/guide/en/README.md) +" msgid "[See PHPDoc](https://github.com/yiisoft/docs/blob/master/014-docs.md#phpdoc)." msgstr "[Memvalidasi Input](https://github.com/yiisoft/validator/blob/master/docs/guide/en/README.md) +" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Formatting" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "No alignment" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Property, variable and constant value assignments shouldn't be aligned. The same applies to phpdoc tags. The reason is that aligned statements often cause larger diff and even conflicts." msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "final class X\n" @@ -149,18 +155,18 @@ msgid "" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Chain calls" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Chained calls should be formatted for better readability. If it's a long chain that doesn't fit the line length of 120 characters, then each call should on a new line:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "$object\n" @@ -172,145 +178,139 @@ msgid "" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "If it's a short chain, it's alright for it to be on a single line:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "$object = $object->withName('test');\n" msgstr "" -#. type: Title ## -#: ../src/en/internals/010-code-style.md -#, no-wrap -msgid "Strings" -msgstr "" - #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "When no variables involved, use `'Hello!'`" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "To get variables into string prefer `\"Hello, $username!\"`" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Classes and interfaces" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Final by default" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Classes should be `final` by default." msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Private by default" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Constants, properties and methods should be private by default." msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Composition over inheritance" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, fuzzy #| msgid "[Dependency injection container](concept/di-container.md) +" msgid "Prefer [composition to inheritance](guide/en/concept/di-container.md)." msgstr "[Dependency Injection Container](concept/di-container.md) +" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Property, constant and method order" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Order should be the following:" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Constants" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Properties" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md ../src/en/internals/017-tags.md -#: ../src/en/internals/018-widgets.md +#: ../src/internals/010-code-style.md ../src/internals/017-tags.md +#: ../src/internals/018-widgets.md #, no-wrap msgid "Methods" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Within each category, items should be sorted by visibility:" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "public" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "protected" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "private" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Abstract classes" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Abstract classes *shouldn't* be prefixed or postfixed with `Abstract`." msgstr "" #. type: Title #### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Immutable methods" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Immutable method convention is the following:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "public function withName(string $name): self\n" @@ -322,28 +322,28 @@ msgid "" msgstr "" #. type: Bullet: '1. ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Cloned object name is `$new`." msgstr "" #. type: Bullet: '2. ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Return type is `self`." msgstr "" #. type: Title #### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Boolean check methods" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Methods that are there to check if something is true should be named like the following:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "public function isDeleted(): bool;\n" @@ -352,29 +352,29 @@ msgid "" msgstr "" #. type: Title #### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Flags in methods " msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Boolean flags in methods are better to be avoided. It's a sign the method may be doing too much, and there should be two methods instead of one." msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "public function login(bool $refreshPage = true): void;\n" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "It is better to be two methods:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "public function login(): void;\n" @@ -382,18 +382,18 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Variables" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Add an underscore (`_`) prefix for unused variables. For example:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "foreach ($items as $key => $_value) {\n" @@ -402,18 +402,18 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Imports" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Prefer importing classes and functions to using fully qualified names:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "use Yiisoft\\Arrays\\ArrayHelper;\n" @@ -425,24 +425,24 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Additional conventions" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[Namespaces](004-namespaces.md)" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, fuzzy #| msgid "[Actions](structure/action.md) +" msgid "[Exceptions](007-exceptions.md)" msgstr "[Actions](structure/action.md) +" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[Interfaces](008-interfaces.md)" msgstr "" diff --git a/_translations/po/ru/guide_databases_db-migrations.md.po b/_translations/po/ru/guide_databases_db-migrations.md.po index e229880..8129095 100644 --- a/_translations/po/ru/guide_databases_db-migrations.md.po +++ b/_translations/po/ru/guide_databases_db-migrations.md.po @@ -6,7 +6,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2025-12-27 07:40+0000\n" +"POT-Creation-Date: 2025-12-27 10:28+0000\n" "PO-Revision-Date: 2025-09-04 11:19+0500\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -24,24 +24,210 @@ msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "To use migrations, install [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package:" +msgid "During the course of developing and maintaining a database-driven application, the structure of the database being used evolves just like the source code does. For example, during the development of an application, a new table may be found necessary; after the application is deployed to production, it may be discovered that an index should be created to improve the query performance; and so on. Because a database structure change often requires some source code changes, Yii supports the so-called *database migration* feature that allows you to keep track of database changes in terms of *database migrations* which are version-controlled together with the source code." msgstr "" -#. type: Fenced code block (shell) +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "The following steps show how database migration can be used by a team during development:" +msgstr "" + +#. type: Bullet: '1. ' +#: ../src/guide/databases/db-migrations.md +msgid "Tim creates a new migration (e.g. creates a new table, changes a column definition, etc.)." +msgstr "" + +#. type: Bullet: '2. ' +#: ../src/guide/databases/db-migrations.md +msgid "Tim commits the new migration into the source control system (e.g. Git, Mercurial)." +msgstr "" + +#. type: Bullet: '3. ' +#: ../src/guide/databases/db-migrations.md +msgid "Doug updates his repository from the source control system and receives the new migration." +msgstr "" + +#. type: Bullet: '4. ' +#: ../src/guide/databases/db-migrations.md +msgid "Doug applies the migration to his local development database, thereby synchronizing his database to reflect the changes that Tim has made." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "And the following steps show how to deploy a new release with database migrations to production:" +msgstr "" + +#. type: Bullet: '1. ' +#: ../src/guide/databases/db-migrations.md +msgid "Scott creates a release tag for the project repository that contains some new database migrations." +msgstr "" + +#. type: Bullet: '2. ' +#: ../src/guide/databases/db-migrations.md +msgid "Scott updates the source code on the production server to the release tag." +msgstr "" + +#. type: Bullet: '3. ' +#: ../src/guide/databases/db-migrations.md +msgid "Scott applies any accumulated database migrations to the production database." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Yii provides a set of migration command line tools that allow you to:" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +#, fuzzy +#| msgid "Sentry integration" +msgid "create new migrations;" +msgstr "Интеграция с Sentry" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "apply migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +#, fuzzy +#| msgid "Sentry integration" +msgid "revert migrations;" +msgstr "Интеграция с Sentry" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "re-apply migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "show migration history and status." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "All these tools are accessible through the command `yii migrate`. In this section we will describe in detail how to accomplish various tasks using these tools." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> [!TIP]\n" +"> Migrations could affect not only database schema but adjust existing data to fit new schema, create RBAC\n" +"hierarchy or clean up cache.\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> [!NOTE]\n" +"> When manipulating data using a migration you may find that using your Active Record or entity classes\n" +"> for this might be useful because some of the logic is already implemented there. Keep in mind however, that in contrast\n" +"> to code written in the migrations, whose nature is to stay constant forever, application logic is subject to change.\n" +"> So when using Active Record or entity classes in migration code, changes to the logic in the source code\n" +"> may accidentally break the existing migrations. For this reason migration code should be kept independent of other\n" +"> application logic such.\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +msgid "Initial configuration" +msgstr "Безопасная конфигурация сервера" + +#. type: Plain text #: ../src/guide/databases/db-migrations.md +msgid "To use migrations, install [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package:" +msgstr "" + +#. type: Fenced code block (sh) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md #, fuzzy, no-wrap -msgid "composer require yiisoft/db-migration\n" +msgid "make composer require yiisoft/db-migration\n" msgstr "composer install yiisoft/security\n" -#. type: Title ### +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Create a directory to store migrations `src/Migration` right in the project root." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, fuzzy +#| msgid "Add the following to your php.ini:" +msgid "Add the following configuration to `config/common/params.php`:" +msgstr "Добавьте в свой php.ini следующее:" + +#. type: Fenced code block (php) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, no-wrap +msgid "" +"'yiisoft/db-migration' => [\n" +" 'newMigrationNamespace' => 'App\\\\Migration',\n" +" 'sourceNamespaces' => ['App\\\\Migration'],\n" +"],\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "If you want to place migrations elsewhere, you can define the path in `newMigrationPath`. If your migrations to be applied are from multiple sources, such as external modules, `sourcePaths` could be used to define these." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "You need a database connection configured as well. See [Working with databases](../start/databases.md) for an example of configuring it for PostgreSQL." +msgstr "" + +#. type: Title ## #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "Example usage" +msgid "Creating a migration" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "First, configure a DI container. Create `config/common/db.php` with the following content:" +#, fuzzy +#| msgid "To install the packages, run the following command:" +msgid "To create a new empty migration, run the following command:" +msgstr "Для установки пакетов выполните в консоли следующую команду:" + +#. type: Fenced code block (sh) +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"make shell\n" +"./yii migrate:create \n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "The required `name` argument gives a brief description about the new migration. For example, if the migration is about creating a new table named *news*, you may use the name `create_news_table` and run the following command:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"make shell\n" +"./yii migrate:create create_news_table\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> [!NOTE]\n" +"> Because the `name` argument will be used as part of the generated migration class name,\n" +"> it should only contain letters, digits, and/or underscore characters.\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "The above command will create a new PHP class file named `src/Migration/M251225221906CreateNewsTable.php`. The file contains the following code which mainly declares a migration class with the skeleton code:" msgstr "" #. type: Fenced code block (php) @@ -52,64 +238,460 @@ msgid "" "\n" "declare(strict_types=1);\n" "\n" -"use Yiisoft\\Db\\Connection\\ConnectionInterface;\n" -"use Yiisoft\\Db\\Sqlite\\Connection as SqliteConnection;\n" +"namespace App\\Migration;\n" +"\n" +"use Yiisoft\\Db\\Migration\\MigrationBuilder;\n" +"use Yiisoft\\Db\\Migration\\RevertibleMigrationInterface;\n" +"\n" +"final class M251225221906CreateNewsTable implements RevertibleMigrationInterface\n" +"{\n" +" public function up(MigrationBuilder $b): void\n" +" {\n" +" // TODO: Implement the logic to apply the migration.\n" +" }\n" "\n" -"return [\n" -" ConnectionInterface::class => [\n" -" 'class' => SqliteConnection::class,\n" -" '__construct()' => [\n" -" 'dsn' => 'sqlite:' . __DIR__ . '/Data/yiitest.sq3'\n" -" ]\n" -" ]\n" -"];\n" +" public function down(MigrationBuilder $b): void\n" +" {\n" +" // TODO: Implement the logic to revert the migration.\n" +" }\n" +"}\n" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -#, fuzzy -#| msgid "Add the following to your php.ini:" -msgid "Add the following to `config/params.php`:" -msgstr "Добавьте в свой php.ini следующее:" +msgid "In the migration class, you are expected to write code in the `up()` method that makes changes to the database structure. You may also want to write code in the `down()` method to revert the changes made by `up()`. The `up()` method is invoked when you upgrade the database with this migration, while the `down()` method is invoked when you downgrade the database. The following code shows how you may implement the migration class to create a `news` table:" +msgstr "" #. type: Fenced code block (php) #: ../src/guide/databases/db-migrations.md #, no-wrap msgid "" -"...\n" -"'yiisoft/db-migration' => [\n" -" 'newMigrationNamespace' => 'App\\\\Migration',\n" -" 'sourceNamespaces' => ['App\\\\Migration'],\n" -"],\n" -"...\n" +"columnBuilder();\n" +"\n" +" $b->createTable('news', [\n" +" 'id' => $cb::uuidPrimaryKey(),\n" +" 'title' => $cb::string()->notNull(),\n" +" 'content' => $cb::text(),\n" +" ]);\n" +" }\n" +"\n" +" public function down(MigrationBuilder $b): void\n" +" {\n" +" $b->dropTable('news');\n" +" }\n" +"}\n" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "Now test if it works:" +msgid "Migration builder `$b` in the above manages database schema while the column builder `$cb` manages column types. Both allow using *abstract types*. When a migration is applied to a particular database, the abstract types will be translated into the corresponding database physical types and corresponding SQL to define them." msgstr "" -#. type: Fenced code block (shell) +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Methods available in migration builder belong to the following types:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Raw queries" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "getDb — to get database connection instance." +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "execute — to execute raw SQL query." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Data" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "insert / update / delete" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "batchInsert" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "upsert" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Tables and views" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "createTable / renameTable / dropTable" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "truncateTable" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addCommentOnTable / dropCommentFromTable" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "createView / dropView" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Columns" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addColumn / renameColumn / alterColumn / dropColumn" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addCommentOnColumn / dropCommentFromColumn" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Keys and indexes" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addPrimaryKey / dropPrimaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addForeignKey / dropForeignKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "createIndex / dropIndex" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Additionally, there's a `columnBuilder()` which is used to obtain a column builder as in example above. The builder has static methods that define various column types:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Keys" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "primaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "smallPrimaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "bigPrimaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "uuidPrimaryKey" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Boolean" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "boolean" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Numbers" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "bit" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "tinyint" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "smallint" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "integer" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "bigint" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "flat" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "double" +msgstr "" + +#. type: Bullet: ' - ' #: ../src/guide/databases/db-migrations.md +msgid "decimal" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md ../src/internals/010-code-style.md #, no-wrap -msgid "./yii list migrate\n" +msgid "Strings" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "char" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "string" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "text" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Date and time" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "timestamp" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "datetime" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "datetimeWithTimezone" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "time" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "timeWithTimezone" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "date" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Special types" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "money" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "binary" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "uuid" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "array" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "structured" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "json" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "enum" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "All the above methods create a base type which could be adjusted with additional methods:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "null / notNull" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "defaultValue" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "unique" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "scale / size / unsigned" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "primaryKey / autoIncrement" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "check" msgstr "" +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "comment" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "computed" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "extra" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +#, fuzzy +#| msgid "References" +msgid "reference" +msgstr "Ссылки" + #. type: Title ### #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "Creating a migration" +msgid "Irreversible migrations" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "To work with migrations, you can use the provided [view](https://github.com/yiisoft/db-migration/tree/master/resources/views)." +msgid "Not all migrations are reversible. For example, if the `up()` method deletes a row of a table, you may not be able to recover this row in the `down()` method. Sometimes, you may be just too lazy to implement the `down()`, because it is not very common to revert database migrations. In this case, you should implement `Yiisoft\\Db\\Migration\\MigrationInterface` that has `up()` only." +msgstr "" + +#. type: Title ### +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Sentry integration" +msgid "Transactional migrations" +msgstr "Интеграция с Sentry" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "While performing complex DB migrations, it is important to ensure each migration to either succeed or fail as a whole so that the database can maintain integrity and consistency. To achieve this goal, it is recommended that you may enclose the DB operations of each migration in a transaction automatically by adding `TransactionalMigrationInterface` to `implements` of your migration." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "As a result, if any operation in the `up()` or `down()` method fails, all prior operations will be rolled back automatically." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> Note: Not all DBMS support transactions. And some DB queries cannot be put into a transaction. For some examples,\n" +"please refer to [implicit commit](https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html).\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Practice-orientation." +msgid "Generating a migration" +msgstr "Практикоориентированность." + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Instead of writing migrations by hand, the command provides a convenient way generate some of the code." msgstr "" #. type: Fenced code block (shell) #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "./yii migrate:create my_first_table --command=table --fields=name,example --table-comment=my_first_table\n" +msgid "" +"make shell\n" +"./yii migrate:create -- my_first_table --command=table --fields=name,example --table-comment=my_first_table\n" msgstr "" #. type: Plain text @@ -134,19 +716,21 @@ msgid "" "use Yiisoft\\Db\\Migration\\TransactionalMigrationInterface;\n" "\n" "/**\n" -" * Handles the creation of a table `my_first_table`.\n" +" * Handles the creation of table `my_first_table`.\n" " */\n" -"final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface\n" +"final class M251227095006CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface\n" "{\n" " public function up(MigrationBuilder $b): void\n" " {\n" +" $columnBuilder = $b->columnBuilder();\n" +"\n" " $b->createTable('my_first_table', [\n" -" 'id' => $b->primaryKey(),\n" +" 'id' => $columnBuilder::primaryKey(),\n" " 'name',\n" " 'example',\n" " ]);\n" -" \n" -" $b->addCommentOnTable('my_first_table', 'dest');\n" +"\n" +" $b->addCommentOnTable('my_first_table', 'my_first_table');\n" " }\n" "\n" " public function down(MigrationBuilder $b): void\n" @@ -158,7 +742,159 @@ msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "For more information [see](https://github.com/yiisoft/db-migration/tree/master/docs/guide/en)" +msgid "Commands available are:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +#, fuzzy +#| msgid "Sentry integration" +msgid "create - empty migration." +msgstr "Интеграция с Sentry" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "table - creating a table. Use `--fields` specify a list of fields to use. Types could be specified as well such as `id:primaryKey,name:string:defaultValue(\"Alex\"),user_id:integer:foreignKey,category_id2:integer:foreignKey(category id2)`." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "dropTable - dropping a table." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "addColumn - adding a column." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "dropColumn - dropping a column." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "junction - creating a junction table. Use `--and` specify a second table." +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Configuration" +msgid "Applying Migrations" +msgstr "Настройка" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "To upgrade a database to its latest structure, you should apply all available new migrations using the following command:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "./yii migrate:up\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "This command will list all migrations that have not been applied so far. If you confirm that you want to apply these migrations, it will run the `up()` method in every new migration class, one after another, in the order of their timestamp values. If any of the migrations fails, the command will quit without applying the rest of the migrations." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "For each migration that has been successfully applied, the command will insert a row into a database table named `migration` to record the successful application of the migration. This will allow the migration tool to identify which migrations have been applied and which have not." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Sometimes, you may only want to apply one or a few new migrations, instead of all available migrations. You can do so by specifying the number of migrations that you want to apply when running the command. For example, the following command will try to apply the next three available migrations:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "./yii migrate:up --limit=3\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Defining aliases " +msgid "Reverting Migrations " +msgstr "Определение псевдонимов " + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "To revert (undo) one or multiple migrations that have been applied before, you can run the following command:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"./yii migrate:down # revert the most recently applied migration\n" +"./yii migrate:down --limit=3 # revert the most 3 recently applied migrations\n" +"./yii migrate:down --all # revert all migrations\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> Note: Not all migrations are reversible. Trying to revert such migrations will cause an error and stop the\n" +"entire reverting process.\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Resolving aliases " +msgid "Redoing Migrations " +msgstr "Разрешение псевдонимов " + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Redoing migrations means first reverting the specified migrations and then applying again. This can be done as follows:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"./yii migrate:redo # redo the last applied migration\n" +"./yii migrate:redo --limit=3 # redo the last 3 applied migrations\n" +"./yii migrate:redo --all # redo all migrations\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "> Note: If a migration is not reversible, you will not be able to redo it.\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, fuzzy, no-wrap +#| msgid "Resolving aliases " +msgid "Listing Migrations " +msgstr "Разрешение псевдонимов " + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "To list which migrations have been applied and which are not, you may use the following commands:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"./yii migrate/history # showing the last 10 applied migrations\n" +"./yii migrate:history --limit=5 # showing the last 5 applied migrations\n" +"./yii migrate:history --all # showing all applied migrations\n" +"\n" +"./yii migrate:new # showing the first 10 new migrations\n" +"./yii migrate:new --limit=5 # showing the first 5 new migrations\n" +"./yii migrate:new --all # showing all new migrations\n" msgstr "" #. type: Title ### @@ -169,5 +905,10 @@ msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "Migrations in Yii 2.0 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 further changes in the database schema are applied using the new `migration` component and recorded in the new migration table." +msgid "Migrations in Yii 2.0 and the [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package are not compatible, and the `migration` table is also not compatible." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "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 further changes in the database schema are applied using the new `migration` component and recorded in the new migration table." msgstr "" diff --git a/_translations/po/ru/guide_start_databases.md.po b/_translations/po/ru/guide_start_databases.md.po index b2d8a53..0ec59a3 100644 --- a/_translations/po/ru/guide_start_databases.md.po +++ b/_translations/po/ru/guide_start_databases.md.po @@ -6,7 +6,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2025-12-27 06:04+0000\n" +"POT-Creation-Date: 2025-12-27 06:16+0000\n" "PO-Revision-Date: 2025-09-04 11:19+0500\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -16,6 +16,22 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n" +#. type: Fenced code block (sh) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, fuzzy, no-wrap +msgid "make composer require yiisoft/db-migration\n" +msgstr "composer install yiisoft/security\n" + +#. type: Fenced code block (php) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, no-wrap +msgid "" +"'yiisoft/db-migration' => [\n" +" 'newMigrationNamespace' => 'App\\\\Migration',\n" +" 'sourceNamespaces' => ['App\\\\Migration'],\n" +"],\n" +msgstr "" + #. type: Title # #: ../src/guide/index.md ../src/guide/start/databases.md #, no-wrap @@ -256,27 +272,11 @@ msgstr "" msgid "To use migrations we need another package installed:" msgstr "" -#. type: Fenced code block (sh) -#: ../src/guide/start/databases.md -#, fuzzy, no-wrap -msgid "make composer require yiisoft/db-migration\n" -msgstr "composer install yiisoft/security\n" - #. type: Plain text #: ../src/guide/start/databases.md msgid "Create a directory to store migrations `src/Migration` right in the project root. Add the following configuration to `config/common/params.php`:" msgstr "" -#. type: Fenced code block (php) -#: ../src/guide/start/databases.md -#, no-wrap -msgid "" -"'yiisoft/db-migration' => [\n" -" 'newMigrationNamespace' => 'App\\\\Migration',\n" -" 'sourceNamespaces' => ['App\\\\Migration'],\n" -"],\n" -msgstr "" - #. type: Plain text #: ../src/guide/start/databases.md msgid "Now you can use `make yii migrate:create page` to create a new migration. For our example we need a `page` table with some columns:" diff --git a/_translations/po/ru/internals_010-code-style.md.po b/_translations/po/ru/internals_010-code-style.md.po index fdc7cb4..676db98 100644 --- a/_translations/po/ru/internals_010-code-style.md.po +++ b/_translations/po/ru/internals_010-code-style.md.po @@ -6,7 +6,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2025-12-24 08:02+0000\n" +"POT-Creation-Date: 2025-12-27 10:28+0000\n" "PO-Revision-Date: 2025-12-24 08:02+0000\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -16,115 +16,121 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n" +#. type: Title ## +#: ../src/guide/databases/db-migrations.md ../src/internals/010-code-style.md +#, no-wrap +msgid "Strings" +msgstr "" + #. type: Title # -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "010 — Code style" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Code formatting used in Yii 3 packages is based on [PSR-1](https://www.php-fig.org/psr/psr-1/) and [PSR-12](https://www.php-fig.org/psr/psr-12/) with extra rules added on top of it." msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md ../src/en/internals/017-tags.md -#: ../src/en/internals/018-widgets.md +#: ../src/internals/010-code-style.md ../src/internals/017-tags.md +#: ../src/internals/018-widgets.md #, no-wrap msgid "Names" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use English only." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use camelCase notation, including abbreviations (e.g., `enableIdn`)." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use the shortest possible, but an explanatory name." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Never trim or abbreviate a name." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Postfix classes, interfaces, traits and variables, which is a [collection](https://en.wikipedia.org/wiki/Collection_(abstract_data_type)), with `Collection`." msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Types" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Declare [argument and return types](https://www.php.net/manual/en/migration70.new-features.php) where possible." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[Use types for properties](https://wiki.php.net/rfc/typed_properties_v2)." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use strict typing. Avoid mixed and union types where possible except compatible types such as `string|Stringable`." msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Comments" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Inline comments are to be avoided unless code couldn't be understood without them. A good example is a workaround for a bug in a certain PHP version." msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Method comment is necessary except it adds nothing to what method name and signature already has." msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Class comment should describe the purpose of the class." msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[See PHPDoc](https://github.com/yiisoft/docs/blob/master/014-docs.md#phpdoc)." msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Formatting" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "No alignment" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Property, variable and constant value assignments shouldn't be aligned. The same applies to phpdoc tags. The reason is that aligned statements often cause larger diff and even conflicts." msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "final class X\n" @@ -148,18 +154,18 @@ msgid "" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Chain calls" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Chained calls should be formatted for better readability. If it's a long chain that doesn't fit the line length of 120 characters, then each call should on a new line:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "$object\n" @@ -171,149 +177,143 @@ msgid "" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "If it's a short chain, it's alright for it to be on a single line:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "$object = $object->withName('test');\n" msgstr "" -#. type: Title ## -#: ../src/en/internals/010-code-style.md -#, no-wrap -msgid "Strings" -msgstr "" - #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "When no variables involved, use `'Hello!'`" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "To get variables into string prefer `\"Hello, $username!\"`" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Classes and interfaces" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Final by default" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Classes should be `final` by default." msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Private by default" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Constants, properties and methods should be private by default." msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Composition over inheritance" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, fuzzy #| msgid "Dependency injection and container" msgid "Prefer [composition to inheritance](guide/en/concept/di-container.md)." msgstr "Внедрение зависимостей и контейнер внедрения зависимостей" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Property, constant and method order" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, fuzzy #| msgid "That's equal to the following:" msgid "Order should be the following:" msgstr "Это соответствует:" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Constants" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Properties" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md ../src/en/internals/017-tags.md -#: ../src/en/internals/018-widgets.md +#: ../src/internals/010-code-style.md ../src/internals/017-tags.md +#: ../src/internals/018-widgets.md #, no-wrap msgid "Methods" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Within each category, items should be sorted by visibility:" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "public" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "protected" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "private" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Abstract classes" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Abstract classes *shouldn't* be prefixed or postfixed with `Abstract`." msgstr "" #. type: Title #### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Immutable methods" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, fuzzy #| msgid "That's equal to the following:" msgid "Immutable method convention is the following:" msgstr "Это соответствует:" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "public function withName(string $name): self\n" @@ -325,28 +325,28 @@ msgid "" msgstr "" #. type: Bullet: '1. ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Cloned object name is `$new`." msgstr "" #. type: Bullet: '2. ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Return type is `self`." msgstr "" #. type: Title #### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Boolean check methods" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Methods that are there to check if something is true should be named like the following:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "public function isDeleted(): bool;\n" @@ -355,29 +355,29 @@ msgid "" msgstr "" #. type: Title #### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Flags in methods " msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Boolean flags in methods are better to be avoided. It's a sign the method may be doing too much, and there should be two methods instead of one." msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "public function login(bool $refreshPage = true): void;\n" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "It is better to be two methods:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "public function login(): void;\n" @@ -385,18 +385,18 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Variables" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Add an underscore (`_`) prefix for unused variables. For example:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "foreach ($items as $key => $_value) {\n" @@ -405,18 +405,18 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Imports" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Prefer importing classes and functions to using fully qualified names:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "use Yiisoft\\Arrays\\ArrayHelper;\n" @@ -428,23 +428,23 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Additional conventions" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[Namespaces](004-namespaces.md)" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[Exceptions](007-exceptions.md)" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, fuzzy #| msgid "[Preface](preface.md)" msgid "[Interfaces](008-interfaces.md)" diff --git a/_translations/pot/guide_databases_db-migrations.md.pot b/_translations/pot/guide_databases_db-migrations.md.pot index 66c6438..54f4510 100644 --- a/_translations/pot/guide_databases_db-migrations.md.pot +++ b/_translations/pot/guide_databases_db-migrations.md.pot @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2025-12-27 07:40+0000\n" +"POT-Creation-Date: 2025-12-27 10:28+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -22,6 +22,148 @@ msgstr "" msgid "Migrations" msgstr "" +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"During the course of developing and maintaining a database-driven " +"application, the structure of the database being used evolves just like the " +"source code does. For example, during the development of an application, a " +"new table may be found necessary; after the application is deployed to " +"production, it may be discovered that an index should be created to improve " +"the query performance; and so on. Because a database structure change often " +"requires some source code changes, Yii supports the so-called *database " +"migration* feature that allows you to keep track of database changes in " +"terms of *database migrations* which are version-controlled together with " +"the source code." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"The following steps show how database migration can be used by a team during " +"development:" +msgstr "" + +#. type: Bullet: '1. ' +#: ../src/guide/databases/db-migrations.md +msgid "" +"Tim creates a new migration (e.g. creates a new table, changes a column " +"definition, etc.)." +msgstr "" + +#. type: Bullet: '2. ' +#: ../src/guide/databases/db-migrations.md +msgid "" +"Tim commits the new migration into the source control system (e.g. Git, " +"Mercurial)." +msgstr "" + +#. type: Bullet: '3. ' +#: ../src/guide/databases/db-migrations.md +msgid "" +"Doug updates his repository from the source control system and receives the " +"new migration." +msgstr "" + +#. type: Bullet: '4. ' +#: ../src/guide/databases/db-migrations.md +msgid "" +"Doug applies the migration to his local development database, thereby " +"synchronizing his database to reflect the changes that Tim has made." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"And the following steps show how to deploy a new release with database " +"migrations to production:" +msgstr "" + +#. type: Bullet: '1. ' +#: ../src/guide/databases/db-migrations.md +msgid "" +"Scott creates a release tag for the project repository that contains some " +"new database migrations." +msgstr "" + +#. type: Bullet: '2. ' +#: ../src/guide/databases/db-migrations.md +msgid "" +"Scott updates the source code on the production server to the release tag." +msgstr "" + +#. type: Bullet: '3. ' +#: ../src/guide/databases/db-migrations.md +msgid "" +"Scott applies any accumulated database migrations to the production database." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Yii provides a set of migration command line tools that allow you to:" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "create new migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "apply migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "revert migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "re-apply migrations;" +msgstr "" + +#. type: Bullet: '* ' +#: ../src/guide/databases/db-migrations.md +msgid "show migration history and status." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"All these tools are accessible through the command `yii migrate`. In this " +"section we will describe in detail how to accomplish various tasks using " +"these tools." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> [!TIP]\n" +"> Migrations could affect not only database schema but adjust existing data to fit new schema, create RBAC\n" +"hierarchy or clean up cache.\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> [!NOTE]\n" +"> When manipulating data using a migration you may find that using your Active Record or entity classes\n" +"> for this might be useful because some of the logic is already implemented there. Keep in mind however, that in contrast\n" +"> to code written in the migrations, whose nature is to stay constant forever, application logic is subject to change.\n" +"> So when using Active Record or entity classes in migration code, changes to the logic in the source code\n" +"> may accidentally break the existing migrations. For this reason migration code should be kept independent of other\n" +"> application logic such.\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "Initial configuration" +msgstr "" + #. type: Plain text #: ../src/guide/databases/db-migrations.md msgid "" @@ -29,91 +171,595 @@ msgid "" "db-migration/) package:" msgstr "" -#. type: Fenced code block (shell) +#. type: Fenced code block (sh) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, no-wrap +msgid "make composer require yiisoft/db-migration\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"Create a directory to store migrations `src/Migration` right in the project " +"root." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Add the following configuration to `config/common/params.php`:" +msgstr "" + +#. type: Fenced code block (php) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, no-wrap +msgid "" +"'yiisoft/db-migration' => [\n" +" 'newMigrationNamespace' => 'App\\\\Migration',\n" +" 'sourceNamespaces' => ['App\\\\Migration'],\n" +"],\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"If you want to place migrations elsewhere, you can define the path in " +"`newMigrationPath`. If your migrations to be applied are from multiple " +"sources, such as external modules, `sourcePaths` could be used to define " +"these." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"You need a database connection configured as well. See [Working with " +"databases](../start/databases.md) for an example of configuring it for " +"PostgreSQL." +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "Creating a migration" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "To create a new empty migration, run the following command:" +msgstr "" + +#. type: Fenced code block (sh) +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"make shell\n" +"./yii migrate:create \n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"The required `name` argument gives a brief description about the new " +"migration. For example, if the migration is about creating a new table named " +"*news*, you may use the name `create_news_table` and run the following " +"command:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"make shell\n" +"./yii migrate:create create_news_table\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> [!NOTE]\n" +"> Because the `name` argument will be used as part of the generated migration class name,\n" +"> it should only contain letters, digits, and/or underscore characters.\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"The above command will create a new PHP class file named `src/Migration/" +"M251225221906CreateNewsTable.php`. The file contains the following code " +"which mainly declares a migration class with the skeleton code:" +msgstr "" + +#. type: Fenced code block (php) +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"columnBuilder();\n" +"\n" +" $b->createTable('news', [\n" +" 'id' => $cb::uuidPrimaryKey(),\n" +" 'title' => $cb::string()->notNull(),\n" +" 'content' => $cb::text(),\n" +" ]);\n" +" }\n" +"\n" +" public function down(MigrationBuilder $b): void\n" +" {\n" +" $b->dropTable('news');\n" +" }\n" +"}\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"Migration builder `$b` in the above manages database schema while the column " +"builder `$cb` manages column types. Both allow using *abstract types*. When " +"a migration is applied to a particular database, the abstract types will be " +"translated into the corresponding database physical types and corresponding " +"SQL to define them." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "Methods available in migration builder belong to the following types:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Raw queries" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "getDb — to get database connection instance." +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "execute — to execute raw SQL query." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Data" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "insert / update / delete" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "batchInsert" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "upsert" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Tables and views" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "createTable / renameTable / dropTable" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "truncateTable" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addCommentOnTable / dropCommentFromTable" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "createView / dropView" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Columns" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addColumn / renameColumn / alterColumn / dropColumn" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addCommentOnColumn / dropCommentFromColumn" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Keys and indexes" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addPrimaryKey / dropPrimaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "addForeignKey / dropForeignKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "createIndex / dropIndex" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"Additionally, there's a `columnBuilder()` which is used to obtain a column " +"builder as in example above. The builder has static methods that define " +"various column types:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Keys" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "primaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "smallPrimaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "bigPrimaryKey" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "uuidPrimaryKey" +msgstr "" + +#. type: Bullet: '- ' #: ../src/guide/databases/db-migrations.md -#, no-wrap -msgid "composer require yiisoft/db-migration\n" +msgid "Boolean" msgstr "" -#. type: Title ### +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "boolean" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Numbers" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "bit" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "tinyint" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "smallint" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "integer" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "bigint" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "flat" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "double" +msgstr "" + +#. type: Bullet: ' - ' #: ../src/guide/databases/db-migrations.md +msgid "decimal" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md ../src/internals/010-code-style.md #, no-wrap -msgid "Example usage" +msgid "Strings" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "char" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "string" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "text" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Date and time" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "timestamp" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "datetime" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "datetimeWithTimezone" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "time" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "timeWithTimezone" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "date" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "Special types" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "money" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "binary" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "uuid" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "array" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "structured" +msgstr "" + +#. type: Bullet: ' - ' +#: ../src/guide/databases/db-migrations.md +msgid "json" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "enum" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md msgid "" -"First, configure a DI container. Create `config/common/db.php` with the " -"following content:" +"All the above methods create a base type which could be adjusted with " +"additional methods:" msgstr "" -#. type: Fenced code block (php) +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "null / notNull" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "defaultValue" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "unique" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "scale / size / unsigned" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "primaryKey / autoIncrement" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "check" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "comment" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "computed" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "extra" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "reference" +msgstr "" + +#. type: Title ### #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "" -" [\n" -" 'class' => SqliteConnection::class,\n" -" '__construct()' => [\n" -" 'dsn' => 'sqlite:' . __DIR__ . '/Data/yiitest.sq3'\n" -" ]\n" -" ]\n" -"];\n" +msgid "Irreversible migrations" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "Add the following to `config/params.php`:" +msgid "" +"Not all migrations are reversible. For example, if the `up()` method deletes " +"a row of a table, you may not be able to recover this row in the `down()` " +"method. Sometimes, you may be just too lazy to implement the `down()`, " +"because it is not very common to revert database migrations. In this case, " +"you should implement `Yiisoft\\Db\\Migration\\MigrationInterface` that has " +"`up()` only." msgstr "" -#. type: Fenced code block (php) +#. type: Title ### #: ../src/guide/databases/db-migrations.md #, no-wrap +msgid "Transactional migrations" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md msgid "" -"...\n" -"'yiisoft/db-migration' => [\n" -" 'newMigrationNamespace' => 'App\\\\Migration',\n" -" 'sourceNamespaces' => ['App\\\\Migration'],\n" -"],\n" -"...\n" +"While performing complex DB migrations, it is important to ensure each " +"migration to either succeed or fail as a whole so that the database can " +"maintain integrity and consistency. To achieve this goal, it is recommended " +"that you may enclose the DB operations of each migration in a transaction " +"automatically by adding `TransactionalMigrationInterface` to `implements` of " +"your migration." msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md -msgid "Now test if it works:" +msgid "" +"As a result, if any operation in the `up()` or `down()` method fails, all " +"prior operations will be rolled back automatically." msgstr "" -#. type: Fenced code block (shell) +#. type: Plain text #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "./yii list migrate\n" +msgid "" +"> Note: Not all DBMS support transactions. And some DB queries cannot be put into a transaction. For some examples,\n" +"please refer to [implicit commit](https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html).\n" msgstr "" -#. type: Title ### +#. type: Title ## #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "Creating a migration" +msgid "Generating a migration" msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md msgid "" -"To work with migrations, you can use the provided [view](https://github.com/" -"yiisoft/db-migration/tree/master/resources/views)." +"Instead of writing migrations by hand, the command provides a convenient way " +"generate some of the code." msgstr "" #. type: Fenced code block (shell) #: ../src/guide/databases/db-migrations.md #, no-wrap -msgid "./yii migrate:create my_first_table --command=table --fields=name,example --table-comment=my_first_table\n" +msgid "" +"make shell\n" +"./yii migrate:create -- my_first_table --command=table --fields=name,example --table-comment=my_first_table\n" msgstr "" #. type: Plain text @@ -136,19 +782,21 @@ msgid "" "use Yiisoft\\Db\\Migration\\TransactionalMigrationInterface;\n" "\n" "/**\n" -" * Handles the creation of a table `my_first_table`.\n" +" * Handles the creation of table `my_first_table`.\n" " */\n" -"final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface\n" +"final class M251227095006CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface\n" "{\n" " public function up(MigrationBuilder $b): void\n" " {\n" +" $columnBuilder = $b->columnBuilder();\n" +"\n" " $b->createTable('my_first_table', [\n" -" 'id' => $b->primaryKey(),\n" +" 'id' => $columnBuilder::primaryKey(),\n" " 'name',\n" " 'example',\n" " ]);\n" -" \n" -" $b->addCommentOnTable('my_first_table', 'dest');\n" +"\n" +" $b->addCommentOnTable('my_first_table', 'my_first_table');\n" " }\n" "\n" " public function down(MigrationBuilder $b): void\n" @@ -160,9 +808,179 @@ msgstr "" #. type: Plain text #: ../src/guide/databases/db-migrations.md +msgid "Commands available are:" +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "create - empty migration." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "" +"table - creating a table. Use `--fields` specify a list of fields to use. " +"Types could be specified as well such as `id:primaryKey,name:string:" +"defaultValue(\"Alex\"),user_id:integer:foreignKey,category_id2:integer:" +"foreignKey(category id2)`." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "dropTable - dropping a table." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "addColumn - adding a column." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "dropColumn - dropping a column." +msgstr "" + +#. type: Bullet: '- ' +#: ../src/guide/databases/db-migrations.md +msgid "" +"junction - creating a junction table. Use `--and` specify a second table." +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "Applying Migrations" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"To upgrade a database to its latest structure, you should apply all " +"available new migrations using the following command:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "./yii migrate:up\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"This command will list all migrations that have not been applied so far. If " +"you confirm that you want to apply these migrations, it will run the `up()` " +"method in every new migration class, one after another, in the order of " +"their timestamp values. If any of the migrations fails, the command will " +"quit without applying the rest of the migrations." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"For each migration that has been successfully applied, the command will " +"insert a row into a database table named `migration` to record the " +"successful application of the migration. This will allow the migration tool " +"to identify which migrations have been applied and which have not." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"Sometimes, you may only want to apply one or a few new migrations, instead " +"of all available migrations. You can do so by specifying the number of " +"migrations that you want to apply when running the command. For example, " +"the following command will try to apply the next three available migrations:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "./yii migrate:up --limit=3\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "Reverting Migrations " +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"To revert (undo) one or multiple migrations that have been applied before, " +"you can run the following command:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"./yii migrate:down # revert the most recently applied migration\n" +"./yii migrate:down --limit=3 # revert the most 3 recently applied migrations\n" +"./yii migrate:down --all # revert all migrations\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"> Note: Not all migrations are reversible. Trying to revert such migrations will cause an error and stop the\n" +"entire reverting process.\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "Redoing Migrations " +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"Redoing migrations means first reverting the specified migrations and then " +"applying again. This can be done as follows:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "" +"./yii migrate:redo # redo the last applied migration\n" +"./yii migrate:redo --limit=3 # redo the last 3 applied migrations\n" +"./yii migrate:redo --all # redo all migrations\n" +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "> Note: If a migration is not reversible, you will not be able to redo it.\n" +msgstr "" + +#. type: Title ## +#: ../src/guide/databases/db-migrations.md +#, no-wrap +msgid "Listing Migrations " +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"To list which migrations have been applied and which are not, you may use " +"the following commands:" +msgstr "" + +#. type: Fenced code block +#: ../src/guide/databases/db-migrations.md +#, no-wrap msgid "" -"For more information [see](https://github.com/yiisoft/db-migration/tree/" -"master/docs/guide/en)" +"./yii migrate/history # showing the last 10 applied migrations\n" +"./yii migrate:history --limit=5 # showing the last 5 applied migrations\n" +"./yii migrate:history --all # showing all applied migrations\n" +"\n" +"./yii migrate:new # showing the first 10 new migrations\n" +"./yii migrate:new --limit=5 # showing the first 5 new migrations\n" +"./yii migrate:new --all # showing all new migrations\n" msgstr "" #. type: Title ### @@ -176,9 +994,15 @@ msgstr "" msgid "" "Migrations in Yii 2.0 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 further changes " -"in the database schema are applied using the new `migration` component and " -"recorded in the new migration table." +"is also not compatible." +msgstr "" + +#. type: Plain text +#: ../src/guide/databases/db-migrations.md +msgid "" +"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 further changes in the database schema " +"are applied using the new `migration` component and recorded in the new " +"migration table." msgstr "" diff --git a/_translations/pot/guide_start_databases.md.pot b/_translations/pot/guide_start_databases.md.pot index fa4684f..3ddde79 100644 --- a/_translations/pot/guide_start_databases.md.pot +++ b/_translations/pot/guide_start_databases.md.pot @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2025-12-27 06:04+0000\n" +"POT-Creation-Date: 2025-12-27 06:16+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -16,6 +16,22 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" +#. type: Fenced code block (sh) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, no-wrap +msgid "make composer require yiisoft/db-migration\n" +msgstr "" + +#. type: Fenced code block (php) +#: ../src/guide/databases/db-migrations.md ../src/guide/start/databases.md +#, no-wrap +msgid "" +"'yiisoft/db-migration' => [\n" +" 'newMigrationNamespace' => 'App\\\\Migration',\n" +" 'sourceNamespaces' => ['App\\\\Migration'],\n" +"],\n" +msgstr "" + #. type: Title # #: ../src/guide/index.md ../src/guide/start/databases.md #, no-wrap @@ -279,12 +295,6 @@ msgstr "" msgid "To use migrations we need another package installed:" msgstr "" -#. type: Fenced code block (sh) -#: ../src/guide/start/databases.md -#, no-wrap -msgid "make composer require yiisoft/db-migration\n" -msgstr "" - #. type: Plain text #: ../src/guide/start/databases.md msgid "" @@ -292,16 +302,6 @@ msgid "" "root. Add the following configuration to `config/common/params.php`:" msgstr "" -#. type: Fenced code block (php) -#: ../src/guide/start/databases.md -#, no-wrap -msgid "" -"'yiisoft/db-migration' => [\n" -" 'newMigrationNamespace' => 'App\\\\Migration',\n" -" 'sourceNamespaces' => ['App\\\\Migration'],\n" -"],\n" -msgstr "" - #. type: Plain text #: ../src/guide/start/databases.md msgid "" diff --git a/_translations/pot/internals_010-code-style.md.pot b/_translations/pot/internals_010-code-style.md.pot index 99b2e74..32d81df 100644 --- a/_translations/pot/internals_010-code-style.md.pot +++ b/_translations/pot/internals_010-code-style.md.pot @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2025-12-24 08:02+0000\n" +"POT-Creation-Date: 2025-12-27 10:28+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -16,14 +16,20 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" +#. type: Title ## +#: ../src/guide/databases/db-migrations.md ../src/internals/010-code-style.md +#, no-wrap +msgid "Strings" +msgstr "" + #. type: Title # -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "010 — Code style" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "" "Code formatting used in Yii 3 packages is based on [PSR-1](https://www.php-" "fig.org/psr/psr-1/) and [PSR-12](https://www.php-fig.org/psr/psr-12/) with " @@ -31,34 +37,34 @@ msgid "" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md ../src/en/internals/017-tags.md -#: ../src/en/internals/018-widgets.md +#: ../src/internals/010-code-style.md ../src/internals/017-tags.md +#: ../src/internals/018-widgets.md #, no-wrap msgid "Names" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use English only." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use camelCase notation, including abbreviations (e.g., `enableIdn`)." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Use the shortest possible, but an explanatory name." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Never trim or abbreviate a name." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "" "Postfix classes, interfaces, traits and variables, which is a [collection]" "(https://en.wikipedia.org/wiki/Collection_(abstract_data_type)), with " @@ -66,76 +72,76 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Types" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "" "Declare [argument and return types](https://www.php.net/manual/en/" "migration70.new-features.php) where possible." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "" "[Use types for properties](https://wiki.php.net/rfc/typed_properties_v2)." msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "" "Use strict typing. Avoid mixed and union types where possible except " "compatible types such as `string|Stringable`." msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Comments" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "" "Inline comments are to be avoided unless code couldn't be understood without " "them. A good example is a workaround for a bug in a certain PHP version." msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "" "Method comment is necessary except it adds nothing to what method name and " "signature already has." msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Class comment should describe the purpose of the class." msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "" "[See PHPDoc](https://github.com/yiisoft/docs/blob/master/014-docs.md#phpdoc)." msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Formatting" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "No alignment" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "" "Property, variable and constant value assignments shouldn't be aligned. The " "same applies to phpdoc tags. The reason is that aligned statements often " @@ -143,7 +149,7 @@ msgid "" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "final class X\n" @@ -167,13 +173,13 @@ msgid "" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Chain calls" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "" "Chained calls should be formatted for better readability. If it's a long " "chain that doesn't fit the line length of 120 characters, then each call " @@ -181,7 +187,7 @@ msgid "" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "$object\n" @@ -193,143 +199,137 @@ msgid "" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "If it's a short chain, it's alright for it to be on a single line:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "$object = $object->withName('test');\n" msgstr "" -#. type: Title ## -#: ../src/en/internals/010-code-style.md -#, no-wrap -msgid "Strings" -msgstr "" - #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "When no variables involved, use `'Hello!'`" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "To get variables into string prefer `\"Hello, $username!\"`" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Classes and interfaces" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Final by default" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Classes should be `final` by default." msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Private by default" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Constants, properties and methods should be private by default." msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Composition over inheritance" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Prefer [composition to inheritance](guide/en/concept/di-container.md)." msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Property, constant and method order" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Order should be the following:" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Constants" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Properties" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md ../src/en/internals/017-tags.md -#: ../src/en/internals/018-widgets.md +#: ../src/internals/010-code-style.md ../src/internals/017-tags.md +#: ../src/internals/018-widgets.md #, no-wrap msgid "Methods" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Within each category, items should be sorted by visibility:" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "public" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "protected" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "private" msgstr "" #. type: Title ### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Abstract classes" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Abstract classes *shouldn't* be prefixed or postfixed with `Abstract`." msgstr "" #. type: Title #### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Immutable methods" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Immutable method convention is the following:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "public function withName(string $name): self\n" @@ -341,30 +341,30 @@ msgid "" msgstr "" #. type: Bullet: '1. ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Cloned object name is `$new`." msgstr "" #. type: Bullet: '2. ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Return type is `self`." msgstr "" #. type: Title #### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Boolean check methods" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "" "Methods that are there to check if something is true should be named like " "the following:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "public function isDeleted(): bool;\n" @@ -373,31 +373,31 @@ msgid "" msgstr "" #. type: Title #### -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Flags in methods " msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "" "Boolean flags in methods are better to be avoided. It's a sign the method " "may be doing too much, and there should be two methods instead of one." msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "public function login(bool $refreshPage = true): void;\n" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "It is better to be two methods:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "public function login(): void;\n" @@ -405,18 +405,18 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Variables" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Add an underscore (`_`) prefix for unused variables. For example:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "foreach ($items as $key => $_value) {\n" @@ -425,18 +425,18 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Imports" msgstr "" #. type: Plain text -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "Prefer importing classes and functions to using fully qualified names:" msgstr "" #. type: Fenced code block (php) -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "" "use Yiisoft\\Arrays\\ArrayHelper;\n" @@ -448,22 +448,22 @@ msgid "" msgstr "" #. type: Title ## -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md #, no-wrap msgid "Additional conventions" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[Namespaces](004-namespaces.md)" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[Exceptions](007-exceptions.md)" msgstr "" #. type: Bullet: '- ' -#: ../src/en/internals/010-code-style.md +#: ../src/internals/010-code-style.md msgid "[Interfaces](008-interfaces.md)" msgstr "" diff --git a/src/es/guide/databases/db-migrations.md b/src/es/guide/databases/db-migrations.md index 7779b50..196ac40 100644 --- a/src/es/guide/databases/db-migrations.md +++ b/src/es/guide/databases/db-migrations.md @@ -1,59 +1,298 @@ # Migrations +During the course of developing and maintaining a database-driven +application, the structure of the database being used evolves just like the +source code does. For example, during the development of an application, a +new table may be found necessary; after the application is deployed to +production, it may be discovered that an index should be created to improve +the query performance; and so on. Because a database structure change often +requires some source code changes, Yii supports the so-called *database +migration* feature that allows you to keep track of database changes in +terms of *database migrations* which are version-controlled together with +the source code. + +The following steps show how database migration can be used by a team during +development: + +1. Tim creates a new migration (e.g. creates a new table, changes a column + definition, etc.). +2. Tim commits the new migration into the source control system (e.g. Git, + Mercurial). +3. Doug updates his repository from the source control system and receives + the new migration. +4. Doug applies the migration to his local development database, thereby + synchronizing his database to reflect the changes that Tim has made. + +And the following steps show how to deploy a new release with database +migrations to production: + +1. Scott creates a release tag for the project repository that contains some + new database migrations. +2. Scott updates the source code on the production server to the release + tag. +3. Scott applies any accumulated database migrations to the production + database. + +Yii provides a set of migration command line tools that allow you to: + +* create new migrations; +* apply migrations; +* revert migrations; +* re-apply migrations; +* show migration history and status. + +All these tools are accessible through the command `yii migrate`. In this +section we will describe in detail how to accomplish various tasks using +these tools. + +> [!TIP] +> Migrations could affect not only database schema but adjust existing data to fit new schema, create RBAC +hierarchy or clean up cache. + +> [!NOTE] +> When manipulating data using a migration you may find that using your Active Record or entity classes +> for this might be useful because some of the logic is already implemented there. Keep in mind however, that in contrast +> to code written in the migrations, whose nature is to stay constant forever, application logic is subject to change. +> So when using Active Record or entity classes in migration code, changes to the logic in the source code +> may accidentally break the existing migrations. For this reason migration code should be kept independent of other +> application logic such. + +## Initial configuration + To use migrations, install [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package: ```shell -composer require yiisoft/db-migration +make composer require yiisoft/db-migration ``` -### Example usage +Create a directory to store migrations `src/Migration` right in the project +root. -First, configure a DI container. Create `config/common/db.php` with the -following content: +Add the following configuration to `config/common/params.php`: + +```php +'yiisoft/db-migration' => [ + 'newMigrationNamespace' => 'App\\Migration', + 'sourceNamespaces' => ['App\\Migration'], +], +``` + +If you want to place migrations elsewhere, you can define the path in +`newMigrationPath`. If your migrations to be applied are from multiple +sources, such as external modules, `sourcePaths` could be used to define +these. + +You need a database connection configured as well. See [Working with +databases](../start/databases.md) for an example of configuring it for +PostgreSQL. + +## Creating a migration + +To create a new empty migration, run the following command: + +```sh +make shell +./yii migrate:create +``` + +The required `name` argument gives a brief description about the new +migration. For example, if the migration is about creating a new table named +*news*, you may use the name `create_news_table` and run the following +command: + +``` +make shell +./yii migrate:create create_news_table +``` + + +> [!NOTE] +> Because the `name` argument will be used as part of the generated migration class name, +> it should only contain letters, digits, and/or underscore characters. + +The above command will create a new PHP class file named +`src/Migration/M251225221906CreateNewsTable.php`. The file contains the +following code which mainly declares a migration class with the skeleton +code: ```php [ - 'class' => SqliteConnection::class, - '__construct()' => [ - 'dsn' => 'sqlite:' . __DIR__ . '/Data/yiitest.sq3' - ] - ] -]; +final class M251225221906CreateNewsTable implements RevertibleMigrationInterface +{ + public function up(MigrationBuilder $b): void + { + // TODO: Implement the logic to apply the migration. + } + + public function down(MigrationBuilder $b): void + { + // TODO: Implement the logic to revert the migration. + } +} ``` -Add the following to `config/params.php`: +In the migration class, you are expected to write code in the `up()` method +that makes changes to the database structure. You may also want to write +code in the `down()` method to revert the changes made by `up()`. The `up()` +method is invoked when you upgrade the database with this migration, while +the `down()` method is invoked when you downgrade the database. The +following code shows how you may implement the migration class to create a +`news` table: ```php -... -'yiisoft/db-migration' => [ - 'newMigrationNamespace' => 'App\\Migration', - 'sourceNamespaces' => ['App\\Migration'], -], -... -``` +columnBuilder(); + + $b->createTable('news', [ + 'id' => $cb::uuidPrimaryKey(), + 'title' => $cb::string()->notNull(), + 'content' => $cb::text(), + ]); + } + + public function down(MigrationBuilder $b): void + { + $b->dropTable('news'); + } +} ``` -### Creating a migration +Migration builder `$b` in the above manages database schema while the column +builder `$cb` manages column types. Both allow using *abstract types*. When +a migration is applied to a particular database, the abstract types will be +translated into the corresponding database physical types and corresponding +SQL to define them. + +Methods available in migration builder belong to the following types: + +- Raw queries + - getDb — to get database connection instance. + - execute — to execute raw SQL query. +- Data + - insert / update / delete + - batchInsert + - upsert +- Tables and views + - createTable / renameTable / dropTable + - truncateTable + - addCommentOnTable / dropCommentFromTable + - createView / dropView +- Columns + - addColumn / renameColumn / alterColumn / dropColumn + - addCommentOnColumn / dropCommentFromColumn +- Keys and indexes + - addPrimaryKey / dropPrimaryKey + - addForeignKey / dropForeignKey + - createIndex / dropIndex + +Additionally, there's a `columnBuilder()` which is used to obtain a column +builder as in example above. The builder has static methods that define +various column types: + +- Keys + - primaryKey + - smallPrimaryKey + - bigPrimaryKey + - uuidPrimaryKey +- Boolean + - boolean +- Numbers + - bit + - tinyint + - smallint + - integer + - bigint + - flat + - double + - decimal +- Strings + - char + - string + - text +- Date and time + - timestamp + - datetime + - datetimeWithTimezone + - time + - timeWithTimezone + - date +- Special types + - money + - binary + - uuid + - array + - structured + - json +- enum + +All the above methods create a base type which could be adjusted with +additional methods: + +- null / notNull +- defaultValue +- unique +- scale / size / unsigned +- primaryKey / autoIncrement +- check +- comment +- computed +- extra +- reference -To work with migrations, you can use the provided -[view](https://github.com/yiisoft/db-migration/tree/master/resources/views). +### Irreversible migrations + +Not all migrations are reversible. For example, if the `up()` method deletes +a row of a table, you may not be able to recover this row in the `down()` +method. Sometimes, you may be just too lazy to implement the `down()`, +because it is not very common to revert database migrations. In this case, +you should implement `Yiisoft\Db\Migration\MigrationInterface` that has +`up()` only. + + +### Transactional migrations + +While performing complex DB migrations, it is important to ensure each +migration to either succeed or fail as a whole so that the database can +maintain integrity and consistency. To achieve this goal, it is recommended +that you may enclose the DB operations of each migration in a transaction +automatically by adding `TransactionalMigrationInterface` to `implements` of +your migration. + +As a result, if any operation in the `up()` or `down()` method fails, all +prior operations will be rolled back automatically. + +> Note: Not all DBMS support transactions. And some DB queries cannot be put into a transaction. For some examples, +please refer to [implicit commit](https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html). + +## Generating a migration + +Instead of writing migrations by hand, the command provides a convenient way +generate some of the code. ```shell -./yii migrate:create my_first_table --command=table --fields=name,example --table-comment=my_first_table +make shell +./yii migrate:create -- my_first_table --command=table --fields=name,example --table-comment=my_first_table ``` That would generate the following: @@ -70,19 +309,21 @@ use Yiisoft\Db\Migration\RevertibleMigrationInterface; use Yiisoft\Db\Migration\TransactionalMigrationInterface; /** - * Handles the creation of a table `my_first_table`. + * Handles the creation of table `my_first_table`. */ -final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface +final class M251227095006CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface { public function up(MigrationBuilder $b): void { + $columnBuilder = $b->columnBuilder(); + $b->createTable('my_first_table', [ - 'id' => $b->primaryKey(), + 'id' => $columnBuilder::primaryKey(), 'name', 'example', ]); - - $b->addCommentOnTable('my_first_table', 'dest'); + + $b->addCommentOnTable('my_first_table', 'my_first_table'); } public function down(MigrationBuilder $b): void @@ -92,17 +333,98 @@ final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationI } ``` -For more information -[see](https://github.com/yiisoft/db-migration/tree/master/docs/guide/en) +Commands available are: + +- create - empty migration. +- table - creating a table. Use `--fields` specify a list of fields to + use. Types could be specified as well such as + `id:primaryKey,name:string:defaultValue("Alex"),user_id:integer:foreignKey,category_id2:integer:foreignKey(category + id2)`. +- dropTable - dropping a table. +- addColumn - adding a column. +- dropColumn - dropping a column. +- junction - creating a junction table. Use `--and` specify a second table. + +## Applying Migrations + +To upgrade a database to its latest structure, you should apply all +available new migrations using the following command: + +``` +./yii migrate:up +``` + +This command will list all migrations that have not been applied so far. If +you confirm that you want to apply these migrations, it will run the `up()` +method in every new migration class, one after another, in the order of +their timestamp values. If any of the migrations fails, the command will +quit without applying the rest of the migrations. + +For each migration that has been successfully applied, the command will +insert a row into a database table named `migration` to record the +successful application of the migration. This will allow the migration tool +to identify which migrations have been applied and which have not. + +Sometimes, you may only want to apply one or a few new migrations, instead +of all available migrations. You can do so by specifying the number of +migrations that you want to apply when running the command. For example, +the following command will try to apply the next three available migrations: + +``` +./yii migrate:up --limit=3 +``` + +## Reverting Migrations + +To revert (undo) one or multiple migrations that have been applied before, +you can run the following command: + +``` +./yii migrate:down # revert the most recently applied migration +./yii migrate:down --limit=3 # revert the most 3 recently applied migrations +./yii migrate:down --all # revert all migrations +``` + +> Note: Not all migrations are reversible. Trying to revert such migrations will cause an error and stop the +entire reverting process. + + +## Redoing Migrations + +Redoing migrations means first reverting the specified migrations and then +applying again. This can be done as follows: + +``` +./yii migrate:redo # redo the last applied migration +./yii migrate:redo --limit=3 # redo the last 3 applied migrations +./yii migrate:redo --all # redo all migrations +``` + +> Note: If a migration is not reversible, you will not be able to redo it. + +## Listing Migrations + +To list which migrations have been applied and which are not, you may use +the following commands: + +``` +./yii migrate/history # showing the last 10 applied migrations +./yii migrate:history --limit=5 # showing the last 5 applied migrations +./yii migrate:history --all # showing all applied migrations + +./yii migrate:new # showing the first 10 new migrations +./yii migrate:new --limit=5 # showing the first 5 new migrations +./yii migrate:new --all # showing all new migrations +``` ### Upgrading from Yii 2.0 Migrations in Yii 2.0 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` +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 further changes in the database schema are applied using the new `migration` component and recorded in the new migration table. - diff --git a/src/guide/databases/db-migrations.md b/src/guide/databases/db-migrations.md index 56964ab..1b2b265 100644 --- a/src/guide/databases/db-migrations.md +++ b/src/guide/databases/db-migrations.md @@ -1,56 +1,266 @@ # Migrations +During the course of developing and maintaining a database-driven application, the structure of the database +being used evolves just like the source code does. For example, during the development of an application, +a new table may be found necessary; after the application is deployed to production, it may be discovered +that an index should be created to improve the query performance; and so on. Because a database structure change +often requires some source code changes, Yii supports the so-called *database migration* feature that allows +you to keep track of database changes in terms of *database migrations* which are version-controlled together +with the source code. + +The following steps show how database migration can be used by a team during development: + +1. Tim creates a new migration (e.g. creates a new table, changes a column definition, etc.). +2. Tim commits the new migration into the source control system (e.g. Git, Mercurial). +3. Doug updates his repository from the source control system and receives the new migration. +4. Doug applies the migration to his local development database, thereby synchronizing his database + to reflect the changes that Tim has made. + +And the following steps show how to deploy a new release with database migrations to production: + +1. Scott creates a release tag for the project repository that contains some new database migrations. +2. Scott updates the source code on the production server to the release tag. +3. Scott applies any accumulated database migrations to the production database. + +Yii provides a set of migration command line tools that allow you to: + +* create new migrations; +* apply migrations; +* revert migrations; +* re-apply migrations; +* show migration history and status. + +All these tools are accessible through the command `yii migrate`. In this section we will describe in detail +how to accomplish various tasks using these tools. + +> [!TIP] +> Migrations could affect not only database schema but adjust existing data to fit new schema, create RBAC +hierarchy or clean up cache. + +> [!NOTE] +> When manipulating data using a migration you may find that using your Active Record or entity classes +> for this might be useful because some of the logic is already implemented there. Keep in mind however, that in contrast +> to code written in the migrations, whose nature is to stay constant forever, application logic is subject to change. +> So when using Active Record or entity classes in migration code, changes to the logic in the source code +> may accidentally break the existing migrations. For this reason migration code should be kept independent of other +> application logic such. + +## Initial configuration + To use migrations, install [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package: ```shell -composer require yiisoft/db-migration +make composer require yiisoft/db-migration ``` -### Example usage +Create a directory to store migrations `src/Migration` right in the project root. -First, configure a DI container. Create `config/common/db.php` with the following content: +Add the following configuration to `config/common/params.php`: + +```php +'yiisoft/db-migration' => [ + 'newMigrationNamespace' => 'App\\Migration', + 'sourceNamespaces' => ['App\\Migration'], +], +``` + +If you want to place migrations elsewhere, you can define the path in `newMigrationPath`. If your migrations to be +applied are from multiple sources, such as external modules, `sourcePaths` could be used to define these. + +You need a database connection configured as well. See [Working with databases](../start/databases.md) for an example +of configuring it for PostgreSQL. + +## Creating a migration + +To create a new empty migration, run the following command: + +```sh +make shell +./yii migrate:create +``` + +The required `name` argument gives a brief description about the new migration. For example, if +the migration is about creating a new table named *news*, you may use the name `create_news_table` +and run the following command: + +``` +make shell +./yii migrate:create create_news_table +``` + + +> [!NOTE] +> Because the `name` argument will be used as part of the generated migration class name, +> it should only contain letters, digits, and/or underscore characters. + +The above command will create a new PHP class file named `src/Migration/M251225221906CreateNewsTable.php`. +The file contains the following code which mainly declares a migration class with the skeleton code: ```php [ - 'class' => SqliteConnection::class, - '__construct()' => [ - 'dsn' => 'sqlite:' . __DIR__ . '/Data/yiitest.sq3' - ] - ] -]; +final class M251225221906CreateNewsTable implements RevertibleMigrationInterface +{ + public function up(MigrationBuilder $b): void + { + // TODO: Implement the logic to apply the migration. + } + + public function down(MigrationBuilder $b): void + { + // TODO: Implement the logic to revert the migration. + } +} ``` -Add the following to `config/params.php`: +In the migration class, you are expected to write code in the `up()` method that makes changes to the database structure. +You may also want to write code in the `down()` method to revert the changes made by `up()`. The `up()` method is invoked +when you upgrade the database with this migration, while the `down()` method is invoked when you downgrade the database. +The following code shows how you may implement the migration class to create a `news` table: ```php -... -'yiisoft/db-migration' => [ - 'newMigrationNamespace' => 'App\\Migration', - 'sourceNamespaces' => ['App\\Migration'], -], -... -``` +columnBuilder(); + + $b->createTable('news', [ + 'id' => $cb::uuidPrimaryKey(), + 'title' => $cb::string()->notNull(), + 'content' => $cb::text(), + ]); + } + + public function down(MigrationBuilder $b): void + { + $b->dropTable('news'); + } +} ``` -### Creating a migration +Migration builder `$b` in the above manages database schema while the column builder `$cb` manages column types. Both +allow using *abstract types*. When a migration is applied to a particular database, the abstract types will +be translated into the corresponding database physical types and corresponding SQL to define them. + +Methods available in migration builder belong to the following types: + +- Raw queries + - getDb — to get database connection instance. + - execute — to execute raw SQL query. +- Data + - insert / update / delete + - batchInsert + - upsert +- Tables and views + - createTable / renameTable / dropTable + - truncateTable + - addCommentOnTable / dropCommentFromTable + - createView / dropView +- Columns + - addColumn / renameColumn / alterColumn / dropColumn + - addCommentOnColumn / dropCommentFromColumn +- Keys and indexes + - addPrimaryKey / dropPrimaryKey + - addForeignKey / dropForeignKey + - createIndex / dropIndex + +Additionally, there's a `columnBuilder()` which is used to obtain a column builder as in example above. The builder +has static methods that define various column types: + +- Keys + - primaryKey + - smallPrimaryKey + - bigPrimaryKey + - uuidPrimaryKey +- Boolean + - boolean +- Numbers + - bit + - tinyint + - smallint + - integer + - bigint + - flat + - double + - decimal +- Strings + - char + - string + - text +- Date and time + - timestamp + - datetime + - datetimeWithTimezone + - time + - timeWithTimezone + - date +- Special types + - money + - binary + - uuid + - array + - structured + - json +- enum + +All the above methods create a base type which could be adjusted with additional methods: + +- null / notNull +- defaultValue +- unique +- scale / size / unsigned +- primaryKey / autoIncrement +- check +- comment +- computed +- extra +- reference -To work with migrations, you can use the provided [view](https://github.com/yiisoft/db-migration/tree/master/resources/views). +### Irreversible migrations + +Not all migrations are reversible. For example, if the `up()` method deletes a row of a table, you may +not be able to recover this row in the `down()` method. Sometimes, you may be just too lazy to implement +the `down()`, because it is not very common to revert database migrations. In this case, you should implement +`Yiisoft\Db\Migration\MigrationInterface` that has `up()` only. + + +### Transactional migrations + +While performing complex DB migrations, it is important to ensure each migration to either succeed or fail as a whole +so that the database can maintain integrity and consistency. To achieve this goal, it is recommended that you may +enclose the DB operations of each migration in a transaction automatically by adding `TransactionalMigrationInterface` +to `implements` of your migration. + +As a result, if any operation in the `up()` or `down()` method fails, all prior operations will +be rolled back automatically. + +> Note: Not all DBMS support transactions. And some DB queries cannot be put into a transaction. For some examples, +please refer to [implicit commit](https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html). + +## Generating a migration + +Instead of writing migrations by hand, the command provides a convenient way generate some of the code. ```shell -./yii migrate:create my_first_table --command=table --fields=name,example --table-comment=my_first_table +make shell +./yii migrate:create -- my_first_table --command=table --fields=name,example --table-comment=my_first_table ``` That would generate the following: @@ -67,19 +277,21 @@ use Yiisoft\Db\Migration\RevertibleMigrationInterface; use Yiisoft\Db\Migration\TransactionalMigrationInterface; /** - * Handles the creation of a table `my_first_table`. + * Handles the creation of table `my_first_table`. */ -final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface +final class M251227095006CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface { public function up(MigrationBuilder $b): void { + $columnBuilder = $b->columnBuilder(); + $b->createTable('my_first_table', [ - 'id' => $b->primaryKey(), + 'id' => $columnBuilder::primaryKey(), 'name', 'example', ]); - - $b->addCommentOnTable('my_first_table', 'dest'); + + $b->addCommentOnTable('my_first_table', 'my_first_table'); } public function down(MigrationBuilder $b): void @@ -89,14 +301,87 @@ final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationI } ``` -For more information [see](https://github.com/yiisoft/db-migration/tree/master/docs/guide/en) +Commands available are: + +- create - empty migration. +- table - creating a table. Use `--fields` specify a list of fields to use. Types could be specified as well such as + `id:primaryKey,name:string:defaultValue("Alex"),user_id:integer:foreignKey,category_id2:integer:foreignKey(category id2)`. +- dropTable - dropping a table. +- addColumn - adding a column. +- dropColumn - dropping a column. +- junction - creating a junction table. Use `--and` specify a second table. + +## Applying Migrations + +To upgrade a database to its latest structure, you should apply all available new migrations using the following command: + +``` +./yii migrate:up +``` + +This command will list all migrations that have not been applied so far. If you confirm that you want to apply +these migrations, it will run the `up()` method in every new migration class, one after another, +in the order of their timestamp values. If any of the migrations fails, the command will quit without applying +the rest of the migrations. + +For each migration that has been successfully applied, the command will insert a row into a database table named +`migration` to record the successful application of the migration. This will allow the migration tool to identify +which migrations have been applied and which have not. + +Sometimes, you may only want to apply one or a few new migrations, instead of all available migrations. +You can do so by specifying the number of migrations that you want to apply when running the command. +For example, the following command will try to apply the next three available migrations: + +``` +./yii migrate:up --limit=3 +``` + +## Reverting Migrations + +To revert (undo) one or multiple migrations that have been applied before, you can run the following command: + +``` +./yii migrate:down # revert the most recently applied migration +./yii migrate:down --limit=3 # revert the most 3 recently applied migrations +./yii migrate:down --all # revert all migrations +``` + +> Note: Not all migrations are reversible. Trying to revert such migrations will cause an error and stop the +entire reverting process. + + +## Redoing Migrations + +Redoing migrations means first reverting the specified migrations and then applying again. This can be done +as follows: + +``` +./yii migrate:redo # redo the last applied migration +./yii migrate:redo --limit=3 # redo the last 3 applied migrations +./yii migrate:redo --all # redo all migrations +``` + +> Note: If a migration is not reversible, you will not be able to redo it. + +## Listing Migrations + +To list which migrations have been applied and which are not, you may use the following commands: + +``` +./yii migrate/history # showing the last 10 applied migrations +./yii migrate:history --limit=5 # showing the last 5 applied migrations +./yii migrate:history --all # showing all applied migrations + +./yii migrate:new # showing the first 10 new migrations +./yii migrate:new --limit=5 # showing the first 5 new migrations +./yii migrate:new --all # showing all new migrations +``` ### Upgrading from Yii 2.0 Migrations in Yii 2.0 and the [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package are not compatible, -and the `migration` table is also 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 further changes in the database schema are applied using the new `migration` component and recorded in the new migration table. - diff --git a/src/id/guide/databases/db-migrations.md b/src/id/guide/databases/db-migrations.md index 7779b50..196ac40 100644 --- a/src/id/guide/databases/db-migrations.md +++ b/src/id/guide/databases/db-migrations.md @@ -1,59 +1,298 @@ # Migrations +During the course of developing and maintaining a database-driven +application, the structure of the database being used evolves just like the +source code does. For example, during the development of an application, a +new table may be found necessary; after the application is deployed to +production, it may be discovered that an index should be created to improve +the query performance; and so on. Because a database structure change often +requires some source code changes, Yii supports the so-called *database +migration* feature that allows you to keep track of database changes in +terms of *database migrations* which are version-controlled together with +the source code. + +The following steps show how database migration can be used by a team during +development: + +1. Tim creates a new migration (e.g. creates a new table, changes a column + definition, etc.). +2. Tim commits the new migration into the source control system (e.g. Git, + Mercurial). +3. Doug updates his repository from the source control system and receives + the new migration. +4. Doug applies the migration to his local development database, thereby + synchronizing his database to reflect the changes that Tim has made. + +And the following steps show how to deploy a new release with database +migrations to production: + +1. Scott creates a release tag for the project repository that contains some + new database migrations. +2. Scott updates the source code on the production server to the release + tag. +3. Scott applies any accumulated database migrations to the production + database. + +Yii provides a set of migration command line tools that allow you to: + +* create new migrations; +* apply migrations; +* revert migrations; +* re-apply migrations; +* show migration history and status. + +All these tools are accessible through the command `yii migrate`. In this +section we will describe in detail how to accomplish various tasks using +these tools. + +> [!TIP] +> Migrations could affect not only database schema but adjust existing data to fit new schema, create RBAC +hierarchy or clean up cache. + +> [!NOTE] +> When manipulating data using a migration you may find that using your Active Record or entity classes +> for this might be useful because some of the logic is already implemented there. Keep in mind however, that in contrast +> to code written in the migrations, whose nature is to stay constant forever, application logic is subject to change. +> So when using Active Record or entity classes in migration code, changes to the logic in the source code +> may accidentally break the existing migrations. For this reason migration code should be kept independent of other +> application logic such. + +## Initial configuration + To use migrations, install [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package: ```shell -composer require yiisoft/db-migration +make composer require yiisoft/db-migration ``` -### Example usage +Create a directory to store migrations `src/Migration` right in the project +root. -First, configure a DI container. Create `config/common/db.php` with the -following content: +Add the following configuration to `config/common/params.php`: + +```php +'yiisoft/db-migration' => [ + 'newMigrationNamespace' => 'App\\Migration', + 'sourceNamespaces' => ['App\\Migration'], +], +``` + +If you want to place migrations elsewhere, you can define the path in +`newMigrationPath`. If your migrations to be applied are from multiple +sources, such as external modules, `sourcePaths` could be used to define +these. + +You need a database connection configured as well. See [Working with +databases](../start/databases.md) for an example of configuring it for +PostgreSQL. + +## Creating a migration + +To create a new empty migration, run the following command: + +```sh +make shell +./yii migrate:create +``` + +The required `name` argument gives a brief description about the new +migration. For example, if the migration is about creating a new table named +*news*, you may use the name `create_news_table` and run the following +command: + +``` +make shell +./yii migrate:create create_news_table +``` + + +> [!NOTE] +> Because the `name` argument will be used as part of the generated migration class name, +> it should only contain letters, digits, and/or underscore characters. + +The above command will create a new PHP class file named +`src/Migration/M251225221906CreateNewsTable.php`. The file contains the +following code which mainly declares a migration class with the skeleton +code: ```php [ - 'class' => SqliteConnection::class, - '__construct()' => [ - 'dsn' => 'sqlite:' . __DIR__ . '/Data/yiitest.sq3' - ] - ] -]; +final class M251225221906CreateNewsTable implements RevertibleMigrationInterface +{ + public function up(MigrationBuilder $b): void + { + // TODO: Implement the logic to apply the migration. + } + + public function down(MigrationBuilder $b): void + { + // TODO: Implement the logic to revert the migration. + } +} ``` -Add the following to `config/params.php`: +In the migration class, you are expected to write code in the `up()` method +that makes changes to the database structure. You may also want to write +code in the `down()` method to revert the changes made by `up()`. The `up()` +method is invoked when you upgrade the database with this migration, while +the `down()` method is invoked when you downgrade the database. The +following code shows how you may implement the migration class to create a +`news` table: ```php -... -'yiisoft/db-migration' => [ - 'newMigrationNamespace' => 'App\\Migration', - 'sourceNamespaces' => ['App\\Migration'], -], -... -``` +columnBuilder(); + + $b->createTable('news', [ + 'id' => $cb::uuidPrimaryKey(), + 'title' => $cb::string()->notNull(), + 'content' => $cb::text(), + ]); + } + + public function down(MigrationBuilder $b): void + { + $b->dropTable('news'); + } +} ``` -### Creating a migration +Migration builder `$b` in the above manages database schema while the column +builder `$cb` manages column types. Both allow using *abstract types*. When +a migration is applied to a particular database, the abstract types will be +translated into the corresponding database physical types and corresponding +SQL to define them. + +Methods available in migration builder belong to the following types: + +- Raw queries + - getDb — to get database connection instance. + - execute — to execute raw SQL query. +- Data + - insert / update / delete + - batchInsert + - upsert +- Tables and views + - createTable / renameTable / dropTable + - truncateTable + - addCommentOnTable / dropCommentFromTable + - createView / dropView +- Columns + - addColumn / renameColumn / alterColumn / dropColumn + - addCommentOnColumn / dropCommentFromColumn +- Keys and indexes + - addPrimaryKey / dropPrimaryKey + - addForeignKey / dropForeignKey + - createIndex / dropIndex + +Additionally, there's a `columnBuilder()` which is used to obtain a column +builder as in example above. The builder has static methods that define +various column types: + +- Keys + - primaryKey + - smallPrimaryKey + - bigPrimaryKey + - uuidPrimaryKey +- Boolean + - boolean +- Numbers + - bit + - tinyint + - smallint + - integer + - bigint + - flat + - double + - decimal +- Strings + - char + - string + - text +- Date and time + - timestamp + - datetime + - datetimeWithTimezone + - time + - timeWithTimezone + - date +- Special types + - money + - binary + - uuid + - array + - structured + - json +- enum + +All the above methods create a base type which could be adjusted with +additional methods: + +- null / notNull +- defaultValue +- unique +- scale / size / unsigned +- primaryKey / autoIncrement +- check +- comment +- computed +- extra +- reference -To work with migrations, you can use the provided -[view](https://github.com/yiisoft/db-migration/tree/master/resources/views). +### Irreversible migrations + +Not all migrations are reversible. For example, if the `up()` method deletes +a row of a table, you may not be able to recover this row in the `down()` +method. Sometimes, you may be just too lazy to implement the `down()`, +because it is not very common to revert database migrations. In this case, +you should implement `Yiisoft\Db\Migration\MigrationInterface` that has +`up()` only. + + +### Transactional migrations + +While performing complex DB migrations, it is important to ensure each +migration to either succeed or fail as a whole so that the database can +maintain integrity and consistency. To achieve this goal, it is recommended +that you may enclose the DB operations of each migration in a transaction +automatically by adding `TransactionalMigrationInterface` to `implements` of +your migration. + +As a result, if any operation in the `up()` or `down()` method fails, all +prior operations will be rolled back automatically. + +> Note: Not all DBMS support transactions. And some DB queries cannot be put into a transaction. For some examples, +please refer to [implicit commit](https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html). + +## Generating a migration + +Instead of writing migrations by hand, the command provides a convenient way +generate some of the code. ```shell -./yii migrate:create my_first_table --command=table --fields=name,example --table-comment=my_first_table +make shell +./yii migrate:create -- my_first_table --command=table --fields=name,example --table-comment=my_first_table ``` That would generate the following: @@ -70,19 +309,21 @@ use Yiisoft\Db\Migration\RevertibleMigrationInterface; use Yiisoft\Db\Migration\TransactionalMigrationInterface; /** - * Handles the creation of a table `my_first_table`. + * Handles the creation of table `my_first_table`. */ -final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface +final class M251227095006CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface { public function up(MigrationBuilder $b): void { + $columnBuilder = $b->columnBuilder(); + $b->createTable('my_first_table', [ - 'id' => $b->primaryKey(), + 'id' => $columnBuilder::primaryKey(), 'name', 'example', ]); - - $b->addCommentOnTable('my_first_table', 'dest'); + + $b->addCommentOnTable('my_first_table', 'my_first_table'); } public function down(MigrationBuilder $b): void @@ -92,17 +333,98 @@ final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationI } ``` -For more information -[see](https://github.com/yiisoft/db-migration/tree/master/docs/guide/en) +Commands available are: + +- create - empty migration. +- table - creating a table. Use `--fields` specify a list of fields to + use. Types could be specified as well such as + `id:primaryKey,name:string:defaultValue("Alex"),user_id:integer:foreignKey,category_id2:integer:foreignKey(category + id2)`. +- dropTable - dropping a table. +- addColumn - adding a column. +- dropColumn - dropping a column. +- junction - creating a junction table. Use `--and` specify a second table. + +## Applying Migrations + +To upgrade a database to its latest structure, you should apply all +available new migrations using the following command: + +``` +./yii migrate:up +``` + +This command will list all migrations that have not been applied so far. If +you confirm that you want to apply these migrations, it will run the `up()` +method in every new migration class, one after another, in the order of +their timestamp values. If any of the migrations fails, the command will +quit without applying the rest of the migrations. + +For each migration that has been successfully applied, the command will +insert a row into a database table named `migration` to record the +successful application of the migration. This will allow the migration tool +to identify which migrations have been applied and which have not. + +Sometimes, you may only want to apply one or a few new migrations, instead +of all available migrations. You can do so by specifying the number of +migrations that you want to apply when running the command. For example, +the following command will try to apply the next three available migrations: + +``` +./yii migrate:up --limit=3 +``` + +## Reverting Migrations + +To revert (undo) one or multiple migrations that have been applied before, +you can run the following command: + +``` +./yii migrate:down # revert the most recently applied migration +./yii migrate:down --limit=3 # revert the most 3 recently applied migrations +./yii migrate:down --all # revert all migrations +``` + +> Note: Not all migrations are reversible. Trying to revert such migrations will cause an error and stop the +entire reverting process. + + +## Redoing Migrations + +Redoing migrations means first reverting the specified migrations and then +applying again. This can be done as follows: + +``` +./yii migrate:redo # redo the last applied migration +./yii migrate:redo --limit=3 # redo the last 3 applied migrations +./yii migrate:redo --all # redo all migrations +``` + +> Note: If a migration is not reversible, you will not be able to redo it. + +## Listing Migrations + +To list which migrations have been applied and which are not, you may use +the following commands: + +``` +./yii migrate/history # showing the last 10 applied migrations +./yii migrate:history --limit=5 # showing the last 5 applied migrations +./yii migrate:history --all # showing all applied migrations + +./yii migrate:new # showing the first 10 new migrations +./yii migrate:new --limit=5 # showing the first 5 new migrations +./yii migrate:new --all # showing all new migrations +``` ### Upgrading from Yii 2.0 Migrations in Yii 2.0 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` +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 further changes in the database schema are applied using the new `migration` component and recorded in the new migration table. - diff --git a/src/ru/guide/databases/db-migrations.md b/src/ru/guide/databases/db-migrations.md index 7779b50..196ac40 100644 --- a/src/ru/guide/databases/db-migrations.md +++ b/src/ru/guide/databases/db-migrations.md @@ -1,59 +1,298 @@ # Migrations +During the course of developing and maintaining a database-driven +application, the structure of the database being used evolves just like the +source code does. For example, during the development of an application, a +new table may be found necessary; after the application is deployed to +production, it may be discovered that an index should be created to improve +the query performance; and so on. Because a database structure change often +requires some source code changes, Yii supports the so-called *database +migration* feature that allows you to keep track of database changes in +terms of *database migrations* which are version-controlled together with +the source code. + +The following steps show how database migration can be used by a team during +development: + +1. Tim creates a new migration (e.g. creates a new table, changes a column + definition, etc.). +2. Tim commits the new migration into the source control system (e.g. Git, + Mercurial). +3. Doug updates his repository from the source control system and receives + the new migration. +4. Doug applies the migration to his local development database, thereby + synchronizing his database to reflect the changes that Tim has made. + +And the following steps show how to deploy a new release with database +migrations to production: + +1. Scott creates a release tag for the project repository that contains some + new database migrations. +2. Scott updates the source code on the production server to the release + tag. +3. Scott applies any accumulated database migrations to the production + database. + +Yii provides a set of migration command line tools that allow you to: + +* create new migrations; +* apply migrations; +* revert migrations; +* re-apply migrations; +* show migration history and status. + +All these tools are accessible through the command `yii migrate`. In this +section we will describe in detail how to accomplish various tasks using +these tools. + +> [!TIP] +> Migrations could affect not only database schema but adjust existing data to fit new schema, create RBAC +hierarchy or clean up cache. + +> [!NOTE] +> When manipulating data using a migration you may find that using your Active Record or entity classes +> for this might be useful because some of the logic is already implemented there. Keep in mind however, that in contrast +> to code written in the migrations, whose nature is to stay constant forever, application logic is subject to change. +> So when using Active Record or entity classes in migration code, changes to the logic in the source code +> may accidentally break the existing migrations. For this reason migration code should be kept independent of other +> application logic such. + +## Initial configuration + To use migrations, install [yiisoft/db-migration](https://github.com/yiisoft/db-migration/) package: ```shell -composer require yiisoft/db-migration +make composer require yiisoft/db-migration ``` -### Example usage +Create a directory to store migrations `src/Migration` right in the project +root. -First, configure a DI container. Create `config/common/db.php` with the -following content: +Add the following configuration to `config/common/params.php`: + +```php +'yiisoft/db-migration' => [ + 'newMigrationNamespace' => 'App\\Migration', + 'sourceNamespaces' => ['App\\Migration'], +], +``` + +If you want to place migrations elsewhere, you can define the path in +`newMigrationPath`. If your migrations to be applied are from multiple +sources, such as external modules, `sourcePaths` could be used to define +these. + +You need a database connection configured as well. See [Working with +databases](../start/databases.md) for an example of configuring it for +PostgreSQL. + +## Creating a migration + +To create a new empty migration, run the following command: + +```sh +make shell +./yii migrate:create +``` + +The required `name` argument gives a brief description about the new +migration. For example, if the migration is about creating a new table named +*news*, you may use the name `create_news_table` and run the following +command: + +``` +make shell +./yii migrate:create create_news_table +``` + + +> [!NOTE] +> Because the `name` argument will be used as part of the generated migration class name, +> it should only contain letters, digits, and/or underscore characters. + +The above command will create a new PHP class file named +`src/Migration/M251225221906CreateNewsTable.php`. The file contains the +following code which mainly declares a migration class with the skeleton +code: ```php [ - 'class' => SqliteConnection::class, - '__construct()' => [ - 'dsn' => 'sqlite:' . __DIR__ . '/Data/yiitest.sq3' - ] - ] -]; +final class M251225221906CreateNewsTable implements RevertibleMigrationInterface +{ + public function up(MigrationBuilder $b): void + { + // TODO: Implement the logic to apply the migration. + } + + public function down(MigrationBuilder $b): void + { + // TODO: Implement the logic to revert the migration. + } +} ``` -Add the following to `config/params.php`: +In the migration class, you are expected to write code in the `up()` method +that makes changes to the database structure. You may also want to write +code in the `down()` method to revert the changes made by `up()`. The `up()` +method is invoked when you upgrade the database with this migration, while +the `down()` method is invoked when you downgrade the database. The +following code shows how you may implement the migration class to create a +`news` table: ```php -... -'yiisoft/db-migration' => [ - 'newMigrationNamespace' => 'App\\Migration', - 'sourceNamespaces' => ['App\\Migration'], -], -... -``` +columnBuilder(); + + $b->createTable('news', [ + 'id' => $cb::uuidPrimaryKey(), + 'title' => $cb::string()->notNull(), + 'content' => $cb::text(), + ]); + } + + public function down(MigrationBuilder $b): void + { + $b->dropTable('news'); + } +} ``` -### Creating a migration +Migration builder `$b` in the above manages database schema while the column +builder `$cb` manages column types. Both allow using *abstract types*. When +a migration is applied to a particular database, the abstract types will be +translated into the corresponding database physical types and corresponding +SQL to define them. + +Methods available in migration builder belong to the following types: + +- Raw queries + - getDb — to get database connection instance. + - execute — to execute raw SQL query. +- Data + - insert / update / delete + - batchInsert + - upsert +- Tables and views + - createTable / renameTable / dropTable + - truncateTable + - addCommentOnTable / dropCommentFromTable + - createView / dropView +- Columns + - addColumn / renameColumn / alterColumn / dropColumn + - addCommentOnColumn / dropCommentFromColumn +- Keys and indexes + - addPrimaryKey / dropPrimaryKey + - addForeignKey / dropForeignKey + - createIndex / dropIndex + +Additionally, there's a `columnBuilder()` which is used to obtain a column +builder as in example above. The builder has static methods that define +various column types: + +- Keys + - primaryKey + - smallPrimaryKey + - bigPrimaryKey + - uuidPrimaryKey +- Boolean + - boolean +- Numbers + - bit + - tinyint + - smallint + - integer + - bigint + - flat + - double + - decimal +- Strings + - char + - string + - text +- Date and time + - timestamp + - datetime + - datetimeWithTimezone + - time + - timeWithTimezone + - date +- Special types + - money + - binary + - uuid + - array + - structured + - json +- enum + +All the above methods create a base type which could be adjusted with +additional methods: + +- null / notNull +- defaultValue +- unique +- scale / size / unsigned +- primaryKey / autoIncrement +- check +- comment +- computed +- extra +- reference -To work with migrations, you can use the provided -[view](https://github.com/yiisoft/db-migration/tree/master/resources/views). +### Irreversible migrations + +Not all migrations are reversible. For example, if the `up()` method deletes +a row of a table, you may not be able to recover this row in the `down()` +method. Sometimes, you may be just too lazy to implement the `down()`, +because it is not very common to revert database migrations. In this case, +you should implement `Yiisoft\Db\Migration\MigrationInterface` that has +`up()` only. + + +### Transactional migrations + +While performing complex DB migrations, it is important to ensure each +migration to either succeed or fail as a whole so that the database can +maintain integrity and consistency. To achieve this goal, it is recommended +that you may enclose the DB operations of each migration in a transaction +automatically by adding `TransactionalMigrationInterface` to `implements` of +your migration. + +As a result, if any operation in the `up()` or `down()` method fails, all +prior operations will be rolled back automatically. + +> Note: Not all DBMS support transactions. And some DB queries cannot be put into a transaction. For some examples, +please refer to [implicit commit](https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html). + +## Generating a migration + +Instead of writing migrations by hand, the command provides a convenient way +generate some of the code. ```shell -./yii migrate:create my_first_table --command=table --fields=name,example --table-comment=my_first_table +make shell +./yii migrate:create -- my_first_table --command=table --fields=name,example --table-comment=my_first_table ``` That would generate the following: @@ -70,19 +309,21 @@ use Yiisoft\Db\Migration\RevertibleMigrationInterface; use Yiisoft\Db\Migration\TransactionalMigrationInterface; /** - * Handles the creation of a table `my_first_table`. + * Handles the creation of table `my_first_table`. */ -final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface +final class M251227095006CreateMyFirstTableTable implements RevertibleMigrationInterface, TransactionalMigrationInterface { public function up(MigrationBuilder $b): void { + $columnBuilder = $b->columnBuilder(); + $b->createTable('my_first_table', [ - 'id' => $b->primaryKey(), + 'id' => $columnBuilder::primaryKey(), 'name', 'example', ]); - - $b->addCommentOnTable('my_first_table', 'dest'); + + $b->addCommentOnTable('my_first_table', 'my_first_table'); } public function down(MigrationBuilder $b): void @@ -92,17 +333,98 @@ final class M240115143455CreateMyFirstTableTable implements RevertibleMigrationI } ``` -For more information -[see](https://github.com/yiisoft/db-migration/tree/master/docs/guide/en) +Commands available are: + +- create - empty migration. +- table - creating a table. Use `--fields` specify a list of fields to + use. Types could be specified as well such as + `id:primaryKey,name:string:defaultValue("Alex"),user_id:integer:foreignKey,category_id2:integer:foreignKey(category + id2)`. +- dropTable - dropping a table. +- addColumn - adding a column. +- dropColumn - dropping a column. +- junction - creating a junction table. Use `--and` specify a second table. + +## Applying Migrations + +To upgrade a database to its latest structure, you should apply all +available new migrations using the following command: + +``` +./yii migrate:up +``` + +This command will list all migrations that have not been applied so far. If +you confirm that you want to apply these migrations, it will run the `up()` +method in every new migration class, one after another, in the order of +their timestamp values. If any of the migrations fails, the command will +quit without applying the rest of the migrations. + +For each migration that has been successfully applied, the command will +insert a row into a database table named `migration` to record the +successful application of the migration. This will allow the migration tool +to identify which migrations have been applied and which have not. + +Sometimes, you may only want to apply one or a few new migrations, instead +of all available migrations. You can do so by specifying the number of +migrations that you want to apply when running the command. For example, +the following command will try to apply the next three available migrations: + +``` +./yii migrate:up --limit=3 +``` + +## Reverting Migrations + +To revert (undo) one or multiple migrations that have been applied before, +you can run the following command: + +``` +./yii migrate:down # revert the most recently applied migration +./yii migrate:down --limit=3 # revert the most 3 recently applied migrations +./yii migrate:down --all # revert all migrations +``` + +> Note: Not all migrations are reversible. Trying to revert such migrations will cause an error and stop the +entire reverting process. + + +## Redoing Migrations + +Redoing migrations means first reverting the specified migrations and then +applying again. This can be done as follows: + +``` +./yii migrate:redo # redo the last applied migration +./yii migrate:redo --limit=3 # redo the last 3 applied migrations +./yii migrate:redo --all # redo all migrations +``` + +> Note: If a migration is not reversible, you will not be able to redo it. + +## Listing Migrations + +To list which migrations have been applied and which are not, you may use +the following commands: + +``` +./yii migrate/history # showing the last 10 applied migrations +./yii migrate:history --limit=5 # showing the last 5 applied migrations +./yii migrate:history --all # showing all applied migrations + +./yii migrate:new # showing the first 10 new migrations +./yii migrate:new --limit=5 # showing the first 5 new migrations +./yii migrate:new --all # showing all new migrations +``` ### Upgrading from Yii 2.0 Migrations in Yii 2.0 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` +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 further changes in the database schema are applied using the new `migration` component and recorded in the new migration table. -