diff --git a/code_samples/data_migration/examples/sql_execute.yaml b/code_samples/data_migration/examples/sql_execute.yaml new file mode 100644 index 0000000000..c11ca0bb4a --- /dev/null +++ b/code_samples/data_migration/examples/sql_execute.yaml @@ -0,0 +1,13 @@ +- + type: sql + mode: execute + query: + - + driver: mysql + sql: 'INSERT INTO test_table (test_value) VALUES ("foo");' + - + driver: sqlite + sql: 'INSERT INTO test_table (test_value) VALUES ("foo");' + - + driver: postgresql + sql: "INSERT INTO test_table (test_value) VALUES ('foo');" diff --git a/code_samples/data_migration/examples/try_catch_step.yaml b/code_samples/data_migration/examples/try_catch_step.yaml new file mode 100644 index 0000000000..389e219ace --- /dev/null +++ b/code_samples/data_migration/examples/try_catch_step.yaml @@ -0,0 +1,14 @@ +- + type: try_catch + mode: execute + allowed_exceptions: + - Throwable + stop_after_first_exception: true + steps: + - + type: language + mode: create + metadata: + languageCode: ger-DE + name: German + enabled: true diff --git a/docs/content_management/data_migration/importing_data.md b/docs/content_management/data_migration/importing_data.md index 4af7563dc6..c228b9313f 100644 --- a/docs/content_management/data_migration/importing_data.md +++ b/docs/content_management/data_migration/importing_data.md @@ -74,6 +74,14 @@ The following data migration step modes are available: | `user` | ✔ | ✔ | | | | | `user_group` | ✔ | ✔ | ✔ | | | +Additionally, the following special migration types are available: + +| `type` | `execute` | +|------------------------|:---------:| +| `repeatable` | ✔ | +| `sql` | ✔ | +| `try_catch` | ✔ | + ### Repeatable steps You can run a set of one or more similar migration steps multiple times by using the special `repeatable` migration type. @@ -122,6 +130,58 @@ Then, you can use `faker()` in expressions, for example: This step generates field values with fake personal names. +### SQL migrations + +You can execute raw SQL queries directly in migrations by using the `sql` migration type. +Use it for custom database operations that don't fit into standard entity migrations, such as creating custom tables or performing bulk updates. + +Each query requires a `driver` property that specifies which database system the query is for. +The migration system automatically filters queries and executes only those matching your current database driver. + +```yaml +[[= include_file('code_samples/data_migration/examples/sql_execute.yaml') =]] +``` + +The supported database drivers are: + +- `mysql` - MySQL/MariaDB +- `postgresql` - PostgreSQL +- `sqlite` - SQLite + +You can define queries for multiple database drivers in a single migration step. +The system executes only the queries that match your configured database platform. +If no matching queries are found, the migration throws an error. + +!!! caution + + SQL migrations bypass the content model abstraction layer and directly modify the database. + Use them with caution and ensure your queries are compatible with your target database system. + +### Error handling with try-catch + +You can wrap one or more migration steps with a `try_catch` step to handle exceptions gracefully. + +Use it for migrations that may fail under specific conditions but should not halt the entire migration process. + +For example, you can ensure a language creation migration succeeds even if the language already exists. +If the migration fails for this reason, the exception is suppressed, allowing the remaining migrations to proceed without interruption. + +A `try_catch` migration requires the `steps` property and accepts optional `allowed_exceptions` and `stop_after_first_exception` settings. + +Default values are: + +- `allowed_exceptions`: empty list +- `stop_after_first_exception`: `true` + +```yaml +[[= include_file('code_samples/data_migration/examples/try_catch_step.yaml') =]] +``` + +When an exception is thrown within a try-catch step, it's compared against the list of `allowed_exceptions`. +If the exception matches, it's caught and the migration continues or stops depending on the `stop_after_first_exception` configuration setting. +The migration is marked as successful. +Non-matching exceptions throw immediately, halting the migration process and returning an error. + ### Expression syntax You can use [Symfony expression syntax]([[= symfony_doc =]]/reference/formats/expression_language.html) in data migrations, like in [repeatable steps](#repeatable-steps), where you can use it to generate varied content in migration steps. diff --git a/docs/release_notes/ibexa_dxp_v5.0.md b/docs/release_notes/ibexa_dxp_v5.0.md index 074b312180..3f8dcedfca 100644 --- a/docs/release_notes/ibexa_dxp_v5.0.md +++ b/docs/release_notes/ibexa_dxp_v5.0.md @@ -10,6 +10,22 @@ month_change: false
+ +#### Try-catch support in data migrations + +Data migrations now support try-catch error handling, allowing you to wrap migration steps with exception handling logic. +You can use it for migrations that might fail under certain conditions but should not break the entire migration process. + +For example, you can create languages without checking if they already exist: + +``` yaml +[[= include_file('code_samples/data_migration/examples/try_catch_step.yaml') =]] +``` + +The try-catch step allows you to specify which exceptions to catch and whether to continue executing remaining steps after an exception occurs. + +For more information, see [Error handling with try-catch](importing_data.md#error-handling-with-try-catch). + [[% set version = 'v5.0.5' %]] [[= release_note_entry_begin("Ibexa DXP " + version, '2026-01-15', ['Headless', 'Experience', 'Commerce']) =]]