PHP SQLite3::backup 怎么把内存数据库复制到文件

我在做一次“先用内存库准备数据，再把结果落盘”的小任务时，最容易写错的地方不是 SQL，而是把源连接和目标连接混在一起。PHP 的 SQLite3::backup() 已经直接提供了这条复制路径：源连接调用方法，传入一个已经打开的目标连接，目标数据库的内容会被源数据库覆盖。

官方地址：https://www.php.net/manual/en/sqlite3.backup.php

把内存库复制到文件的关键是准备两个 SQLite3 对象：源对象打开 :memory:，目标对象打开文件名，然后调用 $source->backup($destination)。返回 true 后再关闭两个连接。

先把源库和目标库分成两个连接

backup() 的参数不是文件路径，而是一个已经通过 SQLite3 打开的目标连接。因此，我会把“数据从哪里来”和“文件写到哪里”分别命名，避免把方法方向写反。

exec('CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT)');
$source->exec("INSERT INTO notes (body) VALUES ('来自内存库')");

// 目标连接指向持久化文件；文件不存在时由 SQLite 创建。
$destination = new SQLite3(__DIR__ . '/notes.sqlite');

// backup() 会把源数据库复制到目标数据库的 main 库。
$ok = $source->backup($destination);
if (!$ok) {
    // 失败时同时读取两个连接的错误信息，便于定位是哪一侧出问题。
    $sourceError = $source->lastErrorMsg();
    $destinationError = $destination->lastErrorMsg();
    $source->close();
    $destination->close();
    throw new RuntimeException("备份失败：源={$sourceError}；目标={$destinationError}");
}

// 复制完成后再关闭连接，避免目标文件仍被当前进程占用。
$source->close();
$destination->close();

这里的核心关系是：$source 是调用者，$destination 是传入的目标对象。官方手册将返回值定义为成功时 true、失败时 false；它不会返回一个新的数据库连接。

理解 backup 的覆盖行为，别把它当增量合并

我第一次整理这段代码时，曾经下意识地把目标文件理解成“接收新增记录的容器”。实际语义更直接：backup() 会把一个数据库的内容复制到另一个数据库，并覆盖目标数据库的内容。

因此，目标文件里原先存在的表和数据不能当作会自动保留的增量层。要是目标文件需要保留历史数据，就应先在业务层决定合并策略，不能指望 backup() 替你做记录级合并。对于本文的内存库落盘场景，最清晰的前提是：目标文件就是这次备份的接收副本。

可以把两端的职责记成下面这张表：

备份成功后怎样处理关闭和错误

这个任务通常很短，但关闭顺序仍值得固定下来：先判断返回值，再关闭源连接和目标连接。失败分支也要关闭已经打开的对象，避免异常路径留下资源。

如果目标文件无法写入、连接状态不适合备份，或者 SQLite 层拒绝了操作，backup() 会返回 false。我更倾向于在失败分支同时记录 lastErrorMsg()，然后把连接关闭，再把错误交给上层；这样不会把“备份失败”和“文件仍被占用”混成两个问题。

backup($destination)) {
        throw new RuntimeException($source->lastErrorMsg());
    }
} finally {
    // 无论成功还是失败，都释放源连接和目标连接。
    $source->close();
    $destination->close();
}

这段写法的价值不在于多写了几行，而在于把资源生命周期放到了复制操作的外层：backup() 只负责复制，try/finally 负责收尾。

ATTACH 数据库和并发写入时要多看一眼

默认情况下，源库和目标库都使用名称 main。如果连接中通过 ATTACH ... AS archive 挂载了其他数据库，才需要用 sourceDatabase 和 destinationDatabase 指定对应名称；这两个参数描述的是数据库名，不是文件路径。

另外，本文的模式适合“准备好内存数据后复制到文件”的明确边界。它不等价于为一个持续高并发写入的在线系统自动制作一致性快照。若复制期间还有其他代码修改源库或目标库，应先设计调用时机、写入互斥和失败重试，否则即使方法调用返回了结果，也不能把它解释成完整的业务事务。

最后回到最小答案：创建内存源连接，创建文件目标连接，调用 $source->backup($destination)，判断布尔返回值，最后关闭两端。目标连接不是路径字符串，备份也不是增量合并。

常见问题

SQLite3::backup() 能不能直接传文件路径？

不能。参数要求的是已经打开的 SQLite3 目标连接；先用文件名创建目标对象，再把对象传入。

目标文件原来的数据会自动保留吗？

不能按增量合并来理解。官方定义是覆盖目标数据库内容；需要保留历史记录时，应另行设计业务合并。

为什么不直接使用 VACUUM INTO？

VACUUM INTO 是 SQLite 提供的另一条备份路径，而本文只讨论 PHP SQLite3::backup() 在内存连接与持久化连接之间的复制方式。两者不要混成同一个参数模型。