dbtool-cli-v1/DATABASE_SUPPORT_MATRIX.md

# dbtool-cli-v1 Database Support Matrix

日期：2026-03-26  
作者：Product Manager  
对应 issue：`CMP-21`

## 1. 决策摘要

- 当前项目不承诺“所有数据库的完整功能”，只承诺一个可验证的跨数据库核心操作闭环。
- 对本产品而言，“完整核心支持”指的是：用户可以稳定完成 `connect -> inspect -> query -> export`，并获得一致的安全边界、错误反馈和结果语义。
- PostgreSQL、MySQL、SQLite 都是当前项目的 **Tier A 目标数据库**，但只针对核心操作闭环，不延伸到数据库管理全家桶。
- 保存连接 profile、导入、migration、事务控制、存储过程 / function 管理、权限 / 用户管理、备份 / 恢复都不属于当前项目承诺。
- 下一批数据库只保留候选池，不进入当前项目承诺；是否进入下一阶段，取决于当前三库的 Tier A 质量是否稳定。

## 2. 支持等级定义

### Tier A：完整核心支持

- 属于当前项目明确承诺
- 必须进入 README、帮助文案、QA 验收和未来发布判断
- 必须在产品语义上跨数据库尽量一致
- 若存在数据库差异，必须明确记录且不破坏主流程

### Tier B：有限支持

- 不是当前版本必须交付的基线
- 只在下一阶段被明确立项后才进入承诺
- 可以先有数据库差异化设计，但不能反向定义当前版本范围

### Tier C：候选 / 实验 / 不承诺

- 当前项目不承诺交付
- 可以保留为研究方向、候选数据库或后续需求池
- 不进入当前版本完成标准

## 3. 产品语义：什么叫“完整功能”

本项目里的“完整功能”不是：

- 全量数据库管理功能
- 替代 DBeaver、DataGrip、pgAdmin、MySQL Workbench
- 覆盖 DBA 全工作流

本项目里的“完整核心支持”是：

1. 能明确选择目标数据库
2. 能验证连接
3. 能定位 schema / table / column
4. 能执行 SQL
5. 能执行参数化查询
6. 能把结果导出为 CSV / JSON
7. 能在失败时给出可行动提示，且不泄露密码

## 4. 当前阶段数据库等级

| 数据库 | 当前阶段目标等级 | 当前阶段定位 | 备注 |
| --- | --- | --- | --- |
| PostgreSQL | Tier A | 核心服务器数据库 | 当前 demo 已覆盖核心 happy path |
| MySQL | Tier A | 核心服务器数据库 | 当前 demo 已覆盖核心 happy path |
| SQLite | Tier A | 核心本地文件数据库 | 当前 demo 已覆盖核心 happy path，但允许文件型语义差异 |

结论：**当前项目不是“先做 PostgreSQL，其他顺带”；而是三种数据库都要对核心闭环负责。**

## 5. 能力矩阵

| 能力维度 | PostgreSQL | MySQL | SQLite | 当前项目要求 | 说明 |
| --- | --- | --- | --- | --- | --- |
| 连接（ad hoc） | Tier A | Tier A | Tier A | 必须统一 | 当前命令模型已经存在 |
| 连接 profile 管理 | Tier C | Tier C | Tier C | 当前不做 | 内部有 profile 概念，不等于用户可保存 / 列表化 |
| schema / table / column introspection | Tier A | Tier A | Tier A | 必须统一心智 | 允许 schema 语义按数据库差异映射 |
| query 执行 | Tier A | Tier A | Tier A | 必须统一 | 支持 inline SQL 与 `.sql` 文件 |
| 参数化查询 | Tier A | Tier A | Tier A | 必须统一 | 作为核心安全与复用能力保留 |
| 导出 CSV / JSON | Tier A | Tier A | Tier A | 必须统一 | 只承诺结果集导出 |
| 导入 | Tier C | Tier C | Tier C | 当前不做 | 不进入当前项目完成标准 |
| migration / script 执行 | Tier C | Tier C | Tier C | 当前不做 | 原始 SQL 文件执行不等于产品化 migration 工作流 |
| 事务控制 | Tier C | Tier C | Tier C | 当前不做 | 不为本期提供专门 UX 或契约 |
| 存储过程 / function | Tier C | Tier C | Tier C | 当前不做 | 可通过普通查询间接触达，但不承诺专门支持 |
| 权限与用户管理 | Tier C | Tier C | Tier C | 当前不做 | 属于管理面，易导致范围失控 |
| 备份 / 恢复 | Tier C | Tier C | Tier C | 当前不做 | 属于运维 / DBA 面，不进入当前项目 |

## 6. 哪些能力必须统一，哪些允许差异

### 必须统一支持

- 命令入口仍围绕 `connect`、`inspect`、`query`、`export`
- 成功 / 失败都必须给出稳定的终端反馈
- 参数化查询属于核心能力，不允许只在单一数据库成立
- 导出格式只承诺 CSV / JSON
- 密码只能经安全输入路径注入，输出不得泄露密码

### 允许数据库差异化

- 顶层 inspect 对象的命名和映射方式
- schema 概念的具体落点
- 多语句 SQL 的执行限制
- 返回元数据的丰富程度
- 底层驱动报错文本细节

### 当前已知差异（允许保留）

- MySQL 的 `--schema` 当前映射到数据库名
- SQLite 使用文件路径连接，不使用 host / port
- SQLite demo inspect 使用 `main` 作为 schema
- PostgreSQL / MySQL 非参数化 query 可以执行多语句 SQL 文件
- SQLite 当前按单条 statement 执行，多语句输入会显式失败

## 7. 当前阶段范围与非目标

### 当前阶段范围

- 把 PostgreSQL / MySQL / SQLite 的核心闭环做实并做稳
- 固化跨数据库一致的产品语义
- 用共享矩阵约束 CTO 的拆解边界
- 让 QA 能按数据库分层建立未来验收策略

### 当前阶段非目标

- 扩库到更多数据库
- 为单一数据库补一堆高级能力
- 把原始 SQL 执行能力包装成 migration 产品
- 进入 GUI 正式开发
- 承诺数据库管理平台式能力

## 8. 下一批候选数据库

这些数据库可进入下一阶段候选池，但**不进入当前项目承诺**：

| 候选数据库 | 保留原因 | 最早讨论时点 |
| --- | --- | --- |
| SQL Server | 企业环境常见，和当前目标用户重叠 | 当前三库 Tier A 稳定后 |
| MariaDB | 与 MySQL 用户群接近，可验证兼容价值 | 当前 MySQL 质量收敛后 |
| DuckDB | 与 SQLite 一样适合本地文件 / 分析型场景 | 当前文件型流程稳定后 |

当前不建议把 Oracle、MongoDB、Redis 等直接放入下一批：

- Oracle：产品与合规复杂度高
- MongoDB：数据模型差异过大，会改写当前统一心智
- Redis：不是当前 SQL / schema / export 产品语义的自然延伸

## 9. CLI Demo 如何向产品界面 / 产品流程演进

CLI demo 当前已经验证了未来产品最重要的五个对象：

- connection target
- catalog / schema browser state
- query request
- result set
- export action

未来 GUI 或更完整产品流程应直接映射这些对象，而不是另起一套产品语言：

- `connect` -> Connection Manager / Test Connection
- `inspect` -> Schema Browser / Object Inspector
- `query` -> Query Editor / Run Action
- `export` -> Export Drawer / Export Feedback

演进原则：

- 先复用 CLI 已稳定的产品语义
- 再增加界面层承载
- 不在 GUI 中偷偷扩充当前版本未承诺的能力

## 10. 给 CTO 和 QA 的交接说明

### 给 CTO

- 当前项目的拆解中心应是“三库同一核心闭环”，不是“继续扩命令面”
- Tier A 项必须优先保证一致性、失败路径和可发布性
- Tier C 项不要被拆成当前项目 issue，除非先有新的产品决策

### 给 QA

- 未来验收策略应先按 Tier A 能力建立主矩阵
- 同一能力要按 PostgreSQL / MySQL / SQLite 分库验证
- 差异项要记录，但不应把已允许的数据库差异误判成产品缺陷

## 11. 阶段通过标准

当前阶段可以认为产品边界清晰，当且仅当：

- PostgreSQL / MySQL / SQLite 的 Tier A 范围被团队共同接受
- Tier C 能力没有混入当前项目承诺
- CTO 可以据此继续拆任务，而不再重新解释“完整支持”是什么意思
- QA 可以据此建立分数据库验收矩阵