From 2d4d14f5c1954d4767605800ee9b2c83af7f1d3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Wed, 11 Feb 2026 10:07:25 +0100 Subject: [PATCH 1/5] Added doc for try_catch and sql in migrations --- .../data_migration/examples/sql_execute.yaml | 13 +++++ .../examples/try_catch_step.yaml | 14 +++++ .../data_migration/importing_data.md | 54 +++++++++++++++++++ docs/release_notes/ibexa_dxp_v5.0.md | 14 +++++ 4 files changed, 95 insertions(+) create mode 100644 code_samples/data_migration/examples/sql_execute.yaml create mode 100644 code_samples/data_migration/examples/try_catch_step.yaml 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..746354d9d0 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,52 @@ 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 using the `sql` migration type. +This is useful 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 will execute 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. + +This is useful 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. + +```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 default value of `stop_after_first_exception` is `true`. + ### 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..822f7f04e0 100644 --- a/docs/release_notes/ibexa_dxp_v5.0.md +++ b/docs/release_notes/ibexa_dxp_v5.0.md @@ -59,6 +59,20 @@ when@prod: The [Collaborative editing](collaborative_editing.md) REST API endpoints are now included in the [OpenAPI-based REST API reference](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Collaboration-Sessions). + +#### Try-catch support in data migrations + +Data migrations now support try-catch error handling, allowing you to wrap migration steps with exception handling logic. +This is useful 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: + +[[= 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). + ### Full changelog [[% include 'snippets/release_50.md' %]] From 9d284c5e6e41adf9735ad41b207a1fe0205c5d63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Wed, 11 Feb 2026 10:10:26 +0100 Subject: [PATCH 2/5] Vale suggestions --- .../data_migration/importing_data.md | 10 +++---- docs/release_notes/ibexa_dxp_v5.0.md | 28 +++++++++---------- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/content_management/data_migration/importing_data.md b/docs/content_management/data_migration/importing_data.md index 746354d9d0..7e85052627 100644 --- a/docs/content_management/data_migration/importing_data.md +++ b/docs/content_management/data_migration/importing_data.md @@ -133,7 +133,7 @@ This step generates field values with fake personal names. ### SQL migrations You can execute raw SQL queries directly in migrations using the `sql` migration type. -This is useful for custom database operations that don't fit into standard entity migrations, such as creating custom tables or performing bulk updates. +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. @@ -145,11 +145,11 @@ The migration system automatically filters queries and executes only those match The supported database drivers are: - `mysql` - MySQL/MariaDB -- `postgresql` - PostgreSQL +- `postgresql` - PostgreSQL - `sqlite` - SQLite You can define queries for multiple database drivers in a single migration step. -The system will execute only the queries that match your configured database platform. +The system executes only the queries that match your configured database platform. If no matching queries are found, the migration throws an error. !!! caution @@ -161,9 +161,9 @@ If no matching queries are found, the migration throws an error. You can wrap one or more migration steps with a `try_catch` step to handle exceptions gracefully. -This is useful for migrations that may fail under specific conditions but should not halt the entire migration process. +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. +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. diff --git a/docs/release_notes/ibexa_dxp_v5.0.md b/docs/release_notes/ibexa_dxp_v5.0.md index 822f7f04e0..7a5961bc6e 100644 --- a/docs/release_notes/ibexa_dxp_v5.0.md +++ b/docs/release_notes/ibexa_dxp_v5.0.md @@ -10,6 +10,20 @@ 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: + +[[= 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']) =]] @@ -59,20 +73,6 @@ when@prod: The [Collaborative editing](collaborative_editing.md) REST API endpoints are now included in the [OpenAPI-based REST API reference](/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Collaboration-Sessions). - -#### Try-catch support in data migrations - -Data migrations now support try-catch error handling, allowing you to wrap migration steps with exception handling logic. -This is useful 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: - -[[= 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). - ### Full changelog [[% include 'snippets/release_50.md' %]] From a65cedc0135aa6fb39a143543100c5f3b343ad2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Wed, 11 Feb 2026 10:16:56 +0100 Subject: [PATCH 3/5] Vale suggestion --- docs/content_management/data_migration/importing_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/data_migration/importing_data.md b/docs/content_management/data_migration/importing_data.md index 7e85052627..dbb106a35d 100644 --- a/docs/content_management/data_migration/importing_data.md +++ b/docs/content_management/data_migration/importing_data.md @@ -132,7 +132,7 @@ This step generates field values with fake personal names. ### SQL migrations -You can execute raw SQL queries directly in migrations using the `sql` migration type. +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. From e9be6992a2469c8355dadbc3a04b4ade6feff14f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Wed, 11 Feb 2026 10:22:29 +0100 Subject: [PATCH 4/5] Added missing code block --- docs/release_notes/ibexa_dxp_v5.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/release_notes/ibexa_dxp_v5.0.md b/docs/release_notes/ibexa_dxp_v5.0.md index 7a5961bc6e..3f8dcedfca 100644 --- a/docs/release_notes/ibexa_dxp_v5.0.md +++ b/docs/release_notes/ibexa_dxp_v5.0.md @@ -18,7 +18,9 @@ You can use it for migrations that might fail under certain conditions but shoul 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. From af4288ebf4998b6b73e72ed5f51e24020d5dc43b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Wed, 11 Feb 2026 11:36:57 +0100 Subject: [PATCH 5/5] Review feedback --- docs/content_management/data_migration/importing_data.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/content_management/data_migration/importing_data.md b/docs/content_management/data_migration/importing_data.md index dbb106a35d..c228b9313f 100644 --- a/docs/content_management/data_migration/importing_data.md +++ b/docs/content_management/data_migration/importing_data.md @@ -168,13 +168,19 @@ If the migration fails for this reason, the exception is suppressed, allowing th 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 default value of `stop_after_first_exception` is `true`. +The migration is marked as successful. +Non-matching exceptions throw immediately, halting the migration process and returning an error. ### Expression syntax