diff --git a/docs/update_and_migration/doctrine_migrations.md b/docs/update_and_migration/doctrine_migrations.md new file mode 100644 index 0000000000..170086e4f8 --- /dev/null +++ b/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? diff --git a/docs/update_and_migration/from_4.6/update_from_4.6.md b/docs/update_and_migration/from_4.6/update_from_4.6.md index 70949ef346..7d69c8c3e8 100644 --- a/docs/update_and_migration/from_4.6/update_from_4.6.md +++ b/docs/update_and_migration/from_4.6/update_from_4.6.md @@ -734,6 +734,25 @@ In addition, consider upgrading your project to one of [the actively supported P 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//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. diff --git a/docs/update_and_migration/from_4.6/update_to_5.0.md b/docs/update_and_migration/from_4.6/update_to_5.0.md index 9217395f37..f96845875f 100644 --- a/docs/update_and_migration/from_4.6/update_to_5.0.md +++ b/docs/update_and_migration/from_4.6/update_to_5.0.md @@ -14,9 +14,9 @@ Before you update to v5.0, you need to [update to the latest maintenance release 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 @@ rm -r config/graphql #### 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 @@ Notice the use of the `--no-update` option to only edit the `composer.json` entr # 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 @@ Notice the use of the `--no-update` option to only edit the `composer.json` entr # 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 @@ Notice the use of the `--no-update` option to only edit the `composer.json` entr # 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 @@ composer run-script post-update-cmd [[% 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 -p < vendor/ibexa/installer/upgrade/db/mysql/ibexa-4.6.latest-to-5.0.0.sql - ``` - -=== "PostgreSQL" - - ```bash - psql < 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=` 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 @@ composer ibexa:setup --platformsh #### 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.