sqlc生成的Go代码编译报错“undefined: sqlc”是因为sqlc是纯代码生成工具，不提供运行时包，需正确配置package名、存放路径及依赖管理。
sqlc 生成的 Go 代码为什么编译报错：undefined: sqlc
因为 sqlc 不是 Go 的运行时依赖，而是纯代码生成工具——它不提供任何运行时包，也不会自动把生成的代码加进 go.mod。你看到的 import "github.com/kyleconroy/sqlc/internal/codegen/golang" 这类路径，只出现在 sqlc 源码里，不是你项目该引用的。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 确保你用的是官方二进制（
sqlc），不是go install github.com/kyleconroy/sqlc/...安装的旧版（v1.15 前会污染 GOPATH） - 生成命令必须带
-package参数，比如：sqlc generate -f ./sqlc.yaml -package db，否则默认 package 名是main，和你的模块冲突 - 生成的代码要放在项目目录下（如
db/子目录），且该目录不能有go.mod；否则 Go 会把它当独立 module 加载失败 - 检查
sqlc.yaml里的emit_json_tags和emit_db_tags是否符合你实际 ORM 或 scanner 习惯，错配会导致Scan失败但编译不报错
query.sql 里写 SELECT *，生成的 struct 字段顺序乱、字段名大小写不对
sqlc 是按 PostgreSQL / MySQL 的列元信息推导字段名和类型，不解析 SQL 语义。用 SELECT * 时，它完全依赖数据库返回的 column name，而不同驱动、不同版本对别名/大小写的处理不一致——比如 pgx 默认把所有字段转小写，MySQL 可能保留原 casing。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 永远显式写出字段名：
SELECT id, user_name AS user_name, created_at AS created_at，避免依赖* - 在
sqlc.yaml中启用emit_lowercase（默认 false），可强制统一字段命名风格 - 如果字段含下划线（如
user_id），sqlc 默认转成UserID；但若数据库返回的是USER_ID，可能变成UserId—— 此时需配合name_mapping配置做映射 - PostgreSQL 用户注意：
SELECT "user_id"（双引号）会保留原始名，但 sqlc 仍按小写处理；稳妥做法是用AS显式声明别名
执行 sqlc generate 报错：error: couldn't load schema: failed to connect to `host=localhost user=postgres database=postgres`: dial error (dial tcp [::1]:5432: connect: connection refused)
sqlc 在生成阶段需要连接数据库（除非你禁用 strict 模式），目的是获取表结构、类型、约束等元数据。这个报错说明它根本连不上，不是 SQL 写错了，而是环境没准备好。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 临时起一个本地数据库最省事：
docker run -d --name pg -e POSTGRES_PASSWORD=pass -p 5432:5432 -d postgres，然后改sqlc.yaml里的database_url - 不想启 DB？加
strict: false到sqlc.yaml的sql:下，并确保所有 query 文件里都有完整类型注释，例如：-- name: GetUser :one -- columns: id:bigint, name:text, created_at:timestamptz
- Mac M1 用户常见坑：
host=localhost走 IPv6 回环，容易超时；换成host=127.0.0.1或加?hostaddr=127.0.0.1 - CI 环境别硬编码
database_url，用env:引入变量，比如database_url: "{{ .DB_URL }}"
生成的 db.Querier 接口没法直接用 sql.DB，必须传 *sql.Tx 或 sqlc.Querier
sqlc 默认生成的接口依赖它自己的 sqlc.Querier（内部封装了 QueryRowContext 等方法），而不是标准库的 *sql.DB 或 *sql.Tx。这不是 bug，是为支持多 driver（pgx、mysql、sqlite）做的抽象层。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 最简用法：把
*sql.DB转成sqlc.Querier，只需调用db.NewDB(...)（生成代码里自带的构造函数），它接受*sql.DB并返回实现了sqlc.Querier的 struct - 事务场景别传
*sql.Tx给NewDB——应该用db.NewTx(tx)，它返回一个绑定到该事务的Querier - 如果想绕过 sqlc 接口、直接用
*sql.DB，就别用生成的GetUser方法，改用db.QueryRowContext(ctx, query, args...)手写；但这样就失去类型安全和字段绑定 - 注意：生成的
db.Querier接口不含Exec方法，DML 语句（INSERT/UPDATE）也得走它生成的专用方法，比如q.CreateUser(ctx, arg)
最容易被忽略的是：sqlc 生成的代码不包含连接池管理、重试、日志或 trace，它只管“怎么把 SQL 映射成 Go 类型”。要不要加中间层、用什么 driver、怎么传 context，全得你自己补——而且得在生成前就想清楚，因为部分选项（如 emit_interface）一旦关了，再开就得全量重生成。
