DBPull

Refresh your local database from a remote database over SSH with one command.

DBPull synchronizes a remote database to a local database by rebuilding the target schema, copying data, and installing triggers. It is designed for development environments where local data needs to stay in sync with staging or other remote databases.

Tested with: MariaDB, MySQL

Features

• SSH tunnel support
• Interactive configuration
• Schema + data + triggers synchronization
• Table and data exclusion
• Sync preview (plan)
• Connection diagnostics (doctor)
• Cross-platform builds

Installation

Install the latest release:

curl -fsSL https://faisallbhr.github.io/dbpull/install.sh | sh

You can also download a binary from GitHub Releases, or build from source:

make build

Quick Start

dbpull init
dbpull doctor
dbpull plan
dbpull sync

Basic Configuration

Configuration is stored in the OS config directory by default:

• Linux: ~/.config/dbpull/dbpull.yml
• macOS: ~/Library/Application Support/dbpull/dbpull.yml
• Windows: %AppData%\dbpull\dbpull.yml

Use --config /path/to/dbpull.yml when you need a different file.

source:
  ...

ssh:
  ...

target:
  host: 127.0.0.1
  port: 3306
  database: production
  username: root
  password: secret
  allow_remote_target: false

sync:
  triggers: true

  exclude_tables:
    - cache
    - tmp_*
    - *_logs

  exclude_data:
    - audits
    - sessions_*
    - *_histories

• exclude_tables skips the table completely.
• exclude_data keeps the schema but skips copying rows.
• triggers installs source triggers after data synchronization so they do not run while rows are copied. Default: true.

sync only accepts local targets (localhost, 127.0.0.1, or ::1) by default. To sync to a remote target, set target.allow_remote_target: true; DBPull will still require an interactive y confirmation before opening any connections. Remote sync is rejected in non-interactive environments.

Advanced Performance Configuration

Most users do not need to change these values. If needed, add them manually under sync:

sync:
  # Optional advanced settings
  batch_size: 10000
  workers: 2
  transaction_batches: 20
  max_batch_bytes: 16777216

• batch_size: max rows per insert batch before other limits. Default: 10000.
• workers: number of tables copied in parallel. Default: 2. Use 1 for sequential data sync.
• transaction_batches: commit after this many insert batches. Default: 20.
• max_batch_bytes: estimated max data size per batch before flushing. Default: 16777216 (16 MiB).
• Peak batch memory is roughly workers x max_batch_bytes, plus row and query overhead.
• More workers can improve full sync speed, but also uses more source/target connections and memory.

Recommended starting point:

sync:
  batch_size: 10000
  workers: 2
  max_batch_bytes: 16777216
  transaction_batches: 20

Schema sync remains sequential to avoid unnecessary foreign key, metadata lock, and DDL recovery risk. Data sync uses the worker setting.

Commands

Command	Description
init	Create configuration
config	Edit configuration
doctor	Check connections
plan	Preview synchronization
sync	Synchronize database
list-tables	List source tables
version	Show version

Build

make build
make build-all
make release

License

This project is licensed under the MIT License. See the LICENSE file for details.