SQLite 在 Go 生态中通常承担嵌入式存储、本地缓存或轻量级服务的数据层角色。它不需要独立服务进程，一个文件即可承载完整数据库，但这也意味着所有并发访问都集中到同一个文件上。如果直接沿用 MySQL 那套连接池配置，上线后很容易连续出现 database is locked 或 SQLITE_BUSY 报错。下面围绕驱动选择、连接参数、事务控制、类型扫描和并发配置展开，把关键细节一次说清楚。

一、驱动选型与初始化连接时容易忽略的两个开关

在 Go 里连接 SQLite 首先面临驱动选择。目前社区使用最多的是 mattn/go-sqlite3 和 modernc.org/sqlite。前者基于 CGO，底层调用 SQLite 官方 C 库，功能完整、性能稳定，但编译时需要本机安装 C 编译器，交叉编译相对麻烦。后者是纯 Go 实现，不依赖 CGO，跨平台编译非常顺畅，适合对部署环境要求简单的项目，不过在极端写入负载下性能略逊于 CGO 方案。对于大多数入门和中小型应用，modernc.org/sqlite 已经够用，省去不少环境配置成本。

选定驱动后，初始化连接不能只写一句 sql.Open 就结束。SQLite 的很多行为都由 PRAGMA 控制，而默认值并不适合并发写入场景。最常见的有三个：journal_mode、busy_timeout 和 foreign_keys。journal_mode 默认是 delete 模式，改为 WAL 后读写可以并发推进，写操作不会长时间阻塞读；busy_timeout 决定遇到锁时的等待时间，默认可能直接返回 SQLITE_BUSY；foreign_keys 默认关闭，如果建了外键却不生效，很容易产生脏数据。可以创建连接后执行这些配置。

下面是一个初始化连接的示例，使用 modernc.org/sqlite 驱动，并通过 Exec 设置 PRAGMA：

package main
import (
    "database/sql"
    "log"
    _ "modernc.org/sqlite"
)
func initDB(path string) (*sql.DB, error) {
    db, err := sql.Open("sqlite", path)
    if err != nil {
        return nil, err
    }
    // 单写场景建议将最大连接数设为 1，避免写锁竞争
    db.SetMaxOpenConns(1)
    pragmas := []string{
        "PRAGMA journal_mode=WAL;",
        "PRAGMA busy_timeout=5000;",
        "PRAGMA foreign_keys=ON;",
        "PRAGMA synchronous=NORMAL;",
    }
    for _, p := range pragmas {
        if _, err := db.Exec(p); err != nil {
            db.Close()
            return nil, err
        }
    }
    return db, nil
}

busy_timeout 也可以在 DSN 中通过 _busy_timeout 参数传入，但通过 PRAGMA 更直观。如果使用 CGO 驱动，驱动名是 sqlite3，DSN 直接写文件路径即可，例如 sql.Open("sqlite3", "./data.db")。纯 Go 驱动名通常是 sqlite。连接池大小 SetMaxOpenConns(1) 只在写多场景推荐，如果全是读，可以适当调大。

二、写入与事务：为什么单条插入那么慢

SQLite 的写入性能高度依赖事务的使用方式。如果没有显式开启事务，每条 INSERT 语句默认都在自己的事务中执行，SQLite 会在每次提交时同步数据到磁盘。这意味着插入一万条数据会执行一万次磁盘同步，耗时可能从几秒变成几分钟。正确的做法是把批量写入放进一个事务中，SQLite 在事务提交时才做一次同步，性能差距非常明显。

使用 database/sql 的标准事务接口可以轻松做到这一点。先调用 db.Begin 获取事务对象，然后在事务内创建预处理语句，循环执行插入，最后统一提交。需要注意，如果中间出错必须回滚，否则连接不会自动释放。下面是一个批量插入的完整示例：

func batchInsert(db *sql.DB, users []User) error {
    tx, err := db.Begin()
    if err != nil {
        return err
    }
    defer tx.Rollback()
    stmt, err := tx.Prepare("INSERT INTO users(name, age) VALUES(?, ?)")
    if err != nil {
        return err
    }
    defer stmt.Close()
    for _, u := range users {
        if _, err := stmt.Exec(u.Name, u.Age); err != nil {
            return err
        }
    }
    return tx.Commit()
}

这个示例中 defer tx.Rollback 非常关键。事务提交成功后，defer 调用的 Rollback 会返回 ErrTxDone，但不会影响已经提交的数据；如果函数中途返回错误，Rollback 会确保事务被回滚。Prepare 语句放在事务内部也能减少重复解析 SQL 的开销。

另一个容易踩的坑是忘记检查 tx.Commit 的返回值。有些人写完代码后直接 return nil，导致事务没有真正提交也不会被发现。务必把 return tx.Commit() 作为最后一步，并且上层调用要处理返回的 error。

三、查询与 Scan：动态类型带来的几个疑问

SQLite 与 MySQL、PostgreSQL 最大的不同之一就是动态类型。建表时声明的列类型只是亲和性建议，实际存储的值可以不同类型。例如一个 age 列声明为 INTEGER，但你可以插入文本，SQLite 不会强制转换。读取时，database/sql 的 Scan 会把整数值扫描到 int64，浮点数扫描到 float64，文本扫描到 string，NULL 扫描不到任何类型，需要特殊处理。这种灵活性带来了便利，也让初学者经常遇到 scan 类型错误。

先看一个简单查询示例：

func queryUsers(db *sql.DB) ([]User, error) {
    rows, err := db.Query("SELECT id, name, age FROM users ORDER BY id")
    if err != nil {
        return nil, err
    }
    defer rows.Close()
    var users []User
    for rows.Next() {
        var u User
        var age int64
        if err := rows.Scan(&u.ID, &u.Name, &age); err != nil {
            return nil, err
        }
        u.Age = int(age)
        users = append(users, u)
    }
    return users, rows.Err()
}

这个例子中 user.Name 如果数据库中该列可能为 NULL，直接 Scan 到 string 会报错。正确做法是使用 sql.NullString，或者建表时给默认值。例如 var name sql.NullString，扫描后判断 name.Valid 再赋值。同样，整型如果可能为空，应使用 sql.NullInt64。时间字段通常存储为 RFC3339 文本或 Unix 时间戳整数，读取后手动转换，因为 database/sql 不会自动处理 time.Time 与 SQLite 的映射。

查询完成后必须调用 rows.Err 检查遍历过程中是否发生错误。很多人只判断 rows.Next 循环结束就返回，忽略了最后可能因为锁超时导致 rows 提前中断的情况。在 SQLite 本地文件中，这种情况较少，但一旦出现锁等待超时，rows.Err 会返回 SQLITE_BUSY，需要业务层重试或提示。

四、并发读写与连接池：为什么写多读少也要小心

SQLite 的并发模型是文件级锁。在 WAL 模式下，读写可以同时进行：读操作看到的是事务开始时的快照，写操作写入 WAL 文件，不会阻塞正在进行的读。但写写仍然是串行的，同一时刻只能有一个写事务。所以如果应用写入频繁，盲目增大连接池并不会提升吞吐，反而会增加锁竞争和 database is locked 错误。

因此，在写多读少的场景，最稳妥的配置是把最大连接数设为 1。这样所有数据库操作都通过同一个连接串行执行，避免多个连接同时尝试写入。但代价是可能降低读的并发能力，不过对于小型服务来说，通常单连接已经足够。如果读远多于写，可以保留多个读连接并配合 WAL 模式，但要注意 database/sql 连接池无法区分读写连接，写操作仍然可能分配到不同连接上。

下面给出一个比较适合本地小服务的连接池配置：

func configurePool(db *sql.DB) {
    // 单写场景：限制为 1，避免并发写锁冲突
    db.SetMaxOpenConns(1)
    db.SetMaxIdleConns(1)
    db.SetConnMaxLifetime(time.Hour)
}

如果使用多连接只读，可尝试 db.SetMaxOpenConns(4)，但前提是所有写操作都通过显式事务并且业务层做了重试。否则一旦某个连接持有写锁，其他连接发起的写请求会等待 busy_timeout 后报错。很多 database is locked 问题就源于连接池中闲置连接未及时释放，导致写操作被分配到一个已经处于事务中的连接。

SQLite 在 Go 项目中的要点可以归纳为：选择合适的驱动、初始化时设置 WAL 和 busy_timeout、批量写入必须使用事务、Scan 处理动态类型和 NULL、根据读写比例调整连接池。掌握这几点，基本能避开大多数入门阶段的坑。