diff --git a/docs/commerce/shopping_list/install_shopping_list.md b/docs/commerce/shopping_list/install_shopping_list.md index 1c5d0829ca..dd289d1710 100644 --- a/docs/commerce/shopping_list/install_shopping_list.md +++ b/docs/commerce/shopping_list/install_shopping_list.md @@ -40,6 +40,8 @@ ibexa.rest.shopping_list: Add the tables needed by the bundle: +TODO: Ibexa Doctrine Migrations + === "MySQL" ```sql 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 157a477af4..fbe24f7067 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 @@ -738,6 +738,37 @@ No additional steps needed. No additional steps needed. +## v4.6.33 + +### Database update + +With v4.6.33, [[= product_name_base =]] introduces Doctrine migrations to manage database schema changes. +With [[= product_name_base =]] Doctrine migrations, you no longer have to run the SQL upgrade scripts. +The `ibexa/doctrine-migrations` package is installed automatically as a dependency of [[= product_name =]]'s packages, so no separate installation step is required. + +[[% include 'snippets/update/db/db_backup_warning.md' %]] + +Run the following command to apply all database migrations present in your currently installed code: + +```bash +php bin/console ibexa:doctrine:migrations:migrate +``` + +If your project uses [multiple repositories](repository_configuration.md#defining-custom-connection) with separate databases, run the command once per repository. +Running the command more than once is safe. +It has no effect if you apply it to a SiteAccess whose repository has already been migrated. + +[[= product_name_base =]] Doctrine migrations only manage [[= product_name =]]'s own database tables. +Your custom tables are not affected, even if you also manage them with standard Doctrine migrations. + +!!! caution "Command scope" + + This command isn't a full schema conformity checker. + It checks for the presence of key elements (such as a column or table) to determine whether a change has already been applied. + If a past upgrade was partially applied to your database, Doctrine migrations can be misled into marking the migration as complete when it isn't. + + Always back up your database and test this command in a non-production environment first. + ## 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 5e805b8878..5e30c9061c 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 @@ -9,14 +9,21 @@ month_change: true Before you update to v5.0, you need to [update to the latest maintenance release of v4.6 (v[[= latest_tag_4_6 =]])](update_from_4.6.md). +!!! caution Database migration sequence" + + Before you update the database, make sure that you run `ibexa:doctrine:migrations:migrate` when your project is on the latest v4.6.x patch version. + See [Database update](update_from_4.6.md#database-update). + + Running v5.0 migrations on a database when v4.6 migrations are not applied can cause schema inconsistencies. + ### Move from old to new Commerce 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 +117,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 +129,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 +154,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 +179,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 +315,31 @@ 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: - -=== "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" +Doctrine migrations manage the database schema updates. +The following command migrates your database from the v4.6 schema to the v5.0 schema: - If you don't have access to [[= product_name =]]'s `ibexa/installer` package, apply the following database update: - - === "MySQL" +```bash +php bin/console ibexa:doctrine:migrations:migrate +``` - ``` sql - [[= include_file('docs/update_and_migration/from_4.6/sql/ibexa_oss_4.6.latest-to-5.0.0_mysql.sql', glue=" ") =]] - ``` +If your project uses [multiple repositories](repository_configuration.md#defining-custom-connection) with separate databases, run the command once per repository. +Running the command more than once is safe. +It has no effect if you apply it to a SiteAccess whose repository has already been migrated. - === "PostgreSQL" +Doctrine migrations only manage [[= product_name =]]'s own database tables. +Your custom tables are not affected, even if you also manage them with standard Doctrine migrations. - ``` sql - [[= include_file('docs/update_and_migration/from_4.6/sql/ibexa_oss_4.6.latest-to-5.0.0_postgresql.sql', glue=" ") =]] - ``` +!!! caution "Command scope" -As this script targets all editions, on editions lower than Commerce you may encounter errors about missing tables which can safely be ignored. + This command isn't a full schema conformity checker. + It checks for the presence of key elements (such as a column or table) to determine whether a change has already been applied. + If a past upgrade was partially applied to your database, Doctrine migrations can be misled into marking the migration as complete when it isn't. -Many tables and columns are renamed. -If you have custom code directly querying those, you will need to update them. +!!! caution "Command scope" -You can track the renaming in the `ibexa-4.6.latest-to-5.0.0.sql` file or below. + Many tables and columns are renamed between v4.6 and v5.0. + If you have custom code that directly queries those, you need to update them. + You can track the renaming below. ??? note "Tables and columns renaming map" @@ -432,7 +428,7 @@ You can track the renaming in the `ibexa-4.6.latest-to-5.0.0.sql` file or below. ??? note "DFS (Distributed File System)" If [DFS IO handler](clustering.md#dfs-io-handler) is used and, as recommended, its table is on its own database, you'll have to rename table and columns there. - Here are the DFS renaming queries (extracted from `ibexa-4.6.latest-to-5.0.0.sql`): + Here are the DFS renaming queries: ```sql ALTER TABLE ezdfsfile RENAME TO ibexa_dfs_file; @@ -487,6 +483,7 @@ return RectorConfig::configure() SymfonySetList::SYMFONY_71, // https://getrector.com/find-rule?activeRectorSetGroup=symfony&rectorSet=symfony-symfonysymfony-71 SymfonySetList::SYMFONY_72, // https://getrector.com/find-rule?activeRectorSetGroup=symfony&rectorSet=symfony-symfonysymfony-72 SymfonySetList::SYMFONY_73, // https://getrector.com/find-rule?activeRectorSetGroup=symfony&rectorSet=symfony-symfonysymfony-73 + SymfonySetList::SYMFONY_74, // https://getrector.com/find-rule?activeRectorSetGroup=symfony&rectorSet=symfony-symfonysymfony-74 SymfonySetList::ANNOTATIONS_TO_ATTRIBUTES, ] ) @@ -1127,5 +1124,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 project is now running [[= product_name =]] v5.0, with packages and database schema both up to date. + +To learn about cnfiguration updates, PHP API changes, or other changes introduced between v5.0.0 and v[[= latest_tag_5_0 =]] that aren't related to the database, see [Update from v5.0.x to v5.0.latest](update_from_5.0.md). diff --git a/docs/users/oauth_server.md b/docs/users/oauth_server.md index d61f152fc3..12650e9aeb 100644 --- a/docs/users/oauth_server.md +++ b/docs/users/oauth_server.md @@ -20,6 +20,8 @@ composer require ibexa/oauth2-server --with-all-dependencies Add the tables needed by the bundle: +TODO: Ibexa Doctrine Migrations + === "MySQL" ```bash diff --git a/mkdocs.yml b/mkdocs.yml index 2a0d484018..133e0d3248 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -933,6 +933,7 @@ nav: - Migrate from eZ Publish Platform: update_and_migration/migrate_to_ibexa_dxp/migrating_from_ez_publish_platform.md - Migrate from eZ Publish: update_and_migration/migrate_to_ibexa_dxp/migrating_from_ez_publish.md - Common migration issues: update_and_migration/migrate_to_ibexa_dxp/common_issues.md + - Edition upgrade: update_and_migration/edition_upgrade.md - Resources: - Resources: resources/resources.md - Release process and roadmap: resources/release_process_and_roadmap.md