# 转岗计划 · 第 3 周学习计划（PostgreSQL + SQL + sqlc）

> 所属阶段：第一段 Go 全栈基础（第 1~5 周）。总纲见同目录 `README.md`，上周计划 `week02-gin-api.md`，下周计划 `week04-auth-project1.md`。

目标：把第 2 周任务清单里的 `MemoryStore` 换成 PostgreSQL。学会表结构设计、常用 SQL、索引、事务和数据库迁移，用 sqlc 生成类型安全的数据访问代码。因为上周用接口隔离了存储层，本周主要是新写一个 `PgStore`，接口代码基本不用动。

前置条件：第 2 周的 `todo-api` 已完成，`go test ./... -race` 能通过，前端能联调。

要求：SQL 自己写，AI 只帮你检查和解释。表结构设计、索引、事务是所有后端岗位的基本功，后面 RAG 和 Agent 项目设计状态表也靠它。

**为什么学 PostgreSQL 而招聘里 MySQL 更多**：招聘里写 MySQL 的明显更多，但两者的常用 SQL 大部分相同。本周用 PostgreSQL 学（它的 pgvector 扩展在 RAG 里也能用），文末附“MySQL 差异速查”和一个半天的小练习，面试时能说清差异就够了。

参考资料：
- PostgreSQL 官方文档（中文）：http://www.postgres.cn/docs/current/
- sqlc 文档：https://docs.sqlc.dev/
- golang-migrate：https://github.com/golang-migrate/migrate
- pgx：https://github.com/jackc/pgx

---

## 最终项目结构

只列出本周新增或修改的文件，其他保持第 2 周的样子。

```
todo-api/
└── backend/
    ├── docker-compose.yml               # 本地 PostgreSQL
    ├── Makefile                         # 常用命令：db-up、migrate-up、sqlc 等
    ├── .env.example                     # DATABASE_URL 示例（.env 本身不提交）
    ├── sqlc.yaml                        # sqlc 配置
    ├── db/
    │   ├── migrations/
    │   │   ├── 000001_create_tasks.up.sql
    │   │   ├── 000001_create_tasks.down.sql
    │   │   ├── 000002_add_tasks_indexes.up.sql
    │   │   ├── 000002_add_tasks_indexes.down.sql
    │   │   ├── 000003_create_tags.up.sql
    │   │   └── 000003_create_tags.down.sql
    │   └── queries/
    │       ├── tasks.sql                # 带 sqlc 注释的查询
    │       └── tags.sql
    ├── sql/
    │   └── practice/                    # 练习用 SQL，不参与程序运行
    │       ├── day1_crud.sql
    │       ├── day2_schema.sql
    │       ├── day3_queries.sql
    │       └── seed.sql
    ├── internal/
    │   ├── config/
    │   │   └── config.go                # 读环境变量
    │   ├── db/                          # sqlc 生成的代码（不要手改）
    │   │   ├── db.go
    │   │   ├── models.go
    │   │   ├── tasks.sql.go
    │   │   └── tags.sql.go
    │   ├── model/
    │   │   └── task.go                  # 新增 Tags 字段
    │   ├── store/
    │   │   ├── store.go                 # 接口方法加上 context.Context
    │   │   ├── memory_store.go          # 同步改签名
    │   │   ├── pg_store.go              # PostgreSQL 实现
    │   │   ├── pg_tx.go                 # 事务辅助函数
    │   │   └── pg_store_test.go         # 集成测试（需要数据库）
    │   └── handler/
    │       └── task_handler.go          # 传入 c.Request.Context()，新增分页和标签参数
    └── main.go                          # 按配置选择 memory 或 postgres
```

## 本周数据库表

```
tasks
  id          BIGSERIAL PRIMARY KEY
  title       TEXT NOT NULL  (长度 1~100，用 CHECK 约束)
  done        BOOLEAN NOT NULL DEFAULT false
  created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
  updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()

tags
  id    BIGSERIAL PRIMARY KEY
  name  TEXT NOT NULL UNIQUE

task_tags（多对多关联表）
  task_id  BIGINT REFERENCES tasks(id) ON DELETE CASCADE
  tag_id   BIGINT REFERENCES tags(id) ON DELETE CASCADE
  PRIMARY KEY (task_id, tag_id)
```

---

## 第 1 天：装 PostgreSQL，用 psql 写增删改查

**学习内容**
- 用 Docker 跑 PostgreSQL（不用往系统里直接装）。没有 Docker 的话先装：`sudo apt install docker.io docker-compose-v2`。
- `psql` 常用命令：`\l` 列数据库、`\dt` 列表、`\d 表名` 看表结构、`\q` 退出。
- 基本 SQL：`CREATE TABLE`、`INSERT`、`SELECT ... WHERE ... ORDER BY ... LIMIT`、`UPDATE`、`DELETE`。
- 常用类型：`BIGSERIAL`、`TEXT`、`BOOLEAN`、`TIMESTAMPTZ`、`JSONB`（先知道有这个，Agent 项目会用到类似的思路）。

**要建的文件**
- `backend/docker-compose.yml`：
  - 一个 `postgres:16` 服务，端口 `5432:5432`，环境变量 `POSTGRES_USER=todo`、`POSTGRES_PASSWORD=todo`、`POSTGRES_DB=todo`。
  - 用具名卷 `pgdata` 保存数据，容器删了数据还在。
- `backend/.env.example`：`DATABASE_URL=postgres://todo:todo@localhost:5432/todo?sslmode=disable`
- `backend/sql/practice/day1_crud.sql`：
  - 建一张练习表 `practice_tasks`。
  - 插入 5 条数据，查询未完成的、按创建时间倒序、只取前 3 条，更新一条，删除一条。
  - 每条语句上面写一行注释说明它在做什么。

**运行方式**
```bash
cd todo-api/backend
docker compose up -d
docker compose exec -T postgres psql -U todo -d todo < sql/practice/day1_crud.sql
docker compose exec postgres psql -U todo -d todo   # 进入交互模式
```

**完成标准**：不看资料能写出带 `WHERE`、`ORDER BY`、`LIMIT` 的查询，以及 `UPDATE ... WHERE id = ...`，并能说出漏写 `WHERE` 的后果。

---

## 第 2 天：表结构设计和数据库迁移

**学习内容**
- 主键、外键、`NOT NULL`、`UNIQUE`、`CHECK`、`DEFAULT` 约束：能交给数据库保证的规则，就不要只靠代码保证。
- 一对多（一个用户多个任务）和多对多（任务和标签）怎么建表。
- 为什么要用迁移文件：表结构变更也要进 Git，每个环境按顺序执行，避免“代码升级了、库表没升级”导致接口报错。
- 安装 golang-migrate：`go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest`。

**要建的文件**
- `backend/sql/practice/day2_schema.sql`：
  - 练习设计一套 `users`、`practice_tasks`（带 `user_id` 外键）、`tags`、`task_tags` 表。
  - 写注释回答：删除用户时，他的任务该怎么处理？`ON DELETE CASCADE` 和 `ON DELETE RESTRICT` 各适合什么场景？
- `backend/db/migrations/000001_create_tasks.up.sql`：按上面“本周数据库表”建 `tasks` 表，`title` 加 `CHECK (char_length(title) BETWEEN 1 AND 100)`。
- `backend/db/migrations/000001_create_tasks.down.sql`：`DROP TABLE IF EXISTS tasks;`
- `backend/Makefile`：
  - `db-up`：`docker compose up -d`
  - `migrate-up`：`migrate -path db/migrations -database "$(DATABASE_URL)" up`
  - `migrate-down`：回退一步 `down 1`
  - `migrate-new`：`migrate create -ext sql -dir db/migrations -seq $(name)`
  - `psql`：进入数据库

**运行方式**：`export $(cat .env | xargs) && make migrate-up`，再 `make psql` 用 `\d tasks` 看表结构；`make migrate-down` 再 `make migrate-up`，确认能来回执行。

**完成标准**：能说清楚“为什么上线时先跑迁移再发新代码”，以及 down 迁移的作用。

---

## 第 3 天：多表查询、分组统计和索引

**学习内容**
- `JOIN`（内连接）和 `LEFT JOIN` 的区别。
- `GROUP BY` + `COUNT` / `SUM`、`HAVING`。
- 子查询和 `EXISTS`。
- 索引：B-tree 索引适合什么查询；用 `EXPLAIN ANALYZE` 看查询计划，分清 `Seq Scan` 和 `Index Scan`。
- 索引的代价：写入变慢、占空间，不是越多越好。

**要建的文件**
- `backend/sql/practice/seed.sql`：用 `generate_series` 往 `practice_tasks` 插入 10 万条测试数据，随机分配给 100 个用户和若干标签。
- `backend/sql/practice/day3_queries.sql`，至少包含：
  - 每个用户的任务总数和已完成数（`GROUP BY` + `COUNT(*) FILTER (WHERE done)`）。
  - 查出没有任何任务的用户（`LEFT JOIN ... WHERE ... IS NULL`）。
  - 查出带某个标签的任务（两次 `JOIN` 经过关联表）。
  - 任务数超过 1000 的用户（`HAVING`）。
  - 对“按用户查未完成任务并按时间倒序”的查询，加索引前后各跑一次 `EXPLAIN ANALYZE`，把耗时和计划写在注释里。
- `backend/db/migrations/000002_add_tasks_indexes.up.sql`：给 `tasks` 加 `(done, created_at DESC)` 的组合索引。
- `backend/db/migrations/000002_add_tasks_indexes.down.sql`：删除这个索引。

**运行方式**：在 `psql` 里执行 `\i` 或用第 1 天的方式执行 SQL 文件。

**完成标准**：能解释组合索引的“最左前缀”规则，能看懂 `EXPLAIN ANALYZE` 输出里最关键的两三行。

---

## 第 4 天：sqlc 生成代码，写 PgStore

**学习内容**
- sqlc 的思路：你写 SQL，它生成 Go 结构体和函数，编译期就能发现字段写错。
- pgx 连接池 `pgxpool`。
- `context.Context`：数据库调用都要带上下文，请求取消或超时时能停止查询。
- 安装 sqlc：`go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest`；添加依赖 `go get github.com/jackc/pgx/v5`。

**要建的文件**
- `backend/sqlc.yaml`：引擎 `postgresql`，`schema` 指向 `db/migrations`，`queries` 指向 `db/queries`，输出包 `db` 到 `internal/db`，`sql_package: "pgx/v5"`。
- `backend/db/queries/tasks.sql`：
  - `-- name: ListTasks :many`（支持按 `done` 过滤，用 `sqlc.narg('done')` 处理“可选参数”）
  - `-- name: GetTask :one`
  - `-- name: CreateTask :one`（`RETURNING *`）
  - `-- name: UpdateTask :one`（同时更新 `updated_at = now()`）
  - `-- name: DeleteTask :execrows`（根据影响行数判断是否存在）
- 运行 `sqlc generate`，生成 `internal/db/` 下的代码。读一遍生成的 `tasks.sql.go`，看懂它在做什么。
- 修改 `internal/store/store.go`：`TaskStore` 每个方法第一个参数加 `ctx context.Context`。
- 修改 `internal/store/memory_store.go` 和 `internal/handler/task_handler.go`：同步改签名，handler 里传 `c.Request.Context()`。
- `internal/store/pg_store.go`：
  - `type PgStore struct { pool *pgxpool.Pool; q *db.Queries }`
  - `func NewPgStore(pool *pgxpool.Pool) *PgStore`
  - 实现 `TaskStore` 全部方法；`pgx.ErrNoRows` 和影响行数为 0 时返回 `store.ErrNotFound`。
  - `func toModel(t db.Task) model.Task`：把生成的结构体转成自己的 `model.Task`，不让生成代码泄露到 handler 层。
- `Makefile` 增加 `sqlc` 目标：`sqlc generate`。

**运行方式**：`make sqlc && go build ./...`；`go test ./... -race`（内存版测试要继续通过）。

**完成标准**：能说清楚 `model.Task` 和 `db.Task` 为什么分开，以及给存储层加 `context` 的意义。

---

## 第 5 天：事务和标签功能

**学习内容**
- 事务的作用：几条写操作要么全成功、要么全失败。
- `BEGIN` / `COMMIT` / `ROLLBACK`；在 Go 里用 `pool.Begin(ctx)`，`defer tx.Rollback(ctx)`，最后 `tx.Commit(ctx)`。
- 隔离级别先了解“读已提交”（PostgreSQL 默认）就够，知道还有更严格的级别。
- `INSERT ... ON CONFLICT DO NOTHING / DO UPDATE`（“存在就跳过或更新”，Agent 项目里做幂等写入会用到）。

**要建的文件**
- `backend/db/migrations/000003_create_tags.up.sql` / `.down.sql`：建 `tags`、`task_tags` 表。
- `backend/db/queries/tags.sql`：
  - `-- name: UpsertTag :one`（`INSERT ... ON CONFLICT (name) DO UPDATE SET name = EXCLUDED.name RETURNING id`）
  - `-- name: AddTaskTag :exec`
  - `-- name: ListTagsByTaskIDs :many`（一次查多个任务的标签，避免“查 N 个任务就发 N 次查询”）
- `internal/store/pg_tx.go`：
  - `func (s *PgStore) withTx(ctx context.Context, fn func(q *db.Queries) error) error`：开启事务、执行函数、出错回滚、成功提交。
- `internal/model/task.go`：`Task` 增加 `Tags []string` 字段，`Validate()` 校验标签数量不超过 5 个、每个不超过 20 字。
- `internal/store/pg_store.go`：
  - `Create` 改成在事务里：插入任务 → 逐个 `UpsertTag` → `AddTaskTag`。
  - `List` 查出任务后，用 `ListTagsByTaskIDs` 一次性补上标签。
- `MemoryStore` 同步支持 `Tags`（简单存在结构体里即可），保证两种实现行为一致。
- 更新 `api.http`：新增带标签的创建请求。

**完成标准**：在 `Create` 里故意在插入标签后返回一个错误，确认任务也没有写进数据库（回滚生效），验证完再删掉这段代码。

---

## 第 6 天：配置切换和集成测试

**学习内容**
- 用环境变量选择存储实现，开发时也能随时切回内存版。
- 集成测试和单元测试的区别：集成测试连真数据库，跑得慢，但能发现 SQL 写错。
- 测试之间的数据隔离：每个测试前清空表（`TRUNCATE ... RESTART IDENTITY CASCADE`）。

**要建的文件**
- `internal/config/config.go`：
  - `type Config struct { Port string; Store string; DatabaseURL string }`
  - `func Load() (Config, error)`：`STORE` 只能是 `memory` 或 `postgres`；选了 `postgres` 但没有 `DATABASE_URL` 时返回错误。
- 修改 `main.go`：
  - 调用 `config.Load()`。
  - `postgres` 模式下创建 `pgxpool`，启动时 `Ping`，失败就打日志退出；优雅关机时关闭连接池。
  - `/api/health` 增加数据库检查：数据库不通时返回 503。
- `internal/store/pg_store_test.go`：
  - 没有设置 `TEST_DATABASE_URL` 时调用 `t.Skip`，这样没装数据库的环境也能跑 `go test`。
  - `setupPg(t)`：连接测试库、清空表，`t.Cleanup` 里关闭连接。
  - 测试：创建 → 获取 → 更新 → 按 `done` 过滤 → 删除 → 再获取返回 `ErrNotFound`；带标签创建后列表里能看到标签；重复标签名不会重复插入。
- `Makefile` 增加 `test-integration`：设置 `TEST_DATABASE_URL` 后跑 `go test ./internal/store -v`。

**运行方式**：`STORE=postgres go run .`，前端不用改，直接联调；`make test-integration`。

**完成标准**：切换 `STORE` 环境变量，前端功能完全一样；重启后端后数据还在。

---

## 第 7 天：分页、慢查询和收尾

**学习内容**
- 两种分页：`LIMIT/OFFSET`（简单，但页数越往后越慢）和“游标分页”（`WHERE id < 上一页最后一个 id`）。
- 慢查询排查的一般步骤：先找出慢的 SQL → `EXPLAIN ANALYZE` → 看是不是缺索引或者查了太多数据 → 改完再测。

**要建的文件和修改**
- `db/queries/tasks.sql`：新增 `-- name: ListTasksPage :many`，用游标分页（参数 `before_id`、`limit`）。
- `internal/handler/task_handler.go`：`GET /api/tasks` 支持 `?limit=20&before_id=xxx`，返回 `{ items, next_before_id }`；`limit` 默认 20、最大 100。
- 前端 `src/api/tasks.ts` 和 `TaskList`：加“加载更多”按钮。
- `todo-api/README.md`：补充数据库部分：如何启动 PostgreSQL、跑迁移、切换存储、跑集成测试；画一张表关系图（mermaid `erDiagram`）。
- 提交并推送到 `zhuangang` 仓库（路径 `todo-api/`）。**确认 `.env` 没有被提交**。

**完成标准**
- `go vet ./...` 没有警告，`gofmt -l .` 没有输出。
- `go test ./... -race` 和 `make test-integration` 都通过。
- 新电脑按 README 能从零跑起来：`docker compose up -d` → `make migrate-up` → `STORE=postgres go run .`。
- 在总纲 `README.md` 的进度记录里勾掉第 3 周。

---

## 本周自查清单

- [ ] 会用 Docker 启动 PostgreSQL，会用 psql
- [ ] 能独立写增删改查、`JOIN`、`GROUP BY`、`HAVING`
- [ ] 会设计一对多、多对多的表，知道外键删除策略怎么选
- [ ] 会写迁移文件，理解为什么表结构要版本化
- [ ] 能用 `EXPLAIN ANALYZE` 判断有没有走索引
- [ ] 会用 sqlc 生成代码，知道生成代码和业务模型为什么分开
- [ ] 会在 Go 里写事务，并验证过回滚
- [ ] 会用 `ON CONFLICT` 做“存在就跳过或更新”
- [ ] 写了能自动跳过的集成测试
- [ ] 会做游标分页
- [ ] 看过文末 MySQL 差异速查，能说出 3 个以上的差异

## 附：MySQL 差异速查（第 7 天有余力时做，或放到第 5 周的缓冲时间）

招聘里 MySQL 出现得多，会 PostgreSQL 后只需要知道这些差异：

| 方面 | PostgreSQL | MySQL 8 |
| --- | --- | --- |
| 自增主键 | `BIGSERIAL` 或 `GENERATED ... AS IDENTITY` | `BIGINT AUTO_INCREMENT` |
| 插入后拿回数据 | `INSERT ... RETURNING *` | 不支持 `RETURNING`，用 `LAST_INSERT_ID()` 再查一次 |
| 存在就更新 | `ON CONFLICT (...) DO UPDATE` | `ON DUPLICATE KEY UPDATE` |
| 布尔 | `BOOLEAN` | `TINYINT(1)`（`BOOLEAN` 是它的别名） |
| 时间 | `TIMESTAMPTZ` 带时区 | `DATETIME` 不带时区，`TIMESTAMP` 有范围限制；一般统一存 UTC |
| JSON | `JSONB`，可建索引 | `JSON`，索引要借助生成列 |
| 字符集 | 默认 UTF-8 | 建库时指定 `utf8mb4`，否则存不了表情符号 |
| 字符串比较 | 默认区分大小写 | 默认排序规则一般不区分大小写 |
| 存储引擎 | 只有一种 | 用 InnoDB（支持事务和外键） |
| 占位符（Go 驱动） | `$1, $2` | `?` |

**小练习（半天）**
- 在 `docker-compose.yml` 里加一个 `mysql:8` 服务（端口 `3306`）。
- `sql/practice/mysql_schema.sql`：把 `000001` 和 `000003` 迁移改写成 MySQL 语法，跑通。
- `sql/practice/mysql_notes.md`：记下改写时遇到的每一处差异。
- 了解即可：sqlc 也支持 MySQL（`engine: mysql`），GORM 两种数据库都支持，换库主要改的是 SQL 方言和驱动。

下周预告：第 4 周在这套基础上做项目一“团队任务看板”：注册登录、JWT、看板成员权限、按状态分列的任务，前后端完整联调。