Clone Db Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require inigopascall/clone-db
   

2. Publish Config

   php artisan vendor:publish --provider="InigoPascall\CloneDb\CloneDbServiceProvider" --tag="config"
   

   Edit config/clone-db.php to define:

   • source_connection (e.g., mysql_live)
   • destination_connection (e.g., mysql_staging)
   • batch_size (default: 1000)
   • tables (optional: whitelist/blacklist tables)

3. First Run

   php artisan clone-db:run
   

   Verify dependencies are resolved and data integrity is preserved.

First Use Case: Staging Sync

Clone a production subset (e.g., users, orders) to staging:

// config/clone-db.php
'tables' => [
    'include' => ['users', 'orders'],
    'exclude' => ['sensitive_data'],
],

Run:

php artisan clone-db:run --tables=users,orders

Implementation Patterns

Workflow: Incremental Syncs

1. Partial Clones Use --tables flag to sync specific schemas:

   php artisan clone-db:run --tables=customers,products
   

2. Exclude Tables Skip large tables (e.g., logs) via config:

   'exclude' => ['logs', 'audit_trail'],
   

3. Batch Optimization Adjust batch_size for memory constraints (default: 1000):

   'batch_size' => 500, // For memory-limited servers
   

Integration Tips

1. Pre/Post Hooks Extend via service provider:

   // app/Providers/CloneDbServiceProvider.php
   public function boot()
   {
       CloneDb::beforeClone(function () {
           // Backup destination DB
       });
   
       CloneDb::afterClone(function () {
           // Run migrations or seeders
       });
   }
   

2. Custom Dependency Ordering Override table ordering logic:

   // app/Providers/CloneDbServiceProvider.php
   CloneDb::setTableOrderResolver(function ($tables) {
       return $this->customOrderLogic($tables);
   });
   

3. Event Listeners Listen for clone-db.starting, clone-db.completed:

   // app/Listeners/CloneDbLogger.php
   public function handle()
   {
       Log::info('Clone started at: '.now());
   }
   

Gotchas and Tips

Pitfalls

1. Foreign Key Loops

   • Issue: Circular dependencies (e.g., A → B → A) will fail.
   • Fix: Manually exclude one table or restructure data.

2. Transaction Limits

   • Issue: Large batches may hit max_allowed_packet or transaction timeouts.
   • Fix: Reduce batch_size or disable transactions:

     'disable_transactions' => true,
     

3. Case-Sensitive Tables

   • Issue: MySQL on Linux is case-sensitive; users ≠ Users.
   • Fix: Ensure config/table names match DB schema exactly.

Debugging

1. Dry Run Test without writing:

   php artisan clone-db:run --dry-run
   

2. Verbose Logging Enable debug mode:

   php artisan clone-db:run --verbose
   

   Or set in config:

   'debug' => env('DB_CLONE_DEBUG', false),
   

3. Partial Failures

   • If a table fails, check logs for constraint errors.
   • Use --skip-failed to continue after errors (destructive).

Extension Points

1. Custom Table Processors Modify how data is inserted:

   CloneDb::setTableProcessor(function ($table, $batch) {
       // Transform data before insert
       return $this->transformBatch($batch);
   });
   

2. Connection Validation Add pre-clone checks:

   CloneDb::beforeClone(function () {
       if (!DB::connection('destination')->getPdo()) {
           throw new \Exception('Destination DB unavailable');
       }
   });
   

3. Post-Clone Actions Automate post-sync tasks:

   CloneDb::afterClone(function () {
       Artisan::call('migrate', ['--force' => true]);
   });