feat(lyra): 接入 PostgreSQL 与 Goose 迁移

- 使用 pgx/sqlx 建立连接，从环境变量读取数据库密码 - 添加本地 PostgreSQL Compose 配置与初始迁移 - 补充 Goose 操作手册和连接串排错说明
2026-10-17 15:09:46 +08:00
parent 3f16384376
commit 8c0c9978e5
15 changed files with 580 additions and 33 deletions
@@ -0,0 +1,71 @@
+# Goose 初始迁移
+
+日期：2026-10-17
+
+## 目标与范围
+
+用户已同意创建首个 Goose 迁移并提供后续自行管理的说明。以当前工作区的
+`docs/demo.sql` 为来源，保留已有未提交改动，不修改其表结构设计。
+本次不连接或修改用户数据库，不把迁移嵌入服务启动，也不修改 Go 应用依赖。
+
+## 实施步骤
+
+1. 核对 Goose 官方 SQL 注解、事务行为及 CLI 命令。
+2. 新建 `migrations/00001_init.sql`，Up 保留示例中的函数、三张表、约束、
+   注释、索引与触发器；去掉外层事务，以 StatementBegin/StatementEnd
+   包裹 PL/pgSQL 函数。Down 按依赖逆序删除表，最后删除函数，不使用 CASCADE。
+3. 更新 `migrations/README.md`，说明 CLI 使用、连接信息的安全提供、首次
+   初始化、状态检查、后续迁移及回滚风险。采用固定 CLI 版本 v3.29.0，命令在 Lyra
+   module 根执行；数据库必须已创建，首个迁移要求目标对象尚不存在。
+4. 同步项目 README 与架构文档的迁移进度。`docs/demo.sql` 保留为参考，
+   正式迁移以 migrations 为准，避免双重执行。
+
+## 工作分工与验证
+
+- librarian：只读核对官方规则与 CLI 能力。
+- fixer：仅负责首个 SQL 迁移及上述三个说明文档；不修改其他代码或配置，
+  不运行任何连接数据库的命令。
+- 父会话：维护计划、检查最终 diff 与文案，确认无意外改动及敏感信息。
+- fixer 验证：静态对比 Up 与当前 demo 的 SQL 内容，检查 Down 依赖顺序；
+  使用 v3.29.0 的 `goose -env=none -dir ./migrations validate` 检查文件解析，
+  此命令不连接数据库。校验用工具仅构建到 `/tmp/opencode`，不修改应用依赖。
+- 不为仅 SQL/文档变更重复运行无关 Go HTTP 测试。不宣称数据库集成验证通过；
+  未在 PostgreSQL 实际执行的限制在交付时明确说明。
+
+## 已核对的规则
+
+- 官方 v3.29.0：Up/Down 默认使用事务；函数体需 StatementBegin/StatementEnd。
+- 后续新建迁移使用 `goose -s create <名称> sql`，延续顺序编号。
+- CLI 默认读取 `.env`；说明中的命令统一加 `-env=none`，显式使用环境变量，
+  避免误用本地配置。`-version` 为工具版本，`version` 为数据库版本。
+- 官方来源：https://pressly.github.io/goose/documentation/annotations/
+  与 https://github.com/pressly/goose/releases/tag/v3.29.0。
+
+## 实施与验收记录
+
+- 已完成初始迁移与使用文档；父会话已检查 SQL 与相关文档差异。
+- 实测修正：v3.29.0 的 validate 不使用位置参数，必须通过 `-dir` 或
+  `GOOSE_MIGRATION_DIR` 选择目录；已按实际行为编写说明。
+- fixer 已构建 v3.29.0 PostgreSQL 专用 CLI 至 `/tmp/opencode/lyra-goose-bin`，
+  离线解析得到 Up=40、Down=4；与 demo 的 Up 内容逐行对比完全一致。
+- 后续编号 00002 已在临时目录验证；没有修改应用依赖或连接数据库。
+- 最终文案校正：目标库为空是执行前提，不当作已验证事实；普通 down 是否
+  丢数据取决于迁移内容，00001 的 Down 则确定会删除三张表及其数据。
+- `git diff --check` 通过。PostgreSQL 上的实际执行尚未验证。
+
+## 后续：整理日常操作手册
+
+用户已要求将实际操作步骤写入 Lyra docs。以下为新增文档任务，不改已有迁移。
+
+1. 新建 `docs/goose.md`，作为唯一完整操作手册：固定版本安装、项目根目录、
+   `.env.local` 配置、密码 URL 编码、validate/status/up/version、后续新增迁移、
+   回滚警告与常见故障。所有数据库操作命令使用 `-env=.env.local`。
+2. 将 `migrations/README.md` 收敛为迁移目录说明和手册链接，移除旧的交互输入
+   密码流程，避免两份操作步骤不一致；项目 README 增加手册入口。
+3. 仅使用演示占位值，不读取 .env.local、真实连接配置或既有错误中的疑似凭据。
+   不运行服务、不连接数据库、不更改 SQL、依赖和配置，也不暂存用户改动。
+4. fixer 负责上述三个文档和静态链接/命令一致性检查；父会话负责最终差异与
+   文案审查。已有 CLI 验证证据复用，不为文档改动重复构建或执行数据库命令。
+
+说明：用户已确认 status 成功并显示 00001 Pending；这是连接及迁移发现成功的
+证据，不足以宣称 Up 或 Down 已完成数据库集成验证。
@@ -0,0 +1,32 @@
+# PostgreSQL 启动连接检查
+
+日期：2026-10-17
+
+## 已批准目标
+
+用户要求在 main.go 中通过 sqlx 查询数据库信息，检查尚无业务表的数据库连接。
+查询只读取 current_database()、current_user、version()，不依赖业务表，不执行 DDL。
+
+## 实施范围
+
+1. 保留当前工作区所有用户改动，仅在 cmd/lyra/main.go 中注册项目已选定的
+   pgx stdlib 驱动，使用带超时的连接及 GetContext 查询，输出数据库信息。
+2. 通过 go.mod/go.sum 加入 pgx/v5/stdlib 所需依赖；etc/lyra.toml 仅将
+   driver 的 postgres 改为 pgx，与驱动注册名保持一致，不读出或改动敏感配置。
+3. 补充数据库连接关闭；不重构配置加载、不实现 dotenv、不涉及 Goose 或业务表。
+
+## 分工与证据路径
+
+- fixer：写入范围限定 main.go、go.mod、go.sum、TOML 的 driver 一行；
+  首次修改检查缩进和换行，保留已有修改。负责 gofmt、go test ./... 与构建验证。
+- 父会话：检查新增查询、超时、驱动名与范围，检查无明文凭据及意外文件改动。
+- 不打印配置文件完整内容或完整 DSN；不读取 .env.local 或 compose 中的敏感值。
+- 不运行服务、不连接真实数据库；编译/测试只证明查询代码可编译和现有测试通过，
+  实际连接是否成功由用户本地启动后观察查询输出确认。
+
+## 验收
+
+- 已加入 pgx/v5 v5.11.0 驱动、五秒超时连接与系统信息查询，保留 HTTP 通路。
+- fixer 执行 `go build ./...`、`go test ./...` 均通过，未连接真实数据库。
+- 最终安全校正：连接与查询失败时只记录固定的阶段提示，不直接输出驱动原始
+  错误，避免连接串解析错误意外携带敏感配置。