Docket Laravel Package

Getting Started

Docket is a migration orchestration/tracking package (v0.1.x, pre-1.0) that wraps Laravel migrations in tracked "runs" and manages the database connections used to execute them. Start here:

1. composer require teylabs/docket and publish its config/migrations (php artisan vendor:publish --tag=docket-config / docket-migrations, or the equivalents listed in the package README).
2. Read config/docket.php and the package service provider first — they define the generated connection naming, the runs table, and how the current-run stack is initialized.
3. Inspect the package migrations for the runs table and its self-referencing foreign key; this is the schema v0.1.1 fixes on PostgreSQL.
4. First use case: run your application migrations through Docket's command instead of php artisan migrate directly, so each batch is recorded as a run and failed batches roll back on the same connection they started on.

Because this is a 0.1.x release, pin an exact version in composer.json and read the changelog before upgrading.

Implementation Patterns

• Run-scoped migrations. Treat each Docket run as the unit of work. Kick off migrations through the package's artisan command/API rather than calling migrate directly, so the run record and the migration writes stay in sync.
• Generated connections. Docket creates a database connection per run. Don't hard-code connection names in your own migrations; resolve the active connection from the package (config/current-run stack) so default-connection switches don't strand writes.
• Current-run stack. Use the stack to scope any custom logic (seeders, data backfills) to the active run. v0.1.1 makes an empty stack an explicit, handled state — rely on the package's accessor rather than indexing the stack yourself.
• CI integration. Run Docket in CI against both MySQL and PostgreSQL. The v0.1.1 fixes are Postgres-specific (FK ordering, transaction isolation), so a MySQL-only pipeline will not catch regressions.
• Wrap and assert. In tests, assert that a failed migration leaves no partial run record and that the connection used for rollback matches the one used for the write.

Gotchas and Tips

• Upgrade to v0.1.1 before relying on rollback semantics. Earlier versions could leave a failed migration write on a different connection after a default-connection switch, so the rollback did not hit the same connection. This is the headline fix (#33).
• PostgreSQL FK ordering. If you maintain custom migrations or extend the runs schema, create the run primary key before any self-referencing FK. v0.1.1 does this for you (#35); hand-rolled schema changes must match.
• Empty current-run stack. Code that assumed a run is always present should now handle the explicit empty state (#37). Guard seeders and hooks that read the current run.
• Deprecated object-storage membership method. Custom extensions calling the old membership helper should move to the supported API (#37).
• Debugging. Inspect the runs table and the generated connection names together; a mismatch between the recorded connection and the one your migration actually used is the usual culprit for "migration succeeded but run failed" symptoms.
• Version pinning. At 0.1.x, minor bumps can carry behavioral fixes to transaction and connection handling. Pin exact versions and upgrade deliberately, re-running the Postgres migration suite each time.