all-in-kingsoft/hhs/GORM/13-多数据库支持.md

tags, create time

tags	create time
GORM Go ORM MySQL PostgreSQL SQLite SQL Server	2026-04-28 00:00

多数据库支持

概述

GORM 采用「驱动适配器（Driver Adapter）」架构——你写一份 GORM 代码，通过切换 gorm.Open() 的 dialector 就能连接不同的数据库后端。理想情况下所有操作都应该无缝兼容，但现实是：不同数据库的方言差异会让某些功能表现出微妙甚至明显的行为不同。

[!question] 核心问题 如果代码要在三种数据库上都能跑，那是不是意味着每个查询都要写三遍？答案当然是否定的——GORM 的优势恰恰在于"一次编写，多处运行"。那么问题来了：哪些操作能保证一致？哪些地方需要特别注意？ 本章就是为了解答这些问题。

flowchart TD
    Code["你的 GORM 代码"] --> Adapter{"Driver Adapter"}
    
    Adapter --> |mysql| MySQL["MySQL / MariaDB"]
    Adapter --> |postgres| PG["PostgreSQL"]
    Adapter --> |sqlite| SQLite["SQLite"]
    Adapter --> |mssql| MSSQL["SQL Server"]
    
    style Code fill:#4FC08D,color:#fff
    style Adapter fill:#EAB308,color:#fff
    style MySQL fill:#3B82F6,color:#fff
    style PG fill:#8B5CF6,color:#fff
    style SQLite fill:#A0AEC0,color:#fff
    style MSSQL fill:#F59E0B,color:#000

[!tip] 驱动适配器的本质 GORM 内部会为每种数据库维护一个 dialector（方言鉴别器）。调用 Create、Find 等操作时，dialector 会负责将 GORM 的中间表达式翻译成对应数据库的 SQL 方言。理解这一点就能明白：为什么同样的 db.Limit(10) 在不同数据库中生成的 SQL 完全不同。

驱动安装与初始化

MySQL / MariaDB

import "gorm.io/driver/mysql"

dsn := "user:password@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local"
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
// 注意：MySQL 是最常见的选择，DSN 参数也是最多的

DSN 必配参数详解：

参数	优先级	推荐值	说明
charset	⭐⭐⭐	utf8mb4	必须用 utf8mb4，传统的 utf8 在 MySQL 中只支持 3 字节，无法存储 emoji
parseTime	⭐⭐⭐	True	自动把数据库的 datetime 转成 Go time.Time，否则你会拿到 driver.Value
loc	⭐⭐⭐	Local 或 Asia/Shanghai	解决北京时间偏移问题；不设置的话可能拿到 UTC 时间
timeout	⭐⭐	30s	TCP 握手阶段超时
readTimeout	⭐⭐	30s	从服务器读取响应超时
writeTimeout	⭐⭐	30s	向服务器发送请求超时

[!important] utf8 vs utf8mb4 常见陷阱 很多开发者不知道 MySQL 的 utf8 实际上是 "utf8mb3"——它最多支持 3 字节的字符。遇到 emoji、生僻汉字时会直接报错。这就是为什么 DSN 里必须明确指定 utf8mb4（真正的全量 UTF-8）。

// 如果你在代码中也设置了 CharacterSet，别忘了：
db.Set("gorm:table_options", "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4")

PostgreSQL

import "gorm.io/driver/postgres"

dsn := "host=localhost user=gorm password=gorm dbname=gorm port=5432 sslmode=require TimeZone=Asia/Shanghai"
db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
// PostgreSQL 使用标准的 Connection String 格式

PostgreSQL 特有注意：

• sslmode 在开发环境可设为 disable，生产环境保持 require（最低要求）或 verify-full（最强校验）
• TimeZone 要与服务端一致，否则 time.Time 字段会出现几小时的偏移
• PG 对大小写敏感：未加引号的标识符会自动转为小写，这意味着 struct 字段名映射时要格外小心

[!warning] PostgreSQL 的大写陷阱 如果你在建表时用的是双引号 "UserName"，那后续所有查询都必须也带上双引号，否则 PG 会去找 username（小写）。建议：建表一律用小写，避免此坑。

SQLite

import "gorm.io/driver/sqlite"

db, err := gorm.Open(sqlite.Open("test.db"), &gorm.Config{})
// 最简单的一种——只需要一个文件路径

SQLite 注意事项：

• 默认是文件级排他锁，并发写入会有阻塞
• 高并发场景使用 WAL + 共享缓存模式：file:test.db?cache=shared&_journal=WAL
• 不支持外键约束——AutoMigrate 不会创建外键，需要在原始 SQL 中手动添加
• 所有列本质上都是「无类型」的（type affinity），GORM 的类型映射在某些边界情况下可能有意外表现

[!tip] SQLite 开启 WAL 模式 WAL（Write-Ahead Logging）允许读写并发，性能提升显著：

db, _ := gorm.Open(sqlite.Open("file:test.db?cache=shared&_journal=WAL&_timeout=5000"), &gorm.Config{})
// cache=shared：允许多个连接共享缓存
// _journal=WAL：启用预写日志
// _timeout：锁定等待超时（毫秒）

SQL Server

import "gorm.io/driver/mssql"

dsn := "sqlserver://user:password@host:1433?database=dbname&encrypt=disable"
db, err := gorm.Open(mssql.Open(dsn), &gorm.Config{})

SQL Server 特有注意：

• 连接字符串使用 URI 格式，与其他驱动风格不同
• SQL Server 默认强制 TLS 加密，开发环境下需加 encrypt=disable
• 数据类型和自增逻辑与 MySQL/PG 都不同（详见下方方言差异表）

方言差异速查表

这是跨数据库迁移时最容易踩坑的部分。下面这张表汇总了最常见的差异场景：

特性	MySQL	PostgreSQL	SQLite	SQL Server
time.Time	DATETIME / TIMESTAMP	TIMESTAMPTZ	TEXT（序列化后）	DATETIME2
string	VARCHAR(n)	VARCHAR / TEXT	TEXT	NVARCHAR(n)
uint	INT UNSIGNED	BIGINT	INTEGER	INT
float64	DOUBLE	DOUBLE PRECISION	REAL	FLOAT
自增主键	AUTO_INCREMENT	SERIAL / BIGSERIAL	AUTOINCREMENT	IDENTITY(1,1)
NOW() 函数	NOW()	NOW()	DATETIME('now')	GETUTCDATE()
LIMIT 语法	LIMIT N OFFSET M	LIMIT N OFFSET M	LIMIT N OFFSET M	TOP N / OFFSET FETCH
软删除索引	⚠️ InnoDB 唯一约束 Bug	✅ 正常	✅ 正常	✅ 正常
ON DELETE	CASCADE / SET NULL 等	CASCADE / SET NULL 等	❌ 不支持	CASCADE / SET NULL 等

[!question] 为什么 uint 在 PG 中变成 BIGINT？ Go 的 uint 在 64 位系统上是 8 字节（与 int64 同宽），而 MySQL 有独立的 INT UNSIGNED 正好对齐。但 PostgreSQL 没有无符号整数类型，所以 GORM 将其映射为最大的匹配类型 BIGINT。这就引出了一个问题：如果你的代码中写了 uint，迁移到 PG 后会不会出现溢出？ 答案是：只要数据范围在 BIGINT 内就没问题，但如果业务依赖的是 32 位上限，就需要改用 uint32。

CREATE TABLE 实际输出对比

同一个 struct 在不同数据库中生成的建表语句差异很大：

type User struct {
    ID        uint      `gorm:"primaryKey;autoIncrement"`
    Name      string    `gorm:"size:64;not null"`
    Age       int       `gorm:"not null;default:0"`
    CreatedAt time.Time `gorm:"autoTime"`
}

数据库	实际建表语句摘要
MySQL	id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(64) NOT NULL, age INT NOT NULL DEFAULT 0, created_at DATETIME
PostgreSQL	id BIGSERIAL PRIMARY KEY, name VARCHAR(64) NOT NULL, age INT NOT NULL DEFAULT 0, created_at TIMESTAMP WITH TIME ZONE
SQLite	id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, age INTEGER NOT NULL DEFAULT 0, created_at TEXT

[!warning] autoTime 的隐藏机制 autoTime tag 在 SQLite 中的表现尤其值得注意：因为 SQLite 没有原生的 DATETIME 类型，GORM 会把 time.Time 序列化为 RFC 3339 格式的字符串存入 TEXT 列。读出来的时候再反序列化回来。这意味着你在 SQLite 中无法使用数据库层面的时间函数（如 WHERE created_at > '2024-01-01' 来利用索引）。

AutoMigrate 跨数据库的注意事项

// MySQL 下执行迁移
err := db.AutoMigrate(&User{}, &Order{})

// PostgreSQL 下执行同样的迁移
pgDB, _ := gorm.Open(postgres.Open(pgDSN), &gorm.Config{})
err = pgDB.AutoMigrate(&User{}, &Order{})
// 注意：同样一个 User struct，在 PG 中会自动用 BIGSERIAL 而非 AUTO_INCREMENT

[!warning] AutoMigrate 的本质局限 AutoMigrate 的设计原则是 "只加不改"——它能新增表和新增列，但无法修改已有列的结构（比如改列名、改类型、改约束）。这在任何数据库中都一样，但在 SQLite 下表现得最极端：SQLite 根本不支持 ALTER TABLE 的大部分操作，所以 AutoMigrate 实际上只能新建一张表然后把旧数据搬过来。

最佳实践：使用专门的迁移工具（Goose、golang-migrate、Migration），手写版本化的 SQL 脚本。这样你可以精确控制每个版本的迁移和回滚，而不是依赖 AutoMigrate 的黑盒行为。

查询语法差异

LIMIT / OFFSET 分页

// 标准分页写法——GORM 会自动处理底层方言差异
db.Limit(10).Offset(20).Find(&users)

// 底层翻译后的 SQL：
// MySQL:     SELECT * FROM users LIMIT 10 OFFSET 20
// PostgreSQL: SELECT * FROM users LIMIT 10 OFFSET 20
// SQLite:    SELECT * FROM users LIMIT 10 OFFSET 20
// SQL Server: SELECT * FROM users ORDER BY id OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY

[!important] SQL Server 分页的性能陷阱 老版本的 GORM 驱动会把 SQL Server 的分页转换为子查询方案（TOP N WHERE id NOT IN (SELECT TOP M ...)），在大数据量下性能较差。升级到最新版驱动后已改用 OFFSET FETCH 标准语法。升级前务必确认你用的驱动版本 ≥ v1.5.0。

UUID 与原生函数

不同数据库生成 UUID 的方式完全不同，GORM 只能做基本映射，具体的默认值必须由你指定：

type Order struct {
    ID   uuid.UUID `gorm:"type:uuid;default:gen_random_uuid()"` // PostgreSQL：内置函数 gen_random_uuid()
    // MySQL 要用 type:char(36);default:(UUID())
    // SQL Server 要用 type:uniqueidentifier;default:newid()
    // SQLite 需要用 Hook 或在 Go 层生成
}

[!tip] SQLite 下的 UUID 生成方案 由于 SQLite 没有内置 UUID 函数，推荐的两种方式：

1. Go 层生成：在 BeforeCreate Hook 中用 github.com/google/uuid 生成
2. 触发器：用 SQLite 的 BEFORE INSERT TRIGGER 自动生成

func (o *Order) BeforeCreate(tx *gorm.DB) error {
    if o.ID == uuid.Nil {
        o.ID = uuid.New()
    }
    return nil
}

软删除与唯一索引

这是最隐蔽的一个坑——MySQL InnoDB 引擎在处理软删除（DeletedAt 字段）时，唯一约束不会自动排除已软删除的行。换句话说：

type Product struct {
    gorm.Model
    SKU string `gorm:"uniqueIndex"`
}

// 假设 SKU="ABC" 的记录被软删除了
// 此时你还能再次插入 SKU="ABC" 的新记录吗？
// MySQL: ✅ 可以（唯一的 bug 行为——软删除行不参与唯一约束检查）
// PG:    ❌ 不可以（正确行为——唯一约束包含软删除行）

[!danger] MySQL 软删除唯一约束 Bug 如果你用了软删除 + 唯一索引，在 MySQL 下可能出现"同一 SKU 多条有效记录"的数据不一致问题。

解决方案：

1. 用复合唯一索引：uniqueIndex:idx_sku_active，并在查询时总是带上 DeletedAt 条件
2. 或者换用 PG/SQL Server——它们的行为是正确的

高级用法

多数据库连接管理

生产环境中通常需要同时连接多个数据库（比如 MySQL 存业务数据、Redis 做缓存、ES 做搜索），以下是常见模式：

var (
    masterDB *gorm.DB // 主库
    slaveDB  *gorm.DB // 从库 / 其他数据库
)

func initMultiDB() error {
    var err error
    
    masterDB, err = gorm.Open(mysql.Open(os.Getenv("MASTER_DSN")), &gorm.Config{
        Logger: logger.Default.LogMode(logger.Info),
    })
    if err != nil {
        return fmt.Errorf("master db: %w", err)
    }

    slaveDB, err = gorm.Open(postgres.Open(os.Getenv("SLAVE_DSN")), &gorm.Config{
        Logger: logger.Default.LogMode(logger.Silent),
    })
    if err != nil {
        return fmt.Errorf("slave db: %w", err)
    }

    // 配置连接池（两种数据库都可以用 DB.SqlDB() 访问底层 *sql.DB）
    sqlDB, _ := masterDB.DB()
    sqlDB.SetMaxOpenConns(50)
    sqlDB.SetMaxIdleConns(10)
    sqlDB.SetConnMaxLifetime(time.Hour)

    return nil
}

[!tip] 连接池调优经验值

• MaxOpenConns：根据 QPS × 平均查询耗时估算。一般 Web 应用 20~100 足够
• MaxIdleConns：设为 MaxOpenConns 的 10%~25%，过多空闲连接会浪费资源
• ConnMaxLifetime：建议设 1 小时，避免与数据库侧的连接超时策略冲突

环境自适应连接

func newDB(env string) (*gorm.DB, error) {
    var driverFunc func(string) gorm.Dialector
    
    switch env {
    case "dev":
        driverFunc = func(dsn string) gorm.Dialector {
            return sqlite.Open(dsn)
        }
    default:
        driverFunc = func(dsn string) gorm.Dialector {
            return postgres.Open(dsn)
        }
    }
    
    dsn := map[string]string{
        "dev":   "file:test_dev.db?cache=shared",
        "staging": os.Getenv("DATABASE_URL"),
        "prod":  os.Getenv("PROD_DATABASE_URL"),
    }[env]
    
    return gorm.Open(driverFunc(dsn), &gorm.Config{
        Logger: ternary(env == "prod", logger.Default.LogMode(logger.Silent), logger.Default),
    })
}

func ternary[T any](cond bool, a, b T) T {
    if cond { return a }; return b
}

多数据库事务

当需要在一个事务中操作多个数据库时，GORM 本身不提供分布式事务支持，但可以分别管理各自的事务：

// 分别在不同的 db 实例上开启事务
tx1 := masterDB.Begin()
tx2 := slaveDB.Begin()

// 独立提交
if err := tx1.Create(&product).Error; err != nil {
    tx1.Rollback()
    tx2.Rollback() // 两个都需要回滚
    return err
}
if err := tx2.Create(&auditLog).Error; err != nil {
    tx1.Rollback()
    tx2.Rollback()
    return err
}

tx1.Commit()
tx2.Commit()

[!important] 跨数据库事务不是 ACID 的 上面的模式叫做 "两阶段提交"的非正式实现——本质上两个事务是独立的。如果 tx1 成功但 tx2 失败，你就有了数据不一致状态。真正的分布式事务需要使用 XA 协议或 Saga 模式，但这超出了 GORM 的能力范围。

建议：能在一个数据库内完成的操作就不要跨库，减少一致性复杂度。

最佳实践总结

数据库选型决策矩阵

场景	推荐数据库	理由
快速原型 / CLI 工具	SQLite	零配置，单文件
个人项目 / 博客	PostgreSQL	免费、功能全、JSONB 强大
企业级业务系统	MySQL / PostgreSQL	社区成熟，生态丰富
Windows 技术栈企业	SQL Server	Active Directory 集成好

开发环境 vs 生产环境

[!tip] 为什么推荐开发用 SQLite？

• 零配置：不需要启动任何数据库服务，go run 即可
• 单文件：方便分享测试数据集，CI/CD 中直接用内存数据库
• 语法兼容性：大部分标准 SQL 都能工作

但请记住：SQLite 不能替代生产数据库做压力测试——它不支持行级锁、事务隔离级别可调、复杂聚合优化器等关键特性。开发用 SQLite 验证逻辑，上线前必须在真实数据库上做一轮完整回归测试。

防坑 Checklist

在准备多数据库部署时，逐项核对：

• 所有 time.Time 字段的时区设置是否已明确
• 是否避免了 uint 类型（改用 int / int64 降低迁移风险）
• 软删除 + 唯一索引的场景是否在目标数据库上过测
• 自定义 SQL（db.Raw()）是否做了方言检查
• AutoMigrate 之外是否有版本化的迁移脚本
• 连接池参数是否针对生产环境调优
• 是否在所有目标数据库上都跑过完整的 CI 测试

关联笔记

• 01-安装与初始化
• 02-模型定义
• 17-迁移工具