Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

docs(db): stop claiming MySQL is a supported DB_DRIVER

wizardchena62a51e6b022
diff --git a/.env.example b/.env.example
index 99442b725..f50926572 100644
--- a/.env.example
+++ b/.env.example
@@ -124,7 +124,7 @@ DOCREADER_TRANSPORT=grpc
# #####################################################################
# ========== B1. 数据库 ⚠️ 必填 ==========
-# 主数据库类型:postgres / mysql / sqlite。
+# 主数据库类型:postgres / sqlite。sqlite 供 Lite 模式使用,见 DB_PATH。
DB_DRIVER=postgres
# 数据库主机地址。
DB_HOST=postgres
@@ -136,7 +136,7 @@ DB_USER=postgres
DB_PASSWORD=postgres123!@#
# 数据库名称。
DB_NAME=WeKnora
-# SQLite 驱动时使用(DB_DRIVER=sqlite),postgres/mysql 忽略。
+# SQLite 驱动时使用(DB_DRIVER=sqlite),postgres 驱动忽略。
# DB_PATH=./data/weknora.db
# ========== B2. Redis / 流处理 / Asynq 队列 ==========
diff --git a/migrations/mysql/README.md b/migrations/mysql/README.md
new file mode 100644
index 000000000..79bd2f658
--- /dev/null
+++ b/migrations/mysql/README.md
@@ -0,0 +1,27 @@
+# migrations/mysql —— 未接线的 MySQL 建表脚本
+
+⚠️ **这里的 SQL 不会被任何代码或脚本执行。MySQL 目前不是 WeKnora 的主库选项。**
+
+## 现状
+
+`internal/container/container.go` 的 `initDatabase()` 中,`DB_DRIVER` 的 switch 只有两个分支:
+
+| `DB_DRIVER` | 迁移来源 |
+| --- | --- |
+| `postgres` | `migrations/versioned/`(golang-migrate 增量迁移) |
+| `sqlite` | `migrations/sqlite/`(golang-migrate 增量迁移,Lite 模式) |
+
+其余取值一律返回 `unsupported database driver`,因此配置 `DB_DRIVER=mysql` 会导致服务启动失败。
+
+本目录下的 `00-init-db.sql` 是一份一次性建表脚本,覆盖 10 张核心表(`tenants`、`models`、`knowledge_bases`、`knowledges`、`sessions`、`messages`、`message_suggestion_sets`、`message_suggestion_events`、`chunks`、`chunk_revisions`)。它会在有人改动这些基础表时被顺带更新,但**没有任何 Go 代码、Makefile 目标或 compose 配置引用它**。
+
+## 要真正支持 MySQL 还差什么
+
+仅有这份建表脚本是不够的——它只对应初始 schema,缺少与 `migrations/versioned/`(Postgres 侧已有 100+ 个增量迁移)对等的增量迁移集。完整接线至少需要:
+
+1. 在 `initDatabase()` 中增加 `case "mysql"`,接上 `gorm.io/driver/mysql` 与 golang-migrate 的 MySQL DSN;
+2. 建立 `migrations/mysql/` 的增量迁移序列,并与 `versioned/` 的 schema 演进保持同步;
+3. 处理 Postgres 专有用法(`JSONB`、数组类型、`ON CONFLICT`、ParadeDB 的 BM25 索引等)在 MySQL 侧的等价实现或降级方案;
+4. 明确向量检索的落地方式——MySQL 本身不提供向量索引,需要依赖外部向量库(`RETRIEVE_DRIVER`)。
+
+相关讨论见 [#1418](https://github.com/Tencent/WeKnora/issues/1418)。在上述工作完成之前,请勿在文档或配置注释中声称支持 `DB_DRIVER=mysql`。
diff --git a/website-docs/06-development/02-database-schema.md b/website-docs/06-development/02-database-schema.md
index 9d0b37d91..4f8350df0 100644
--- a/website-docs/06-development/02-database-schema.md
+++ b/website-docs/06-development/02-database-schema.md
@@ -12,7 +12,7 @@ WeKnora 使用版本化迁移维护数据库结构,PostgreSQL 与 SQLite 分
| `sqlite` | Lite 模式。路径取 `DB_PATH`(默认 `./data/weknora.db`),DSN 附加 `_journal_mode=WAL&_busy_timeout=5000&_foreign_keys=on`,并加载 `sqlite-vec` 扩展(`sqlite_vec.Auto()`)做向量检索 |
| 其他值 | 直接报错 `unsupported database driver` |
-**MySQL 不是主库选项**:`go.mod` 里的 `go-sql-driver/mysql` 是给 Doris 检索引擎(MySQL 协议、`database/sql`)注册协议驱动用的(见 `container.go` import 注释)。`migrations/mysql/00-init-db.sql` 是一份仅含 7 张核心表(tenants/models/knowledge_bases/knowledges/sessions/messages/chunks)的一次性 MySQL 建表脚本,**没有任何 Go 代码或脚本引用它**,未接入应用启动流程,可视为遗留/外部初始化用途。
+**MySQL 不是主库选项**:`go.mod` 里的 `go-sql-driver/mysql` 是给 Doris 检索引擎(MySQL 协议、`database/sql`)注册协议驱动用的(见 `container.go` import 注释)。`migrations/mysql/00-init-db.sql` 是一份仅含 10 张核心表(tenants/models/knowledge_bases/knowledges/sessions/messages/message_suggestion_sets/message_suggestion_events/chunks/chunk_revisions)的一次性 MySQL 建表脚本,**没有任何 Go 代码或脚本引用它**,未接入应用启动流程,可视为遗留/外部初始化用途。
检索引擎(向量/关键词索引的存储)与主库解耦,由 `RETRIEVE_DRIVER` 控制(postgres / elasticsearch / qdrant / milvus / sqlite 等,详见《扩展点指南》)。当 `RETRIEVE_DRIVER` 不含 `postgres` 时,迁移 DSN 会带上 `options=-c app.skip_embedding=true`,`embeddings` 表相关迁移通过该 GUC 条件跳过。