在sqlc中如何正确映射PostgreSQL的timestamptz到Go的time.Time

在使用sqlc生成Go代码时，许多开发者会遇到将PostgreSQL的timestamp with time zone类型映射到Go的time.Time或*time.Time类型的挑战。本文将深入探讨这个问题及其解决方案。

问题背景

当使用sqlc的pgx/v5驱动时，默认情况下pg_catalog.timestamptz类型会被映射为pgtype.Timestamptz，即使字段是可空的(nullable)。这与许多开发者期望的直接映射到time.Time或*time.Time不符。

默认行为分析

sqlc内部处理类型映射的逻辑如下：

1. 对于非pgx驱动，timestamptz会映射为：
   • 非空字段：time.Time
   • 可空字段：sql.NullTime或*time.Time(取决于配置)
2. 对于pgx/v5驱动，则强制使用pgtype.Timestamptz

这种设计导致开发者无法直接获得期望的*time.Time映射。

解决方案

经过社区验证，可以通过sqlc的配置覆盖机制实现正确的类型映射：

overrides:
  - db_type: "pg_catalog.timestamptz"
    go_type:
      import: "time"
      type: "Time"
  - db_type: "pg_catalog.timestamptz"
    go_type:
      import: "time"
      type: "Time"
      pointer: true
    nullable: true

这个配置明确指定了：

1. 非空timestamptz映射为time.Time
2. 可空timestamptz映射为*time.Time

其他类型的注意事项

需要注意的是，这种配置方式对于其他类型如boolean、int、uuid等可能表现不同。特别是使用pgx/v5驱动时：

1. 对于数值类型，可以配合emit_pointers_for_null_types: true实现指针映射
2. 对于uuid类型，pgx/v5会强制使用pgtype.UUID，若想使用google的uuid.UUID需要额外配置

最佳实践建议

1. 明确指定每种需要特殊处理的数据库类型
2. 对于可空字段，显式配置pointer: true
3. 测试生成的代码是否符合预期
4. 对于复杂类型，考虑编写自定义类型处理逻辑

通过合理配置，开发者可以完全控制sqlc生成的类型映射，满足各种业务场景的需求。