tey/docket
Docket is a lightweight Laravel package for defining, organizing, and tracking scheduled tasks or jobs. It provides a simple API to register docket entries, monitor status, and integrate cleanly with existing Laravel workflows.
Architecture fit. Docket is a pre-1.0 Laravel package (v0.1.x) that appears to sit in the migration-execution layer: it wraps Laravel's migrator to track "runs" as first-class records with a run primary key, self-referencing foreign keys, and some form of stack of the "current run." The v0.1.1 notes confirm it manipulates database connections and transaction boundaries directly (#33, #35) and maintains run state in a stack (#37). That is intimate coupling to Laravel's Migrator, DatabaseManager, and connection lifecycle — an area Laravel itself changes between minor versions. Fit is good if the org needs auditable, queryable migration history beyond migrations table rows and deploy-log grepping; it is poor if the requirement is only "run migrations in CI," which Laravel already does.
Integration feasibility. The package is installable and configured like any Laravel package. The real integration work is not installation but validation against our engine matrix. All three fixes in this release are engine- and state-specific (PostgreSQL FK ordering; connection stability under failed writes; empty-stack handling), which tells us the happy path was exercised on MySQL/SQLite first and the harder edges are being discovered in the open. We should not treat v0.1.1 as "the bugs are now fixed" — we should treat it as evidence that the PostgreSQL and failure-path surfaces were under-tested at v0.1.0 and are still settling. Feasible for a spike; not yet feasible to standardize across teams.
Technical risk. Moderate-to-high for production, driven by three factors. (1) Maturity: a third patch release with three correctness fixes, two of which touch transaction isolation and rollback semantics — the worst class of bug to inherit, because a failed migration that partially commits is a data-integrity incident, not an outage. The fix in #33 is precisely a "we might have left a connection in a bad state" class of defect. (2) Blast radius: a defect here fails during deploys, when the system is already in a degraded, mid-change state, and it can leave schema half-applied. (3) Version churn: pre-1.0 with no stated compatibility policy means minor bumps can move the run schema underneath existing rows. The #37 note about removing the "deprecated object-storage membership method" is a small but real signal that internal APIs are still being reshaped; consumers should assume nothing is stable.
Key questions. These must be answered before any adoption decision:
Migrator? The #33 fix implies Docket holds a connection reference across a default-connection switch — what happens with multiple connections, read/write splits, or DB::purge() in a long-running worker?migrate invocation, per deploy, per release tag? That definition determines retention and PII posture for the run history.Stack fit. Natural fit for a Laravel shop already using standard php artisan migrate in CI/CD and wanting a durable, queryable record of what ran, when, and by whom. Low conceptual overhead for the team — it is additive to an existing workflow rather than a replacement. It does not fit shops running schema changes outside Laravel (raw SQL, Alembic, DBA-managed change control), because Docket only sees migrations it orchestrates.
Migration path. None required for greenfield or for any project that has already applied its full history — installing Docket adds a tracking table and begins recording from the next run. The friction is historical: prior migrations will not have run records, so the first deploy produces a history with a single entry and a discontinuity that must be explained in runbooks. Adoption is therefore cleanest at a natural boundary (new service, new major version, or an environment rebuild) rather than retrofitted into a mature production cluster.
Compatibility. Constrain the version tightly (~0.1.1 or an exact pin) — pre-1.0 semver carries no stability guarantee and the changelog style here is bugfix-first, so an unpinned ^0.1 is an unnecessary supply-chain exposure in the deploy path. Pin the database engine and Laravel version in CI to the same combination used in production, and assert on PostgreSQL explicitly given #35/#37.
Sequencing. (1) Spike: install in a throwaway service, run the full migration history against PostgreSQL and MySQL, deliberately induce a failing migration mid-batch and confirm rollback leaves both schema and run history consistent — this directly exercises the #33 and #35 fixes and is the single highest-value validation. (2) Shadow mode: run Docket in one non-critical staging environment for a full release cycle, comparing its run history against CI logs. (3) Pilot: one low-risk production service, with a documented manual recovery procedure if a migration wedges. (4) Decide on standardization only after the pilot survives at least one genuinely failed migration.
Maintenance. Low ongoing effort if pinned and left alone; the cost is periodic deliberate upgrade reviews rather than continuous upkeep. Assign a named owner — deploy-path dependencies without an owner rot silently and then break at the worst moment. Budget one upgrade-and-retest cycle per upstream minor release given pre-1.0 churn.
Support. Expect thin support surfaces: a small maintainer group (single named contributor on this release), GitHub issues rather than an SLA, and a young issue corpus. That is acceptable for internal tooling and unacceptable where an audit/compliance obligation rests on the run history being correct. Establish an internal fallback — the deploy log and migrations table remain the source of truth if Docket misbehaves, and the runbook must say so explicitly.
Scaling. Two dimensions. Concurrency: the package tracks a "current run" stack, which implies stateful assumptions about who is migrating; parallel deploys across environments or regions must be verified, not assumed. History growth: run records accumulate unbounded per deploy; plan a retention/pruning policy and confirm pruning is safe (deleting a parent run should not cascade into audit loss). Neither is a blocker at v0.1 scale, both become one within a year of adoption.
Failure modes. The dominant risk is schema left half-applied after a failed migration — the exact scenario #33 addresses, and the one with the highest recovery cost. Secondary: stale connection state leaking into the remainder of the deploy script after a failed write; incorrect ordering on engines with real FK enforcement (PostgreSQL), producing either a failed deploy or, worse, a silent partial application; empty-stack states (#37) causing a crash at the start of the very first run on a fresh environment — a bad first-impression failure that will hit every new service. Each needs a rehearsed recovery step, not just a note.
Ramp-up. Low for developers: the commands and mental model stay close to Laravel's. The genuine learning is in the failure path — engineers must know how to inspect run state, how to un-wedge a partially applied batch, and when to abandon Docket's history and reconcile manually. That is a half-day of documentation and one tabletop exercise, and it is the difference between a useful audit trail and an incident multiplier. Do not skip it because the package "just wraps migrations."
How can I help you explore Laravel packages today?