dbdump

Fast MySQL dumps without the noise

Reduce database dump time from hours to minutes by automatically excluding audit logs, sessions, and cache tables while keeping your schema intact.

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

3-4 hours down to 15-20 minutes

Smaller Files

15GB down to 3GB

No Broken Keys

All table structures 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.23+ 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/latest/download/dbdump-darwin-arm64.tar.gz
tar -xzf dbdump-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/latest/download/dbdump-darwin-amd64.tar.gz
tar -xzf dbdump-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/latest/download/dbdump-linux-amd64.tar.gz
tar -xzf dbdump-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/latest/download/dbdump-linux-arm64.tar.gz
tar -xzf dbdump-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/latest/download/dbdump-windows-amd64.zip -OutFile dbdump.zip
Expand-Archive dbdump.zip -DestinationPath $HOME\dbdump -Force

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

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

This means excluded tables will exist in your dump as empty tables, so foreign keys never break.

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

# Dry run (preview what will be excluded)
dbdump dump -h localhost -u root -d mydb --dry-run

list

View all tables with their sizes before dumping.

dbdump list -h localhost -u root -d mydb

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	-

Tip: Use DBDUMP_MYSQL_PWD environment variable 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`	Show what would be excluded without dumping
`--no-progress`	Disable progress bar

Excluding Tables

Three ways to exclude tables:

1. Command Line

dbdump dump -u root -d mydb \
  --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 -u root -d mydb --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 -u root -d mydb        # See table sizes
dbdump dump -u root -d mydb --dry-run   # Preview exclusions

Laravel project with extra exclusions

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

Restore a dump

mysql -u root -p mydb < dump_file.sql

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

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?

No. All table structures are preserved. Only the data is excluded for specified tables.

Can I dump only the schema?

Yes! Exclude all tables: dbdump dump -u root -d mydb --exclude-pattern "*"

Is it safe on production?

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