dbdump

Fast MySQL dump tool that excludes noisy data while preserving complete database structure.

Using dbdump from an agent or automation? Start with the deployed llms.txt for a concise, non-interactive setup and safety guide.

Why dbdump?

When dumping production databases for development, you often don't need millions of audit log entries, session data, or cache records. These tables can make dumps take hours and consume gigabytes of space.

dbdump solves this by:

Excluding data from noisy tables (audits, sessions, cache, etc.)
Preserving every table definition, including foreign-key constraints
Reducing work in proportion to the rows excluded
Making development database refreshes practical

Installation

Using Homebrew

brew install helgesverre/tap/dbdump

Upgrade later with brew upgrade helgesverre/tap/dbdump. Available for macOS and Linux (Intel and Apple Silicon / ARM64).

Using Go

If you have Go 1.26+ installed:

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

Pre-built Binaries

Download the matching versioned asset from the releases page. Asset names include the tag, for example dbdump-v1.2.0-darwin-arm64.tar.gz.

macOS (Apple Silicon)

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

macOS (Intel)

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

Linux (AMD64)

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

Linux (ARM64)

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

Windows (AMD64)

Download the versioned Windows asset from the releases page, extract dbdump-windows-amd64.exe, rename it to dbdump.exe, and place it on your PATH.

Verify Installation

dbdump --help

Requirements

MySQL client tools - mysqldump must be in your PATH (comes with MySQL client)
- macOS: brew install mysql-client
- Ubuntu/Debian: sudo apt-get install mysql-client
- CentOS/RHEL: sudo yum install mysql

From Source (Developers)

git clone https://github.com/helgesverre/dbdump.git
cd dbdump
just install

just install builds and installs to ~/.local/bin (no sudo); pass a destination to override, e.g. just install /usr/local/bin. Ensure the target directory is on your PATH.

Requires Go 1.26+ and just.

Quick Start

Interactive Mode (Default)

# Recommended: Use environment variable for password
export DBDUMP_MYSQL_PWD=yourpassword
dbdump dump -H localhost -u root -d mydb

# Or provide password as flag (less secure)
dbdump dump -H localhost -u root -p password -d mydb

This will:

Connect to your database
Show all tables with sizes
Pre-select noisy tables based on patterns
Let you customize the selection
Dump structure for all tables, data for selected tables

Auto Mode (Non-Interactive)

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

Uses smart defaults without interaction.

With Config File

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

Usage

Basic Commands

# Set password securely via environment variable
export DBDUMP_MYSQL_PWD=yourpassword

# Dump database (interactive)
dbdump dump -H localhost -u root -d mydb

# List tables with sizes
dbdump list -H localhost -u root -d mydb

# Non-interactive dry run (see what would be excluded)
dbdump dump -H localhost -u root -d mydb --auto --dry-run

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

# Dump with streaming compression
dbdump dump -H localhost -u root -d mydb --auto --compress gzip

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

Connection Options

-H, --host        Database host (default: 127.0.0.1)
-P, --port        Database port (default: 3306)
-u, --user        Database user
-p, --password    Database password (or use DBDUMP_MYSQL_PWD/MYSQL_PWD env)
-d, --database    Database name
    --profile     Load connection settings from a saved profile (see `dbdump config`)

TLS/SSL Options

    --tls-mode          TLS mode: disabled, preferred, require, verify-ca, verify-identity
    --tls-ca            Path to the TLS CA certificate (PEM) used to verify the server
    --tls-cert          Path to the client certificate (PEM) for mutual TLS
    --tls-key           Path to the client private key (PEM) for mutual TLS
    --tls-skip-verify   Encrypt but skip server certificate verification (insecure)
    --tls-server-name   Override the hostname verified against the server certificate

Dump Options

-o, --output           Output file (default: {database}_{timestamp}.sql)
-c, --config           Config file path
    --exclude          Exclude specific table data (repeatable)
    --exclude-pattern  Exclude tables matching pattern (repeatable)
    --include          Keep this table's data even when a rule excludes it (repeatable)
    --auto             Use smart defaults without interaction
    --dry-run          Show what would be dumped without dumping
    --compress         Compression format: auto, none, gzip, zstd
    --ssh-host         SSH bastion host for tunneling to the database
    --ssh-port         SSH bastion port (default: 22)
    --ssh-user         SSH username (defaults to database user)
    --ssh-key          SSH private key path
    --ssh-local-port   Local port for the SSH tunnel (default: auto)

Compression

dbdump can stream output as plain SQL, gzip, or zstd. --compress auto infers the format from the output filename, while explicit formats override filename inference.

If you omit --output, compressed dumps use matching default names such as mydb_20260331_120000.sql.gz or mydb_20260331_120000.sql.zst.

SSH Tunneling

You can still create a manual tunnel yourself, but dbdump can now manage it directly:

dbdump dump -H 127.0.0.1 -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, -H/--host and -P/--port still describe the database endpoint as seen from the SSH server.

TLS/SSL

dbdump can connect over TLS, applied to both its own inspection connection and the mysqldump subprocess:

# Encrypt and verify the server against a CA
dbdump dump -H db.example.com -u readonly -d myapp \
  --tls-mode verify-identity --tls-ca /etc/ssl/certs/ca.pem --auto

# Mutual TLS (client certificate)
dbdump dump -H db.example.com -u readonly -d myapp \
  --tls-mode verify-ca --tls-ca ca.pem --tls-cert client.pem --tls-key client-key.pem --auto

# Encrypt only, skip verification (dev / self-signed)
dbdump dump -H localhost -u root -d mydb --tls-mode require --tls-skip-verify --auto

Modes mirror MySQL's ssl-mode: disabled, preferred (opportunistic), require (encrypt, no verification), verify-ca (verify the chain), and verify-identity (verify the chain and hostname). An explicit disabled mode ignores certificate options and remains plaintext. Because custom certificates cannot preserve opportunistic fallback consistently across both clients, combine them with require, verify-ca, or verify-identity, not preferred. Behind an SSH tunnel the host becomes 127.0.0.1, so use --tls-server-name to pin the real certificate name. With no --tls-* flag, connections behave exactly as before.

Examples

# Use environment variable for password
export DBDUMP_MYSQL_PWD=secret
dbdump dump -H prod.example.com -u readonly -d myapp_prod

# Exclude specific tables
dbdump dump -H localhost -u root -d mydb \
  --exclude audits \
  --exclude activity_logs \
  --exclude-pattern "temp_*"

# With project config
dbdump dump -H localhost -u root -d mydb --config ./myproject.yaml

# Auto mode with custom output
dbdump dump -H localhost -u root -d mydb --auto -o daily-backup.sql

# Auto mode with gzip output
dbdump dump -H localhost -u root -d mydb --auto --compress gzip

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

Configuration

dbdump supports multiple configuration layers that merge together:

Built-in defaults (always applied)
Global user config (~/.dbdump.yaml) - optional, applies to all dumps
Project config (via --config flag) - optional, project-specific
CLI flags (highest priority)

For a comprehensive guide, see USER-GUIDE.md.

Global User Config

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

name: "My Global Config"

exclude:
  exact:
    - activity_logs
    - user_sessions
  patterns:
    - "temp_*"
    - "*_backup"

Project Config File

Create a project.yaml file in your project:

name: "My Project"

exclude:
  exact:
    - audits
    - activity_logs
    - custom_noisy_table
  patterns:
    - "temp_*"
    - "*_cache"
    - "old_*"

Use it with:

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

Default Exclusions

dbdump includes smart defaults for common Laravel 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 defaults are always applied. Later layers can add more excludes. Use --include <table> to override any matching rule.

How It Works

dbdump writes the dump in three phases:

Phase 1: Structure Dump
- Dumps complete schema for ALL tables
- Preserves foreign-key definitions and other table relationships
- Uses mysqldump --no-data --skip-triggers
Phase 2: Data Dump
- Dumps data for all tables EXCEPT excluded ones
- Uses mysqldump --no-create-info --ignore-table=...
Phase 3: Triggers
- Writes trigger definitions after the data so loading rows does not fire them
- Uses mysqldump --no-data --no-create-info --triggers

Result: A complete database dump with empty noisy tables.

Expected Impact

The savings depend on how much of the source database is in excluded tables. Applications dominated by audit logs, sessions, caches, or telemetry benefit the most: dbdump retains those tables' definitions while omitting their rows. Run dbdump list, followed by dbdump dump --auto --dry-run, to estimate the impact for your database before creating a dump.

Documentation

User Documentation

USER-GUIDE.md - Comprehensive user guide with detailed configuration, examples, and troubleshooting
CHANGELOG.md - Version history

Developer Documentation

TESTING_GUIDE.md - Complete testing documentation
BENCHMARKING.md - Performance testing guide

Development

Building

# Build for current platform
just build

# Build for all platforms
just build-all

# Run tests
just test

# Format code
just fmt

Testing

Integration Tests

# Run the full integration test suite (starts Docker Compose locally)
./test/integration-test.sh

# Cleanup
docker compose -f docker/docker-compose.yml down -v

See test/README.md for detailed testing documentation.

Manual Testing

# Test security (password not in process list)
export DBDUMP_MYSQL_PWD=testpass123
./bin/dbdump dump -H 127.0.0.1 -P 3308 -u root -d testdb --auto
ps aux | grep dbdump  # Should NOT show password

# Verify file permissions (should be 0600)
ls -la testdb_*.sql

# Test data integrity (triggers and events are included; routines are intentionally omitted)
grep -i "CREATE TRIGGER" testdb_*.sql
grep -i "CREATE EVENT" testdb_*.sql

Project Structure

dbdump/
├── cmd/dbdump/          # CLI entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── database/        # Database operations
│   ├── patterns/        # Pattern matching
│   └── ui/              # Interactive UI
├── configs/             # Example configurations
└── justfile             # Build commands

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Author

Helge Sverre

Acknowledgments

Built with Cobra for CLI
Interactive UI using Bubble Tea

Branding

Font: Monda
Icon: Remix Icon
Colors:
- Dark: #0F172A
- Icon: #F9FAFB
- Text: #FFFFFF

Name		Name	Last commit message	Last commit date
.claude		.claude
.github		.github
art		art
cmd/dbdump		cmd/dbdump
configs		configs
docker		docker
docs/spikes		docs/spikes
internal		internal
scripts		scripts
test		test
website		website
.gitignore		.gitignore
.golangci.yml		.golangci.yml
AGENTS.md		AGENTS.md
BENCHMARKING.md		BENCHMARKING.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
TESTING_GUIDE.md		TESTING_GUIDE.md
USER-GUIDE.md		USER-GUIDE.md
claude.md		claude.md
go.mod		go.mod
go.sum		go.sum
justfile		justfile

Latest commit

History

Folders and files

Repository files navigation