DBrancher (DDEV Add-on)

A DDEV add-on that brings isolated, dynamic database routing to your Drupal feature branches. Useful for tricky setups that can’t easily use worktrees.

Features

• Clones Database: When checking out a feature branch, it will make a clone for that branch.
• Auto-Provisioning: Prompts you [y/N] to clone your database when checking out new branches.
• Private Hook Injection: Injects the automation directly into your .git/hooks/post-checkout folder to avoid enforcing it upon teammates who don’t want it.
• PHP Safe Routing: Automatically appends the necessary PDO check to your settings.local.php file during installation.

Smart Garbage Collection

To ensure orphaned databases are deleted when their corresponding pull requests are merged, you must configure Git to automatically prune deleted remote branches:

git config --global fetch.prune true

Once configured, the add-on will automatically sweep MariaDB and delete orphaned databases.

Installation

Run this command from the root of your DDEV project:

ddev add-on get cballenar/ddev-dbrancher-addon

Manual Commands

• ddev dbranch list: Lists all isolated databases and their statuses (Active, Orphaned, etc).
• ddev dbranch drop <branch_name>: Drops the isolated database for a specific branch.
• ddev dbranch drop current: Drops the isolated database for your active branch.
• ddev dbranch drop orphaned: Forces a garbage collection scan for orphaned databases.
• ddev dbranch init [file_path]: Imports a database dump and runs the Drupal update pipeline (updb, cim, cr). If no file_path is provided, it automatically finds the newest .sql.gz dump in your customized search directory.

Customization

By default, the dbranch init script searches your project root for database dumps. If your team stores database dumps in a specific folder (e.g., db_dumps/), you can customize the search directory by creating a .ddev/dbranch-config file:

# .ddev/dbranch-config
DUMP_DIR="db_dumps"