Download the PHP package morozmkhl/scalable-db without Composer
On this page you can find all versions of the php package morozmkhl/scalable-db. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download morozmkhl/scalable-db
More information about morozmkhl/scalable-db
Files in morozmkhl/scalable-db
Package scalable-db
Short Description Advanced sharding, replication & fail‑over package for Laravel 11
License MIT
Homepage https://github.com/morozmkhl/scalable-db
Informations about the package scalable-db
ScalableDB
Shard routing layer for Laravel 11 applications. The package resolves a tenant or entity key to a database shard, switches the default connection for the duration of a callback or HTTP request, and provides optional fail-over and operational CLI commands.
Requirements
| Component | Version |
|---|---|
| PHP | ^8.2 |
| Laravel | ^11.5 |
Installation
Optional publish targets:
The scalable-db-database tag provides a sample database-shards.php stub with read/write host configuration.
Configuration
Publish config/scalable-db.php and define shard connections in config/database.php. Each shard entry maps a logical name to a Laravel connection name and an optional list of replica connections used during fail-over.
Fail-over is disabled by default. Set auto_failover to true to enable replica retry on PDOException.
Further reference: Configuration.
Sharding strategies
Hash
Assigns keys using crc32((string) $key) % shard_count and a slot-to-shard map.
Range
Assigns keys by inclusive numeric ranges.
Lookup
Resolves keys from a lookup table (for example, tenants). Supports optional query result caching.
Strategy details: Sharding strategies.
Read/write splitting
ScalableDB does not implement read/write routing. Configure read, write, and sticky on each shard connection in config/database.php using Laravel's built-in behaviour. The package switches the default connection to the shard master; Laravel routes individual statements to read or write hosts within that connection.
Optional helpers select the read or write PDO for the current connection:
HTTP middleware
Register routes behind the shard.tenant middleware alias. The middleware resolves a tenant identifier in the following order:
$request->user()->tenant_id, or$request->user()->idwhentenant_idis absent- HTTP header
X-Tenant-ID - Query parameter
tenant_id
If no tenant identifier is present, the request proceeds without changing the active shard.
Artisan commands
| Command | Description |
|---|---|
php artisan shard:migrate [--shard=NAME] [--path=PATH] |
Run migrations on all shards or one shard |
php artisan shard:seed |
Run the configured seeder class |
php artisan shard:status |
Report connectivity for masters and replicas |
php artisan shard:diagnose [--json] |
Full diagnostics; exit code 1 on failure |
Command reference: CLI.
Events
| Event | Dispatched when |
|---|---|
ShardResolved |
A shard name is resolved from a tenant key |
ShardFailover |
Fail-over switches from master to a replica or fallback connection |
Telescope
Laravel Telescope is an optional dependency. When present, the package registers a watcher that tags entries with shard:<name> based on the active shard context.
Testing
The test suite uses Pest and Orchestra Testbench. CI runs lint, static analysis, a PHP 8.2/8.4 × SQLite/MySQL matrix, and a Docker demo smoke test.
Demo environment
A Docker-based demo application is provided under demo/.
See Demo.
Limitations
- Single-shard scope. Queries run against one shard per callback or request. Cross-shard joins, aggregates, and transactions are not supported.
- Fail-over trigger. Fail-over reacts to
PDOExceptiononly. Application-level errors and connection timeouts outside PDO are not handled automatically. - Fail-over default.
auto_failoverisfalseby default; replica retry must be enabled explicitly. - Replica writes. Fail-over may route traffic to a read-only replica. Write operations against a replica can fail at the database level.
- No rebalancing. The package does not migrate data between shards or rebalance keys.
- No distributed transactions. Two-phase commit and saga patterns are out of scope.
- Replication setup. MySQL (or other) replication must be configured manually in
config/database.php. - Strategy binding.
ShardManageris registered as a singleton. Changingdefault_strategyat runtime requiresapp()->forgetInstance('shard.manager').
Documentation
Full documentation is in docs/: installation, configuration, architecture, API, CLI, and development notes.
Contributing
Run the following before opening a pull request:
Code style is enforced with Laravel Pint. Static analysis uses PHPStan with Larastan.
License
The MIT License. See LICENSE.