如何在 GORM 中将 PostgreSQL 函数设为字段默认值

如何在 GORM 中将 PostgreSQL 函数设为字段默认值

GORM 支持通过 sql:"DEFAULT:函数名" 标签直接调用 PostgreSQL 内置或自定义函数作为字段默认值，无需额外迁移逻辑，适用于 current_timestamp、uuid_generate_v4() 等场景。

直接让数据库在插入时动态生成默认值，而不是在应用层预先计算，这听起来是不是更优雅？GORM 就提供了这样的能力。通过一个简单的结构体标签 sql:"default:函数名"，你可以轻松调用 PostgreSQL 的内置函数（如 current_timestamp）或自定义函数（如 uuid_generate_v4()），无需编写额外的迁移逻辑。

具体来说，在 GORM v1.x 版本中，这个机制依赖于 sql:"DEFAULT:..." 标签。它的工作原理很直接：GORM 会将标签中指定的函数名原封不动地写入最终生成的 CREATE TABLE 语句的 DEFAULT 子句里。这样一来，默认值的计算就完全交给了数据库，在每次插入记录时动态执行，确保了数据层面的准确性和一致性。

✅ 正确用法示例

来看一个具体的模型定义，一切都清晰了：

type User struct {
    ID        int       `gorm:"primary_key" sql:"DEFAULT:nextval('user_id_seq')"`
    CreatedAt time.Time `sql:"DEFAULT:current_timestamp"`
    UpdatedAt time.Time `sql:"DEFAULT:current_timestamp"`
    UUID      string    `sql:"DEFAULT:uuid_generate_v4()"`
}

⚠️ 需要留意的几个细节

功能强大，但用起来也得讲究，避开一些常见的“坑”能让开发更顺畅：

• 函数名千万别加引号。比如应该写 current_timestamp，而不是 'current_timestamp'。加了单引号，PostgreSQL 会把它当作一个普通的字符串字面量，而不是去调用函数。
• 那么，什么时候才用单引号呢？只有当你想设置的默认值就是一个静态的字符串时，比如 sql:"DEFAULT:'pending'"。
• 如果你用的是自定义函数，例如 uuid_generate_v4()，务必事先确认该函数已在数据库中存在且对当前 Schema 可见。这通常意味着你需要先启用相应的扩展，如 pgcrypto 或 uuid-ossp。
• 注意版本差异。GORM v2（即 gorm.io/gorm）已经弃用了 sql 标签。新的做法是使用 gorm: 标签，并结合 default 选项，写法如下：

  UUID string `gorm:"default:uuid_generate_v4();type:uuid"`

• 建议与 AutoMigrate 功能配合使用。同时，要确保连接数据库的用户账号拥有执行目标函数所需的权限。
• 对于主键自增场景，更通用的最佳实践是使用 gorm:"primaryKey;autoIncrement" 配合数据库序列，而不是手动指定 nextval。

总结

总而言之，只要目标函数能在 PostgreSQL 的 DEFAULT 上下文环境中合法执行——无论是 now()、gen_random_uuid() 还是像 md5(random()::text) 这样的表达式——GORM 都能通过 sql:"DEFAULT:..."（v1）或 gorm:"default:..."（v2）标签实现无缝集成。这真正实现了默认值在数据库端的计算，让数据逻辑更加清晰和稳固。