Laravel Shard Laravel Package

Product Decisions This Supports

• Scale-out vs replatform: When a single Redis node becomes the capacity or connection bottleneck, this package lets you shard in-app instead of migrating to Redis Cluster or a managed cluster. That is a buy-vs-build-vs-replatform call with real cost and lock-in consequences; the package defers building an internal locator/sharding layer.
• Tenant and tier isolation: Shard-per-tenant or shard-per-plan gives per-customer quotas, noisy-neighbor containment, data-residency options, and a smaller blast radius. Feeds pricing/packaging decisions (does a premium tier get dedicated shards?).
• Queue architecture: Keyed queue context restored from the current locator mapping (rather than the captured connection) decides whether jobs stay co-located with tenant data across a shard move. Supports the decision between tenant-affine job processing and centralized queues.
• Observability and SLOs: Pulse shard counters now flush in HTTP, queue, CLI, and Octane contexts, so per-shard dashboards are trustworthy enough for capacity planning and customer-facing latency commitments.
• Maintenance-window policy: Rebalance is explicitly best-effort and requires quiescing writes. That constrains release cadence and any roadmap promise of "live migration"; plan a no online resharding line item.
• Launch gate / risk register: v5.0.1 fixes rebalance paths that could copy or delete the wrong rows when a key matched multiple source rows, and hardens fenced deletion for case-insensitive columns. Set 5.0.1 as the minimum version before any customer-facing shard move.
• Schema-fit decision: The new limitations doc (unique constraints, SQLite conditional deletion, retry risks, queue fallback) is the input to "is our schema compatible?" — treat it as a gate, not a footnote.

When to Consider This Package

Consider adoption when:

• You run Laravel with Redis for cache/session/queue and one node is the bottleneck, while Redis Cluster's single-slot constraints or managed per-shard pricing are unattractive.
• You need tenant- or region-affine key placement rather than uniform hashing.
• Your workload tolerates a controlled quiesce window for shard moves, and you can reconcile retained/fenced rows afterward.
• You can own the runbook: pre-move snapshot, fencing verification, post-move reconciliation, per-shard Pulse monitoring.
• Your Laravel/PHP versions are inside the tested matrix (the suite carries a Laravel-version skip — verify the floor against your own matrix).

Look elsewhere when:

• You need online resharding or per-key migration guarantees with zero write downtime. This release does not claim validation across every production database and column type.
• Your model depends on unique constraints or conditional-deletion semantics the docs flag as risky, or you need cross-key atomicity across shards.
• A managed cluster or proxy with vendor-supported failover and rebalancing better matches your ops maturity.
• Keys or columns use case-insensitive collations without a clear binary-comparison story — validate before trusting fenced deletion.
• The team lacks bandwidth for an ongoing shard-topology runbook; best-effort moves plus manual reconciliation is recurring cost, not a one-time integration.

How to Pitch It (Stakeholders)

Executives: This gives us horizontal headroom on the Redis tier and per-tenant isolation without replatforming to a managed cluster or re-architecting data access. We take on a documented maintenance window and an ops runbook instead of per-shard vendor spend. Two asks: approve 5.0.1 as the minimum version and approve a quiesce-window policy for shard moves.

Engineering: In-app shard locator with copy-then-fence deletion for moving keys between shards, keyed queue affinity that survives a move, and per-shard Pulse counters flushed across HTTP, queue, CLI, and Octane. 5.0.1 is a correctness release: it rejects ambiguous rebalance keys before copying or deleting, guards source deletion with atomic snapshot predicates (binary comparison for case-insensitive columns) so a changed row is retained and counted as fenced, restores queue context from the live locator mapping, and centralizes config reads through RedisShardConfig. Verification: four regressions reproduced then fixed; 276 tests / 725 assertions green in Docker with static analysis, formatting, and CI clean.

State the caveats up front: rebalance remains best-effort — quiesce writes and reconcile retained rows; there is no online resharding. A missing mapping or keyless job still falls back to captured affinity. Schema-dependent limits (unique constraints, retry behavior, SQLite conditional deletion) are documented and should be read before integration, not after.