dbdump

Fast MySQL dumps without the noise

Make development dumps smaller and faster by automatically excluding audit logs, sessions, and cache data while keeping your complete schema.

Get Started View on GitHub

Why dbdump?

Production databases contain millions of rows you don't need for development: audit logs, session data, telescope entries, cache records. These make dumps take hours and consume gigabytes of space.

Faster Dumps

Skip rows you do not need in development

Smaller Files

Keep schema without copying noisy data

Complete Schema

All table definitions and constraints preserved

Quick Start

Get a database dump in two commands.

Set your password

Use an environment variable for security:

export DBDUMP_MYSQL_PWD=yourpassword

Run the dump

Use --auto for smart defaults, or omit it for interactive mode:

dbdump dump -H localhost -u root -d mydb --auto

That's it! Your dump file will be created with noisy tables excluded automatically.

Installation

Using Go

If you have Go 1.26+ installed:

go install github.com/helgesverre/dbdump/cmd/dbdump@latest

Pre-built Binaries

Download the binary for your platform:

curl -LO https://github.com/helgesverre/dbdump/releases/download/vX.Y.Z/dbdump-vX.Y.Z-darwin-arm64.tar.gz
tar -xzf dbdump-vX.Y.Z-darwin-arm64.tar.gz
chmod +x dbdump-darwin-arm64
sudo mv dbdump-darwin-arm64 /usr/local/bin/dbdump

curl -LO https://github.com/helgesverre/dbdump/releases/download/vX.Y.Z/dbdump-vX.Y.Z-darwin-amd64.tar.gz
tar -xzf dbdump-vX.Y.Z-darwin-amd64.tar.gz
chmod +x dbdump-darwin-amd64
sudo mv dbdump-darwin-amd64 /usr/local/bin/dbdump

curl -LO https://github.com/helgesverre/dbdump/releases/download/vX.Y.Z/dbdump-vX.Y.Z-linux-amd64.tar.gz
tar -xzf dbdump-vX.Y.Z-linux-amd64.tar.gz
chmod +x dbdump-linux-amd64
sudo mv dbdump-linux-amd64 /usr/local/bin/dbdump

curl -LO https://github.com/helgesverre/dbdump/releases/download/vX.Y.Z/dbdump-vX.Y.Z-linux-arm64.tar.gz
tar -xzf dbdump-vX.Y.Z-linux-arm64.tar.gz
chmod +x dbdump-linux-arm64
sudo mv dbdump-linux-arm64 /usr/local/bin/dbdump

# Download and extract
Invoke-WebRequest -Uri https://github.com/helgesverre/dbdump/releases/download/vX.Y.Z/dbdump-vX.Y.Z-windows-amd64.zip -OutFile dbdump.zip
Expand-Archive dbdump.zip -DestinationPath $HOME\dbdump -Force
Rename-Item $HOME\dbdump\dbdump-windows-amd64.exe dbdump.exe -Force

# Add to PATH (run once)
$userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
[Environment]::SetEnvironmentVariable("PATH", "$userPath;$HOME\dbdump", "User")
$env:PATH += ";$HOME\dbdump"

Requirement: mysqldump must be in your PATH.

How to install mysqldump

macOS:

brew install mysql-client

Ubuntu/Debian:

sudo apt-get install mysql-client

CentOS/RHEL:

sudo yum install mysql

Windows:

winget install Oracle.MySQL

Verify installation:

dbdump --help

User Guide

How It Works

dbdump uses a two-phase approach to ensure your database structure stays intact:

Phase 1 - Structure: Dumps the schema (CREATE TABLE) for ALL tables
Phase 2 - Data: Dumps data only for tables you want to keep

Excluded tables remain in the dump with their definitions intact. Review exclusions when retained rows depend on omitted parent-table data.

Commands

dump

Create a database dump with smart exclusions.

# Interactive mode (select tables visually)
dbdump dump -H localhost -u root -d mydb

# Auto mode (use smart defaults)
dbdump dump -H localhost -u root -d mydb --auto

# Custom output file
dbdump dump -H localhost -u root -d mydb -o backup.sql

# Gzip-compressed output
dbdump dump -H localhost -u root -d mydb --auto --compress gzip

# Dump through an SSH bastion
dbdump dump -H mysql80 -P 3306 -u root -d mydb \
  --ssh-host bastion.example.com \
  --ssh-user deploy \
  --auto

# Dump over TLS, verifying the server against a CA
dbdump dump -H db.example.com -u root -d mydb \
  --tls-mode verify-identity --tls-ca /etc/ssl/certs/ca.pem --auto

# Non-interactive dry run (preview sizes, rows, and exclusions)
dbdump dump -H localhost -u root -d mydb --auto --dry-run

list

List all tables with their size and row count before dumping.

dbdump list -H localhost -u root -d mydb

config

Save and reuse connection settings as named profiles (stored in ~/.config/dbdump/profiles.yaml with 0600 permissions).

# Save the current connection flags as a profile
dbdump config add prod -H db.example.com -u readonly -d myapp

# List saved profiles
dbdump config list

# Use a profile (explicit flags still override)
dbdump dump --profile prod --auto

# Remove a profile
dbdump config remove prod

Connection Options

Flag	Short	Description	Default
`--host`	`-H`	Database host	127.0.0.1
`--port`	`-P`	Database port	3306
`--user`	`-u`	Database user	-
`--password`	`-p`	Database password	env var
`--database`	`-d`	Database name	-
`--profile`	-	Load connection settings from a saved profile	-

Tip: Use the DBDUMP_MYSQL_PWD environment variable (or MYSQL_PWD as a fallback) instead of -p for security.

Dump Options

Flag	Description
`--output, -o`	Output file path (default: `{database}_{timestamp}.sql`)
`--config, -c`	Path to config file
`--exclude`	Exclude specific table (can be used multiple times)
`--exclude-pattern`	Exclude tables matching pattern (can be used multiple times)
`--auto`	Use smart defaults without interaction
`--dry-run`	Preview the full plan (per-table size and row count, data vs structure-only, totals, resolved output) without dumping
`--compress`	Compression format: `auto`, `none`, `gzip`, or `zstd`
`--ssh-host`	SSH bastion host for built-in tunneling
`--ssh-port`	SSH bastion port (default: `22`)
`--ssh-user`	SSH username (defaults to the database user)
`--ssh-key`	SSH private key path
`--ssh-local-port`	Local tunnel port (default: auto-selected)
`--tls-mode`	TLS mode: `disabled`, `preferred`, `require`, `verify-ca`, `verify-identity`
`--tls-ca`	CA certificate (PEM) used to verify the server
`--tls-cert`, `--tls-key`	Client certificate and key (PEM) for mutual TLS
`--tls-skip-verify`	Encrypt but skip certificate verification (insecure)
`--tls-server-name`	Override the hostname verified against the certificate

An explicit disabled mode stays plaintext and ignores certificate options. Custom TLS options require require, verify-ca, or verify-identity; they cannot be combined with opportunistic preferred mode.

Compression

dbdump can stream output as plain SQL, gzip, or zstd without writing an uncompressed intermediate file first.

# Infer from filename
dbdump dump -H localhost -u root -d mydb -o backup.sql.gz

# Force gzip
dbdump dump -H localhost -u root -d mydb --auto --compress gzip

# Force zstd
dbdump dump -H localhost -u root -d mydb --auto --compress zstd

If you omit --output, dbdump picks the matching default extension automatically.

SSH Tunneling

dbdump can create and tear down a local SSH tunnel for the run, so you do not need to start ssh -L ... separately.

dbdump dump -H mysql80 -P 3306 -u root -d mydb \
  --ssh-host bastion.example.com \
  --ssh-user deploy \
  --ssh-key ~/.ssh/id_ed25519 \
  --auto

When SSH tunneling is enabled, --host and --port still refer to the MySQL endpoint as seen from the SSH server.

Excluding Tables

Three ways to exclude tables:

1. Command Line

dbdump dump -H localhost -u root -d mydb --auto \
  --exclude sessions \
  --exclude cache \
  --exclude-pattern "log_*" \
  --exclude-pattern "temp_*"

2. Project Config File

Create a YAML file for your project:

# myproject.yaml
name: "My Project"
exclude:
  exact:
    - audits
    - sessions
    - cache
  patterns:
    - "temp_*"
    - "*_backup"

Use it with:

dbdump dump -H localhost -u root -d mydb --auto --config ./myproject.yaml

3. Global Config

Create ~/.dbdump.yaml for settings that apply to all dumps:

# ~/.dbdump.yaml
name: "Global Defaults"
exclude:
  exact:
    - activity_logs
  patterns:
    - "old_*"

Default Excludes

dbdump automatically excludes these common "noisy" tables:

Exact matches:

activity_log
audits
sessions
cache
cache_locks
failed_jobs
telescope_entries
telescope_entries_tags
telescope_monitoring
pulse_entries
pulse_aggregates

Patterns:

telescope_*
pulse_*
*_cache

These are always applied. Your config adds to them, it doesn't replace them.

Interactive Mode

When you run without --auto, you get a visual table selector:

Key	Action
`Arrow Up/Down` or `j/k`	Move cursor
`Space`	Toggle table selection
`Enter`	Confirm and start dump
`Ctrl+C`	Cancel

Selected tables will have their data excluded (structure is always kept).

Common Examples

Dump production for local development

export DBDUMP_MYSQL_PWD=secret
dbdump dump -H db.example.com -u readonly -d myapp_prod --auto -o dev-db.sql

Preview before dumping

dbdump list -H localhost -u root -d mydb        # See table sizes
dbdump dump -H localhost -u root -d mydb --auto --dry-run   # Preview exclusions

Laravel project with extra exclusions

dbdump dump -H localhost -u root -d laravel_db \
  --exclude jobs \
  --exclude notifications \
  --exclude password_resets \
  --auto

Remote dump over SSH with gzip output

dbdump dump -H mysql80 -P 3306 -u root -d mydb \
  --ssh-host bastion.example.com \
  --ssh-user deploy \
  --ssh-key ~/.ssh/id_ed25519 \
  --compress gzip \
  --auto

Restore a dump

# Plain SQL
mysql -u root -p mydb < dump_file.sql

# Gzip-compressed
gzip -dc dump_file.sql.gz | mysql -u root -p mydb

# Zstd-compressed
zstd -dc dump_file.sql.zst | mysql -u root -p mydb

Troubleshooting

"mysqldump is required but not found in PATH"

Install MySQL client tools for your system (see installation section above).

"failed to connect to database"

Check that:

Database is running
Host, port, user, password are correct
User has SELECT, SHOW VIEW, TRIGGER, LOCK TABLES permissions

SSH tunnel fails before connecting

Check that the SSH host is reachable, your key is valid, and the bastion allows local port forwarding. The first connection may also require a host-key trust prompt unless the host is already in known_hosts.

Dump is still too large

Use dbdump list to find large tables, then add more exclusions with --exclude or update your config file.

Pattern not matching tables

Patterns use glob syntax: * matches any characters, ? matches one character. Use quotes around patterns on the command line.

FAQ

Does dbdump delete my data?

No. dbdump only reads from your database. It never modifies your source database.

Will excluding tables break foreign keys?

All foreign-key definitions are preserved. Excluding parent-table rows can still leave retained data with missing logical relationships, so preview the plan before dumping.

Can I dump only the schema?

Yes. Exclude every table's data while preserving its structure: dbdump dump -H localhost -u root -d mydb --auto --exclude-pattern "*"

Is it safe on production?

Yes, dbdump only performs read operations. Consider running during low-traffic periods or using a read replica.