Explain workflow storage transaction boundaries in all locales

docs/configuration/database-connection.md

@@ -4,12 +4,32 @@ sidebar_position: 4
 
 # Database Connection
 
-Here is an overview of the steps needed to customize the database connection used for the workflow v2 durable models. This is *only* required if you want to use a different database connection than the default connection you specified for your Laravel application.
+Workflow uses your application's default Laravel database connection unless you
+select another connection for its durable storage.
+
+To move workflow storage to a connection defined in `config/database.php`, set
+its name in your environment:
+
+```dotenv
+DW_STORAGE_CONNECTION=workflows
+```
+
+Workflow models, transactions, row locks and after-commit callbacks use that
+connection. Keep all durable workflow tables on the same Laravel connection.
+Configure queue transport separately through Laravel's queue configuration.
+
+You can also select the connection through custom model classes as described
+below. The configured V2 `run_model` supplies the storage connection for V2
+metadata without an explicit model connection. Keep explicit model connections
+consistent with it. `DW_STORAGE_CONNECTION` takes precedence over model
+connection properties.
 
 For the full v2 override contract, including table-swapped subclasses,
 serializer rules, repository replacement, health diagnostics, and migration
 expectations, see the [Customization Matrix](./customization-matrix.md).
 
+## Custom Model Connections
+
 1. Create classes in your app models directory that extend the base v2 model classes
 2. Set the desired `$connection` option in each class
 3. Publish the workflow config file
@@ -73,4 +93,44 @@ boot.
 
 ## Migrations
 
-Workflow migrations are auto-loaded from the package (`WorkflowServiceProvider::loadMigrationsFrom`) and run against the default database connection. When you route the v2 tables at a non-default connection, publish the migrations with `php artisan vendor:publish --tag=migrations` and set `protected $connection = 'mysql';` on each published migration class so `php artisan migrate` runs them against the correct database.
+Workflow migrations are auto-loaded from the package and honor
+`DW_STORAGE_CONNECTION`. Application migrations keep their own configured
+connections.
+
+When using custom model connections without `DW_STORAGE_CONNECTION`, give
+their published workflow migrations the same `$connection`. Laravel's
+`--database` option can also select the target when running only those workflow
+migrations. Keep application migrations on the application connection.
+
+## Transaction Boundaries
+
+When application data and workflow storage use the same Laravel connection,
+starting a workflow inside a transaction joins that transaction. A rollback
+removes the workflow writes made inside it. The engine publishes workflow tasks
+to the queue and emits lifecycle events after the outermost storage transaction
+commits. A rollback discards those callbacks.
+
+For example, with `DW_STORAGE_CONNECTION=workflows`:
+
+```php
+use App\Workflows\OrderWorkflow;
+use Illuminate\Support\Facades\DB;
+use Workflow\V2\WorkflowStub;
+
+DB::connection('workflows')->transaction(function () {
+    WorkflowStub::make(OrderWorkflow::class, 'order-123')->start('order-123');
+});
+```
+
+Any application models whose changes must commit atomically with this start
+must also use the `workflows` connection.
+
+Transactions on different Laravel connections commit independently, even when
+the connection names point at the same physical database. An application
+transaction on the default connection cannot roll back a workflow that already
+committed on another storage connection. Place changes requiring atomicity on
+the same connection and include them in that connection's transaction.
+
+After-commit publication protects the workflow storage boundary. A separate
+database or message broker used by the queue has its own transaction and
+delivery behavior.

i18n/de/docusaurus-plugin-content-docs/current/configuration/database-connection.md

@@ -4,15 +4,24 @@ sidebar_position: 4
 
 # Datenbankverbindung {#database-connection}
 
-Hier finden Sie die Schritte zum Anpassen der Datenbankverbindung für die
-dauerhaften Workflow-v2-Modelle. Dies ist *nur* erforderlich, wenn Sie eine
-andere Verbindung als die Standardverbindung Ihrer Laravel-Anwendung verwenden
-möchten.
+Workflow verwendet standardmäßig die Laravel-Datenbankverbindung Ihrer Anwendung, sofern Sie keine andere Verbindung für den dauerhaften Speicher auswählen.
+
+Um den Workflow-Speicher auf eine in `config/database.php` definierte Verbindung zu legen, setzen Sie deren Namen in der Umgebung:
+
+```dotenv
+DW_STORAGE_CONNECTION=workflows
+```
+
+Workflow-Modelle, Transaktionen, Zeilensperren und Aktionen nach dem Commit verwenden diese Verbindung. Alle dauerhaften Workflow-Tabellen müssen dieselbe Laravel-Verbindung verwenden. Konfigurieren Sie den Queue-Transport getrennt in Laravels Queue-Konfiguration.
+
+Sie können die Verbindung auch über eigene Modellklassen wie unten beschrieben auswählen. Das konfigurierte V2-`run_model` liefert die Speicherverbindung für V2-Metadaten ohne explizite Modellverbindung. Explizite Modellverbindungen müssen damit übereinstimmen. `DW_STORAGE_CONNECTION` hat Vorrang vor den Verbindungseigenschaften der Modelle.
 
 Den vollständigen v2-Überschreibungsvertrag einschließlich Unterklassen mit
 anderen Tabellen, Serializer-Regeln, Repository-Austausch, Zustandsdiagnosen
 und Migrationserwartungen beschreibt die [Anpassungsmatrix](./customization-matrix.md).
 
+## Eigene Modellverbindungen {#custom-model-connections}
+
 1. Erstellen Sie im Modellverzeichnis Ihrer Anwendung Klassen, die die v2-Basismodellklassen erweitern.
 2. Setzen Sie in jeder Klasse die gewünschte Option `$connection`.
 3. Veröffentlichen Sie die Workflow-Konfigurationsdatei.
@@ -82,10 +91,28 @@ Start, ob die Beziehungen `runs()`, `commands()` und `updates()` explizit
 
 ## Migrationen {#migrations}
 
-Workflow-Migrationen werden automatisch aus dem Paket geladen
-(`WorkflowServiceProvider::loadMigrationsFrom`) und auf der
-Standard-Datenbankverbindung ausgeführt. Wenn Sie die v2-Tabellen auf eine
-andere Verbindung legen, veröffentlichen Sie die Migrationen mit
-`php artisan vendor:publish --tag=migrations` und setzen Sie
-`protected $connection = 'mysql';` in jeder veröffentlichten Migrationsklasse,
-damit `php artisan migrate` sie auf der richtigen Datenbank ausführt.
+Workflow-Migrationen werden automatisch aus dem Paket geladen und berücksichtigen `DW_STORAGE_CONNECTION`. Anwendungsmigrationen behalten ihre eigenen konfigurierten Verbindungen.
+
+Wenn Sie eigene Modellverbindungen ohne `DW_STORAGE_CONNECTION` verwenden, weisen Sie den zugehörigen veröffentlichten Workflow-Migrationen dieselbe `$connection` zu. Mit Laravels Option `--database` können Sie das Ziel auch beim Ausführen ausschließlich dieser Workflow-Migrationen auswählen. Anwendungsmigrationen bleiben auf der Anwendungsverbindung.
+
+## Transaktionsgrenzen {#transaction-boundaries}
+
+Wenn Anwendungsdaten und Workflow-Speicher dieselbe Laravel-Verbindung verwenden, nimmt ein innerhalb einer Transaktion gestarteter Workflow an dieser Transaktion teil. Ein Rollback entfernt die darin geschriebenen Workflow-Daten. Der Kern veröffentlicht Workflow-Aufgaben in der Queue und sendet Lebenszyklusereignisse erst nach dem Commit der äußersten Speichertransaktion. Ein Rollback verwirft diese Aktionen.
+
+Zum Beispiel mit `DW_STORAGE_CONNECTION=workflows`:
+
+```php
+use App\Workflows\OrderWorkflow;
+use Illuminate\Support\Facades\DB;
+use Workflow\V2\WorkflowStub;
+
+DB::connection('workflows')->transaction(function () {
+    WorkflowStub::make(OrderWorkflow::class, 'order-123')->start('order-123');
+});
+```
+
+Anwendungsmodelle, deren Änderungen atomar mit diesem Start festgeschrieben werden müssen, müssen ebenfalls die Verbindung `workflows` verwenden.
+
+Transaktionen auf verschiedenen Laravel-Verbindungen werden unabhängig voneinander festgeschrieben, selbst wenn die Verbindungsnamen auf dieselbe physische Datenbank zeigen. Ein Rollback auf der Standardverbindung der Anwendung kann einen Workflow, der bereits auf einer anderen Speicherverbindung festgeschrieben wurde, nicht zurückrollen. Legen Sie Änderungen, die atomar sein müssen, auf dieselbe Verbindung und schließen Sie sie in deren Transaktion ein.
+
+Die Veröffentlichung nach dem Commit schützt die Grenze des Workflow-Speichers. Eine separate Queue-Datenbank oder ein Message-Broker hat eigene Transaktions- und Zustellungsregeln.

i18n/de/source-hashes.json

@@ -6,7 +6,7 @@
   "capabilities.md": "d9a2bbc0d04adf8cb3f4c7f42d779a43aafab60791210305e7e476c0499528fc",
   "compatibility.md": "5d88e55a566f4103307871846ffc042c8e1e1d10ea57a44bcb3b3542643743d5",
   "configuration/customization-matrix.md": "3d115863eaee7852b541bcd01615f424cc19c5847c7cd7d75e5ae63bc3f5cc78",
-  "configuration/database-connection.md": "a4657d239673a4ecdc3981bcc5a7cf33aa2d37c709768131cd5ba3292987681f",
+  "configuration/database-connection.md": "cc83ae77133236309506fa44d39bfd0c939c32a6154c0bd6099bc64c83bdaec9",
   "configuration/ensuring-same-server.md": "6c665f37cc198c7b1a775a60a94aab5ff4e55383385e76f1834c7840559b512a",
   "configuration/microservices.md": "46dc4afa07588b78829a7e3d259177ce0cf40861f0e31b88dbb6de3a83aa5488",
   "configuration/options.md": "87622f9947b0042d1680197e612daf20a54ab6292a12d30e1077ba65f411e80c",

i18n/es/docusaurus-plugin-content-docs/current/configuration/database-connection.md

@@ -4,13 +4,25 @@ sidebar_position: 4
 
 # Conexión de base de datos {#database-connection}
 
-Estos son los pasos para personalizar la conexión de base de datos de los modelos duraderos de workflow v2. *Solo* hace falta si quieres usar una conexión distinta de la predeterminada de tu aplicación Laravel.
+Workflow usa la conexión de base de datos predeterminada de tu aplicación Laravel, salvo que selecciones otra conexión para su almacenamiento duradero.
+
+Para usar una conexión definida en `config/database.php` como almacenamiento de workflow, establece su nombre en el entorno:
+
+```dotenv
+DW_STORAGE_CONNECTION=workflows
+```
+
+Los modelos, las transacciones, los bloqueos de filas y las acciones posteriores al commit de workflow usan esa conexión. Mantén todas las tablas duraderas de workflow en la misma conexión de Laravel. Configura el transporte de la cola por separado mediante la configuración de colas de Laravel.
+
+También puedes seleccionar la conexión mediante clases de modelos personalizadas, como se explica más abajo. El `run_model` v2 configurado proporciona la conexión de almacenamiento para los metadatos v2 sin conexión explícita en su modelo. Las conexiones explícitas de los modelos deben coincidir con ella. `DW_STORAGE_CONNECTION` tiene prioridad sobre las propiedades de conexión de los modelos.
 
 Consulta la [Matriz de personalización](./customization-matrix.md) para conocer el
 contrato completo de sustituciones v2, incluidas las subclases que cambian de tabla,
 las reglas del serializador, la sustitución del repositorio, los diagnósticos de
 salud y los requisitos de migración.
 
+## Conexiones de modelos personalizados {#custom-model-connections}
+
 1. Crea clases en el directorio de modelos de tu aplicación que extiendan las clases base de modelos v2.
 2. Establece la opción `$connection` deseada en cada clase.
 3. Publica el archivo de configuración de workflow.
@@ -74,4 +86,28 @@ arrancar que hayas sustituido explícitamente las relaciones `runs()`,
 
 ## Migraciones {#migrations}
 
-Las migraciones de workflow se cargan automáticamente desde el paquete (`WorkflowServiceProvider::loadMigrationsFrom`) y se ejecutan en la conexión predeterminada de base de datos. Si diriges las tablas v2 a otra conexión, publica las migraciones con `php artisan vendor:publish --tag=migrations` y establece `protected $connection = 'mysql';` en cada clase de migración publicada para que `php artisan migrate` las ejecute en la base de datos correcta.
+Las migraciones de workflow se cargan automáticamente desde el paquete y respetan `DW_STORAGE_CONNECTION`. Las migraciones de la aplicación conservan sus propias conexiones configuradas.
+
+Si usas conexiones de modelos personalizados sin `DW_STORAGE_CONNECTION`, asigna la misma `$connection` a sus migraciones de workflow publicadas. La opción `--database` de Laravel también permite seleccionar el destino al ejecutar solo esas migraciones de workflow. Mantén las migraciones de la aplicación en su conexión de aplicación.
+
+## Límites de las transacciones {#transaction-boundaries}
+
+Cuando los datos de la aplicación y el almacenamiento de workflow usan la misma conexión de Laravel, iniciar un workflow dentro de una transacción lo incorpora a ella. Un rollback elimina las escrituras de workflow realizadas dentro de esa transacción. El motor publica las tareas de workflow en la cola y emite los eventos del ciclo de vida después del commit de la transacción de almacenamiento más externa. Un rollback descarta esas acciones.
+
+Por ejemplo, con `DW_STORAGE_CONNECTION=workflows`:
+
+```php
+use App\Workflows\OrderWorkflow;
+use Illuminate\Support\Facades\DB;
+use Workflow\V2\WorkflowStub;
+
+DB::connection('workflows')->transaction(function () {
+    WorkflowStub::make(OrderWorkflow::class, 'order-123')->start('order-123');
+});
+```
+
+Los modelos de la aplicación cuyos cambios deban confirmarse atómicamente con este inicio también deben usar la conexión `workflows`.
+
+Las transacciones en conexiones distintas de Laravel se confirman de forma independiente, aunque los nombres de conexión apunten a la misma base de datos física. Una transacción en la conexión predeterminada de la aplicación no puede revertir un workflow ya confirmado en otra conexión de almacenamiento. Coloca los cambios que requieran atomicidad en la misma conexión e inclúyelos en su transacción.
+
+La publicación posterior al commit protege el límite del almacenamiento de workflow. Una base de datos o un broker de mensajes independiente para la cola tiene sus propias reglas de transacción y entrega.

i18n/es/source-hashes.json

@@ -6,7 +6,7 @@
   "capabilities.md": "d9a2bbc0d04adf8cb3f4c7f42d779a43aafab60791210305e7e476c0499528fc",
   "compatibility.md": "5d88e55a566f4103307871846ffc042c8e1e1d10ea57a44bcb3b3542643743d5",
   "configuration/customization-matrix.md": "3d115863eaee7852b541bcd01615f424cc19c5847c7cd7d75e5ae63bc3f5cc78",
-  "configuration/database-connection.md": "a4657d239673a4ecdc3981bcc5a7cf33aa2d37c709768131cd5ba3292987681f",
+  "configuration/database-connection.md": "cc83ae77133236309506fa44d39bfd0c939c32a6154c0bd6099bc64c83bdaec9",
   "configuration/ensuring-same-server.md": "6c665f37cc198c7b1a775a60a94aab5ff4e55383385e76f1834c7840559b512a",
   "configuration/microservices.md": "46dc4afa07588b78829a7e3d259177ce0cf40861f0e31b88dbb6de3a83aa5488",
   "configuration/options.md": "87622f9947b0042d1680197e612daf20a54ab6292a12d30e1077ba65f411e80c",

i18n/fr/docusaurus-plugin-content-docs/current/configuration/database-connection.md

@@ -4,13 +4,25 @@ sidebar_position: 4
 
 # Connexion à la base de données {#database-connection}
 
-Voici les étapes permettant de personnaliser la connexion à la base de données utilisée par les modèles durables workflow v2. Cela est nécessaire *uniquement* pour utiliser une connexion différente de celle définie par défaut dans votre application Laravel.
+Workflow utilise la connexion de base de données Laravel par défaut de votre application, sauf si vous choisissez une autre connexion pour son stockage durable.
+
+Pour utiliser une connexion définie dans `config/database.php` pour le stockage des workflows, indiquez son nom dans l’environnement :
+
+```dotenv
+DW_STORAGE_CONNECTION=workflows
+```
+
+Les modèles, transactions, verrous de ligne et actions après commit de Workflow utilisent cette connexion. Placez toutes les tables durables des workflows sur la même connexion Laravel. Configurez séparément le transport de la file dans la configuration des files de Laravel.
+
+Vous pouvez aussi sélectionner la connexion avec des classes de modèles personnalisées, comme décrit ci-dessous. Le `run_model` v2 configuré fournit la connexion de stockage des métadonnées v2 sans connexion explicite dans leur modèle. Les connexions explicites des modèles doivent être identiques. `DW_STORAGE_CONNECTION` est prioritaire sur les propriétés de connexion des modèles.
 
 Pour le contrat complet des personnalisations v2, notamment les sous-classes
 changeant de table, les règles de sérialisation, le remplacement du dépôt,
 les diagnostics de santé et les exigences de migration, consultez la
 [Matrice de personnalisation](./customization-matrix.md).
 
+## Connexions des modèles personnalisés {#custom-model-connections}
+
 1. Créez dans le répertoire des modèles de votre application des classes qui étendent les modèles de base v2.
 2. Définissez l’option `$connection` souhaitée dans chaque classe.
 3. Publiez le fichier de configuration workflow.
@@ -74,4 +86,28 @@ ont été explicitement redéfinies.
 
 ## Migrations {#migrations}
 
-Les migrations workflow sont chargées automatiquement depuis le package (`WorkflowServiceProvider::loadMigrationsFrom`) et s’exécutent sur la connexion de base de données par défaut. Lorsque vous dirigez les tables v2 vers une autre connexion, publiez les migrations avec `php artisan vendor:publish --tag=migrations` et définissez `protected $connection = 'mysql';` sur chaque classe de migration publiée afin que `php artisan migrate` les exécute sur la bonne base de données.
+Les migrations de Workflow sont chargées automatiquement depuis le package et respectent `DW_STORAGE_CONNECTION`. Les migrations de l’application conservent leurs propres connexions configurées.
+
+Si vous utilisez des connexions de modèles personnalisées sans `DW_STORAGE_CONNECTION`, attribuez la même `$connection` aux migrations Workflow publiées correspondantes. L’option Laravel `--database` permet aussi de sélectionner la cible lors de l’exécution de ces seules migrations Workflow. Gardez les migrations de l’application sur sa connexion.
+
+## Limites des transactions {#transaction-boundaries}
+
+Lorsque les données de l’application et le stockage des workflows utilisent la même connexion Laravel, un workflow démarré dans une transaction y participe. Un rollback supprime les écritures Workflow effectuées dans cette transaction. Le moteur publie les tâches de workflow dans la file et émet les événements de cycle de vie après le commit de la transaction de stockage la plus externe. Un rollback annule ces actions.
+
+Par exemple, avec `DW_STORAGE_CONNECTION=workflows` :
+
+```php
+use App\Workflows\OrderWorkflow;
+use Illuminate\Support\Facades\DB;
+use Workflow\V2\WorkflowStub;
+
+DB::connection('workflows')->transaction(function () {
+    WorkflowStub::make(OrderWorkflow::class, 'order-123')->start('order-123');
+});
+```
+
+Les modèles de l’application dont les changements doivent être validés atomiquement avec ce démarrage doivent aussi utiliser la connexion `workflows`.
+
+Les transactions sur des connexions Laravel différentes sont validées indépendamment, même lorsque leurs noms pointent vers la même base physique. Une transaction sur la connexion par défaut de l’application ne peut pas annuler un workflow déjà validé sur une autre connexion de stockage. Placez les changements qui doivent être atomiques sur la même connexion et incluez-les dans sa transaction.
+
+La publication après commit protège la limite du stockage des workflows. Une base de données ou un broker de messages distinct utilisé par la file possède ses propres règles de transaction et de livraison.