仅在PHPUnit测试中出现SQLite数据库锁定问题的求助

问题背景 #

应用使用SQLite时运行完全正常，但在PHPUnit测试场景下，首次执行写入操作就触发数据库锁定。尝试手动调用beginTransaction()和commit()管理事务，结果在commit()时直接挂起。相同的建表、写入、读取逻辑，放到普通PHP环境执行毫无问题。

测试核心代码片段：

$kv->select(self::MOVIE_TABLE_NAME);
$title = "Rainman";
$movie = $kv->get(1);
$this->assertNull($movie);
$kv->set(['imdb_id' => 1, 'name' => $title, 'year' => 1985], 1);

set方法核心实现（预编译语句已做缓存处理）：

$statement = $this->db->prepare("
    INSERT OR REPLACE INTO $tableName($keyName, value)
        VALUES(:key, :value)
");
$results = $statement->execute(
[
    'key' => $key,
    "value" => json_encode($value)
]);

添加以下配置后，测试终于可以正常通过：

$this->db->query("PRAGMA journal_mode=WAL");
$this->db->query("PRAGMA lock_timeout=5");
$this->db->setAttribute(PDO::ATTR_TIMEOUT, 10);

问题根源 #

1. PHPUnit连接/事务特性：PHPUnit默认会在测试流程中保持数据库连接，若测试用例复用连接，前一个测试未释放的结果集、未提交的隐式事务会残留，导致后续写入操作无法获取锁。
2. SQLite默认锁机制：默认DELETE日志模式下，写入操作需要独占锁，且锁会持续到事务结束。PHPUnit测试环境中，连接的生命周期比普通PHP请求长，更容易出现锁占用未释放的情况。
3. 隐式事务影响：PDO SQLite默认开启自动提交，但部分操作（比如批量写入）会触发隐式事务，若测试中未显式提交/回滚，锁会一直持有。

解决方案验证与优化 #

你添加的配置是针对性的有效方案：

• PRAGMA journal_mode=WAL：将日志模式切换为WAL，这是SQLite推荐的生产级写入模式，支持读写并发——读操作无需等待写锁，写操作也不会阻塞读，从根源上降低锁冲突概率，不仅适用于测试，生产环境也建议启用。
• PRAGMA lock_timeout=5：设置锁等待超时（单位为毫秒），当无法获取锁时直接抛出异常，避免测试无限挂起，方便快速定位问题。
• PDO::ATTR_TIMEOUT：设置PDO层的超时时间，作为上层兜底，防止底层锁等待导致测试卡死。

额外优化建议 #

1. 测试用例隔离：每个测试用例使用独立数据库连接，或在tearDown()中显式关闭连接、回滚事务：

protected function tearDown(): void
{
    if ($this->db->inTransaction()) {
        $this->db->rollBack();
    }
    $this->db = null;
}

2. 显式事务管理：在测试的写入逻辑前后，显式开启和提交事务，避免隐式事务的不确定性：

$this->db->beginTransaction();
$kv->set(['imdb_id' => 1, 'name' => $title, 'year' => 1985], 1);
$this->db->commit();

3. 使用内存数据库：单元测试优先用SQLite内存库（:memory:），每个测试用例的数据库完全独立，彻底避免文件锁问题，测试速度也更快：

$this->db = new PDO('sqlite::memory:');

结论 #

当前的解决方案是正确且有效的，尤其是启用WAL模式，直接改善了SQLite的锁机制。结合测试用例隔离措施，可以彻底解决PHPUnit测试中的SQLite锁定问题。

内容的提问来源于stack exchange，提问作者Tac Tacelosky