@habityzer/db-sync-tool 1.0.3

package/README.md

@@ -0,0 +1,119 @@
+# db-sync-tool
+
+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
+
+```bash
+pnpm add -g @habityzer/db-sync-tool
+# or
+pnpm dlx @habityzer/db-sync-tool --help
+```
+
+The executable is **`dbsync`**. The package is published under the **Habityzer** org on npm (`@habityzer/…`).
+
+## Configuration
+
+### Environment (default)
+
+Create a `.env` in the working directory:
+
+```env
+DATABASE_URL="postgresql://app:!ChangeMe!@127.0.0.1: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:
+
+```json
+{
+  "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`, `-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
+
+- `--drop-before` — drop & recreate database first
+- `--dry-run` — validate backup (full gzip stream check for `.gz`)
+- `--force` — skip confirmation
+- `-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
+
+```bash
+dbsync export
+dbsync export -o ./backups --schema-only
+dbsync restore ./backups/app_20260410_120000.sql.gz
+dbsync restore -i --force
+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

package/bin/dbsync.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { runCli } from '../src/index.js';
+import { AppError } from '../src/utils/errors.js';
+import { printErrorWithSuggestion } from '../src/utils/ui.js';
+
+runCli(process.argv).catch((err) => {
+  if (err instanceof AppError) {
+    printErrorWithSuggestion(err);
+    process.exit(err.exitCode ?? 1);
+    return;
+  }
+  console.error(err?.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@habityzer/db-sync-tool",
+  "version": "1.0.3",
+  "description": "CLI for backing up and restoring PostgreSQL/MySQL databases with .env support, compression, and retention",
+  "type": "module",
+  "bin": {
+    "dbsync": "./bin/dbsync.js"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "cli-progress": "^3.12.0",
+    "commander": "^14.0.0",
+    "dotenv": "^17.0.0",
+    "mysql2": "^3.11.0",
+    "ora": "^9.0.0",
+    "pg": "^8.13.0"
+  },
+  "devDependencies": {
+    "eslint": "^10.0.0",
+    "vite": "^8.0.0",
+    "vitest": "^4.0.0"
+  },
+  "keywords": [
+    "postgresql",
+    "mysql",
+    "backup",
+    "restore",
+    "cli"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Habityzer/dbsync.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Habityzer/dbsync/issues"
+  }
+}

package/src/adapters/mysql.js

@@ -0,0 +1,116 @@
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import mysql from 'mysql2/promise';
+import { AppError } from '../utils/errors.js';
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ */
+export function mysqlConnectionEnv(parsed) {
+  return {
+    ...process.env,
+    MYSQL_PWD: parsed.password,
+  };
+}
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ */
+export function buildMysqlDumpArgs(parsed, opts = {}) {
+  const args = ['-h', parsed.host, '-u', parsed.user];
+  if (parsed.port) args.push('-P', String(parsed.port));
+  args.push(parsed.database);
+  if (opts.schemaOnly) args.push('--no-data');
+  if (opts.dataOnly) args.push('--no-create-info');
+  if (opts.tables?.length) {
+    for (const t of opts.tables) {
+      const name = t.trim();
+      if (name) args.push(name);
+    }
+  }
+  return args;
+}
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ */
+export function buildMysqlArgs(parsed) {
+  const args = ['-h', parsed.host, '-u', parsed.user];
+  if (parsed.port) args.push('-P', String(parsed.port));
+  args.push(parsed.database);
+  return args;
+}
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ */
+export async function testMysqlConnection(parsed) {
+  try {
+    const conn = await mysql.createConnection({
+      host: parsed.host,
+      port: parsed.port ?? 3306,
+      user: parsed.user,
+      password: parsed.password,
+      database: parsed.database || undefined,
+    });
+    await conn.query('SELECT 1');
+    await conn.end();
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new AppError('Cannot connect to database', {
+      suggestion: `Check credentials and host. ${msg}`,
+    });
+  }
+}
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ * @param {{ schemaOnly?: boolean, dataOnly?: boolean, tables?: string[] }} opts
+ */
+export function spawnMysqldump(parsed, opts = {}) {
+  const args = buildMysqlDumpArgs(parsed, opts);
+  const child = spawn('mysqldump', args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: mysqlConnectionEnv(parsed),
+  });
+  return child;
+}
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ */
+export function spawnMysqlRestore(parsed) {
+  const args = buildMysqlArgs(parsed);
+  const child = spawn('mysql', args, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: mysqlConnectionEnv(parsed),
+  });
+  return child;
+}
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ */
+export async function dropMysqlDatabase(parsed) {
+  const db = quoteMySqlIdent(parsed.database);
+  const sql = `DROP DATABASE IF EXISTS ${db}; CREATE DATABASE ${db};`;
+  const args = ['-h', parsed.host, '-u', parsed.user];
+  if (parsed.port) args.push('-P', String(parsed.port));
+  args.push('-e', sql);
+  const child = spawn('mysql', args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: mysqlConnectionEnv(parsed),
+  });
+  let err = '';
+  child.stderr?.on('data', (c) => {
+    err += c.toString();
+  });
+  const [code] = await once(child, 'close');
+  if (code !== 0) {
+    throw new AppError('Failed to drop/recreate database', { suggestion: err.trim() });
+  }
+}
+
+function quoteMySqlIdent(name) {
+  return '`' + String(name).replace(/`/g, '``') + '`';
+}

package/src/adapters/postgres.js

@@ -0,0 +1,148 @@
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import pg from 'pg';
+import { AppError } from '../utils/errors.js';
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ */
+export function pgConnectionEnv(parsed) {
+  const env = {
+    ...process.env,
+    PGPASSWORD: parsed.password,
+    PGHOST: parsed.host,
+    PGUSER: parsed.user,
+    PGDATABASE: parsed.database,
+  };
+  if (parsed.port) env.PGPORT = String(parsed.port);
+  const ssl = parsed.url.searchParams.get('sslmode');
+  if (ssl) env.PGSSLMODE = ssl;
+  return env;
+}
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ * @param {{ schemaOnly?: boolean, dataOnly?: boolean, tables?: string[] }} opts
+ */
+export function buildPgDumpArgs(parsed, opts = {}) {
+  const args = ['-h', parsed.host, '-U', parsed.user];
+  if (parsed.port) args.push('-p', String(parsed.port));
+  args.push('-d', parsed.database);
+  if (opts.schemaOnly) args.push('--schema-only');
+  if (opts.dataOnly) args.push('--data-only');
+  if (opts.tables?.length) {
+    for (const t of opts.tables) {
+      const name = t.trim();
+      if (name) args.push('-t', name);
+    }
+  }
+  return args;
+}
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ * @param {boolean} adminDb - connect to postgres maintenance db
+ */
+export function buildPsqlArgs(parsed, adminDb = false) {
+  const db = adminDb ? 'postgres' : parsed.database;
+  const args = ['-h', parsed.host, '-U', parsed.user, '-d', db, '-v', 'ON_ERROR_STOP=1'];
+  if (parsed.port) args.push('-p', String(parsed.port));
+  return args;
+}
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ */
+export async function testPostgresConnection(parsed) {
+  const client = new pg.Client({
+    host: parsed.host,
+    port: parsed.port ?? 5432,
+    user: parsed.user,
+    password: parsed.password,
+    database: parsed.database || 'postgres',
+    ssl: sslOptionFromUrl(parsed),
+  });
+  try {
+    await client.connect();
+    await client.query('SELECT 1');
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new AppError('Cannot connect to database', {
+      suggestion: `Check credentials and host. ${msg}`,
+    });
+  } finally {
+    await client.end().catch(() => {});
+  }
+}
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ */
+function sslOptionFromUrl(parsed) {
+  const mode = parsed.url.searchParams.get('sslmode');
+  if (!mode || mode === 'disable') return undefined;
+  return { rejectUnauthorized: mode !== 'no-verify' };
+}
+
+/**
+ * Spawn pg_dump; returns child with stdout stream.
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ * @param {{ schemaOnly?: boolean, dataOnly?: boolean, tables?: string[] }} opts
+ */
+export function spawnPgDump(parsed, opts = {}) {
+  const args = buildPgDumpArgs(parsed, opts);
+  const child = spawn('pg_dump', args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: pgConnectionEnv(parsed),
+  });
+  return child;
+}
+
+/**
+ * Spawn psql reading SQL from stdin.
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ * @param {{ admin?: boolean }} opts
+ */
+export function spawnPsqlRestore(parsed, opts = {}) {
+  const args = buildPsqlArgs(parsed, !!opts.admin);
+  const admin = !!opts.admin;
+  const env = {
+    ...pgConnectionEnv(parsed),
+    PGDATABASE: admin ? 'postgres' : parsed.database,
+  };
+  const child = spawn('psql', args, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env,
+  });
+  return child;
+}
+
+/**
+ * Drop and recreate database (connect to postgres).
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ */
+export async function dropPostgresDatabase(parsed) {
+  const dbId = quoteIdent(parsed.database);
+  const sql = `SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = ${literal(parsed.database)} AND pid <> pg_backend_pid(); DROP DATABASE IF EXISTS ${dbId}; CREATE DATABASE ${dbId};`;
+  const env = { ...pgConnectionEnv(parsed), PGDATABASE: 'postgres' };
+  const child = spawn('psql', [...buildPsqlArgs(parsed, true), '-c', sql], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env,
+  });
+  let err = '';
+  child.stderr?.on('data', (c) => {
+    err += c.toString();
+  });
+  const [code] = await once(child, 'close');
+  if (code !== 0) {
+    throw new AppError('Failed to drop/recreate database', { suggestion: err.trim() });
+  }
+}
+
+function quoteIdent(name) {
+  return `"${String(name).replace(/"/g, '""')}"`;
+}
+
+function literal(str) {
+  return `'${String(str).replace(/'/g, "''")}'`;
+}

package/src/commands/clean.js

@@ -0,0 +1,68 @@
+import { unlinkSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig, mergeWithCli } from '../utils/config-loader.js';
+import { scanBackups } from '../utils/backup-scanner.js';
+import { planRetention } from '../utils/retention.js';
+import { formatBytes } from '../utils/progress.js';
+import { BackupError } from '../utils/errors.js';
+import * as ui from '../utils/ui.js';
+
+/**
+ * @param {object} globalOpts
+ * @param {object} cmdOpts
+ */
+export async function runClean(globalOpts, cmdOpts) {
+  const { config } = loadConfig({ configPath: globalOpts.config });
+  const merged = mergeWithCli(config, {});
+  const backupDir = resolve(process.cwd(), merged.backupDir || './backups');
+
+  const entries = scanBackups(backupDir);
+  if (entries.length === 0) {
+    throw new BackupError('📭 No backups found', 'Run dbsync export first');
+  }
+
+  let keepLast =
+    cmdOpts.keepLast !== undefined && cmdOpts.keepLast !== null
+      ? Number(cmdOpts.keepLast)
+      : undefined;
+  let keepDays =
+    cmdOpts.keepDays !== undefined && cmdOpts.keepDays !== null
+      ? Number(cmdOpts.keepDays)
+      : undefined;
+
+  if (keepLast === undefined && keepDays === undefined) {
+    keepLast = merged.keepLast ?? 30;
+  }
+
+  const { remove } = planRetention(entries, {
+    keepLast: keepLast !== undefined && Number.isFinite(keepLast) ? keepLast : undefined,
+    keepDays: keepDays !== undefined && Number.isFinite(keepDays) ? keepDays : undefined,
+  });
+
+  if (remove.length === 0) {
+    ui.success(`${ui.icons.ok} Nothing to clean`);
+    return;
+  }
+
+  ui.infoLine(`${cmdOpts.dryRun ? ui.icons.warn : ui.icons.pkg} ${remove.length} backup(s) eligible for removal:\n`);
+  let freed = 0;
+  for (const e of remove) {
+    freed += e.size;
+    ui.infoLine(`   ${e.filename} (${formatBytes(e.size)})`);
+  }
+  ui.infoLine(`\nTotal freed: ${formatBytes(freed)}`);
+
+  if (cmdOpts.dryRun) {
+    ui.infoLine(`\n${ui.icons.warn} Dry-run: no files deleted`);
+    return;
+  }
+
+  for (const e of remove) {
+    try {
+      unlinkSync(e.path);
+    } catch (err) {
+      ui.warnLine(`Could not delete ${e.path}: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  ui.success(`${ui.icons.ok} Clean complete`);
+}