Darvin Databaser Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require darvinstudio/darvin-databaser-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3/legacy):

   return [
       // ...
       Darvin\DatabaserBundle\DarvinDatabaserBundle::class => ['all' => true],
   ];
   

2. First Use Case: Pull a remote database locally (e.g., staging → development):

   php bin/console databaser:pull root@staging.example.com /var/www/staging /var/www/local
   

   Push local changes to a remote (e.g., development → staging):

   php bin/console databaser:push root@staging.example.com /var/www/staging /var/www/local
   

3. Key Files:

   • config/packages/darvin_databaser.yaml (if created; check for defaults).
   • src/Kernel.php (Symfony 4+) or AppKernel.php (Symfony 3) for bundle registration.
   • var/log/ for debugging output (enable verbose mode with -v).

Implementation Patterns

Workflows

1. CI/CD Integration:

   • Use in deployment pipelines to sync databases between environments (e.g., pre-deploy hook in GitHub Actions):

     - name: Sync Staging DB
       run: php bin/console databaser:pull ${{ secrets.STAGING_USER }}@${{ secrets.STAGING_HOST }}:/path/remote /path/local
     

   • Tip: Wrap commands in a custom Symfony command for reusability.

2. Environment-Specific Config:

   • Override defaults in config/packages/darvin_databaser.yaml:

     darvin_databaser:
         default_port: 2222  # Custom SSH port
         timeout: 300       # Increase for large databases
     

3. Pre/Post-Processing:

   • Before Pull/Push: Run migrations or backups via Symfony events:

     // src/EventListener/DatabaserListener.php
     use Darvin\DatabaserBundle\Event\DatabaserEvent;
     
     public function onPrePull(DatabaserEvent $event) {
         $this->runMigrations(); // Custom logic
     }
     

   • Register the listener in services.yaml:

     services:
         App\EventListener\DatabaserListener:
             tags: ['kernel.event_listener', 'databaser.pre_pull']
     

4. Scheduled Syncs:

   • Use Symfony’s CronBundle or laravel-schedule (if using Laravel’s scheduler) to automate daily syncs:

     * * * * * php bin/console databaser:pull root@backup.example.com /backup/db /local/db
     

Integration Tips

• SSH Key Management:
  • Store keys in ~/.ssh/ with restricted permissions (chmod 600).
  • Use Symfony’s ParameterBag to inject paths dynamically:

    $this->container->getParameter('ssh_key_path');
    

• Database-Specific Handling:
  • For large databases, add --exclude flags to skip non-critical tables:

    php bin/console databaser:pull --exclude=logs,temp root@host /remote /local
    

• Dry Runs:
  • Test connections first with -n (dry run) to validate paths/permissions:

    php bin/console databaser:pull -n root@host /remote /local
    

Gotchas and Tips

Pitfalls

1. Permission Issues:

   • Error: Permission denied (publickey) or Failed to open local file.
   • Fix:
     • Ensure SSH keys are added to ~/.ssh/authorized_keys on the remote.
     • Verify local paths are writable (chmod -R 755 /path/local).
     • Use absolute paths to avoid relative path resolution quirks.

2. Port Conflicts:

   • Error: Connection timed out or Port 22: Connection refused.
   • Fix:
     • Explicitly set -P if the remote uses a non-standard SSH port (e.g., -P 2222).
     • Check firewall rules (ufw allow 2222 on Ubuntu).

3. Database Locks:

   • Error: Table is locked or Deadlock found.
   • Fix:
     • Run during low-traffic periods or use --force (if supported).
     • For MySQL, add --single-transaction to avoid locks:

       php bin/console databaser:pull --option="--single-transaction" root@host /remote /local
       

4. Path Mismatches:

   • Error: No such file or directory for remote/local paths.
   • Fix:
     • Use full paths (e.g., /var/www/ instead of ./).
     • Verify remote paths exist via SSH:

       ssh root@host "ls /var/www/"
       

Debugging

• Verbose Mode: Enable with -v or -vvv for detailed logs:

  php bin/console databaser:pull -vvv root@host /remote /local
  

• Custom Logging: Override the logger in config/packages/monolog.yaml to write to a file:

  handlers:
      databaser:
          type: stream
          path: "%kernel.logs_dir%/databaser.log"
          level: debug
  

Extension Points

1. Custom Commands: Extend the base command to add features (e.g., diff tools):

   // src/Command/CustomDatabaserCommand.php
   use Darvin\DatabaserBundle\Command\AbstractDatabaserCommand;
   
   class CustomDatabaserCommand extends AbstractDatabaserCommand {
       protected function configure() {
           $this->setName('databaser:diff')
                ->addArgument('remote', InputArgument::REQUIRED);
       }
       protected function execute(InputInterface $input, OutputInterface $output) {
           // Custom logic (e.g., call `diff` tool)
       }
   }
   

2. Event Dispatching: Listen for databaser.pre_pull, databaser.post_push, etc., to inject logic:

   // src/EventSubscriber/DatabaserSubscriber.php
   use Darvin\DatabaserBundle\Event\DatabaserEvent;
   
   class DatabaserSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               DatabaserEvent::PRE_PULL => 'onPrePull',
           ];
       }
       public function onPrePull(DatabaserEvent $event) {
           $event->setOption('--exclude', 'cache');
       }
   }
   

3. Configuration Overrides: Dynamically override settings via environment variables:

   # config/packages/darvin_databaser.yaml
   darvin_databaser:
       port: "%env(DATABASER_PORT)%"
       timeout: "%env(int:DATABASER_TIMEOUT)%"
   

Pro Tips

• Backup First: Always back up local/remote databases before syncing:

  mysqldump -u root -p local_db > local_backup.sql
  

• Exclude Binaries: Skip large files (e.g., uploads/) to speed up syncs:

  php bin/console databaser:pull --exclude="uploads/*" root@host /remote /local
  

• Monitor Progress: Use --progress (if supported) or log file sizes pre/post-sync to track changes:

  $event->setOption('--progress', true);