Ibexa Doctrine Migrations

docs/update_and_migration/doctrine_migrations.md

@@ -0,0 +1,33 @@
+---
+description: Update your installation's database schema.
+month_change: true
+---
+
+# Ibexa Doctrine Migrations
+
+Ibexa Doctrine Migrations is a tool to update your installation's database schema introduced in v6.0.0, v5.0.Y, and v4.6.3X for all editions.
+It helps when moving to the latest patch version, it also helps when moving to a upper major version or to an upper edition of the product.
+
+To be able to take advantage of Ibexa Doctrine Migrations, you need to be on a version including it.
+Before changing your major version or your edition, move to the latest patch version of your current major version and edition.
+
+TODO: For example:
+
+- Headless v4.6.x [→ Headless v4.6.latest](update_from_4.6.md) [→ Headless v5.0.latest](update_to_5.0.md)
+- Headless v5.0.x [→ Headless v5.0.latest](update_from_5.0.md) [→ Commerce v5.0.latest](#)
+- Headless v4.6.x → Headless v4.6.latest → Headless v5.0.latest → Commerce v5.0.latest
+
+## Upgrade product edition
+
+TODO: Isn't it the main topic of this page?
+
+Before starting, ensure you have the latest version of your current edition.
+
+TODO:
+
+```bash
+composer require ibexa/commerce:[[= latest_tag_5_0 =]]
+php bin/console ibexa:doctrine:migrations:migrate
+```
+
+TODO: Config?

docs/update_and_migration/from_4.6/update_from_4.6.md

@@ -734,6 +734,25 @@
 
 No additional steps needed.
 
+## v4.6.3X
+
+### Database update
+
+v4.6.3X introduces [Ibexa Doctrine Migrations](doctrine_migrations.md) to manage database schema changes.
+It replaces the previous usage of SQL files (like vendor/ibexa/installer/upgrade/db/<server>/ibexa-x.y.a-to-x.y.b.sql).
+
+Run the following to run a basic schema check and store the database status.
+
+```bash
+php bin/console ibexa:doctrine:migrations:migrate
+```
+
+!!! caution
+
+    Notice that this command isn't a full schema conformity checker.
+    It tests the presence of key elements to determine if a previous change has been applied or not.
+    If, in the past, you had incomplete schema upgrades, Ibexa Doctring Migrations command can be misled into considering a change as fully applied while it's only partially applied.
+
 ## LTS Updates
 
 [LTS Updates](https://doc.ibexa.co/en/4.6/ibexa_products/editions/#lts-updates) are standalone packages with their own update procedures.

docs/update_and_migration/from_4.6/update_to_5.0.md

@@ -14,9 +14,9 @@
 If you've chosen to use the [deprecated Commerce packages](update_from_4.3_old_commerce.md) during the update to 4.4,
 you have to move to [new Commerce ones](update_from_4.3_new_commerce.md).
 
-## Update from v4.6.latest to v5.0.0
+## Update from v4.6.latest to v5.0.latest
 
-When you have the last version of 4.6, you can update to v5.0.0.
+When you have the last version of 4.6, you can update to last version of 5.0 (v[[= latest_tag_5_0 =]]).
 
 ### Requirements
 
@@ -110,7 +110,7 @@
 
 #### Update package requirements
 
-[[= product_name =]] 5.0 is based on Symfony 7.3 and both must be updated.
+[[= product_name =]] 5.0 is based on Symfony 7.4 (since v5.0.7) and both must be updated.
 Your development packages must be updated as well.
 The example below assumes that [`symfony/debug-pack`](https://symfony.com/packages/debug-pack) and `ibexa/rector` are installed.
 Adjust the list based on your project requirements.
@@ -122,22 +122,22 @@
     # Update required PHP version
     composer require --no-update 'php:>=8.3';
     # Update required Symfony version
-    composer config extra.symfony.require '7.3.*'
+    composer config extra.symfony.require '7.4.*'
     # Upgrade Ibexa and Symfony packages: application
     composer require --no-update \
         ibexa/headless:[[= latest_tag_5_0 =]] \
-        symfony/console:^7.3 \
-        symfony/dotenv:^7.3 \
-        symfony/framework-bundle:^7.3 \
-        symfony/runtime:^7.3 \
-        symfony/yaml:^7.3 \
+        symfony/console:^7.4 \
+        symfony/dotenv:^7.4 \
+        symfony/framework-bundle:^7.4 \
+        symfony/runtime:^7.4 \
+        symfony/yaml:^7.4 \
     ;
     # Upgrade Ibexa and Symfony packages: development tools
     composer require --dev --no-update \
         ibexa/rector:[[= latest_tag_5_0 =]] \
-        symfony/debug-bundle:^7.3 \
-        symfony/stopwatch:^7.3 \
-        symfony/web-profiler-bundle:^7.3 \
+        symfony/debug-bundle:^7.4 \
+        symfony/stopwatch:^7.4 \
+        symfony/web-profiler-bundle:^7.4 \
     ;
     ```
 
@@ -147,22 +147,22 @@
     # Update required PHP version
     composer require --no-update 'php:>=8.3';
     # Update required Symfony version
-    composer config extra.symfony.require '7.3.*'
+    composer config extra.symfony.require '7.4.*'
     # Upgrade Ibexa and Symfony packages: application
     composer require --no-update \
         ibexa/experience:[[= latest_tag_5_0 =]] \
-        symfony/console:^7.3 \
-        symfony/dotenv:^7.3 \
-        symfony/framework-bundle:^7.3 \
-        symfony/runtime:^7.3 \
-        symfony/yaml:^7.3 \
+        symfony/console:^7.4 \
+        symfony/dotenv:^7.4 \
+        symfony/framework-bundle:^7.4 \
+        symfony/runtime:^7.4 \
+        symfony/yaml:^7.4 \
     ;
     # Upgrade Ibexa and Symfony packages: development tools
     composer require --dev --no-update \
         ibexa/rector:[[= latest_tag_5_0 =]] \
-        symfony/debug-bundle:^7.3 \
-        symfony/stopwatch:^7.3 \
-        symfony/web-profiler-bundle:^7.3 \
+        symfony/debug-bundle:^7.4 \
+        symfony/stopwatch:^7.4 \
+        symfony/web-profiler-bundle:^7.4 \
     ;
     ```
 
@@ -172,22 +172,22 @@
     # Update required PHP version
     composer require --no-update 'php:>=8.3';
     # Update required Symfony version
-    composer config extra.symfony.require '7.3.*'
+    composer config extra.symfony.require '7.4.*'
     # Upgrade Ibexa and Symfony packages: application
     composer require --no-update \
         ibexa/commerce:[[= latest_tag_5_0 =]] \
-        symfony/console:^7.3 \
-        symfony/dotenv:^7.3 \
-        symfony/framework-bundle:^7.3 \
-        symfony/runtime:^7.3 \
-        symfony/yaml:^7.3 \
+        symfony/console:^7.4 \
+        symfony/dotenv:^7.4 \
+        symfony/framework-bundle:^7.4 \
+        symfony/runtime:^7.4 \
+        symfony/yaml:^7.4 \
     ;
     # Upgrade Ibexa and Symfony packages: development tools
     composer require --dev --no-update \
         ibexa/rector:[[= latest_tag_5_0 =]] \
-        symfony/debug-bundle:^7.3 \
-        symfony/stopwatch:^7.3 \
-        symfony/web-profiler-bundle:^7.3 \
+        symfony/debug-bundle:^7.4 \
+        symfony/stopwatch:^7.4 \
+        symfony/web-profiler-bundle:^7.4 \
     ;
     ```
 
@@ -308,42 +308,18 @@
 
 [[% include 'snippets/update/db/db_backup_warning.md' %]]
 
-The main schema has changed and the provided SQL file `ibexa-4.6.latest-to-5.0.0.sql` updates it:
+[Ibexa Doctrine Migrations](doctrine_migrations.md) manage the database schema update.
+The following command will migrate from the 4.6's schema to 5.0's one:
 
-=== "MySQL"
-
-    ```bash
-    mysql -u <username> -p <password> <database_name> < vendor/ibexa/installer/upgrade/db/mysql/ibexa-4.6.latest-to-5.0.0.sql
-    ```
-
-=== "PostgreSQL"
-
-    ```bash
-    psql <database_name> < vendor/ibexa/installer/upgrade/db/postgresql/ibexa-4.6.latest-to-5.0.0.sql
-    ```
-
-??? note "Ibexa Open Source"
-
-    If you don't have access to [[= product_name =]]'s `ibexa/installer` package, apply the following database update:
-
-    === "MySQL"
-
-        ``` sql
-        [[= include_file('docs/update_and_migration/from_4.6/sql/ibexa_oss_4.6.latest-to-5.0.0_mysql.sql', glue="        ") =]]
-        ```
-
-    === "PostgreSQL"
-
-        ``` sql
-        [[= include_file('docs/update_and_migration/from_4.6/sql/ibexa_oss_4.6.latest-to-5.0.0_postgresql.sql', glue="        ") =]]
-        ```
+```bash
+php bin/console ibexa:doctrine:migrations:migrate
+```
 
-As this script targets all editions, on editions lower than Commerce you may encounter errors about missing tables which can safely be ignored.
+If you're using [multiple repositories](repository_configuration.md#defining-custom-connection), run the command with option `--siteaccess=<siteaccess>` for each repository with a SiteAccess using it.
 
-Many tables and columns are renamed.
+Many tables and columns are renamed between 4.6 and 5.0.
 If you have custom code directly querying those, you will need to update them.
-
-You can track the renaming in the `ibexa-4.6.latest-to-5.0.0.sql` file or below.
+You can track the renaming below.
 
 ??? note "Tables and columns renaming map"
 
@@ -1109,5 +1085,6 @@
 
 #### Conclusion
 
-Your project is now running the latest major version of [[= product_name =]].
-To reach the last patch version, see [Update from v5.0.x to v5.0.latest](update_from_5.0.md)
+Your packages and database are now update to date.
+
+TODO: Look in [Update from v5.0.x to v5.0.latest](update_from_5.0.md) for configuration updates, PHP API usage modifications, and every change between v5.0.0 and v[[= latest_tag_5_0 =]] that isn't related to database.