PHPackages ranitachi/multiple-db-laravel - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Database & ORM](/categories/database) 4. / 5. ranitachi/multiple-db-laravel ActiveLibrary[Database & ORM](/categories/database) ranitachi/multiple-db-laravel ============================= Automatic database read/write splitting for Laravel & MariaDB/MySQL cluster with health checking, sticky connections, and zero-config setup. v1.0.0(1mo ago)00MITPHPPHP ^8.1 Since Jun 14Pushed 1mo agoCompare [ Source](https://github.com/ranitachi/multiple-db-laravel)[ Packagist](https://packagist.org/packages/ranitachi/multiple-db-laravel)[ RSS](/packages/ranitachi-multiple-db-laravel/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (5)Versions (2)Used By (0) Multiple DB Laravel =================== [](#multiple-db-laravel) [![GitHub](https://camo.githubusercontent.com/0a9774e95bf88a2c29e85d1af3eb533f191a26aa2fb2302346b65a41e5c9c969/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f72616e6974616368692f6d756c7469706c652d64622d6c61726176656c)](https://github.com/ranitachi/multiple-db-laravel) Automatic database read/write splitting untuk aplikasi Laravel. Install package via Composer, set environment variables, dan semua query otomatis di-route — **tanpa perlu ubah code** di aplikasi yang sudah ada. Mendukung MySQL, MariaDB, dan proxy seperti MaxScale/ProxySQL (same host, different port). Features -------- [](#features) - **Zero-config splitting** — SELECT → read replica, INSERT/UPDATE/DELETE → master - **Separate credentials** — Username/password bisa berbeda antara read dan write - **Same host, different port** — Cocok untuk setup ProxySQL/MaxScale - **Multiple replicas** — Comma-separated read hosts dengan load distribution otomatis - **Sticky connections** — Setelah write, read selanjutnya di request yang sama pakai master - **Health checking** — Deteksi replica yang down, auto-remove dari rotation - **Fallback** — Fallback ke master jika semua replica down - **Force write** — Middleware, trait, dan helper untuk force master pada critical reads - **Query logging** — Monitor distribusi read/write dan slow queries - **Artisan command** — `php artisan db:cluster-status` Requirements ------------ [](#requirements) - PHP 8.1+ - Laravel 10, 11, atau 12 - MySQL / MariaDB Installation ------------ [](#installation) ### Via Composer [](#via-composer) Package sudah tersedia di [Packagist](https://packagist.org/packages/ranitachi/multiple-db-laravel), cukup install langsung: ``` composer require ranitachi/multiple-db-laravel ``` Laravel auto-discover akan register ServiceProvider secara otomatis. ### Publish Config (Optional) [](#publish-config-optional) ``` php artisan vendor:publish --tag=db-cluster-config ``` ### Set Environment Variables [](#set-environment-variables) ``` DB_WRITE_HOST=10.255.0.91 DB_WRITE_PORT=3306 DB_READ_HOST=10.255.0.91 DB_READ_PORT=3307 ``` Selesai. Tidak perlu ubah code apapun di aplikasi. Contoh Setup ------------ [](#contoh-setup) ### Setup 1: Same Host, Different Port (ProxySQL/MaxScale) [](#setup-1-same-host-different-port-proxysqlmaxscale) ``` DB_HOST=10.255.0.91 DB_PORT=3306 DB_USERNAME=dbadmin DB_PASSWORD=password # Cluster config DB_WRITE_HOST=10.255.0.91 DB_WRITE_PORT=3306 DB_READ_HOST=10.255.0.91 DB_READ_PORT=3307 ``` ### Setup 2: Different Hosts, Same Credentials [](#setup-2-different-hosts-same-credentials) ``` DB_USERNAME=dbadmin DB_PASSWORD=password DB_WRITE_HOST=10.255.0.91 DB_WRITE_PORT=3306 DB_READ_HOST=10.255.0.92,10.255.0.93 DB_READ_PORT=3306 ``` ### Setup 3: Different Hosts, Different Credentials [](#setup-3-different-hosts-different-credentials) ``` DB_WRITE_HOST=10.255.0.91 DB_WRITE_PORT=3306 DB_WRITE_USERNAME=dbadmin_master DB_WRITE_PASSWORD=master_secret DB_READ_HOST=10.255.0.92,10.255.0.93 DB_READ_PORT=3306 DB_READ_USERNAME=dbadmin_readonly DB_READ_PASSWORD=readonly_secret ``` ### Setup 4: Mixed — Same User Write, Different User Read [](#setup-4-mixed--same-user-write-different-user-read) ``` DB_USERNAME=dbadmin DB_PASSWORD=password DB_WRITE_HOST=10.255.0.91 DB_WRITE_PORT=3306 DB_READ_HOST=10.255.0.91 DB_READ_PORT=3307 DB_READ_USERNAME=dbadmin_read DB_READ_PASSWORD=read_password ``` Credential Resolution --------------------- [](#credential-resolution) VariableJika disetJika TIDAK diset (fallback)`DB_WRITE_USERNAME`Pakai value ini untuk writePakai `DB_USERNAME` (default Laravel)`DB_WRITE_PASSWORD`Pakai value ini untuk writePakai `DB_PASSWORD` (default Laravel)`DB_READ_USERNAME`Pakai value ini untuk readPakai `DB_USERNAME` (default Laravel)`DB_READ_PASSWORD`Pakai value ini untuk readPakai `DB_PASSWORD` (default Laravel)Jika credentials sama, cukup set `DB_USERNAME` dan `DB_PASSWORD` seperti biasa. Full Environment Variables -------------------------- [](#full-environment-variables) ``` # Core DB_CLUSTER_ENABLED=true # default: true DB_CLUSTER_CONNECTIONS=mysql # default: mysql (comma-separated) # Write (Master) DB_WRITE_HOST=10.255.0.91 # default: DB_HOST DB_WRITE_PORT=3306 # default: DB_PORT DB_WRITE_USERNAME= # default: DB_USERNAME DB_WRITE_PASSWORD= # default: DB_PASSWORD # Read (Replica) DB_READ_HOST=10.255.0.91 # default: DB_HOST DB_READ_PORT=3307 # default: DB_PORT DB_READ_USERNAME= # default: DB_USERNAME DB_READ_PASSWORD= # default: DB_PASSWORD # Behavior DB_CLUSTER_STICKY=true # default: true # Health Check DB_CLUSTER_HEALTH_CHECK=true # default: true DB_CLUSTER_HEALTH_INTERVAL=30 # default: 30 (seconds) DB_CLUSTER_HEALTH_TIMEOUT=3 # default: 3 (seconds) DB_CLUSTER_HEALTH_CACHE=redis # default: file DB_CLUSTER_HEALTH_FALLBACK=true # default: true # Logging DB_CLUSTER_LOG=false # default: false DB_CLUSTER_LOG_CHANNEL=stack # default: stack DB_CLUSTER_LOG_LEVEL=debug # default: debug DB_CLUSTER_SLOW_THRESHOLD=1000 # default: 0 (disabled), milliseconds # Force Write Tables DB_CLUSTER_FORCE_WRITE_TABLES=payments,sessions ``` Advanced Usage -------------- [](#advanced-usage) Fitur-fitur di bawah ini opsional. Package bekerja tanpa perubahan code. ### Force Write pada Route Tertentu [](#force-write-pada-route-tertentu) Middleware `db.write` sudah auto-register oleh package: ``` Route::middleware('db.write')->group(function () { Route::get('/admin/dashboard', [DashboardController::class, 'index']); Route::get('/payment/status/{id}', [PaymentController::class, 'status']); }); ``` ### Force Write pada Model Tertentu [](#force-write-pada-model-tertentu) ``` use Ranitachi\MultipleDb\Traits\UseWriteConnection; class Payment extends Model { use UseWriteConnection; // Semua query pada model ini selalu ke master } ``` ### Force Write dalam Code [](#force-write-dalam-code) ``` use Ranitachi\MultipleDb\DbClusterHelper; // Paksa satu query ke master $user = DbClusterHelper::onWrite(fn () => User::find($id)); // Write lalu stick ke master untuk sisa request DbClusterHelper::writeAndStick(fn () => $user->update($data)); ``` ### Inline useWritePdo (Laravel built-in) [](#inline-usewritepdo-laravel-built-in) ``` $user = User::query()->useWritePdo()->find($id); ``` ### Cek Status Cluster [](#cek-status-cluster) ``` php artisan db:cluster-status ``` ``` === Connection: mysql === Write : 10.255.0.91:3306 (user: dbadmin) Read : user=dbadmin, port=3307 +---------------+------+-----------+---------------------+ | Host | Port | Status | Checked At | +---------------+------+-----------+---------------------+ | 10.255.0.91 | 3307 | ● HEALTHY | 2025-01-15 10:30:00 | +---------------+------+-----------+---------------------+ ✓ All replicas healthy (1/1) Sticky : Yes Fallback to write : Yes Health interval : 30s ``` How It Works ------------ [](#how-it-works) 1. **ServiceProvider boot** — Baca `DB_WRITE_*` dan `DB_READ_*` dari env 2. **Config injection** — Inject Laravel native `read`/`write` array ke database config 3. **Laravel handles routing** — `DatabaseManager` bawaan Laravel route SELECT → read, DML → write 4. **Health checker** — Ping replica periodik, cache hasilnya, remove yang down 5. **Sticky** — Flag `recordsHaveBeenModified()` setelah write agar read pakai master Karena menggunakan mekanisme **native Laravel**, tidak ada overhead tambahan dan kompatibel penuh dengan Eloquent, Query Builder, raw queries, dan semua package Laravel. Quick Start (Per Aplikasi) -------------------------- [](#quick-start-per-aplikasi) ``` # 1. Install dari Packagist composer require ranitachi/multiple-db-laravel # 2. Set env (minimum) # DB_WRITE_HOST=10.255.0.91 # DB_WRITE_PORT=3306 # DB_READ_HOST=10.255.0.91 # DB_READ_PORT=3307 # 3. Verify php artisan db:cluster-status # 4. Done ``` License ------- [](#license) MIT ### Health Score 36 — LowBetter than 79% of packages Maintenance90 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity42 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 46d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/93108639?v=4)[fnazarullah](/maintainers/fnazarullah)[@fnazarullah](https://github.com/fnazarullah) --- Top Contributors [![ranitachi](https://avatars.githubusercontent.com/u/20563799?v=4)](https://github.com/ranitachi "ranitachi (2 commits)") --- Tags laraveldatabasemysqlmariadbsplitread-writeclusterreplicationmultiple-databasemaxscaleproxysql ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/ranitachi-multiple-db-laravel/health.svg) ``` [![Health](https://phpackages.com/badges/ranitachi-multiple-db-laravel/health.svg)](https://phpackages.com/packages/ranitachi-multiple-db-laravel) ``` ### Alternatives [mongodb/laravel-mongodb A MongoDB based Eloquent model and Query builder for Laravel 7.1k8.4M99](/packages/mongodb-laravel-mongodb)[psalm/plugin-laravel Psalm plugin for Laravel 3345.3M348](/packages/psalm-plugin-laravel)[yajra/laravel-oci8 Oracle DB driver for Laravel via OCI8 8793.2M25](/packages/yajra-laravel-oci8)[ntanduy/cloudflare-d1-database Cloudflare D1 database driver for Laravel — full Eloquent & Query Builder support. 267.8k](/packages/ntanduy-cloudflare-d1-database) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)