Buffalo框架中database.yml仅为示意文件，实际数据库连接由models.NewDB()决定，该函数依赖DATABASE_URL环境变量而非YAML配置；运行buffalo dev前须手动执行buffalo db create与buffalo db migrate初始化数据库。
database.yml 配置只是示意，真正起作用的是 models.NewDB()
很多人卡在 buffalo db create -a 报 “connection refused”，以为是 config/database.yml 写错了——其实 Buffalo 运行时根本不会读这个文件。它只在生成迁移文件或 CLI 提示时当人肉参考用。真实数据库连接由 models/NewDB() 函数决定，而该函数默认读取环境变量 DB_URL（如 postgres://user:pass@localhost:5432/myapp_development?sslmode=disable）。database.yml 里写的 dialect、host 等字段，只影响 buffalo pop 命令行工具解析时的 fallback 行为。
常见错误现象：
-
buffalo db create -a成功，但buffalo dev启动后查表报table not found -
buffalo db migrate报failed to connect to host=localhost user=postgres database=
这说明 CLI 和运行时用了两套配置。解决方法：
- 删掉
config/database.yml或确保它和DB_URL一致（推荐后者） - 在项目根目录加
.env文件，写入DB_URL=... - 确认
models/models.go中NewDB()调用了pop.Connect("development")或类似逻辑（默认模板已包含）
增删改查必须用 app.Pop() 获取连接，不能 new pop.Connection
app.Pop() 不是简单返回一个连接对象，而是从全局连接池中取出一个带上下文绑定的 *pop.Connection 实例。它自动继承当前请求的事务状态（如果在事务中）、日志上下文、超时控制等。直接 pop.NewConnection(...) 会绕过所有这些机制，导致事务不生效、日志丢失、连接泄漏。
正确姿势：
- 创建：
err := app.Pop().Create(&u) - 查询单条：
err := app.Pop().First(&u, "email = ?", "a@example.com") - 更新（先查后改再 Save）：
err := app.Pop().Save(&u) - 删除：
err := app.Pop().Destroy(&u)
注意：Save() 是 update + insert 的合体，对新记录执行 INSERT，对已有 ID 的记录执行 UPDATE；若你明确只要 UPDATE，请先 First() 再改字段再 Save()，否则可能意外插入重复数据。
批量插入要用 BatchInsert()，别碰 CreateInBatches()
db.CreateInBatches() 是 GORM v2 的方法，在 Buffalo 使用的 pop/v6（底层基于 GORM v1）中不存在，调用会直接 panic。真正可用的是 db.BatchInsert([]interface{})。
使用限制很实际：
- 不触发
BeforeCreate钩子 → 时间戳、UUID、加密字段需手动填充 - 主键为自增整数时，插入后
ID字段不会回填到 struct 实例中 - PostgreSQL 下实际发多条单值 INSERT（不支持 multi-value），性能提升有限；MySQL 才真走单语句多值
- 整批失败不告诉你第几个元素错，只能靠
pop.Error.Query定位 SQL 和参数
安全写法示例：
func BulkInsertUsers(db *pop.Connection, users []User) error {
now := time.Now()
for i := range users {
if users[i].CreatedAt.IsZero() {
users[i].CreatedAt = now
}
if users[i].UpdatedAt.IsZero() {
users[i].UpdatedAt = now
}
}
return db.BatchInsert(users)
}
第一次跑 buffalo dev 前，必须手动 create + migrate
buffalo dev 启动时不自动执行任何数据库操作。它只负责热重载代码和重启服务。如果你跳过初始化步骤，访问页面时会因表不存在直接 panic，错误信息像 ERROR: relation "users" does not exist，而不是连接失败。
必须按顺序执行：
-
buffalo db create：根据DB_URL创建数据库（不是建表） -
buffalo db migrate：执行migrations/下所有未跑过的 up 文件（建表、加索引等）
这两个命令失败，buffalo dev 就没意义。尤其注意：SQLite 用户需系统装 gcc，否则 go build 阶段 sqlite3 驱编译失败，整个链路中断。
最常被忽略的一点：model 结构体必须实现 TableName() 方法，且 ID 字段必须存在并标记为主键，否则 Create() 会报 no primary key defined —— 这个错误不提示具体哪一行，只在运行时炸，容易误判成数据库配置问题。
