80 lines
4.8 KiB
Markdown
80 lines
4.8 KiB
Markdown
# Kingbase Generator Identity 基础设施补丁
|
||
|
||
## 1. 补丁目标
|
||
解决 RuoYi 代码生成器（Generator）在 KingbaseES 数据库下执行表结构导入（`importGenTable`）时，因 `gen_table.table_id` 和 `gen_table_column.column_id` 缺失自增/Identity 属性，导致 `useGeneratedKeys="true"` 回填失败并引发主键冲突（Duplicate key violation）的运行时兼容性问题。
|
||
|
||
## 2. 补丁范围与安全红线
|
||
- **涉及对象**：严格仅限 `public.gen_table.table_id` 与 `public.gen_table_column.column_id`。
|
||
- **安全红线**：
|
||
- 严禁修改 21 张 `train_*` 业务表；
|
||
- 严禁修改 `sys_*` 系统/权限/字典表；
|
||
- 严禁 DROP 表、重建表或清空/截断 Generator 历史元数据；
|
||
- 严禁在未做 Precheck 判定前盲目全量执行 Patch。
|
||
|
||
## 3. 文件清单
|
||
|
||
| 文件名 | 类型 | 说明 |
|
||
| :--- | :---: | :--- |
|
||
| `001_generator_identity_precheck.sql` | 只读探测 | 检查两列 Identity 配置、现有数据量及全局 Case 场景。 |
|
||
| `002a_gen_table_identity_patch.sql` | DDL 补丁 | 仅为 `gen_table.table_id` 添加 `GENERATED BY DEFAULT AS IDENTITY`。 |
|
||
| `002b_gen_table_column_identity_patch.sql` | DDL 补丁 | 仅为 `gen_table_column.column_id` 添加 `GENERATED BY DEFAULT AS IDENTITY`。 |
|
||
| `003_generator_identity_verify.sql` | 只读验证 | 综合校验列属性、Sequence 存在、依赖关系及 Sequence 对齐安全性。 |
|
||
|
||
---
|
||
|
||
## 4. 四种 Partial / Full 执行决策矩阵
|
||
|
||
根据 `001_generator_identity_precheck.sql` 查询 4 返回的 `precheck_scenario_verdict`，严格按以下矩阵执行：
|
||
|
||
| 场景编号 | Precheck 判定结果 | 执行动作 |
|
||
| :--- | :--- | :--- |
|
||
| **Scenario A** | `CASE_1_BOTH_NEED_PATCH`<br>（两列均缺失 Identity） | 1. 执行 `002a_gen_table_identity_patch.sql`<br>2. 执行 `002b_gen_table_column_identity_patch.sql`<br>3. 执行 `003_generator_identity_verify.sql` |
|
||
| **Scenario B** | `CASE_2_BOTH_ALREADY_PATCHED`<br>（两列均已配置 Identity） | **严禁执行任何 Patch！**<br>直接执行 `003_generator_identity_verify.sql` 复核。 |
|
||
| **Scenario C** | `CASE_3_ONLY_COLUMN_NEEDS_PATCH`<br>（仅 `column_id` 缺失） | **严禁执行 002a！**<br>1. 仅执行 `002b_gen_table_column_identity_patch.sql`<br>2. 执行 `003_generator_identity_verify.sql` |
|
||
| **Scenario D** | `CASE_4_ONLY_TABLE_NEEDS_PATCH`<br>（仅 `table_id` 缺失） | **严禁执行 002b！**<br>1. 仅执行 `002a_gen_table_identity_patch.sql`<br>2. 执行 `003_generator_identity_verify.sql` |
|
||
|
||
---
|
||
|
||
## 5. 数据环境分类与 Sequence 对齐要求
|
||
|
||
### 5.1 Case A：Generator 元数据为空（0 rows，全新环境）
|
||
- `001` 预检中 `env_type` 为 `EMPTY_METADATA_ENV`；
|
||
- 执行 Patch 后，Kingbase 自动生成的 Sequence 从 1 开始分配；
|
||
- 执行 `003` 核验，Sequence 对齐状态将显示 `EMPTY_TABLE_SAFE`，可直接投入使用。
|
||
|
||
### 5.2 Case B：Generator 元数据已存在（已有历史导入数据）
|
||
- `001` 预检中 `env_type` 为 `EXISTING_METADATA_ENV`；
|
||
- **核心风险**：Kingbase `ADD GENERATED BY DEFAULT AS IDENTITY` 在已有数据环境下默认从 1 开始分配，**不宣称自动对齐已有数据 MAX(id)**！
|
||
- **操作要求**：
|
||
1. 执行对应补丁后，**必须立即执行 `003_generator_identity_verify.sql`**；
|
||
2. 观察验证输出中的 `seq_alignment_status`：
|
||
- 若为 `SAFE`：表明 sequence 位置已超前于现有数据（例如已有试点导入推进了序列），可直接使用；
|
||
- 若为 `UNSAFE`：表明 sequence 当前位置落后或等于现有主键，**绝对禁止直接继续 Generator Import**！
|
||
3. **Sequence 对齐专项步骤（需 DBA 确认并在维护窗口执行）**：
|
||
针对落后的序列，使用 Kingbase 兼容的管理语法调整序列游标：
|
||
```sql
|
||
-- 示例：对齐 gen_table sequence
|
||
SELECT setval('gen_table_table_id_seq', (SELECT COALESCE(MAX(table_id), 0) + 1 FROM gen_table), false);
|
||
-- 示例：对齐 gen_table_column sequence
|
||
SELECT setval('gen_table_column_column_id_seq', (SELECT COALESCE(MAX(column_id), 0) + 1 FROM gen_table_column), false);
|
||
```
|
||
4. 重新执行 `003_generator_identity_verify.sql`，确认全部输出 `SAFE` 且最终结果为 `VERIFY: PASS` 后，方可开放表导入功能。
|
||
|
||
---
|
||
|
||
## 6. 执行命令示例（无真实凭据）
|
||
|
||
```bash
|
||
# 步骤 1: 预检并确认 Scenario
|
||
ksql -h <HOST> -p <PORT> -U <USER> -d <DBNAME> -f 001_generator_identity_precheck.sql
|
||
|
||
# 步骤 2: 根据 Precheck 决策矩阵有选择地执行对应补丁
|
||
# 仅当命中 Scenario A 或 D 时:
|
||
ksql -h <HOST> -p <PORT> -U <USER> -d <DBNAME> -f 002a_gen_table_identity_patch.sql
|
||
# 仅当命中 Scenario A 或 C 时:
|
||
ksql -h <HOST> -p <PORT> -U <USER> -d <DBNAME> -f 002b_gen_table_column_identity_patch.sql
|
||
|
||
# 步骤 3: 严格复核验证
|
||
ksql -h <HOST> -p <PORT> -U <USER> -d <DBNAME> -f 003_generator_identity_verify.sql
|
||
```
|