Add configurable storage connection for workflow models and migrations

README.md

@@ -69,6 +69,34 @@ $workflow->output();
 => 'Hello, world!'
 ```
 
+## Using a dedicated storage connection
+
+By default all workflow persistence (every Eloquent model and every migration shipped
+by this package) lives on your application's **default** database connection. To isolate
+workflow state on its own database — for separate backup/retention/scaling, a different
+driver, or tenant isolation — point the package at a dedicated connection:
+
+```php
+// config/workflows.php
+'storage' => [
+    // null => the application's default connection (the default, unchanged behavior).
+    'connection' => Env::dw('DW_STORAGE_CONNECTION', 'WORKFLOW_STORAGE_CONNECTION', null),
+],
+```
+
+```dotenv
+# .env — must match a key under config('database.connections')
+DW_STORAGE_CONNECTION=durable_workflow
+```
+
+When set, both the models and the migrations are routed to that connection, so
+`php artisan migrate` creates the workflow tables there and all reads/writes target it.
+Leaving it `null` preserves today's behavior exactly.
+
+The schema/database is governed by the connection's own configuration — use
+`search_path` for PostgreSQL or `database` for MySQL on that connection. There is no
+separate schema option.
+
 ## Sponsors
 
 The Durable Workflow package is sustained by the community via sponsors and volunteers.

src/Models/StoredWorkflow.php

@@ -13,12 +13,15 @@
 use Workflow\States\HasStates;
 use Workflow\States\WorkflowContinuedStatus;
 use Workflow\States\WorkflowStatus;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\WorkflowMetadata;
 use Workflow\WorkflowOptions;
 use Workflow\WorkflowStub;
 
 class StoredWorkflow extends Model
 {
+    use ResolvesStorageConnection;
+
     use HasStates;
     use Prunable;
 

src/Models/StoredWorkflowException.php

@@ -5,9 +5,12 @@
 namespace Workflow\Models;
 
 use Illuminate\Database\Eloquent\Model;
+use Workflow\Traits\ResolvesStorageConnection;
 
 class StoredWorkflowException extends Model
 {
+    use ResolvesStorageConnection;
+
     public const UPDATED_AT = null;
 
     /**

src/Models/StoredWorkflowLog.php

@@ -5,9 +5,12 @@
 namespace Workflow\Models;
 
 use Illuminate\Database\Eloquent\Model;
+use Workflow\Traits\ResolvesStorageConnection;
 
 class StoredWorkflowLog extends Model
 {
+    use ResolvesStorageConnection;
+
     public const UPDATED_AT = null;
 
     /**

src/Models/StoredWorkflowSignal.php

@@ -5,9 +5,12 @@
 namespace Workflow\Models;
 
 use Illuminate\Database\Eloquent\Model;
+use Workflow\Traits\ResolvesStorageConnection;
 
 class StoredWorkflowSignal extends Model
 {
+    use ResolvesStorageConnection;
+
     public const UPDATED_AT = null;
 
     /**

src/Models/StoredWorkflowTimer.php

@@ -5,9 +5,12 @@
 namespace Workflow\Models;
 
 use Illuminate\Database\Eloquent\Model;
+use Workflow\Traits\ResolvesStorageConnection;
 
 class StoredWorkflowTimer extends Model
 {
+    use ResolvesStorageConnection;
+
     public const UPDATED_AT = null;
 
     /**

src/Support/WorkflowMigration.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Workflow\Support;
+
+use Illuminate\Database\Migrations\Migration;
+
+abstract class WorkflowMigration extends Migration
+{
+    public function getConnection(): ?string
+    {
+        return config('workflows.storage.connection') ?? $this->connection;
+    }
+}

src/Traits/ResolvesStorageConnection.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Workflow\Traits;
+
+trait ResolvesStorageConnection
+{
+    public function getConnectionName(): ?string
+    {
+        return config('workflows.storage.connection') ?? $this->connection;
+    }
+}

src/V2/Models/ActivityAttempt.php

@@ -7,11 +7,14 @@
 use Illuminate\Database\Eloquent\Concerns\HasUlids;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Enums\ActivityAttemptStatus;
 use Workflow\V2\Support\ConfiguredV2Models;
 
 class ActivityAttempt extends Model
 {
+    use ResolvesStorageConnection;
+
     use HasUlids;
 
     public $incrementing = false;

src/V2/Models/ActivityExecution.php

@@ -9,12 +9,15 @@
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Workflow\Serializers\Serializer;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Enums\ActivityStatus;
 use Workflow\V2\Support\ConfiguredV2Models;
 use Workflow\V2\Support\ExternalPayloads;
 
 class ActivityExecution extends Model
 {
+    use ResolvesStorageConnection;
+
     use HasUlids;
 
     public $incrementing = false;

src/V2/Models/WorkerCompatibilityHeartbeat.php

@@ -5,9 +5,12 @@
 namespace Workflow\V2\Models;
 
 use Illuminate\Database\Eloquent\Model;
+use Workflow\Traits\ResolvesStorageConnection;
 
 class WorkerCompatibilityHeartbeat extends Model
 {
+    use ResolvesStorageConnection;
+
     protected $table = 'workflow_worker_compatibility_heartbeats';
 
     protected $guarded = [];

src/V2/Models/WorkflowChildCall.php

@@ -6,12 +6,15 @@
 
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Enums\ChildCallStatus;
 use Workflow\V2\Enums\ParentClosePolicy;
 use Workflow\V2\Support\ConfiguredV2Models;
 
 class WorkflowChildCall extends Model
 {
+    use ResolvesStorageConnection;
+
     public $incrementing = true;
 
     protected $table = 'workflow_child_calls';

src/V2/Models/WorkflowCommand.php

@@ -10,6 +10,7 @@
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Database\Eloquent\Relations\HasOne;
 use Workflow\Serializers\Serializer;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Enums\CommandOutcome;
 use Workflow\V2\Enums\CommandStatus;
 use Workflow\V2\Enums\CommandType;
@@ -20,6 +21,8 @@
 
 class WorkflowCommand extends Model
 {
+    use ResolvesStorageConnection;
+
     use HasUlids;
 
     private const MESSAGE_COMMAND_TYPES = ['signal', 'update'];

src/V2/Models/WorkflowFailure.php

@@ -7,11 +7,14 @@
 use Illuminate\Database\Eloquent\Concerns\HasUlids;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Enums\FailureCategory;
 use Workflow\V2\Support\ConfiguredV2Models;
 
 class WorkflowFailure extends Model
 {
+    use ResolvesStorageConnection;
+
     use HasUlids;
 
     public $incrementing = false;

src/V2/Models/WorkflowHistoryEvent.php

@@ -8,13 +8,16 @@
 use Illuminate\Database\Eloquent\Concerns\HasUlids;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Enums\HistoryEventType;
 use Workflow\V2\Support\ConfiguredV2Models;
 use Workflow\V2\Support\ExternalPayloads;
 use Workflow\V2\Support\HistoryEventPayloadContract;
 
 class WorkflowHistoryEvent extends Model
 {
+    use ResolvesStorageConnection;
+
     use HasUlids;
 
     public $incrementing = false;

src/V2/Models/WorkflowInstance.php

@@ -8,10 +8,13 @@
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Support\ConfiguredV2Models;
 
 class WorkflowInstance extends Model
 {
+    use ResolvesStorageConnection;
+
     use HasUlids;
 
     public $incrementing = false;

src/V2/Models/WorkflowLink.php

@@ -7,10 +7,13 @@
 use Illuminate\Database\Eloquent\Concerns\HasUlids;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Support\ConfiguredV2Models;
 
 class WorkflowLink extends Model
 {
+    use ResolvesStorageConnection;
+
     use HasUlids;
 
     public $incrementing = false;

src/V2/Models/WorkflowMemo.php

@@ -7,10 +7,13 @@
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use InvalidArgumentException;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Support\ConfiguredV2Models;
 
 class WorkflowMemo extends Model
 {
+    use ResolvesStorageConnection;
+
     // Size and count limits (Phase 1 structural limits)
     public const MAX_MEMOS_PER_RUN = 100;
 

src/V2/Models/WorkflowMessage.php

@@ -6,12 +6,15 @@
 
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Enums\MessageConsumeState;
 use Workflow\V2\Enums\MessageDirection;
 use Workflow\V2\Support\ConfiguredV2Models;
 
 class WorkflowMessage extends Model
 {
+    use ResolvesStorageConnection;
+
     // Structural limits
     public const MAX_MESSAGES_PER_STREAM = 10000;
 

src/V2/Models/WorkflowRun.php

@@ -11,12 +11,15 @@
 use Illuminate\Database\Eloquent\Relations\HasOne;
 use Workflow\Serializers\CodecRegistry;
 use Workflow\Serializers\Serializer;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Enums\RunStatus;
 use Workflow\V2\Support\ConfiguredV2Models;
 use Workflow\V2\Support\ExternalPayloads;
 
 class WorkflowRun extends Model
 {
+    use ResolvesStorageConnection;
+
     use HasUlids;
 
     public $incrementing = false;

src/V2/Models/WorkflowRunLineageEntry.php

@@ -6,10 +6,13 @@
 
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Support\ConfiguredV2Models;
 
 class WorkflowRunLineageEntry extends Model
 {
+    use ResolvesStorageConnection;
+
     public $incrementing = false;
 
     protected $table = 'workflow_run_lineage_entries';

src/V2/Models/WorkflowRunSummary.php

@@ -7,13 +7,16 @@
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Enums\RunStatus;
 use Workflow\V2\Support\ConfiguredV2Models;
 use Workflow\V2\Support\RepairBlockedReason;
 use Workflow\V2\Support\WorkflowTaskProblem;
 
 class WorkflowRunSummary extends Model
 {
+    use ResolvesStorageConnection;
+
     public $incrementing = false;
 
     protected $table = 'workflow_run_summaries';

src/V2/Models/WorkflowRunTimerEntry.php

@@ -8,10 +8,13 @@
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Support\Carbon;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Support\ConfiguredV2Models;
 
 class WorkflowRunTimerEntry extends Model
 {
+    use ResolvesStorageConnection;
+
     public const CURRENT_SCHEMA_VERSION = 1;
 
     public $incrementing = false;

src/V2/Models/WorkflowRunWait.php

@@ -8,10 +8,13 @@
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Support\Carbon;
+use Workflow\Traits\ResolvesStorageConnection;
 use Workflow\V2\Support\ConfiguredV2Models;
 
 class WorkflowRunWait extends Model
 {
+    use ResolvesStorageConnection;
+
     public $incrementing = false;
 
     protected $table = 'workflow_run_waits';