Add configurable storage connection for workflow models and migrations

[discovery-ukraine]

Add configurable storage connection for workflow models and migrations

Summary

This adds an optional workflows.storage.connection config key that routes all
workflow persistence — every Eloquent model under src/Models/ and src/V2/Models/, and
every migration under src/migrations/ — to a dedicated database connection. The key
defaults to null, which resolves to the application's default connection, so existing
deployments are fully backward compatible and see no behavior change.

Motivation

We want workflow state to live in a separate durable_workflow database, isolated from our
central/tenant OLTP databases, across both MariaDB and PostgreSQL. Today the package gives no
supported way to do that:

• No connection hook on the models. Every model in src/Models/ and src/V2/Models/
  extends Illuminate\Database\Eloquent\Model directly and never overrides
  getConnectionName(), so workflow storage always lands on the application's default
  connection.
• Consumer-side model swaps cannot route everything, and would split-brain. The
  ConfiguredV2Models::resolve('*_model', …) mechanism only covers some models. Several
  tables are also reached through hardcoded class references (e.g. new WorkflowMessage(),
  WorkflowChildCall::, WorkerCompatibilityHeartbeat::) alongside the resolve() path.
  Overriding a model only on the resolve() side would leave the hardcoded call sites on the
  default connection — the same table read on two connections (a split-brain). The only
  correct place to route the connection is the model class itself.
• Routing the store is an industry-standard capability. Telescope
  (telescope.storage.database.connection), Horizon, Passport, and
  spatie/laravel-activitylog (activitylog.database_connection) all expose this. A durable
  workflow engine — the system of record for critical long-running processes — benefits even
  more from isolating its store: independent backup/retention/scaling, multi-driver setups,
  and tenant isolation.

What changed

• Config key — a new top-level storage block in src/config/workflows.php:

  'storage' => [
      'connection' => Env::dw('DW_STORAGE_CONNECTION', 'WORKFLOW_STORAGE_CONNECTION', null),
  ],

  It uses the existing DW_* → WORKFLOW_* → default env contract.
• Workflow\Traits\ResolvesStorageConnection — a small trait that overrides
  getConnectionName() to return config('workflows.storage.connection') ?? $this->connection.
  Applied to all 33 models. Because the routing lives on the model class, both hardcoded and
  resolve()-based usages resolve to the same connection — eliminating the split-brain.
• Workflow\Support\WorkflowMigration — an abstract Migration subclass that overrides
  getConnection() the same way. All 39 migrations now extend it instead of
  Illuminate\Database\Migrations\Migration.
• Tests — model connection resolution (incl. backward-compatible null fallback),
  migration routing onto a second connection, and a fail-closed contract test that every
  package migration extends WorkflowMigration.
• Docs — a "Using a dedicated storage connection" section in the README.

Backward compatibility

The key defaults to null. With null, getConnectionName() / getConnection() return the
model's own $connection (also null), i.e. the application's default connection — exactly
today's behavior. Existing apps are unaffected; no migration or config change is required.

How it works

For migrations the routing relies on Laravel's Migrator: runMigration() resolves the
connection from $migration->getConnection() (overriding the --database option), and
runMethod() temporarily sets that connection as the default for the duration of up() /
down(). That is why the bare Schema::create(...) / Schema::dropIfExists(...) calls need
no change — they land on the configured connection automatically. The migration repository
rows still record on the run connection, which is standard Laravel behavior (the same as
Telescope).

Testing

• Tests\Unit\StorageConnectionTest — with workflows.storage.connection = 'secondary',
  asserts getConnectionName() === 'secondary' for StoredWorkflow (v1),
  WorkflowRun (v2 resolve-path) and WorkflowMessage (v2 hardcoded-usage); with the key
  unset, asserts the null/default fallback.
• Tests\Unit\Migrations\StorageConnectionMigrationTest — registers a second sqlite
  connection, points workflows.storage.connection at it, runs the migrations, then asserts
  representative workflow tables (workflows, workflow_runs, workflow_messages) exist on
  the secondary connection and are absent on the default connection.
• Tests\Unit\Migrations\MigrationsTest::testEveryPackageMigrationExtendsWorkflowMigrationBase
  — a fail-closed contract test (matching the existing migration-slate contracts) asserting
  every src/migrations/*.php extends WorkflowMigration and none extends the framework's
  bare Migration. This guards against a future make:migration regenerating a migration on
  the default base class and silently bypassing the storage-connection routing.

[rmcdaniel]

Merged and released as durable-workflow/workflow:2.0.0-alpha.184.

Packagist is already serving the tag, so it can be installed with:

composer require durable-workflow/workflow:2.0.0-alpha.184

I also applied a small ECS formatter cleanup before merging; the storage connection behavior from the PR is included in the release.

[discovery-ukraine]

Thank you so much for your quick response! Now we can continue implementing durable workflows in our project. And thank you greatly for your work!

[rmcdaniel]

Follow-up: the latest workflow prerelease is now 2.0.0-alpha.186, and it includes this storage-connection support.

I also verified the published Packagist artifact with a storage-connection migration smoke: workflows.storage.connection / DW_STORAGE_CONNECTION route representative v1 and v2 models to the configured connection, every package migration uses the workflow migration base, and Laravel migrations create the workflow tables on the dedicated connection instead of the default connection.

Install the latest prerelease with:

composer require durable-workflow/workflow:2.0.0-alpha.186