Laravel Shard Laravel Package

Getting Started

This is a Redis sharding package: it spreads keys across multiple Redis shards, keeps a locator mapping so the app knows which shard owns a key, and provides a rebalance operation to move keys between shards. v5.0.1 is a patch release — no breaking changes, no new public API — so existing usage keeps working.

Minimal steps:

1. composer require the package and publish its config (php artisan vendor:publish).
2. Define your shards and the key→shard locator in the config file. All recurring config reads now go through RedisShardConfig, so read that class (and the docs section on configuration) before hand-rolling config() calls.
3. Point your cache/queue connections at the package's connection resolver rather than the stock redis driver.
4. Run the smallest possible rebalance against a scratch environment first — move one or two keys between two shards and observe the retained/fenced counters in the output.

Where to look first: the new "known limitations" documentation section. It is the single most useful page in this release — it explains SQLite conditional deletion, unique constraints, retry risks, and queue fallback behavior, all of which are things you will otherwise discover the hard way.

First real use case: moving a hot key range off an overloaded shard. Do it during a write-quiet window, watch the counters, and reconcile anything the run reports as retained.

Implementation Patterns

Route every access through the locator. Writes and reads that bypass the locator will land on the wrong shard and will not be moved by a rebalance. Treat the package's connection as the only sanctioned entry point.

Rebalance as a queued, batched job. Rebalance is a cross-shard, best-effort operation. Wrap it in a job that processes bounded batches, persists progress, and can be resumed. Do not run it inline in a web request.

Quiesce writes during a move. This is the core operational contract, and v5.0.1 reinforces it: source deletion is now fenced by atomic snapshot predicates. If the source row changed mid-move, the row is retained and counted as fenced rather than deleted. Build a reconcile step into your runbook that reads the retained count and re-processes those keys after writes resume.

Trust the locator mapping at execution time, not at dispatch time. v5.0.1 restores keyed queue context from the current locator mapping instead of overwriting it with the captured connection. The practical pattern: dispatch rebalance/migration jobs with a key, and let the worker re-resolve the shard on pickup. For keyless jobs the package still falls back to captured affinity — so give your jobs keys if you care about mapping changes taking effect mid-flight.

Centralize config reads. RedisShardConfig is now the single source for recurring configuration. If you have custom code reaching into config('redis-shards.*') directly, migrate it to the service or you will drift from package behavior on the next patch.

Flush-aware Pulse and Octane usage. Pulse shard counters are now flushed in HTTP, queue, CLI, and Octane contexts. Under Octane, register the flush in the worker lifecycle and do not cache counter state across requests in a singleton — the package flushes, so any copy you keep will go stale.

Integration tip: test against the same engine you deploy on. The SQLite conditional-deletion path is documented as a known limitation, so a green SQLite suite does not prove your MySQL/Postgres rebalance is correct.

Gotchas and Tips

• Rebalance is not online resharding. The release states this explicitly. There is no claim validation for every production database and column type. Treat it as a maintenance-window tool with a reconcile pass, not a background daemon.
• Ambiguous keys are rejected. A rebalance key matching multiple source rows is now rejected before any copy or delete. Those keys silently stop moving — log the rejection and resolve the duplicate manually, or you will find stale data on the old shard forever.
• Case-insensitive columns need binary comparison. Fenced source deletion compares as binary strings. On a utf8mb4_unicode_ci-style column, what looks like an unchanged row may compare as changed and be retained. Expected, but it inflates your retained count — don't read that as corruption.
• SQLite behaves differently. Conditional deletion semantics differ enough that the docs now call it out. Fine for unit-level logic, not fine as evidence of production rebalance correctness.
• Unique constraints make retries non-idempotent. A retried move can collide on a unique index. Design the copy as an upsert or a pre-checked skip, and reconcile rather than blindly re-running a failed batch.
• Missing mapping falls back to captured affinity. If a key has no locator entry or the job is keyless, you get the captured connection, not an error. Add an assertion in your own code if you need that case to be loud.
• Debugging retained vs. deleted. Instrument the rebalance output: total scanned, copied, deleted, fenced/retained, rejected. If fenced is non-zero on a quiet database, your quiesce window is not actually quiet.
• Extension points to prefer: the config service, the locator mapping, and the job wrapper. Avoid monkey-patching the deletion path — the atomic predicates are the safety net, and replacing them is how you get data loss.
• Version pin carefully but do not fear this release. v5.0.1 is four regression fixes plus docs, verified with a 276-test Docker suite and static analysis. No migration needed beyond reviewing your direct config reads.