@habityzer/db-sync-tool 1.0.3

package/src/commands/export.js

@@ -0,0 +1,195 @@
+import {
+  createWriteStream,
+  mkdirSync,
+  statSync,
+  existsSync,
+  writeFileSync,
+  unlinkSync,
+} from 'node:fs';
+import { dirname, join, resolve, isAbsolute } from 'node:path';
+import { PassThrough } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { once } from 'node:events';
+import { loadEnvFile } from '../utils/env-loader.js';
+import { loadConfig, mergeWithCli } from '../utils/config-loader.js';
+import { parseDatabaseUrl } from '../utils/url-parser.js';
+import { createCompressStream } from '../utils/compression.js';
+import { createStreamProgress, formatBytes } from '../utils/progress.js';
+import { AppError, FileSystemError } from '../utils/errors.js';
+import * as ui from '../utils/ui.js';
+import { spawnPgDump } from '../adapters/postgres.js';
+import { spawnMysqldump } from '../adapters/mysql.js';
+
+function timestampSuffix() {
+  const now = new Date();
+  const y = now.getFullYear();
+  const m = String(now.getMonth() + 1).padStart(2, '0');
+  const d = String(now.getDate()).padStart(2, '0');
+  const hh = String(now.getHours()).padStart(2, '0');
+  const mm = String(now.getMinutes()).padStart(2, '0');
+  const ss = String(now.getSeconds()).padStart(2, '0');
+  return `${y}${m}${d}_${hh}${mm}${ss}`;
+}
+
+/**
+ * @param {object} opts
+ */
+function resolveOutputPath(opts) {
+  const dbName = opts.dbName || 'database';
+  const compress = opts.compress !== false;
+  const ext = compress ? '.sql.gz' : '.sql';
+  const name = `${dbName}_${timestampSuffix()}${ext}`;
+  const backupDir = resolve(process.cwd(), opts.backupDir || './backups');
+
+  if (!opts.output) {
+    return { filePath: join(backupDir, name), backupDir };
+  }
+
+  const out = opts.output;
+  const resolved = isAbsolute(out) ? out : resolve(process.cwd(), out);
+
+  if (existsSync(resolved) && statSync(resolved).isDirectory()) {
+    return { filePath: join(resolved, name), backupDir: resolved };
+  }
+
+  if (out.endsWith('/') || out.endsWith('\\')) {
+    const dir = resolve(process.cwd(), out);
+    return { filePath: join(dir, name), backupDir: dir };
+  }
+
+  if (/\.sql(\.gz)?$/i.test(out)) {
+    return { filePath: resolved, backupDir: dirname(resolved) };
+  }
+
+  return { filePath: join(resolved, name), backupDir: resolved };
+}
+
+/**
+ * @param {string} dir
+ */
+function ensureWritableDirSync(dir) {
+  try {
+    mkdirSync(dir, { recursive: true });
+    const test = join(dir, '.dbsync-write-test');
+    writeFileSync(test, 'ok');
+    unlinkSync(test);
+  } catch {
+    throw new FileSystemError(
+      `Cannot write to ${dir}`,
+      'Check permissions or create the directory'
+    );
+  }
+}
+
+/**
+ * @param {import('../utils/url-parser.js').ParsedDatabaseUrl} parsed
+ * @param {{ schemaOnly?: boolean, dataOnly?: boolean, tables?: string[] }} dumpOpts
+ * @param {import('node:stream').Transform | import('node:stream').PassThrough} compressStream
+ * @param {import('node:fs').WriteStream} writeStream
+ * @param {{ verbose?: boolean }} ctx
+ */
+async function runDumpPipeline(parsed, dumpOpts, compressStream, writeStream, ctx) {
+  const child =
+    parsed.type === 'postgres'
+      ? spawnPgDump(parsed, dumpOpts)
+      : spawnMysqldump(parsed, dumpOpts);
+
+  let stderr = '';
+  child.stderr?.on('data', (c) => {
+    stderr += c.toString();
+  });
+
+  const progress = createStreamProgress(`${ui.icons.save} Exporting...`, ctx);
+  progress.start();
+  const t0 = Date.now();
+
+  const counter = new PassThrough();
+  counter.on('data', (chunk) => progress.increment(chunk.length));
+
+  // Subscribe before pipeline: if 'close' fires before we await, `once` would miss it and hang.
+  const closePromise = once(child, 'close');
+
+  try {
+    await pipeline(child.stdout, compressStream, counter, writeStream);
+    const [code] = await closePromise;
+    if (code !== 0) {
+      progress.fail(`${ui.icons.err} Export failed`);
+      throw new AppError(`Dump process exited with code ${code}`, {
+        suggestion: stderr.trim() || 'Check pg_dump/mysqldump are installed',
+      });
+    }
+    const bytes = typeof progress.getBytes === 'function' ? progress.getBytes() : 0;
+    const secs = ((Date.now() - t0) / 1000).toFixed(1);
+    progress.succeed(`${ui.icons.save} ${formatBytes(bytes)} in ${secs}s`);
+  } catch (e) {
+    if (e instanceof AppError) throw e;
+    progress.fail(`${ui.icons.err} Export failed`);
+    throw e;
+  }
+}
+
+/**
+ * @param {object} globalOpts
+ * @param {object} cmdOpts
+ */
+export async function runExport(globalOpts, cmdOpts) {
+  loadEnvFile(globalOpts.envFile);
+  const { config } = loadConfig({ configPath: globalOpts.config });
+  const merged = mergeWithCli(config, {});
+
+  const envVar = globalOpts.envVar || 'DATABASE_URL';
+  const rawUrl = process.env[envVar];
+  const parsed = parseDatabaseUrl(rawUrl);
+
+  if (/[!@#$%]/.test(parsed.password)) {
+    ui.warnLine(
+      `${ui.icons.warn} Password contains special characters — encoded for connection. Verify if connection fails.`
+    );
+  }
+
+  const compress = merged.compress !== false && !cmdOpts.noCompress;
+  let level = Number(cmdOpts.compressLevel ?? merged.compressLevel ?? 6);
+  if (!Number.isFinite(level)) level = 6;
+  level = Math.min(9, Math.max(1, level));
+  const tables = cmdOpts.tables
+    ? String(cmdOpts.tables)
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : undefined;
+
+  if (cmdOpts.schemaOnly && cmdOpts.dataOnly) {
+    throw new AppError('Cannot use --schema-only and --data-only together');
+  }
+
+  const { filePath, backupDir } = resolveOutputPath({
+    dbName: parsed.database || 'database',
+    compress,
+    output: cmdOpts.output,
+    backupDir: merged.backupDir,
+  });
+
+  ensureWritableDirSync(backupDir);
+
+  const masked = parsed.url.toString().replace(/:[^:@/]+@/, ':***@');
+  ui.infoLine(`${ui.icons.pkg} Exporting database '${parsed.database || 'default'}'...`);
+  ui.infoLine(`${ui.icons.link} Connected to ${masked}`);
+
+  const compressStream = createCompressStream(compress, level);
+  const writeStream = createWriteStream(filePath);
+
+  const dumpOpts = {
+    schemaOnly: !!cmdOpts.schemaOnly,
+    dataOnly: !!cmdOpts.dataOnly,
+    tables,
+  };
+
+  await runDumpPipeline(parsed, dumpOpts, compressStream, writeStream, {
+    verbose: globalOpts.verbose,
+  });
+
+  const st = statSync(filePath);
+  const compLabel = compress ? `gzip (level ${level})` : 'none';
+  ui.success(`${ui.icons.ok} Exported to: ${filePath}`);
+  ui.infoLine(`${ui.icons.chart} Size: ${formatBytes(st.size)} | Compression: ${compLabel}`);
+}

package/src/commands/info.js

@@ -0,0 +1,31 @@
+import { statSync, existsSync } from 'node:fs';
+import { resolve, isAbsolute } from 'node:path';
+import { parseBackupFilename } from '../utils/backup-scanner.js';
+import { formatBytes } from '../utils/progress.js';
+import { BackupError } from '../utils/errors.js';
+import * as ui from '../utils/ui.js';
+
+/**
+ * @param {object} globalOpts
+ * @param {string} fileArg
+ */
+export async function runInfo(globalOpts, fileArg) {
+  if (!fileArg) {
+    throw new BackupError('Missing file path', 'Usage: dbsync info <file>');
+  }
+  const p = isAbsolute(fileArg) ? fileArg : resolve(process.cwd(), fileArg);
+  if (!existsSync(p)) {
+    throw new BackupError('Invalid backup file', 'Check the path');
+  }
+  const st = statSync(p);
+  const name = p.split(/[/\\]/).pop() || fileArg;
+  const compressed = name.endsWith('.gz');
+  const { database, parsedDate } = parseBackupFilename(name);
+
+  ui.infoLine(`${ui.icons.pkg} Backup: ${name}`);
+  ui.infoLine(`   Size: ${formatBytes(st.size)}`);
+  ui.infoLine(`   Modified: ${st.mtime.toISOString()}`);
+  if (database) ui.infoLine(`   Database: ${database}`);
+  if (parsedDate) ui.infoLine(`   Parsed timestamp: ${parsedDate.toISOString()}`);
+  ui.infoLine(`   Compression: ${compressed ? 'gzip' : 'none'}`);
+}

package/src/commands/list.js

@@ -0,0 +1,63 @@
+import { resolve } from 'node:path';
+import { loadConfig, mergeWithCli } from '../utils/config-loader.js';
+import { scanBackups, filterBackups } from '../utils/backup-scanner.js';
+import { formatBytes } from '../utils/progress.js';
+import { BackupError } from '../utils/errors.js';
+import * as ui from '../utils/ui.js';
+
+/**
+ * @param {string[]} widths
+ * @param {string[]} cells
+ */
+function row(widths, cells) {
+  const parts = cells.map((c, i) => String(c).padEnd(widths[i]));
+  return `│ ${parts.join(' │ ')} │`;
+}
+
+/**
+ * @param {object} globalOpts
+ * @param {object} cmdOpts
+ */
+export async function runList(globalOpts, cmdOpts) {
+  const { config } = loadConfig({ configPath: globalOpts.config });
+  const merged = mergeWithCli(config, {});
+  const backupDir = resolve(process.cwd(), merged.backupDir || './backups');
+
+  let entries = scanBackups(backupDir);
+  let since =
+    cmdOpts.since != null && cmdOpts.since !== ''
+      ? new Date(String(cmdOpts.since).includes('T') ? cmdOpts.since : `${cmdOpts.since}T00:00:00`)
+      : undefined;
+  if (since && Number.isNaN(since.getTime())) {
+    ui.warnLine(`${ui.icons.warn} Ignoring invalid --since date: ${cmdOpts.since}`);
+    since = undefined;
+  }
+  entries = filterBackups(entries, {
+    database: cmdOpts.database,
+    limit: cmdOpts.limit,
+    since,
+  });
+
+  if (entries.length === 0) {
+    throw new BackupError('📭 No backups found', 'Run dbsync export first');
+  }
+
+  ui.infoLine(`${ui.icons.pkg} Available backups:\n`);
+
+  const widths = [3, 28, 10, 12, 12];
+  const sep = `├${widths.map((w) => '─'.repeat(w + 2)).join('┼')}┤`;
+  console.log(`┌${widths.map((w) => '─'.repeat(w + 2)).join('┬')}┐`);
+  console.log(row(widths, ['#', 'File', 'Size', 'Date', 'Database']));
+  console.log(sep);
+
+  let totalBytes = 0;
+  entries.forEach((e, i) => {
+    totalBytes += e.size;
+    const when = (e.parsedDate ?? e.mtime).toISOString().slice(0, 10);
+    const name = e.filename.length > 26 ? `${e.filename.slice(0, 23)}...` : e.filename;
+    console.log(row(widths, [String(i + 1), name, formatBytes(e.size), when, e.database ?? '—']));
+  });
+
+  console.log(`└${widths.map((w) => '─'.repeat(w + 2)).join('┴')}┘`);
+  ui.infoLine(`\nTotal: ${entries.length} backups | ${formatBytes(totalBytes)}`);
+}

package/src/commands/restore.js

@@ -0,0 +1,147 @@
+import { createReadStream, statSync, existsSync } from 'node:fs';
+import { resolve, isAbsolute } from 'node:path';
+import { PassThrough } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { once } from 'node:events';
+import { loadEnvFile } from '../utils/env-loader.js';
+import { loadConfig, mergeWithCli } from '../utils/config-loader.js';
+import { parseDatabaseUrl } from '../utils/url-parser.js';
+import { createDecompressStream } from '../utils/compression.js';
+import { createFileProgressBar, formatBytes } from '../utils/progress.js';
+import { validateBackupFile } from '../utils/backup-validate.js';
+import { scanBackups, filterBackups } from '../utils/backup-scanner.js';
+import { AppError, BackupError } from '../utils/errors.js';
+import * as ui from '../utils/ui.js';
+import { confirm, ask } from '../utils/prompt.js';
+import { spawnPsqlRestore, dropPostgresDatabase } from '../adapters/postgres.js';
+import { spawnMysqlRestore, dropMysqlDatabase } from '../adapters/mysql.js';
+
+/**
+ * @param {string} fileArg
+ */
+function resolveBackupPath(fileArg) {
+  if (!fileArg) return null;
+  if (isAbsolute(fileArg)) return fileArg;
+  return resolve(process.cwd(), fileArg);
+}
+
+/**
+ * @param {object} globalOpts
+ * @param {object} cmdOpts
+ * @param {string | undefined} fileArg
+ */
+export async function runRestore(globalOpts, cmdOpts, fileArg) {
+  loadEnvFile(globalOpts.envFile);
+  const { config } = loadConfig({ configPath: globalOpts.config });
+  const merged = mergeWithCli(config, {});
+  const backupDir = resolve(process.cwd(), merged.backupDir || './backups');
+
+  const envVar = globalOpts.envVar || 'DATABASE_URL';
+  const parsed = parseDatabaseUrl(process.env[envVar]);
+
+  let filePath = fileArg ? resolveBackupPath(fileArg, backupDir) : null;
+
+  if (cmdOpts.interactive || !filePath) {
+    const dbFilter = cmdOpts.database || parsed.database;
+    let entries = filterBackups(scanBackups(backupDir), {
+      database: dbFilter || undefined,
+    });
+    if (entries.length === 0 && dbFilter) {
+      ui.warnLine(
+        `${ui.icons.warn} No backups matched database filter; showing all backups.`
+      );
+      entries = scanBackups(backupDir);
+    }
+    if (entries.length === 0) {
+      throw new BackupError('📭 No backups found', 'Run dbsync export first');
+    }
+    ui.infoLine(`${ui.icons.pkg} Available backups${parsed.database ? ` for '${parsed.database}'` : ''}:\n`);
+    entries.forEach((e, i) => {
+      const when = (e.parsedDate ?? e.mtime).toISOString().slice(0, 10);
+      ui.infoLine(
+        `${i + 1}. ${e.filename} (${formatBytes(e.size)}) - ${when}`
+      );
+    });
+    const ans = await ask(`\nSelect backup to restore (1-${entries.length}) or 'q' to quit: `);
+    if (ans.trim().toLowerCase() === 'q') {
+      process.exit(0);
+    }
+    const n = Number(ans.trim());
+    if (!Number.isInteger(n) || n < 1 || n > entries.length) {
+      throw new AppError('Invalid selection');
+    }
+    filePath = entries[n - 1].path;
+  }
+
+  if (!filePath || !existsSync(filePath)) {
+    throw new BackupError('Invalid backup file', 'Check the path and try again');
+  }
+
+  const isGzip = filePath.endsWith('.gz');
+  if (cmdOpts.dryRun) {
+    await validateBackupFile(filePath, isGzip);
+    ui.success(`${ui.icons.ok} Backup file looks valid (dry-run)`);
+    return;
+  }
+
+  if (!cmdOpts.force) {
+    ui.warnLine(
+      `${ui.icons.warn} Warning: This will overwrite current database '${parsed.database || 'default'}'`
+    );
+    const ok = await confirm('Continue? (y/N): ');
+    if (!ok) {
+      ui.infoLine('Cancelled.');
+      process.exit(0);
+    }
+  }
+
+  if (cmdOpts.dropBefore) {
+    ui.infoLine(`${ui.icons.warn} Dropping and recreating database...`);
+    if (parsed.type === 'postgres') {
+      await dropPostgresDatabase(parsed);
+    } else {
+      await dropMysqlDatabase(parsed);
+    }
+  }
+
+  const masked = parsed.url.toString().replace(/:[^:@/]+@/, ':***@');
+  ui.infoLine(`${ui.icons.spin} Restoring from ${filePath.split(/[/\\]/).pop()}...`);
+  ui.infoLine(`${ui.icons.link} Connected to ${masked}`);
+
+  const st = statSync(filePath);
+  const bar = createFileProgressBar(`${ui.icons.save} Restoring...`, st.size, {
+    verbose: globalOpts.verbose,
+  });
+  bar.start();
+
+  const readStream = createReadStream(filePath);
+  const decompress = createDecompressStream(isGzip);
+  const counter = new PassThrough();
+  counter.on('data', (c) => bar.increment(c.length));
+
+  const child =
+    parsed.type === 'postgres' ? spawnPsqlRestore(parsed) : spawnMysqlRestore(parsed);
+
+  let stderr = '';
+  child.stderr?.on('data', (c) => {
+    stderr += c.toString();
+  });
+
+  const t0 = Date.now();
+  const closePromise = once(child, 'close');
+  try {
+    await pipeline(readStream, decompress, counter, child.stdin);
+    const [code] = await closePromise;
+    bar.stop();
+    if (code !== 0) {
+      throw new AppError(`Restore process exited with code ${code}`, {
+        suggestion: stderr.trim() || 'Check psql/mysql client and permissions',
+      });
+    }
+    const secs = ((Date.now() - t0) / 1000).toFixed(1);
+    ui.success(`${ui.icons.ok} Restore completed successfully (${secs}s)`);
+  } catch (e) {
+    bar.stop();
+    throw e;
+  }
+}

package/src/commands/test.js

@@ -0,0 +1,29 @@
+import { loadEnvFile } from '../utils/env-loader.js';
+import { parseDatabaseUrl } from '../utils/url-parser.js';
+import { testPostgresConnection } from '../adapters/postgres.js';
+import { testMysqlConnection } from '../adapters/mysql.js';
+import * as ui from '../utils/ui.js';
+
+/**
+ * @param {object} globalOpts
+ */
+export async function runTest(globalOpts) {
+  loadEnvFile(globalOpts.envFile);
+  const envVar = globalOpts.envVar || 'DATABASE_URL';
+  const raw = process.env[envVar];
+  const parsed = parseDatabaseUrl(raw);
+
+  if (/[!@#$%]/.test(parsed.password)) {
+    ui.warnLine(
+      `${ui.icons.warn} Password contains special characters — auto-encoded for URL parsing; verify connection if it fails.`
+    );
+  }
+
+  if (parsed.type === 'postgres') {
+    await testPostgresConnection(parsed);
+  } else {
+    await testMysqlConnection(parsed);
+  }
+
+  ui.success(`${ui.icons.ok} Connection OK`);
+}

package/src/index.js

@@ -0,0 +1,118 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command, Option } from 'commander';
+import { AppError } from './utils/errors.js';
+import { printErrorWithSuggestion } from './utils/ui.js';
+import { runExport } from './commands/export.js';
+import { runRestore } from './commands/restore.js';
+import { runList } from './commands/list.js';
+import { runInfo } from './commands/info.js';
+import { runClean } from './commands/clean.js';
+import { runTest } from './commands/test.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+/**
+ * @param {import('commander').Command} program
+ * @param {import('commander').Command} cmd
+ */
+function globalOpts(program, cmd) {
+  if (typeof cmd.optsWithGlobals === 'function') {
+    return cmd.optsWithGlobals();
+  }
+  return { ...program.opts(), ...cmd.opts() };
+}
+
+/**
+ * @param {string[]} argv
+ */
+export async function runCli(argv) {
+  const program = new Command();
+
+  program
+    .name('dbsync')
+    .description('Backup and restore PostgreSQL/MySQL databases with .env support')
+    .version(pkg.version)
+    .option('--env-file <path>', 'Path to .env file', '.env')
+    .option('--env-var <name>', 'Environment variable for database URL', 'DATABASE_URL')
+    .option('--config <path>', 'Path to .db-sync.json / .db-syncconfig.json')
+    .option('-v, --verbose', 'Verbose logging', false);
+
+  program
+    .command('export')
+    .description('Export (backup) the database')
+    .option('-o, --output <path>', 'Output file or directory')
+    .option('--schema-only', 'Export schema only', false)
+    .option('--data-only', 'Export data only', false)
+    .option('--tables <list>', 'Comma-separated table names')
+    .addOption(new Option('--no-compress', 'Disable gzip compression'))
+    .addOption(
+      new Option('--compress-level <n>', 'Gzip level 1-9')
+        .default('6')
+        .argParser((v) => parseInt(String(v), 10))
+    )
+    .action(async (opts, cmd) => {
+      await runExport(globalOpts(program, cmd), opts);
+    });
+
+  program
+    .command('restore')
+    .description('Restore database from a backup file')
+    .argument('[file]', 'Backup .sql or .sql.gz file')
+    .option('--drop-before', 'Drop and recreate database before restore', false)
+    .option('--dry-run', 'Validate backup without importing', false)
+    .option('--force', 'Skip confirmation prompts', false)
+    .option('-i, --interactive', 'Choose backup from list', false)
+    .option('-d, --database <name>', 'Filter interactive list by database name')
+    .action(async (file, opts, cmd) => {
+      await runRestore(globalOpts(program, cmd), opts, file);
+    });
+
+  program
+    .command('list')
+    .description('List backups in the backup directory')
+    .option('-d, --database <name>', 'Filter by database name')
+    .option('-l, --limit <n>', 'Limit number of results', (v) => parseInt(v, 10))
+    .option('--since <date>', 'Backups on or after date (YYYY-MM-DD)')
+    .action(async (opts, cmd) => {
+      await runList(globalOpts(program, cmd), opts);
+    });
+
+  program
+    .command('info')
+    .description('Show details for a backup file')
+    .argument('<file>', 'Backup file path')
+    .action(async (file, _opts, cmd) => {
+      await runInfo(globalOpts(program, cmd), file);
+    });
+
+  program
+    .command('clean')
+    .description('Remove old backups (retention)')
+    .option('--keep-last <n>', 'Keep newest N backups (default from config or 30)')
+    .option('--keep-days <n>', 'Keep backups newer than N days')
+    .option('--dry-run', 'Show files that would be deleted', false)
+    .action(async (opts, cmd) => {
+      await runClean(globalOpts(program, cmd), opts);
+    });
+
+  program
+    .command('test')
+    .description('Test database connection from DATABASE_URL')
+    .action(async (_opts, cmd) => {
+      await runTest(globalOpts(program, cmd));
+    });
+
+  try {
+    await program.parseAsync(argv);
+  } catch (e) {
+    if (e instanceof AppError) {
+      printErrorWithSuggestion(e);
+      process.exitCode = e.exitCode ?? 1;
+      return;
+    }
+    throw e;
+  }
+}

package/src/utils/backup-scanner.js

@@ -0,0 +1,101 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+/**
+ * @typedef {object} BackupEntry
+ * @property {string} path
+ * @property {string} filename
+ * @property {number} size
+ * @property {Date} mtime
+ * @property {string} [database]
+ * @property {Date} [parsedDate]
+ * @property {boolean} compressed
+ */
+
+// dbname_YYYYMMDD_HHMMSS.sql or .sql.gz
+const FILENAME_RE = /^(.+)_(\d{8})_(\d{6})(\.sql)(\.gz)?$/;
+
+/**
+ * @param {string} filename
+ */
+export function parseBackupFilename(filename) {
+  const base = basename(filename);
+  const m = base.match(FILENAME_RE);
+  if (!m) {
+    return { database: undefined, parsedDate: undefined };
+  }
+  const [, db, ymd, hms] = m;
+  const y = Number(ymd.slice(0, 4));
+  const mo = Number(ymd.slice(4, 6)) - 1;
+  const d = Number(ymd.slice(6, 8));
+  const hh = Number(hms.slice(0, 2));
+  const mm = Number(hms.slice(2, 4));
+  const ss = Number(hms.slice(4, 6));
+  const parsedDate = new Date(y, mo, d, hh, mm, ss);
+  return { database: db, parsedDate };
+}
+
+/**
+ * @param {string} backupDir
+ * @returns {BackupEntry[]}
+ */
+export function scanBackups(backupDir) {
+  let names;
+  try {
+    names = readdirSync(backupDir);
+  } catch {
+    return [];
+  }
+
+  /** @type {BackupEntry[]} */
+  const out = [];
+  for (const name of names) {
+    if (!name.endsWith('.sql') && !name.endsWith('.sql.gz')) continue;
+    const p = join(backupDir, name);
+    let st;
+    try {
+      st = statSync(p);
+    } catch {
+      continue;
+    }
+    if (!st.isFile()) continue;
+    const { database, parsedDate } = parseBackupFilename(name);
+    out.push({
+      path: p,
+      filename: name,
+      size: st.size,
+      mtime: st.mtime,
+      database,
+      parsedDate,
+      compressed: name.endsWith('.gz'),
+    });
+  }
+
+  out.sort((a, b) => {
+    const ta = (b.parsedDate ?? b.mtime).getTime();
+    const tb = (a.parsedDate ?? a.mtime).getTime();
+    return ta - tb;
+  });
+
+  return out;
+}
+
+/**
+ * @param {BackupEntry[]} entries
+ * @param {{ database?: string, limit?: number, since?: Date }} filters
+ */
+export function filterBackups(entries, filters = {}) {
+  let list = entries;
+  if (filters.database) {
+    const d = filters.database.toLowerCase();
+    list = list.filter((e) => (e.database || '').toLowerCase() === d);
+  }
+  if (filters.since) {
+    const t = filters.since.getTime();
+    list = list.filter((e) => (e.parsedDate ?? e.mtime).getTime() >= t);
+  }
+  if (filters.limit != null && filters.limit > 0) {
+    list = list.slice(0, filters.limit);
+  }
+  return list;
+}