docs(goose): 添加数据库迁移使用笔记

note/随手记/goose-notes.md

@@ -0,0 +1,175 @@
+# Goose 数据库迁移笔记
+
+Goose 用迁移文件管理数据库结构变更，并在数据库中记录已执行的迁移版本。
+
+本文以 **PostgreSQL、Goose v3.29.0** 为例，命令使用 Bash 语法。
+
+## 1. 基本概念
+
+- **迁移文件**：按版本组织的数据库变更脚本。
+- **Up**：应用变更，例如建表、增加字段。
+- **Down**：撤销对应变更；能否恢复数据取决于具体 SQL。
+- **版本记录**：Goose 默认通过 `goose_db_version` 表跟踪迁移状态。
+- **工具版本与迁移版本不同**：`goose -version` 查看工具版本，`goose version` 查看数据库迁移版本。
+
+通常将迁移文件放在 `migrations/` 目录。下文命令在该目录的上一级执行，目标数据库需事先创建。
+
+## 2. 安装
+
+需要先安装 Go，再安装指定版本的 Goose CLI：
+
+```bash
+go install github.com/pressly/goose/v3/cmd/goose@v3.29.0
+goose -version
+```
+
+固定工具版本有助于保持不同环境的行为一致。Goose 可以作为独立命令行工具使用。
+
+默认安装位置是 `$(go env GOPATH)/bin`；若设置了 `GOBIN`，则安装到该目录。找不到命令时，将实际安装目录加入 `PATH`：
+
+```bash
+# 未设置 GOBIN 时
+export PATH="$PATH:$(go env GOPATH)/bin"
+```
+
+## 3. 配置数据库连接
+
+在工作目录创建 `.env.local`，填写连接配置：
+
+```dotenv
+GOOSE_DRIVER=postgres
+GOOSE_MIGRATION_DIR=./migrations
+GOOSE_DBSTRING="postgres://example_user:URL_ENCODED_PASSWORD@127.0.0.1:5432/example_db?sslmode=disable"
+```
+
+以上用户名、密码和数据库名都是占位值，地址与端口也需按实际环境填写。
+
+- `GOOSE_DRIVER`：数据库驱动；连接 PostgreSQL 时使用 `postgres`。
+- `GOOSE_MIGRATION_DIR`：迁移文件目录。
+- `GOOSE_DBSTRING`：数据库连接串。Goose 不会自动从应用配置文件或零散的应用环境变量中拼装它。
+- Goose 默认读取 `.env`；本文统一使用 `-env=.env.local` 显式指定配置文件。
+- `sslmode=disable` 适用于本地无 TLS 要求的场景；其他环境按实际 TLS 要求配置。
+
+将含凭据的配置文件加入版本控制忽略规则。类 Unix 系统还可限制文件权限：
+
+```bash
+chmod 600 .env.local
+```
+
+系统中已有的同名环境变量可能优先于配置文件生效。修改文件后连接行为未改变时，可只列出相关变量名排查，避免打印连接串：
+
+```bash
+env | cut -d= -f1 | grep -i '^GOOSE'
+```
+
+## 4. 连接串中的 URL 编码
+
+使用 URL 格式的连接串时，用户名、密码中的特殊字符需要进行百分号编码。
+
+| 字符 | 编码 | 字符 | 编码 |
+|---|---|---|---|
+| `@` | `%40` | `:` | `%3A` |
+| `#` | `%23` | `/` | `%2F` |
+| `%` | `%25` | `?` | `%3F` |
+
+例如，演示密码 `demo#pass` 在连接串中写成 `demo%23pass`。
+
+- 分别编码用户名和密码，不要编码整个 URL。
+- 避免对已编码的内容重复编码。
+- 编码只改变连接串的写法，不改变数据库中的实际密码。
+- 不要将真实密码提交给在线编码网站。
+
+## 5. 常用命令
+
+```bash
+# 查看 Goose 工具版本
+goose -version
+
+# 离线检查迁移文件是否能被解析
+goose -env=.env.local validate
+
+# 查看迁移状态与数据库当前迁移版本
+goose -env=.env.local status
+goose -env=.env.local version
+
+# 应用尚未执行的迁移
+goose -env=.env.local up
+
+# 回滚最近一个已应用的迁移；执行前检查对应 Down SQL
+goose -env=.env.local down
+```
+
+`validate` 检查注解与语句拆分，不连接数据库，也不验证 SQL 在 PostgreSQL 上的语义。校验通过不代表数据库连接正常或迁移一定执行成功。
+
+在 v3.29.0 中，`validate` 不接受位置路径参数。迁移目录通过 `GOOSE_MIGRATION_DIR` 或 `-dir` 指定：
+
+```bash
+goose -env=.env.local -dir=./migrations validate
+```
+
+## 6. 创建与执行迁移
+
+### 创建迁移文件
+
+```bash
+goose -env=.env.local -s create create_example_items sql
+```
+
+`-s` 表示使用顺序编号，版本号按目录中已有迁移延续。例如，目录为空时，首个文件可命名为：
+
+```text
+migrations/00001_create_example_items.sql
+```
+
+### 编写 Up 与 Down
+
+下面用一张示例表演示迁移结构：
+
+```sql
+-- +goose Up
+CREATE TABLE public.example_items (
+    id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    name text NOT NULL
+);
+
+-- +goose Down
+DROP TABLE public.example_items;
+```
+
+该示例的 Down 会删除表及其中的数据。
+
+### 检查并执行
+
+```bash
+goose -env=.env.local validate
+goose -env=.env.local status
+goose -env=.env.local up
+goose -env=.env.local status
+goose -env=.env.local version
+```
+
+执行前确认目标数据库已创建，且待创建的对象不存在。`status` 中的 `Pending` 表示对应迁移尚未应用。
+
+Goose 会记录成功应用的迁移；再次执行 `up` 时，已应用版本会被跳过。
+
+## 7. 变更与回滚原则
+
+- **已执行的迁移文件不再修改**；后续结构变更通过新增迁移实现。
+- 为需要回滚的迁移编写对应 Down，并检查它能否正确撤销结构变更。
+- `down` 只回滚最近一个已应用迁移，不是清库或重建数据库的通用命令。
+- 删除表或字段可能丢失数据；反向 SQL 不等于数据恢复。
+- 回滚前阅读对应 SQL、评估影响并备份数据库。
+- 避免手工执行与迁移文件重复的建表脚本，以免对象和版本记录不一致。
+
+## 8. 常见问题
+
+| 报错或现象 | 排查方向 |
+|---|---|
+| 找不到 `goose` 命令 | 检查安装是否成功，以及实际安装目录是否已加入 `PATH` |
+| `hostname resolving error`，主机名混入非法字符 | 检查连接串分隔符，以及用户名、密码的 URL 编码 |
+| `password authentication failed` | 核对用户名、密码及编码；检查系统同名环境变量是否覆盖配置 |
+| `connection refused` / `i/o timeout` | 检查监听地址、端口、容器端口映射和防火墙 |
+| `already exists` | 检查对象是否已被手工创建；先比较现有结构与迁移内容，再确定处理方式 |
+| 修改 `.env.local` 后配置似乎未生效 | 确认使用了 `-env=.env.local`，并排查系统中已有的同名环境变量 |
+
+遇到对象已存在的问题，不要直接删除现有数据，也不要手工插入版本记录来伪造迁移状态。