Laravel Hypercacheio Laravel Package

Getting Started

This package plugs a Go-powered, SQLite-backed queue driver into Laravel's queue system, with optional Active-Active HA replication across nodes. Start by requiring it and publishing its config:

composer require vendor/package
php artisan vendor:publish --tag=queue-config

Set a dedicated connection in config/queue.php (don't reuse database):

'sqlite_ha' => [
    'driver' => 'sqlite-ha',
    'database' => database_path('queue.sqlite'),
    'queue' => 'default',
    'retry_after' => 90,
],

Point QUEUE_CONNECTION=sqlite_ha in .env, then smoke-test with a trivial job:

dispatch(function () { logger('queue works'); });
php artisan queue:work sqlite_ha --once

Where to look first: the published config (replication peers, monitoring hooks), then php artisan queue:monitor / your Vigilance dashboard to confirm job counts match reality. If you're running a single node, HA replication settings can be ignored entirely — the v2.2.8 fixes only affect clustered deployments.

First use case: replacing the database queue driver on a single host to get a persistent, crash-safe queue without Redis. If that works, enable peer replication only once you've validated the single-node path.

Implementation Patterns

Cluster topology. Configure peers symmetrically — each node lists every other node's replication endpoint. Asymmetric peer lists are the most common source of "job ran twice" or "job never ran" reports:

'replication' => [
    'enabled' => env('QUEUE_HA_ENABLED', false),
    'peers'   => explode(',', env('QUEUE_HA_PEERS', '')),
    'node_id' => env('QUEUE_HA_NODE_ID'),
],

node_id must be unique per host; it's how tombstones (OpQDel) are attributed.

Deployment ordering. On v2.2.8+, upgrade all nodes before relying on cross-node queue:clear. ClearQueueJobs() is what makes a clear propagate to SQLite on peers; older nodes will keep ghost rows and Vigilance will keep reporting them.

Health checks in CI/CD. Add a post-deploy check that asserts local SQLite row counts match the cluster-reported pending count. A divergence after a clear or a completed batch is the exact symptom v2.2.8 fixed, so it doubles as a regression guard.

Monitoring integration. Vigilance (or any dashboard reading the SQLite table directly) is now trustworthy for ready counts. If you had previously added filters to suppress ghost jobs, remove them — otherwise you'll hide real work.

Job hygiene. Because completed jobs are now deleted from SQLite on peer nodes, don't write tooling that treats the SQLite table as an audit log. Use Laravel events (JobProcessed, JobFailed) or a failed_jobs mirror for history.

Graceful restarts. php artisan queue:restart only affects the local node's workers. In HA, wrap restarts in a loop across hosts (Ansible, Forge, etc.) rather than assuming a single restart reaches the cluster.

Gotchas and Tips

• Ghost jobs after upgrade. If you see stale ready jobs post-upgrade, they're leftovers from pre-2.2.8 nodes. Drain the queue manually on each node once, then re-enable replication.
• SQLite file locking. Concurrent writers on network filesystems (NFS, some container volumes) still cause corruption. Keep the SQLite file on local disk per node — HA replication moves jobs, not the database file.
• queue:clear timing. Clearing is asynchronous across peers, so a job dispatched one second after a clear may still get processed on a node that hasn't received the tombstone. Expect a brief window of ambiguity; don't build exactly-once semantics on top of clear.
• Replication lag debugging. Compare queue:monitor on each node. Lag between push and SQLite sync (the new OpQPush path) is usually network, not the package; check peer endpoint reachability before filing an issue.
• Config caching. php artisan config:cache will freeze node_id and peer lists. If you generate these dynamically per host, exclude them from caching or use env vars resolved at boot.
• Upgrade is safe but not silent. v2.2.8 is a patch with no API changes, but it changes persistence behavior: rows you may have been counting on will now disappear on peer delete. Adjust any ad-hoc queries or reports that read the table directly.
• Extension points. Hook JobProcessed / JobFailed listeners for observability rather than polling SQLite. If you need custom replication metadata, the config's peer definitions are the intended seam — avoid patching the Go binary.
• When to skip HA entirely. Single-node deployments get zero benefit from this release and should leave replication.enabled false, which sidesteps the duplicate-push path that was cleaned up in handleReplicationConn.