数据

与现有库一致的新表（migrations/0001_create_notes.up.sql）

字符集与引擎写在建表语句里。标题长度用 VARCHAR；限制长度时用 CHAR_LENGTH，LENGTH 按字节算，中文与 emoji 会算多。

CREATE TABLE notes (
    id         BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    scope_id   BIGINT NOT NULL,
    title      VARCHAR(255) NOT NULL,
    file_path  VARCHAR(512) NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    KEY idx_notes_scope_created (scope_id, created_at),
    CONSTRAINT fk_notes_scope FOREIGN KEY (scope_id) REFERENCES scopes(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

一对迁移文件（up 与 down 一起提交）

文件名 NNNN_动词_对象，一次提交这一对。第一行注释写这次改动做什么，方便 migrate 日志里对上号。

migrations/0007_add_notes_scope_index.up.sql
migrations/0007_add_notes_scope_index.down.sql

0007_add_notes_scope_index.up.sql

-- 0007 列表按所属范围倒序读取，补组合索引。
-- 等值条件 scope_id 放左边，排序用的 created_at 放右边。
ALTER TABLE notes
    ADD KEY idx_notes_scope_created (scope_id, created_at);

0007_add_notes_scope_index.down.sql

把 down 写成空文件是最常见的违规。不能反向执行的改动（例如删列后再恢复会丢数据），在发布说明里写清停在哪一步，见发布。

-- 0007 回滚：删掉本编号新增的索引。
ALTER TABLE notes
    DROP KEY idx_notes_scope_created;

scripts/check-migrations.sh

三条检查一次跑完：文件名格式、编号连续、up 与 down 成对。down 是否真的能执行，脚本查不出来，靠下面 migrate-roundtrip——两个都要跑。

#!/bin/sh
# 迁移文件规范检查：文件名、编号连续性、up/down 成对。
dir=migrations
status=0

for f in "$dir"/*.sql; do
    name=$(basename "$f")
    echo "$name" | grep -Eq '^[0-9]{4}_[a-z0-9_]+\.(up|down)\.sql$' \
        || { echo "文件名不合规: $name"; status=1; }
done

expect=1
for f in "$dir"/*.up.sql; do
    num=$(basename "$f" | cut -c1-4 | sed 's/^0*//')
    [ -z "$num" ] && num=0
    if [ "$num" -ne "$expect" ]; then
        echo "编号不连续: 期待 $(printf '%04d' "$expect")，实际 $(basename "$f")"
        status=1
    fi
    expect=$((expect + 1))
    [ -f "$dir/$(basename "$f" .up.sql).down.sql" ] \
        || { echo "缺少 down: $(basename "$f")"; status=1; }
done

exit $status

Makefile（并进 check）

migrate-roundtrip 才是真正证明 down 能跑的那一步：上、全部下、再上。它需要一个空的测试库，用环境配置里的 TEST_MYSQL_DSN；变量未设置时它会跳过。make check 的聚合入口只在质量门禁里定义一次，这一页只加子目标。

.PHONY: migrations migrate-roundtrip migrations-check

migrations:
	sh scripts/check-migrations.sh

migrate-roundtrip:
	migrate -path migrations -database "$(TEST_MYSQL_DSN)" up
	migrate -path migrations -database "$(TEST_MYSQL_DSN)" down -all
	migrate -path migrations -database "$(TEST_MYSQL_DSN)" up

# 挂进 check：check: fmt-check lint type migrations-check secret complexity test
migrations-check: migrations
	ruff check --output-format=concise .

助手交出来的样子

rows, err := db.Query(
    "SELECT id, title FROM notes WHERE id = ?", id)
                                     ↑ 少了 scope_id