@lucyjs/db-version NPM

@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）

注意事项

确保数据库用户具有足够的权限：
MySQL 权限要求：
- SHOW TABLES
- SHOW CREATE TABLE
- SELECT
- DROP TABLE（如果启用 dropBeforeRestore）
PostgreSQL 权限要求：
- SELECT 权限
- 访问 pg_tables 视图的权限
- CREATE 和 DROP 权限（如果启用 dropBeforeRestore）
备份文件可能会很大，请确保有足够的磁盘空间。
PostgreSQL 的序列重置功能要求表有 id 列作为主键。
建议在执行恢复操作前先进行备份。