npm package: @lucyjs/db-version
Description: 数据库管理工具
Author: qingyi
Latest version: 1.1.6

# @lucyjs/db-version

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

## 功能特点

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

## 安装

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

## 使用说明

### 创建实例

```typescript
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
});
```

### 数据库备份

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

### 获取备份文件列表

```typescript
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
//   },
//   ...
// ]
```

### 数据库恢复

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

## API 文档

### DatabaseBackup

#### 构造函数

```typescript
constructor(knex: Knex, options: BackupOptions)
```

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

#### 方法

##### backup()

执行数据库备份。

```typescript
async backup(): Promise<string>
```

返回值：
- 备份文件的完整路径

##### restore()

恢复数据库备份。

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

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

##### getBackupFiles()

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

```typescript
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