docs: add PostgreSQL integration design document
Design for integrating PostgreSQL as a third database option using a SqlDialect abstraction layer to unify SQL dialect differences across MySQL, SQL Server, and PostgreSQL. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Misaka
140
docs/plans/2026-04-05-postgresql-integration-design.md
Normal file
140
docs/plans/2026-04-05-postgresql-integration-design.md
Normal file
@@ -0,0 +1,140 @@
|
|||||||
|
# PostgreSQL 集成设计文档
|
||||||
|
|
||||||
|
**日期:** 2026-04-05
|
||||||
|
**状态:** 已批准
|
||||||
|
**分支:** dev-logging
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
|
||||||
|
将 PostgreSQL 作为第三种可选数据库类型集成到 ERPAuto 中，与现有 MySQL、SQL Server 并列。通过引入 SqlDialect 抽象层，统一管理三种数据库的 SQL 方言差异，同时重构现有 DAO 层消除散落的 `isSqlServer` 判断。
|
||||||
|
|
||||||
|
## 背景
|
||||||
|
|
||||||
|
- PostgreSQL 数据库已通过 SSMA 从 SQL Server 迁移完成，表结构、schema 组织、列名完全一致
|
||||||
|
- 连接信息：`postgresql://admin:***@192.168.31.83:5432/postgres`，数据库 `CompanyDB`
|
||||||
|
- 共 15 个 schema、151 张表，`dbo` schema 包含 ERPAuto 直接使用的表
|
||||||
|
|
||||||
|
## 方案：抽象数据库方言层
|
||||||
|
|
||||||
|
### 1. SqlDialect 接口
|
||||||
|
|
||||||
|
新建 `src/main/types/sql-dialect.types.ts`：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export interface SqlDialect {
|
||||||
|
readonly dbType: DatabaseType
|
||||||
|
|
||||||
|
// 表名引用
|
||||||
|
quoteTableName(schema: string, table: string): string
|
||||||
|
|
||||||
|
// 参数占位符
|
||||||
|
param(index: number): string
|
||||||
|
params(count: number): string
|
||||||
|
|
||||||
|
// SQL 函数
|
||||||
|
currentTimestamp(): string
|
||||||
|
|
||||||
|
// UPSERT
|
||||||
|
upsert(p: {
|
||||||
|
table: string
|
||||||
|
keyColumns: string[]
|
||||||
|
valueColumns: string[]
|
||||||
|
placeholderCount: number
|
||||||
|
startParamIndex: number
|
||||||
|
}): string
|
||||||
|
|
||||||
|
// 分页
|
||||||
|
paginate(p: {
|
||||||
|
sql: string
|
||||||
|
limit: number
|
||||||
|
offset?: number
|
||||||
|
paramIndex: number
|
||||||
|
}): { sql: string; paramIndex: number }
|
||||||
|
|
||||||
|
// 批量限制
|
||||||
|
maxBatchRows(columnsPerRow: number): number
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 三种方言实现
|
||||||
|
|
||||||
|
新建 `src/main/services/database/dialects/` 目录：
|
||||||
|
|
||||||
|
| 文件 | 数据库 | param(n) | quoteTableName | currentTimestamp | upsert | paginate |
|
||||||
|
|------|--------|----------|---------------|-----------------|--------|----------|
|
||||||
|
| `mysql-dialect.ts` | MySQL | `?` | `dbo_Table` | `NOW()` | `ON DUPLICATE KEY` | `LIMIT x OFFSET y` |
|
||||||
|
| `sqlserver-dialect.ts` | SQL Server | `@p{n}` | `[dbo].[Table]` | `GETDATE()` | `MERGE` | `OFFSET/FETCH` |
|
||||||
|
| `postgresql-dialect.ts` | PostgreSQL | `${n+1}` | `"dbo"."Table"` | `CURRENT_TIMESTAMP` | `ON CONFLICT` | `LIMIT x OFFSET y` |
|
||||||
|
|
||||||
|
方言工厂 `dialects/index.ts`：
|
||||||
|
```typescript
|
||||||
|
export function createDialect(type: DatabaseType): SqlDialect
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. DAO 层重构
|
||||||
|
|
||||||
|
每个 DAO 新增 `dialect` 成员，替代原有的 `getTableName()`、`buildPlaceholders()` 和所有 `isSqlServer` 分支：
|
||||||
|
|
||||||
|
**删除：**
|
||||||
|
- `getTableName()` 私有方法
|
||||||
|
- `buildPlaceholders()` 私有方法
|
||||||
|
- 所有 `isSqlServer` 局部变量和条件分支
|
||||||
|
- `*_CONFIG` 中的 `TABLE_NAME_SQLSERVER` / `TABLE_NAME_MYSQL` → 合并为 `TABLE_SCHEMA` + `TABLE_NAME`
|
||||||
|
|
||||||
|
**新增：**
|
||||||
|
- `private dialect: SqlDialect | null = null`
|
||||||
|
- `private getDialect(): SqlDialect`
|
||||||
|
|
||||||
|
**涉及 DAO：**
|
||||||
|
- `DiscreteMaterialPlanDAO` — 占位符、表名、批量大小
|
||||||
|
- `MaterialsToBeDeletedDAO` — 占位符、表名、MERGE/ON DUPLICATE KEY → `upsert()`
|
||||||
|
- `MaterialsTypeToBeDeletedDAO` — 同上
|
||||||
|
- `ExtractorOperationHistoryDAO` — 占位符、表名、GETDATE()/NOW() → `currentTimestamp()`、分页 → `paginate()`
|
||||||
|
|
||||||
|
### 4. PostgreSQL 服务层
|
||||||
|
|
||||||
|
新建 `src/main/services/database/postgresql.ts`：
|
||||||
|
- 使用 `pg` 驱动，`Pool` 连接池
|
||||||
|
- 实现 `IDatabaseService` 接口
|
||||||
|
- `query()` 直接传递参数数组给 `pg`
|
||||||
|
- `transaction()` 使用 `client.query('BEGIN/COMMIT/ROLLBACK')`
|
||||||
|
|
||||||
|
### 5. 工厂、配置、TypeORM
|
||||||
|
|
||||||
|
**database/index.ts：** `create()` 新增 `'postgresql'` 分支，新增 `createPostgreSqlConfig()`
|
||||||
|
|
||||||
|
**database.types.ts：** `DatabaseType` 扩展为 `'mysql' | 'sqlserver' | 'postgresql'`，新增 `PostgreSqlConfig`
|
||||||
|
|
||||||
|
**data-source.ts：** TypeORM `type` 映射新增 `'postgres'`
|
||||||
|
|
||||||
|
**config.template.yaml：** 新增 `postgresql` 配置段
|
||||||
|
|
||||||
|
**package.json：** 新增 `pg` 依赖
|
||||||
|
|
||||||
|
## 改动范围
|
||||||
|
|
||||||
|
| 层 | 文件 | 动作 |
|
||||||
|
|---|---|---|
|
||||||
|
| 类型 | `types/database.types.ts` | 修改 |
|
||||||
|
| 方言 | `database/dialects/index.ts` | 新建 |
|
||||||
|
| 方言 | `database/dialects/mysql-dialect.ts` | 新建 |
|
||||||
|
| 方言 | `database/dialects/sqlserver-dialect.ts` | 新建 |
|
||||||
|
| 方言 | `database/dialects/postgresql-dialect.ts` | 新建 |
|
||||||
|
| 服务 | `database/postgresql.ts` | 新建 |
|
||||||
|
| 工厂 | `database/index.ts` | 修改 |
|
||||||
|
| TypeORM | `database/data-source.ts` | 修改 |
|
||||||
|
| DAO | `database/discrete-material-plan-dao.ts` | 重构 |
|
||||||
|
| DAO | `database/materials-to-be-deleted-dao.ts` | 重构 |
|
||||||
|
| DAO | `database/materials-type-to-be-deleted-dao.ts` | 重构 |
|
||||||
|
| DAO | `database/extractor-operation-history-dao.ts` | 重构 |
|
||||||
|
| 配置 | `config.template.yaml` | 修改 |
|
||||||
|
| 依赖 | `package.json` | 修改 |
|
||||||
|
|
||||||
|
共 **4 个新文件 + 10 个修改文件**。
|
||||||
|
|
||||||
|
## 不在范围内
|
||||||
|
|
||||||
|
- IPC 处理器新增（前端暂不需要直接切换 PostgreSQL）
|
||||||
|
- Entity/Repository 的 TypeScript 类型适配（TypeORM 内部处理方言差异）
|
||||||
|
- 数据迁移工具
|
||||||
|
- 前端 UI 变更
|
||||||
Reference in New Issue
Block a user