Product Decisions This Supports
- Scaling-strategy sequencing. Sharding is the last rung on the ladder (vertical scale → read replicas → native partitioning → sharding). This package makes the top rung cheap to evaluate, so the decision becomes "when do we need it and what does it cost?" rather than an open-ended architecture debate. It supports gating sharding behind concrete thresholds (write throughput, table size, index rebuild / vacuum windows) instead of adopting it speculatively.
- Build vs. buy on shard routing. A YAML-driven topology (define shards once, route through Laravel's Query Builder) is a credible alternative to hand-rolling a routing layer, or to adopting Vitess (MySQL) / Citus (Postgres). Useful for sizing the "we could build this ourselves in a quarter" claim against a real reference implementation.
- Tenancy and isolation packaging. Natural shard keys are almost always the tenant or account ID. That makes sharding a product lever, not just an infra one: per-tenant shards enable noisy-neighbor containment, per-tenant backup/restore, per-tenant migration windows, and enterprise-tier isolation commitments you can put in a contract.
- Data residency and compliance roadmap. Geography-based shard mapping is a direct answer to EU/US data-locality requirements without standing up a second application stack. Feeds into whether "regional data residency" is a roadmap item or a sales-blocker workaround.
- Cost modeling. Compare sharding across commodity instances against one oversized primary plus replicas. Gives finance/eng a shared artifact for the infra line item ahead of a growth cycle.
- Feature feasibility constraints. Deciding to shard determines which features stay cheap: cross-shard joins, global admin search, aggregate reporting, and analytics all get materially harder. This package forces that inventory early, which tells you whether you also need a warehouse/CDC path on the roadmap.
- Plan-tier design. Data-volume-linked tiers become shard-count conversations rather than pricing-page guesses.
When to Consider This Package
Adopt / evaluate when:
- You're on Laravel with MySQL or Postgres and are approaching single-primary limits (write throughput, table bloat, migration lock times).
- A natural shard key —
tenant_id, account_id, region — is already present in nearly every hot query path.
- You want a fast proof-of-concept of routing semantics before committing engineering quarters, and you're comfortable vendoring or forking the code.
- Read/write patterns are tenant-local: no cross-shard transactions, minimal ad-hoc joins, aggregations already headed to a warehouse.
Look elsewhere when:
- Maturity risk dominates. Last release March 2022, 26 stars, zero dependents. There is no community, no issue-triage cadence, and no security-patch stream. If your architecture depends on this for years, you are effectively adopting an internal fork — budget ownership accordingly, or choose a supported path (Vitess/PlanetScale for MySQL, Citus or a managed horizontally-scalable Postgres for Postgres).
- You need Eloquent relationship fidelity, cross-shard joins/aggregations, distributed transactions, or multi-shard migration orchestration.
- You need resharding/rebalancing, shard-aware observability, or failure/retry semantics under partial shard outages — verify what exists here before assuming it's covered.
- Your dataset is coverable for 18–24 months with declarative partitioning plus read replicas. Sharding is a one-way door; buy time.
Validation questions before any commitment: How does it intercept queries (Query Builder vs. Eloquent model events)? What happens to transactions spanning shards? How are migrations and schema drift handled across N shards? What is the resharding story when one shard gets hot? What's the failure mode when a shard is unreachable?
How to Pitch It (Stakeholders)
To executives: Sharding is the expensive answer to a growth problem we will eventually have, and the Laravel ecosystem has no first-party tooling for it — that's the gap this fills. Treat this package as a cheap de-risking instrument, not a dependency: a time-boxed spike that tells us whether our data model is even shardable, what it would cost, and which features we'd have to redesign. That's a small spend against a multi-quarter architecture decision.
To engineering: Config-driven shard topology (YAML) over Laravel's Query Builder, targeting MySQL/Postgres. Attractive because the routing contract is explicit and inspectable rather than buried in model magic. The trade-off is maturity: unmaintained since early 2022 and effectively a single-maintainer project, so plan to vendor it and own the fork.
Recommendation: Run a 2–3 week spike with hard exit criteria — (1) shard key present in ≥95% of hot query paths, (2) written inventory of cross-shard queries and where each goes instead, (3) a migration and resharding plan, (4) a fork-and-own cost estimate. In parallel, get a quote/benchmark on a managed alternative so the build-vs-buy comparison is real. Decision to fund now: the spike, and a named owner for the fallback plan. Not a decision to adopt.