DumpMaster

Interactive MySQL dump toolkit for humans.

Save your MySQL connections once. Pick a database, pick a mode, get a .sql file. Works against native installs, Docker containers, and remote / managed MySQL — with four fallback strategies so it just works even when your machine doesn't have mysqldump on PATH.

Install

npm install -g dumpmaster

Requires Node ≥ 18. Nothing else is required — DumpMaster fetches its own mysqldump via Docker if you don't have one installed.

Start it

dumpmaster

Full-screen keyboard-driven UI. Use ↑ ↓ to move, ⏎ to select, esc to go back, q to quit.

◆ DumpMaster · MySQL backups made friendly — local, remote, or docker
─────────────────────────────────────────────────────────────────────
 Connection: prod-read  •  Database: orders               ready
─────────────────────────────────────────────────────────────────────
 ┌ Dumping orders… ─────────────────────────────────────────────┐
 │  streaming orders_20260912-091822.sql   128.4 MB written     │
 │  (single-file dumps don't have a known total)                │
 └──────────────────────────────────────────────────────────────┘

What it does

• Save connections (host / port / user / password / SSL / optional Docker container).
• Passwords in your OS keychain (via keytar) — or AES-256-GCM in a local file protected by a master password if the keychain isn't available.
• Pick from your saved connections, list databases, dump one — as a single .sql or a folder of one-file-per-table.
• Automatically picks the best dump strategy for your setup:

| You have | Strategy chosen | What it does | |---|---|---| | mysqldump on PATH | local | Spawns the binary directly. Fastest. | | A running MySQL container on this machine | docker-exec | Runs mysqldump inside your container over the Unix socket. No image pull. | | No mysqldump, but Docker is running | docker-image | Pulls mysql:<major> or mariadb:<major> and runs a throwaway container. | | Remote / managed MySQL that firewalls docker's egress IP | native (opt-in retry) | Streams the dump from Node via mysql2 — same network path as the DB list. |

• Auto-detects running MySQL containers — if you'd be about to fall into docker-image for a localhost connection but a MySQL container is already running, it offers to use that instead (no image pull, seconds instead of minutes).
• MariaDB support — detected from SELECT VERSION(), images and flags switch automatically.
• Retry-with-native escape hatch — when a Docker-based dump fails (firewalls, allowlists, VPN mismatches), the error card offers a one-key retry that dumps directly from Node.
• Doctor — one command that tells you what's installed and what isn't.

The connection form

| Field | Notes | |---|---| | Nickname | Any label you'll recognize. | | Host | localhost, an IP, or a full hostname. | | Port | Defaults to 3306. | | User / Password | Standard MySQL credentials. Password stored in the OS keychain (or encrypted file). | | Use SSL/TLS | Turn on for servers that refuse plain connections (most managed / remote MySQL). Local dev servers usually don't need it. | | Run mysqldump inside container | Only when your MySQL runs as a container on this machine. Picker is auto-populated by docker ps. Leave (none) otherwise. |

Every field has inline helper text explaining why it's there, so a first-timer never has to guess.

Keyboard cheatsheet

| Screen | Keys | Action | |---|---|---| | Anywhere | esc | Back / cancel | | Home | q | Quit | | Connection list | a e d ⏎ | Add · edit · delete · use | | Connection form | ↑↓ / tab / shift+tab | Move between fields (never trapped) | | Connection form | space | Toggle SSL | | Connection form | ctrl+s | Save from any field | | DB picker | type | Live filter | | Error card | r | Retry in place | | Dump in progress | ctrl+c | Cleanly kills the child and exits |

Non-interactive mode

Everything the TUI does is also a commander subcommand — for scripts and CI.

# Add a connection
dumpmaster connections add \
  --name prod-read \
  --host db.internal --port 3306 \
  --user reader --password '••••'

# List / remove
dumpmaster connections list
dumpmaster connections remove prod-read

# Dump
dumpmaster dump --connection prod-read --db orders --mode single --out ./backups

# Environment check
dumpmaster doctor

Where files land

<baseOutDir>/<connection nickname>/
├── orders_20260912-091822.sql              ← single mode
└── orders_20260912-172705/                 ← folder mode
    ├── schema.sql
    └── tables/
        ├── users.sql
        ├── invoices.sql
        └── …

<baseOutDir> defaults to ./dumps and can be overridden with --out. Every dump gets a unique timestamped name, so nothing is ever overwritten.

Config file

~/.dumpmaster/config.json  (mode 0600)

Holds connection metadata only. Passwords are never stored in plain text. They live in your OS keychain via keytar — Windows Credential Manager, macOS Keychain, or libsecret on Linux. If the keychain isn't available on your machine, DumpMaster falls back to AES-256-GCM ciphertext in the same JSON file, keyed off a master password you enter once per session.

To move from the fallback to the keychain: npm rebuild keytar in the project root — the master-password prompt goes away.

Troubleshooting

Every error surfaces as a card with a plain-English title, the real underlying message, and a numbered list of fixes. The r key retries the failed action in place. A few of the frequent ones:

Almost always means the Docker container's outbound IP isn't on the server's firewall allowlist — your host has a working route (VPN, allowlisted IP), the container doesn't. From the error card, pick "Retry with native (mysql2) dump — bypass docker". Or install mysqldump locally so it uses your host's network.

A network-side failure, not a MySQL rejection. Almost always a dropped VPN when the hostname is on a private endpoint. nslookup <host> from another terminal confirms it. Press r to retry once your network is back.

You're pointed at a MariaDB server. DumpMaster now detects that from SELECT VERSION() and uses mariadb:<major> instead. Update to the latest version if you're seeing this.

Version / vendor mismatch on flags. DumpMaster splits its flag set by target family — MySQL-only flags (--set-gtid-purged, --column-statistics) are omitted against MariaDB. Update to the latest version.

Fixed in the latest version — the derived key is cached per session. If it still happens, npm rebuild keytar to get onto your OS keychain instead.

Full runtime diagnostics:

dumpmaster doctor

Reports whether mysqldump, docker (daemon included), and keytar are available, and what versions.

Development

git clone https://github.com/AshwinthRajendiran/Dump-Master.git
cd Dump-Master
npm install
npm run build
node bin/dumpmaster.js

Source is TypeScript (src/), compiled to ESM (dist/). The TUI is ink; the CLI is commander.

Reference docs

• DumpMaster internals — how the four strategies are picked and executed.
• How MySQL and mysqldump work in the world — background on where MySQL runs and why the same command behaves differently in different places.
• User flow map — every screen and decision the app can walk you through.

License

MIT — see LICENSE.

Made for anyone who has ever fought MySQL Workbench to take a backup.