Merge pull request #1041 from gplanchat/docs/magento-public-promise

docs(magento): describe the database backend where Magento was memory or Temporal only (#739, #1036)

Author: gplanchat

README.md

@@ -14,7 +14,8 @@ It runs on Symfony, Sylius, Laravel, Magento 2.4 and Mage-OS. On Symfony and Lar
 through Messenger or the application's queue; on Magento, through `bin/magento durable:worker`. The
 same workflow code runs on three backends (where the journal lives): in memory (tests), on one SQL
 database (Doctrine DBAL or Laravel's database layer), or on a Temporal cluster. To switch, you install
-that backend's bridge and change one configuration value. Magento offers memory and Temporal only.
+that backend's bridge and change one configuration value. Magento has its own
+database backend instead of the two SQL bridges, see [Backends](documentation/user/backends/_index.md).
 
 ## Example: a workflow that waits three days
 
@@ -98,7 +99,7 @@ This monorepo holds every package. A split publishes each one to its own read-on
 | `gplanchat/durable-bridge-illuminate` | [`src/Bridge/Illuminate/`](src/Bridge/Illuminate/) | Illuminate (Laravel) journal and stores: durable execution on one SQL database through Laravel's database layer (**DUR030**) |
 | `gplanchat/durable-laravel` | [`src/DurableLaravel/`](src/DurableLaravel/) | Laravel integration: binds the four storage ports from one published config file, work rides the application's queue |
 | `gplanchat/durable-filament` | [`src/DurableFilament/`](src/DurableFilament/) | Filament 3 and 4 panel plugin: read-only dashboard of workflow runs, requires the Laravel integration |
-| `gplanchat/durable-magento` | [`src/DurableModule/`](src/DurableModule/) | Magento 2 / Mage-OS module: `durable:worker`, a read-only admin grid and process history, memory and Temporal backends (**DUR046**) |
+| `gplanchat/durable-magento` | [`src/DurableModule/`](src/DurableModule/) | Magento 2 / Mage-OS module: `durable:worker`, a read-only admin grid and process history, memory, database and Temporal backends (**DUR046**, **DUR056**) |
 | `gplanchat/durable-plugin` | [`src/DurablePlugin/`](src/DurablePlugin/) | Sylius 2 admin plugin: workflow dashboard, backend-neutral (**DUR037**) |
 | `gplanchat/durable-phpstan` | [`src/DurablePhpstan/`](src/DurablePhpstan/) | PHPStan extension: resolves stub calls against their typed contract |
 | `gplanchat/durable-rector` | [`src/DurableRector/`](src/DurableRector/) | Rector rules migrating a project off the official Temporal PHP SDK |

UPGRADE.md

@@ -1375,6 +1375,23 @@ class-not-found error.
 The Temporal SDK class `Temporal\Workflow\Saga` is unchanged, and the migration set from the SDK
 still reports it as unmigratable.
 
+### Changed: Magento reaches a third backend, its own database (#739)
+
+`gplanchat/durable-magento` now has a database backend (DUR056) next to memory and Temporal. It
+uses neither SQL bridge: the `conflict` on `gplanchat/durable-bridge-dbal` and
+`gplanchat/durable-bridge-illuminate` stays.
+
+**Who is affected**: Magento stores that declare `resource/durable` in `app/etc/env.php`, or
+that add the key later. A store that sets neither it nor `durable/temporal/dsn` keeps its journal
+in the process, and one with only a DSN keeps Temporal. Declaring both keys throws
+`BackendSelectionException` the first time the module resolves its journal
+(`RuntimeFactory::backend()`, `JournalConnectionResolver::connect()`).
+
+**What to do**: nothing, unless you want the database backend. Then declare a dedicated
+`db/connection/durable`, set `resource/durable` to `['connection' => 'durable']`, and run
+`bin/magento durable:setup` and `bin/magento durable:worker`. The
+[backends page](documentation/user/backends/_index.md) lists what the database backend supports.
+
 ## 0.1.0-beta1
 
 ### A failed retry enqueue is sent again; journals gain `ActivityRetryQueued` (#590)

documentation/user/concepts/_index.fr.md

@@ -345,11 +345,13 @@ Durable tourne sur quatre backends qui partagent le même code de workflows et d
 - Nécessite l'extension PHP `ext-grpc`.
 
 > [!NOTE]
-> **Sur Magento, deux des quatre seulement sont atteignables.** `gplanchat/durable-magento` déclare
-> un `conflict` Composer sur les deux ponts SQL : `Magento\Framework\App\ResourceConnection` n'est
-> ni Doctrine DBAL ni la connexion d'Illuminate, aucun des deux n'a donc de quoi se brancher. L'état
-> vit dans un cluster Temporal, ou il vit dans un processus, et c'est la présence de
-> `durable/temporal/dsn` dans `app/etc/env.php` qui tranche.
+> **Sur Magento, trois états sont possibles, et aucun n'utilise les ponts SQL.**
+> `gplanchat/durable-magento` déclare un `conflict` Composer sur les deux ponts :
+> `Magento\Framework\App\ResourceConnection` n'est ni Doctrine DBAL ni la connexion d'Illuminate. Son
+> backend base de données est un adaptateur à lui, sur la connexion que `resource/durable` désigne
+> dans `app/etc/env.php`. Un DSN dans `durable/temporal/dsn` sélectionne Temporal. Sans l'un ni
+> l'autre, le journal vit dans un processus. Déclarer les deux échoue au démarrage avec
+> `BackendSelectionException`.
 
 Pour la mise en place, voir [Backends](../backends/).
 
@@ -371,8 +373,9 @@ worker.
 
 **Magento** ne se sert ni de l'un ni de l'autre. Les workers sont des commandes
 `bin/magento durable:worker --role=journal|activity` qui interrogent le backend directement ; rien ne
-passe par le `MessageQueue` de Magento, parce que sur Temporal une activité est déjà une commande
-Temporal et une reprise une tâche de workflow.
+passe par le `MessageQueue` de Magento. Sur Temporal, une activité est déjà une commande Temporal
+et une reprise une tâche de workflow. Sur le backend base de données, les workers interrogent les files
+en tables de la connexion du journal.
 
 ### Une reprise est livrée au moins une fois
 

documentation/user/concepts/_index.md

@@ -355,11 +355,12 @@ Durable runs on four backends that share the same workflow and activity code:
 - Requires the `ext-grpc` PHP extension.
 
 > [!NOTE]
-> **On Magento, only two of the four are reachable.** `gplanchat/durable-magento` declares a Composer
-> `conflict` on both SQL bridges: `Magento\Framework\App\ResourceConnection` is neither Doctrine
-> DBAL nor Illuminate's connection, so neither has anything to bind to. The state lives in a Temporal
-> cluster, or it lives in one process, and the presence of `durable/temporal/dsn` in `app/etc/env.php`
-> decides which.
+> **On Magento, three states are possible, and none uses the SQL bridges.** `gplanchat/durable-magento`
+> declares a Composer `conflict` on both bridges: `Magento\Framework\App\ResourceConnection` is neither
+> Doctrine DBAL nor Illuminate's connection. Its database backend is its own adapter, on the
+> connection that `resource/durable` names in `app/etc/env.php`. A DSN in `durable/temporal/dsn`
+> selects Temporal. With neither, the journal lives in one process. Declaring both fails at boot with
+> `BackendSelectionException`.
 
 For setup details, see [Backends](../backends/).
 
@@ -379,8 +380,9 @@ the same consumer interface, a different underlying protocol.
 is a deferred timer-firing job on the queue's own delay, and `php artisan queue:work` is the only worker.
 
 **Magento** uses neither. Workers are `bin/magento durable:worker --role=journal|activity` commands
-that poll the backend directly; nothing rides Magento's own `MessageQueue`, because on Temporal an
-activity is already a Temporal command and a resume a workflow task.
+that poll the backend directly; nothing rides Magento's own `MessageQueue`. On Temporal, an
+activity is already a Temporal command and a resume a workflow task. On the database backend, the
+workers poll the table queues of the journal's connection.
 
 ### A resume is delivered at least once
 

documentation/user/configuration/_index.fr.md

@@ -443,6 +443,6 @@ de données. Les lignes DBAL et Illuminate ne s'y appliquent pas.
 
 ## Voir aussi
 
-- [Backends](../backends/) compare la mémoire et Temporal : mise en place Docker, workers, paramètres du DSN.
+- [Backends](../backends/) compare les backends mémoire, SQL et Temporal : mise en place Docker, workers, paramètres du DSN.
 - [Premiers pas](../getting-started/) couvre la configuration du routage Messenger.
 - [Tester des workflows](../testing/) couvre `DurableBundleTestTrait` et la configuration de test en mémoire.

documentation/user/configuration/_index.md

@@ -435,6 +435,6 @@ rows do not apply there.
 
 ## See also
 
-- [Backends](../backends/) compares In-Memory and Temporal: Docker setup, workers, DSN parameters.
+- [Backends](../backends/) compares the in-memory, SQL and Temporal backends: Docker setup, workers, DSN parameters.
 - [Getting started](../getting-started/) covers Messenger routing configuration.
 - [Testing workflows](../testing/) covers `DurableBundleTestTrait` and in-memory test configuration.

documentation/user/dashboard/run-not-progressing.fr.md

@@ -47,12 +47,21 @@ tableau de bord nomme chaque rôle dont la file n'est interrogée par aucun work
 `bin/console durable:health` sort avec un code non nul quand la file d'un rôle n'a été interrogée
 par personne depuis deux minutes, et nomme le `durable:worker --role` à démarrer.
 
+## Aucun worker ne vide les tables du backend base de données de Magento
+
+Rien n'échoue : l'exécution reste en file dans les tables du journal. La grille Magento affiche
+`waiting for a worker` pour une exécution en cours qu'aucun worker n'a prise, à partir de la colonne
+`picked_up_at` de la table des exécutions. Le backend base de données n'a que les rôles
+journal et activité : démarrez `bin/magento durable:worker --role=journal` et `--role=activity`, ou
+lancez-le sans `--role` pour vider les deux. `durable:health` vérifie seulement que la base du
+journal répond ; la grille montre une exécution qui attend un worker.
+
 ## `waiting for a worker` n'apparaît jamais
 
-Le backend n'a pas cette information. Les backends SQL l'ont, sur une table des exécutions qui a la
-colonne `picked_up_at` (voir [la procédure de mise à jour](https://github.com/gplanchat/durable-dev/blob/main/UPGRADE.md)
-pour une table créée avant elle). Temporal ne l'a pas depuis la liste des exécutions, et la grille
-Magento ne l'affiche pas : Temporal UI liste les tâches en attente.
+Le backend n'a pas cette information. Les backends SQL et le backend base de données de Magento l'ont, sur une table des exécutions
+qui a la colonne `picked_up_at` (voir [la procédure de mise à jour](https://github.com/gplanchat/durable-dev/blob/main/UPGRADE.md)
+pour une table créée avant elle). Temporal ne l'a pas depuis la liste des exécutions, aucune grille
+ne l'affiche donc : Temporal UI liste les tâches en attente.
 
 ## Les filtres par nom et par identifiant manquent
 

documentation/user/dashboard/run-not-progressing.md

@@ -44,11 +44,20 @@ dashboard names each role whose queue has no poller. From a shell, `bin/console
 exits non-zero when a role's queue has gone two minutes without a poll, and names the
 `durable:worker --role` to start.
 
+## No worker is draining the tables on the Magento database backend
+
+Nothing fails: the run stays queued in the journal's tables. The Magento grid shows `waiting for a
+worker` for a running execution that no worker has picked up, from the `picked_up_at` column of the
+runs table. The database backend has the journal and activity roles only: start
+`bin/magento durable:worker --role=journal` and `--role=activity`, or run it without `--role` to
+drain both. `durable:health` only checks that the journal database answers; the grid shows a run
+that waits for a worker.
+
 ## `waiting for a worker` never appears
 
-The backend records no pickup time. The SQL backends record it, on a runs table that has the `picked_up_at` column
-(see [Upgrading](https://github.com/gplanchat/durable-dev/blob/main/UPGRADE.md) for a table created
-before it existed). Temporal records none the run list can read, and the Magento grid does not show it:
+The backend records no pickup time. The SQL backends and the Magento database backend record it,
+on a runs table that has the `picked_up_at` column (see [Upgrading](https://github.com/gplanchat/durable-dev/blob/main/UPGRADE.md) for a table created
+before it existed). Temporal records none the run list can read, so no grid shows it there:
 Temporal UI lists the pending tasks.
 
 ## The name and id filters are missing

src/DurableModule/README.md

@@ -48,23 +48,34 @@ Magento Open Source and Adobe Commerce are not in CI: their packages come from
 `repo.magento.com`, which needs credentials. Mage-OS 2.2.0 replaces `magento/framework` 103.0.8-p4,
 Magento 2.4.8-p4's framework: the closest booted line to a Magento 2.4.8 shop, not proof of one.
 
-## Two backends, and Composer enforces it
+## Three backends, and Composer enforces the bridges' absence
 
-Magento reaches **in-memory** and **Temporal**, and nothing else. The module declares `conflict` on
-both SQL bridges, because `Magento\Framework\App\ResourceConnection` is neither Doctrine DBAL nor
-Illuminate's connection. This is the final shape, not a stage: an incoherent install is refused by
-the dependency solver rather than by a runtime check nobody reads.
+Magento reaches **in-memory**, its own **database** backend and **Temporal**. The module declares
+`conflict` on both SQL bridges, because `Magento\Framework\App\ResourceConnection` is neither
+Doctrine DBAL nor Illuminate's connection: the database backend is an adapter of this module, built
+on that connection layer (DUR056). An install with a bridge is refused by the dependency solver
+rather than by a runtime check nobody reads.
 
-Which backend you get is decided by a DSN in `app/etc/env.php`, not by a setting:
+`app/etc/env.php` selects the backend. Declare a journal connection under `db/connection` and name
+it in `resource/durable` to select the database (`bin/magento durable:setup` creates the tables, and
+`bin/magento durable:worker` drains their queues):
+
+```php
+'db' => ['connection' => ['durable' => [/* host, dbname, username, password... */]]],
+'resource' => ['durable' => ['connection' => 'durable']],
+```
+
+A DSN selects Temporal instead:
 
 ```php
 'durable' => [
     'temporal' => ['dsn' => 'temporal://temporal:7233?namespace=default&tls=0'],
 ],
 ```
 
-Without it the journal lives in the process that writes it, and dies with it — fine for a console
-command, ruinous for anything served by PHP-FPM.
+Declaring both throws `BackendSelectionException` the first time the module resolves its journal.
+Without either the journal lives in the process that writes it, and dies with it, which suits a
+console command, ruinous for anything served by PHP-FPM.
 
 With `transport=guzzle` in the DSN, gRPC travels through Guzzle 7.14 or newer, which Magento
 already ships. To hand it the application's client — its proxy, its TLS options — set the
@@ -281,10 +292,11 @@ cluster.
 
 **Nothing rides Magento's `MessageQueue`.** On Temporal an activity is a Temporal command and a
 resume is a workflow task; a topic here would be a second queue for an operator to supervise, for
-nothing. Magento has no native journal of its own and will not get one.
+nothing.
 
-**There is no SQL journal on `ResourceConnection`**, and none is planned — see the two backends
-above.
+**The database backend does not use the SQL bridges.** It keeps its journal through
+`ResourceConnection` on a dedicated `db/connection/durable`, selected by `resource/durable`; see
+[Three backends](#three-backends-and-composer-enforces-the-bridges-absence).
 
 ## License