# 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`，并排查系统中已有的同名环境变量 |

遇到对象已存在的问题，不要直接删除现有数据，也不要手工插入版本记录来伪造迁移状态。