From c5e21fdbbdc3645e9cadb15f9c6da496b89181ef Mon Sep 17 00:00:00 2001 From: alexmerlin Date: Wed, 24 Sep 2025 09:54:31 +0300 Subject: [PATCH 1/3] Issue #133: Added instructions to create migration Signed-off-by: alexmerlin --- docs/book/v6/installation/doctrine-orm.md | 30 ++++++++++++++++------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/docs/book/v6/installation/doctrine-orm.md b/docs/book/v6/installation/doctrine-orm.md index ddcd98a5..0788c2d9 100644 --- a/docs/book/v6/installation/doctrine-orm.md +++ b/docs/book/v6/installation/doctrine-orm.md @@ -2,19 +2,31 @@ ## Setup database -Make sure you fill out the database credentials in `config/autoload/local.php` under `$databases['default']`. +Use an existing empty one or create a new **MariaDB**/**MySQL** database. -Create a new MySQL database - set collation to `utf8mb4_general_ci` +> Recommended collation: `utf8mb4_general_ci`. -## Running migrations +With a database created, fill out the database connection params in `config/autoload/local.php` under `$databases['default']`. -Run the database migrations by using the following command: +#### Creating migrations + +Create a new migration by running: + +```shell +php ./vendor/bin/doctrine-migrations diff +``` + +The new migration file will be placed in `src/Core/src/App/src/Migration/`. + +#### Running migrations + +Execute a new migration by running: ```shell -php vendor/bin/doctrine-migrations migrate +php ./vendor/bin/doctrine-migrations migrate ``` -This command will prompt you to confirm that you want to run it. +This command will prompt you to confirm that you want to run it: > WARNING! You are about to execute a migration in database "..." that could result in schema changes and data loss. Are you sure you wish to continue? (yes/no) [yes]: @@ -27,7 +39,7 @@ Hit `Enter` to confirm the operation. To list all the fixtures, run: ```shell -php bin/doctrine fixtures:list +php ./bin/doctrine fixtures:list ``` This will output all the fixtures in the order of execution. @@ -35,13 +47,13 @@ This will output all the fixtures in the order of execution. To execute all fixtures, run: ```shell -php bin/doctrine fixtures:execute +php ./bin/doctrine fixtures:execute ``` To execute a specific fixture, run: ```shell -php bin/doctrine fixtures:execute --class=FixtureClassName +php ./bin/doctrine fixtures:execute --class=FixtureClassName ``` More details on how fixtures work can be found on [dot-data-fixtures documentation](https://github.com/dotkernel/dot-data-fixtures#creating-fixtures) From c4f902069f4188c0bc8469f880bddd094f62e936 Mon Sep 17 00:00:00 2001 From: alexmerlin Date: Wed, 24 Sep 2025 09:56:55 +0300 Subject: [PATCH 2/3] Issue #133: Added instructions to create migration Signed-off-by: alexmerlin --- docs/book/v6/installation/doctrine-orm.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/book/v6/installation/doctrine-orm.md b/docs/book/v6/installation/doctrine-orm.md index 0788c2d9..ee2c657e 100644 --- a/docs/book/v6/installation/doctrine-orm.md +++ b/docs/book/v6/installation/doctrine-orm.md @@ -8,7 +8,7 @@ Use an existing empty one or create a new **MariaDB**/**MySQL** database. With a database created, fill out the database connection params in `config/autoload/local.php` under `$databases['default']`. -#### Creating migrations +### Creating migrations Create a new migration by running: @@ -18,7 +18,7 @@ php ./vendor/bin/doctrine-migrations diff The new migration file will be placed in `src/Core/src/App/src/Migration/`. -#### Running migrations +### Running migrations Execute a new migration by running: @@ -32,7 +32,7 @@ This command will prompt you to confirm that you want to run it: Hit `Enter` to confirm the operation. -## Executing fixtures +### Executing fixtures **Fixtures are used to seed the database with initial values and should be executed after migrating the database.** From 3ce94030de8153941dcf82a972a13b5df936840a Mon Sep 17 00:00:00 2001 From: alexmerlin Date: Wed, 24 Sep 2025 10:13:44 +0300 Subject: [PATCH 3/3] Issue #133: Added instructions to create migration Signed-off-by: alexmerlin --- docs/book/v6/installation/doctrine-orm.md | 56 +++++++++++++++++++---- 1 file changed, 48 insertions(+), 8 deletions(-) diff --git a/docs/book/v6/installation/doctrine-orm.md b/docs/book/v6/installation/doctrine-orm.md index ee2c657e..82cce92b 100644 --- a/docs/book/v6/installation/doctrine-orm.md +++ b/docs/book/v6/installation/doctrine-orm.md @@ -1,16 +1,36 @@ # Doctrine ORM -## Setup database +This step saves the database connection credentials in an API configuration file. +We do not cover the creation steps of the database itself. -Use an existing empty one or create a new **MariaDB**/**MySQL** database. +## Setup database -> Recommended collation: `utf8mb4_general_ci`. +Create a new **MariaDB**/**MySQL** database and set its collation to `utf8mb4_general_ci`. + +Make sure you fill out the database credentials in `config/autoload/local.php` under `$databases['default']`. +Below is the item you need to focus on: + +```php +$databases = [ + 'default' => [ + 'host' => 'localhost', + 'dbname' => 'my_database', + 'user' => 'my_user', + 'password' => 'my_password', + 'port' => 3306, + 'driver' => 'pdo_mysql', + 'charset' => 'utf8mb4', + 'collate' => 'utf8mb4_general_ci', + ], + // you can add more database connections into this array +]; +``` -With a database created, fill out the database connection params in `config/autoload/local.php` under `$databases['default']`. +> `my_database`, `my_user`, `my_password` are provided only as an example. ### Creating migrations -Create a new migration by running: +Create a database migration by executing the following command: ```shell php ./vendor/bin/doctrine-migrations diff @@ -20,17 +40,37 @@ The new migration file will be placed in `src/Core/src/App/src/Migration/`. ### Running migrations -Execute a new migration by running: +Run the database migrations by executing the following command: ```shell php ./vendor/bin/doctrine-migrations migrate ``` -This command will prompt you to confirm that you want to run it: +> If you have already run the migrations, you may get the below message: + +```text +WARNING! You have x previously executed migrations in the database that are not registered migrations. + {migration list} +Are you sure you wish to continue? (y/n) +``` + +> In this case, you should double-check to make sure the new migrations are ok to run. -> WARNING! You are about to execute a migration in database "..." that could result in schema changes and data loss. Are you sure you wish to continue? (yes/no) [yes]: +When using an empty database, you will get this confirmation message: + +```text +WARNING! You are about to execute a migration in database "" that could result in schema changes and data loss. Are you sure you wish to continue? (yes/no) +``` Hit `Enter` to confirm the operation. +This will run all the migrations in chronological order. +Each migration will be logged in the `migrations` table to prevent running the same migration more than once, which is often not desirable. + +If everything ran correctly, you will get this confirmation. + +```text +[OK] Successfully migrated to version: Core\App\Migration\VersionYYYYMMDDHHMMSS +``` ### Executing fixtures