dbsync (@habityzer/dbsync)

CLI for backing up and restoring PostgreSQL and MySQL databases with .env support, gzip compression, timestamped backups, listing, retention cleanup, and interactive restore.

Requirements

• Node.js 18+
• PostgreSQL client tools on PATH when using Postgres: pg_dump, psql
• MySQL client tools on PATH when using MySQL: mysqldump, mysql

Install

pnpm add -g @habityzer/dbsync
# or
pnpm dlx @habityzer/dbsync --help

The executable is dbsync. The package is published under the Habityzer org on npm (@habityzer/dbsync).

If pnpm add -g warns that the package has no binaries, pnpm is skipping the global link because the npm tarball did not ship bin/dbsync.js with the executable bit. Use npm install -g @habityzer/dbsync (npm still wires up the CLI), pnpm dlx @habityzer/dbsync, or upgrade once a release publishes the bin as executable.

The package was previously published as @habityzer/db-sync-tool. Switch installs to @habityzer/dbsync; after the first release under the new name you can run npm deprecate @habityzer/db-sync-tool "Renamed to @habityzer/dbsync".

Configuration

Environment (default)

Create a .env in the working directory:

DATABASE_URL="postgresql://app:[email protected]:5434/app?serverVersion=16"

• postgresql:// is normalized to postgres://
• Query params serverVersion, charset, and driver are stripped for native tools
• Override file: --env-file <path>
• Override variable name: --env-var MY_DATABASE_URL

Optional JSON config

.db-sync.json or .db-syncconfig.json in the project root:

{
  "backupDir": "./backups",
  "compress": true,
  "compressLevel": 6,
  "keepLast": 30,
  "timestampFormat": "YYYYMMDD_HHMMSS"
}

Override path: --config <path>.

Commands

| Command | Description | |--------|-------------| | dbsync export | Stream dump → gzip (default) → file under backupDir | | dbsync restore [file] | Stream file → decompress if needed → psql / mysql | | dbsync list | List backups with size, date, database name | | dbsync info <file> | File metadata and parsed backup name | | dbsync clean | Retention: --keep-last, --keep-days, --dry-run | | dbsync test | SELECT 1 via pg / mysql2 drivers |

Global options

• --env-file, --env-var, --config, --admin-url, -v/--verbose, -h/--help, -V/--version

Export

• -o, --output — file path or directory (default naming: {db}_{YYYYMMDD}_{HHMMSS}.sql.gz)
• --schema-only, --data-only, --tables a,b
• --no-compress, --compress-level 1-9

Restore

By default the target database is dropped and recreated, then the backup is applied. The CLI prints this plan before asking for confirmation.

• --admin-url / DBSYNC_ADMIN_URL / DATABASE_ADMIN_URL / .db-sync.json adminUrl — optional privileged connection used only for drop/recreate (terminate backends, DROP DATABASE, CREATE DATABASE). Must use the same host and port as DATABASE_URL; only user and password may differ. Use this when DATABASE_URL is an application user whose password is wrong for psql, or a role that cannot drop databases (e.g. app vs postgres superuser).
• --no-drop-before — import into the existing database without dropping it (advanced)
• PostgreSQL: owner/privilege lines in plain SQL dumps are skipped by default (portable restores). Use --preserve-privileges only if you need exact ACLs and matching roles on the server.
• -y, --yes or --force — skip the confirmation prompt (same meaning)
• --dry-run — validate backup (full gzip stream check for .gz)
• -i, --interactive — pick backup from list
• -d, --database — filter interactive list

List

• -d, --database, -l, --limit, --since YYYY-MM-DD

Clean

• --keep-last N — keep newest N (default from config or 30 if nothing else set)
• --keep-days N — also keep anything newer than N days (union with keep-last)
• --dry-run

Examples

dbsync export
dbsync export -o ./backups --schema-only
dbsync restore ./backups/app_20260410_120000.sql.gz
dbsync restore -i -y
dbsync list --database app --limit 5
dbsync info ./backups/app_20260410_120000.sql.gz
dbsync clean --keep-last 10 --dry-run
dbsync test

Large databases

Exports and restores use streaming (no in-memory buffering of the full dump). Progress shows bytes transferred during export (spinner) and a bar during restore when the input file size is known.

Troubleshooting

| Issue | Suggestion | |-------|------------| | No .env | Create .env with DATABASE_URL or pass --env-file | | Cannot connect | Run dbsync test; check host, port, user, password, SSL params | | pg_dump / psql not found | Install PostgreSQL client tools and ensure they are on PATH | | Permission denied on backup dir | Fix directory permissions or choose another --output / backupDir |

License

MIT