Shard Matrix Laravel Package

Getting Started

• Treat this package as a shard router for Laravel’s Query Builder: you define shard connections and routing rules in YAML, then send shard-keyed queries through the package so it selects the right MySQL/Postgres connection.
• Minimal install:

  composer require jrsaunders/shard-matrix
  

  Then publish/configure the package config. Check the README for the exact publish command/tag; the important artifact is the YAML shard map, typically config/shard-matrix.yaml.
• Define every physical shard connection in config/database.php first. The YAML should reference those Laravel connection names, not raw credentials, so env-specific hosts/passwords stay in Laravel config.
• Start with one high-volume or multi-tenant table, not the whole schema. A good first use case is orders or events keyed by tenant_id/account_id: create the table on each shard, insert through the shard-aware builder, then query by the same shard key.
• Where to look first:
  1. README YAML example and package service provider.
  2. The shard resolver/manager class that maps shard key values to connections.
  3. The query builder integration point—how the package wraps DB::table() or DB::connection().
• Smoke test in Tinker: insert a row with a known shard key, query it back by that key, and log the resolved connection name. If you cannot see which connection was used, add temporary logging before building more features.

Implementation Patterns

• Choose an immutable, high-cardinality shard key: tenant_id, account_id, user_id. Avoid mutable keys like status, email, or created date. Every hot-path query should include the shard key.
• Resolve shard context once per request/job and reuse it. A middleware can map tenant -> shard and bind it to a scoped service; jobs and Artisan commands must explicitly rehydrate that context because there is no HTTP session.
• Use the package’s shard-aware Query Builder for sharded tables. Prefer DB::table(...) via the package’s builder over plain Eloquent unless the package documents an Eloquent trait/model integration. Eloquent relationships across shards will not work transparently.
• Keep global/reference tables small and replicated or pinned to a global shard: countries, plan types, feature flags. Join them in application code or on the same shard; do not rely on cross-shard SQL joins.
• Run schema migrations per shard. Keep one canonical migration set and loop over shard connections, recording applied migrations per shard. Avoid ad-hoc schema changes on individual shards.
• For writes, wrap the routed shard operation in a normal Laravel transaction. Do not expect distributed transactions across shards; use an outbox table, idempotency keys, and retryable jobs for cross-shard workflows.
• For admin/reporting queries, implement explicit fan-out: iterate shard connections, run the query per shard, merge results in PHP, and paginate with care. Do not let a reporting page accidentally scan every shard on every request.
• Testing pattern: use real MySQL/Postgres test shards if possible. Seed the YAML shard map for the test environment, run migrations on each test shard, and assert both the row and the resolved connection name.

Gotchas and Tips

• Maturity risk is real: last release was 2022 and adoption is low. Before production, verify PHP/Laravel version constraints, run the test suite, and audit the shard resolver and query builder code paths you depend on.
• YAML config typos are a common failure mode. Validate that every connection name in the shard map exists in config/database.php, and log the resolved shard key -> connection mapping in non-production.
• Cross-shard joins, aggregates, and whereIn across tenants are not magically solved. Design around them with denormalized read tables, fan-out services, or a reporting warehouse.
• Transactions are per shard. A workflow that writes to two shards needs idempotency, compensation, or an outbox pattern; a Laravel DB::transaction() will not make it atomic.
• Eloquent relationships and eager loading can silently break shard boundaries. Keep related rows on the same shard key, or resolve related records manually via the correct shard connection.
• Shard rebalancing is hard. Pick a shard key and capacity plan you can live with; do not assume the package will automatically move rows between shards.
• Debug with connection names: inspect the package’s resolved connection, enable query logs on that connection, and assert toSql() plus the connection name in tests.
• Clear Laravel config cache after YAML changes (php artisan config:clear). If the package caches the shard map, clear that cache too.
• Extension points to investigate: custom shard resolvers, query builder macros, model traits, and package events. If the package lacks a hook you need, wrap it behind your own repository/service layer so you can replace it later.