@lucyjs/db-version

数据库版本管理和备份恢复工具，支持 MySQL 和 PostgreSQL。

功能特点

• 多数据库支持
  • MySQL
  • PostgreSQL
• 数据库备份
  • 完整的数据库备份（表结构和数据）
  • 自动处理不同数据库的语法差异
  • 支持特殊数据类型（布尔值、日期、二进制数据等）
  • PostgreSQL 序列自动重置
  • 自动清理旧备份文件
• 数据库恢复
  • 从备份文件恢复数据库
  • 自动处理外键约束
  • 支持忽略错误继续执行
  • 完整的错误处理机制

安装

npm install @lucyjs/db-version
# 或
yarn add @lucyjs/db-version

使用说明

创建实例

import { DatabaseBackup } from '@lucyjs/db-version';
import knex from 'knex';

// MySQL 示例
const mysqlDb = knex({
  client: 'mysql',
  connection: {
    host: 'localhost',
    user: 'root',
    password: 'password',
    database: 'your_database'
  }
});

const mysqlBackup = new DatabaseBackup(mysqlDb, {
  backupDir: './backups',
  prefix: 'mysql_backup',
  keepCount: 7,
  databaseType: 'mysql'  // 指定数据库类型为 MySQL
});

// PostgreSQL 示例
const pgDb = knex({
  client: 'pg',
  connection: {
    host: 'localhost',
    user: 'postgres',
    password: 'password',
    database: 'your_database'
  }
});

const pgBackup = new DatabaseBackup(pgDb, {
  backupDir: './backups',
  prefix: 'pg_backup',
  keepCount: 7,
  databaseType: 'postgresql'  // 指定数据库类型为 PostgreSQL
});

数据库备份

// 执行备份
try {
  const backupPath = await backup.backup();
  console.log(`备份成功：${backupPath}`);
} catch (error) {
  console.error('备份失败：', error);
}

获取备份文件列表

const backupFiles = await backup.getBackupFiles();
console.log('可用的备份文件：', backupFiles);
// 输出格式：
// [
//   {
//     name: 'backup_2024-01-20_143000.sql',
//     path: '/path/to/backups/backup_2024-01-20_143000.sql',
//     time: 1705747800000
//   },
//   ...
// ]

数据库恢复

// 从指定备份文件恢复
try {
  await backup.restore('/path/to/backup.sql', {
    dropBeforeRestore: true,  // 恢复前清空所有表
    ignoreErrors: false       // 遇到错误时是否继续
  });
  console.log('恢复成功');
} catch (error) {
  console.error('恢复失败：', error);
}

API 文档

DatabaseBackup

构造函数

constructor(knex: Knex, options: BackupOptions)

参数：

• knex: Knex 实例
• options: 备份选项
  • backupDir: 备份文件保存目录
  • prefix?: 备份文件名前缀（默认：'backup'）
  • keepCount?: 保留的备份文件数量（默认：7）
  • databaseType: 数据库类型（'mysql' | 'postgresql'）

方法

backup()

执行数据库备份。

async backup(): Promise<string>

返回值：

• 备份文件的完整路径

restore()

恢复数据库备份。

async restore(backupFile: string, options?: RestoreOptions): Promise<void>

参数：

• backupFile: 备份文件路径
• options: 恢复选项
  • dropBeforeRestore?: 是否在恢复前清空所有表（默认：true）
  • ignoreErrors?: 是否忽略错误继续执行（默认：false）

getBackupFiles()

获取可用的备份文件列表。

async getBackupFiles(): Promise<Array<{ name: string; path: string; time: number }>>

返回值：

• 备份文件列表，按时间降序排序
  • name: 文件名
  • path: 文件完整路径
  • time: 文件修改时间戳

数据库特定说明

MySQL

• 支持所有 MySQL 数据类型
• 布尔值会被转换为 0/1
• 二进制数据使用 X'hex' 格式

PostgreSQL

• 支持所有 PostgreSQL 数据类型
• 自动处理序列（serial、bigserial）的重置
• 布尔值保持 true/false 格式
• 二进制数据使用 \x 格式
• 支持 schema（默认使用 public schema）

注意事项

1. 确保数据库用户具有足够的权限：

   MySQL 权限要求：

   • SHOW TABLES
   • SHOW CREATE TABLE
   • SELECT
   • DROP TABLE（如果启用 dropBeforeRestore）

   PostgreSQL 权限要求：

   • SELECT 权限
   • 访问 pg_tables 视图的权限
   • CREATE 和 DROP 权限（如果启用 dropBeforeRestore）

2. 备份文件可能会很大，请确保有足够的磁盘空间。

3. PostgreSQL 的序列重置功能要求表有 id 列作为主键。

4. 建议在执行恢复操作前先进行备份。

License

MIT