Laravel Sharding Laravel Package

Product Decisions This Supports

• Feature viability for tenant/user-scoped reporting: v0.6.4 makes keyed distinct(), grouped, and having aggregates work when the query genuinely reads a single shard. This directly supports per-tenant dashboards, unique-entity counts, and grouped reporting without application-level workarounds or false “cannot be combined across shards” failures.
• Build vs. buy: The package now handles shard-aware aggregate semantics more precisely—especially avg() on grouped keyed queries—reducing the need to build custom routing and aggregation logic around sharded Laravel models.
• Roadmap confidence for sharding adoption: The fix narrows aggregate refusals to queries that actually fan out across shards, and preserves refusals for unkeyed queries and keyed queries during rebalance when pin_by_key is off. That makes rollout planning more predictable for teams moving from single-database to keyed sharding.
• Lower operational/support burden: Fewer false-negative aggregate errors means fewer production incidents, less query rewriting, and fewer support escalations from teams using keyed queries for common analytics patterns.
• Supports correctness-focused use cases: Taking a keyed avg() whole from its shard, instead of as a sum and count from two queries, avoids incorrect results on grouped queries where the two queries may not resolve to the same group.

When to Consider This Package

• You are adopting sharding in a Laravel/PHP application where the dominant access pattern is keyed—e.g., user_id, tenant ID, or account ID—and you want framework-level query routing rather than hand-rolled shard selection.
• Your product needs keyed aggregate queries such as distinct()->count(), grouped counts, having, or avg() within a single shard, and you want those queries to succeed rather than be refused unnecessarily.
• You can accept documented limitations around cross-shard aggregates and unkeyed reporting queries, and you understand behavior during rebalance—especially the interaction with pin_by_key.
• You need a lower-effort path than building shard-aware query parsing, aggregate refusal rules, and rebalance-aware routing in-house.
• Look elsewhere if your primary workload depends on global, unkeyed aggregates across all shards, complex cross-shard joins, distributed transactions, or reporting that routinely fans out and combines aggregates across shards.
• Look elsewhere if you cannot tolerate shard-aware query restrictions or need a fully transparent distributed database rather than an application-level sharding package.

How to Pitch It (Stakeholders)

For executives: v0.6.4 is a correctness and reliability fix for sharded Laravel queries. It removes false failures for keyed aggregate queries—such as per-tenant distinct counts and grouped reporting—and fixes an avg() edge case on grouped keyed queries. This reduces production incidents and support burden while making sharding more viable for customer-facing analytics.

For engineering: The release refines aggregate refusal logic to use the same readsOneShard() check as raw aggregates. A keyed query that reads one shard can now answer distinct(), grouped, and having aggregates locally; unkeyed queries remain refused, and keyed queries during rebalance remain refused when pin_by_key is off and the query fans out again. Keyed avg() is taken whole from its shard rather than split into sum/count queries, avoiding incorrect grouped results. No breaking changes are indicated; this is an adoption-confidence update rather than a new feature release.