Sqlite使用WAL模式指南

一、WAL模式初步介绍

1.1 什么情况需要开启WAL

开启SQLite的WAL模式（Write-Ahead-Log），多线程的并发性将得到进一步的提升。

此时写操作会先append到wal文件末尾，而不是直接覆盖旧数据。而读操作开始时，会记下当前的WAL文件状态，并且只访问在此之前的数据。这就确保了多线程读与读、读与写之间可以并发地进行。

1.2 WAL模式的原理

在引入WAL机制之前，SQLite使用rollback journal机制实现原子事务。

rollback journal机制的原理是：在修改数据库文件中的数据之前，先将修改所在分页中的数据备份在另外一个地方，然后才将修改写入到数据库文件中；如果事务失败，则将备份数据拷贝回来，撤销修改；如果事务成功，则删除备份数据，提交修改。

WAL机制的原理是：修改并不直接写入到数据库文件中，而是写入到另外一个称为WAL的文件中；如果事务失败，WAL中的记录会被忽略，撤销修改；如果事务成功，它将在随后的某个时间被写回到数据库文件中，提交修改。

• 同步WAL文件和数据库文件的行为被称为checkpoint（检查点），它由SQLite自动执行，默认是在WAL文件积累到1000页修改的时候；当然，在适当的时候，也可以手动执行checkpoint，SQLite提供了相关的接口。执行checkpoint之后，WAL文件会被清空。
• 在读的时候，SQLite将在WAL文件中搜索，找到最后一个写入点，记住它，并忽略在此之后的写入点（这保证了读写和读读可以并行执行）；随后，它确定所要读的数据所在页是否在WAL文件中，如果在，则读WAL文件中的数据，如果不在，则直接读数据库文件中的数据。
• 在写的时候，SQLite将之写入到WAL文件中即可，但是必须保证独占写入，因此写写之间不能并行执行。
• WAL在实现的过程中，使用了共享内存技术，因此，所有的读写进程必须在同一个机器上，否则，无法保证数据一致性。

1.3 如何开启WAL

1.3.1 日志模式的类型

PRAGMA journal_mode 是一个 SQLite 命令，用于查询或更改数据库的日志模式。日志模式决定了 SQLite 如何处理事务和保证数据的一致性。

以下是一些可以设置的日志模式：

• DELETE：这是默认模式。在这种模式下，日志文件（也称为回滚日志）在每个事务结束时都会被删除。
• TRUNCATE：与 DELETE模式类似，但是在事务结束时，日志文件不是被删除，而是被截断为零长度。这种模式的性能通常比 DELETE 模式稍好一些。
• PERSIST：在这种模式下，日志文件在事务结束时不会被删除或截断。相反，它会被保留并用于下一个事务。这种模式的性能通常比TRUNCATE 模式稍好一些。但是PERSIST可能会影响secure_delete的设置。
• MEMORY：在这种模式下，日志文件被存储在内存中，而不是在磁盘上。这种模式的性能最好，但是如果系统崩溃，所有未提交的事务都会丢失。
• WAL：这是 Write-Ahead Logging 模式。在这种模式下，所有的更改首先被写入到一个单独的日志文件（WAL文件），然后在事务提交时被写入到主数据库文件。这种模式提供了最好的并发性能。

1.3.2 日志模式的SQLite命令

可以使用 PRAGMA journal_mode 命令来查询或更改日志模式，例如：

• 查询日志模式：PRAGMA journal_mode;
• 更改日志模式：PRAGMA journal_mode=WAL;

需要注意的是，更改日志模式会影响所有的数据库连接，而且只有在数据库没有被 其他连接使用时才能更改。

二、开启WAL后必须要设置的参数

  ptr->execute("PRAGMA journal_mode = WAL");
  ptr->execute("PRAGMA wal_autocheckpoint=5000;");
  ptr->execute("PRAGMA SYNCHRONOUS=NORMAL");

  if (sqlite3_busy_timeout(connection, 20 * 1000) != SQLITE_OK) {
    LOG(ERROR) << "config busy timeout fail, db_path: " << db_path;
  } else {
    LOG(INFO) << "config busy timeout success, db_path: " << db_path;
  }

2.1 设置SYNCHRONOUS

ptr->execute("PRAGMA SYNCHRONOUS=NORMAL");

2.1.1 SYNCHRONOUS的类型

PRAGMA synchronous 是一个 SQLite 命令，用于控制数据库文件在磁盘上的写入同步级别。这个设置会影响到数据的持久性和性能。PRAGMA synchronous 有以下几个级别：

OFF (0)：同步关闭。SQLite 不会等待操作系统将数据写入磁盘。这种模式下，性能最高，但在系统崩溃或电源故障时，可能会导致数据库损坏或数据丢失。

NORMAL (1)：普通同步。SQLite 会在某些关键操作（如事务提交）时等待操作系统将数据写入磁盘。这种模式下，性能较好，但在某些罕见的情况下，仍然可能导致数据库损坏。

FULL (2)：完全同步（默认）。SQLite 会在关键操作时确保数据已经写入磁盘。这种模式下，数据的持久性得到了保证，但性能可能较低。

EXTRA (3)：额外同步。这个级别类似于 FULL，但会在某些额外的操作时进行同步，以提供更高的数据持久性保证。这种模式下，性能可能会进一步降低。

2.1.2 WAL下如何选择SYNCHRONOUS类型

Sqlite默认是FULL，虽然是最安全的，但是在wal下性能较差，根据官方文档，建议使用NORMAL。

官方文档链接：pragma_synchronoushttps://sqlite.org/pragma.html#pragma_synchronous

NORMAL (1) When synchronous is NORMAL (1), the SQLite database engine will still sync at the most critical moments, but less often than in FULL mode. There is a very small (though non-zero) chance that a power failure at just the wrong time could corrupt the database in journal_mode=DELETE on an older filesystem. WAL mode is safe from corruption with synchronous=NORMAL, and probably DELETE mode is safe too on modern filesystems. WAL mode is always consistent with synchronous=NORMAL, but WAL mode does lose durability. A transaction committed in WAL mode with synchronous=NORMAL might roll back following a power loss or system crash. Transactions are durable across application crashes regardless of the synchronous setting or journal mode. The synchronous=NORMAL setting is a good choice for most applications running in WAL mode.

In WAL mode when synchronous is NORMAL (1), the WAL file is synchronized before each checkpoint and the database file is synchronized after each completed checkpoint and the WAL file header is synchronized when a WAL file begins to be reused after a checkpoint, but no sync operations occur during most transactions. With synchronous=FULL in WAL mode, an additional sync operation of the WAL file happens after each transaction commit. The extra WAL sync following each transaction helps ensure that transactions are durable across a power loss. Transactions are consistent with or without the extra syncs provided by synchronous=FULL. If durability is not a concern, then synchronous=NORMAL is normally all one needs in WAL mode. 在WAL模式下，当同步为NORMAL (1)时，WAL文件在每个检查点之前同步，数据库文件在每个完成的检查点之后同步，当一个检查点后WAL文件开始被重用时，WAL文件头同步，但在大多数事务期间不发生同步操作。在WAL模式下，synchronous=FULL会在每次事务提交后额外同步WAL文件。每次事务后额外的WAL同步有助于确保事务在电源中断后是持久的。不论是否有synchronous=FULL提供的额外同步，事务都是一致的。如果不考虑持久性，那么在WAL模式下，通常只需要synchronous=NORMAL。

2.2 设置checkpoint

2.2.1 PRAGMA wal_autocheckpoint

  ptr->execute("PRAGMA wal_autocheckpoint=5000;");

pagesize默认设置的是4k，autocheckpoint设置5000，表示5000个page的数据量，会进行一下checkpoint，也就是20M。

2.2.2 sqlite3_wal_checkpoint_v2

如果只设置了wal_autocheckpoint，WAL文件还是可能由于以下的原因一直增加：

1. 有未完成的读事务。在SQLite中，只有当所有的读事务都完成后，checkpoint才能将WAL文件中的修改应用到主数据库文件中。如果有一个读事务一直没有完成，那么即使WAL文件的大小超过了wal_autocheckpoint的值，checkpoint也无法进行。我们可以通过PRAGMA database_list;命令查看当前的读事务。
2. 应用程序在进行大量的写操作。如果应用程序在短时间内进行了大量的写操作，那么即使设置了wal_autocheckpoint，WAL文件的大小也可能会迅速增加。

由于以上原因，所以还需要定时调用sqlite3_wal_checkpoint_v2，主动回写WAL：

1. 对于未完成的读事务：sqlite3_wal_checkpoint_v2函数有一个模式参数，如果我们将这个参数设置为SQLITE_CHECKPOINT_RESTART或者SQLITE_CHECKPOINT_TRUNCATE，那么即使有未完成的读事务，checkpoint操作也会尽可能地将WAL文件中的修改应用到主数据库文件中。但是请注意，这并不意味着可以忽视未完成的读事务，因为未完成的读事务仍然会阻止WAL文件被完全清空。
2. 对于大量的写操作：sqlite3_wal_checkpoint_v2函数可以在任何时候手动触发checkpoint操作，因此我们可以在预期会有大量写操作的情况下，提前或者频繁地调用这个函数，以减小WAL文件的大小。但是请注意，频繁地进行checkpoint操作可能会影响数据库的性能，因此我们需要在WAL文件的大小和数据库性能之间找到一个平衡。

我们的实现如下，在释放数据库连接的时候，同时检查wal文件的大小，如果超过20M，则主动调用一次sqlite3_wal_checkpoint_v2

    auto current_time = GetCurrentTimeInSeconds();
    int64_t file_size = 0;
    base::GetFileSize(base::FilePath(item.using_db_path + "-wal"), &file_size);
    if ((file_size > 20 * 1024 * 1024) || (current_time - item.last_check_point_time_in_seconds > 5 * 60)) {
        item.connection->Checkpoint();
        item.last_check_point_time_in_seconds = GetCurrentTimeInSeconds();
    }

void WWConnection::Checkpoint() {
  if (!GetDataBase())
    return;

  int pnLog = 0;
  int pnCkpt = 0;
  auto rc = sqlite3_wal_checkpoint_v2(GetDataBase(), NULL, SQLITE_CHECKPOINT_TRUNCATE, &pnLog, &pnCkpt);
  if (rc == SQLITE_OK) {
    LOG(INFO) << "[WWConnection::Checkpoint] PASSIVE file:" << wwDBPath << " pnLog:" << pnLog << " pnCkpt:" << pnCkpt;
  }
  else {
    LOG(WARNING) << "[WWConnection::Checkpoint] PASSIVE file:" << wwDBPath << " rc:" << rc;
  }
}

2.3 设置sqlite3_busy_timeout

2.3.1 产生busy的原因

在 SQLite 的 WAL（Write-Ahead Logging）模式下，"busy" 错误通常是由于多个连接试图同时访问数据库时发生的。以下是一些可能导致 "busy" 错误的情况：

1. 写入冲突：当一个连接正在执行写操作（如 INSERT、UPDATE 或 DELETE）时，其他连接试图执行写操作或读取尚未提交的数据。在这种情况下，其他连接会收到 "busy" 错误。WAL 模式允许多个读取器与一个写入器并发访问数据库，但不允许多个写入器同时进行。
2. 检查点操作：在 WAL 模式下，所有的更改首先被写入到一个单独的日志文件（WAL 文件），然后在事务提交时被写入到主数据库文件。当 WAL 文件达到一定大小或者触发某些条件时，SQLite 会执行一个检查点操作，将 WAL 文件中的更改写入主数据库文件。在检查点操作期间，如果其他连接试图访问数据库，它们可能会收到 "busy" 错误。
3. 独占操作：某些操作（如 VACUUM、ALTER TABLE 或 PRAGMA journal_mode）需要独占访问数据库。在这些操作期间，其他连接试图访问数据库会收到 "busy" 错误。

2.3.2 解决措施

1. 设置忙等待超时：使用 PRAGMA busy_timeout 命令设置一个超时值（以毫秒为单位）。当连接收到 "busy" 错误时，它会等待指定的时间，然后再次尝试访问数据库。例如，设置忙等待超时为 3000 毫秒（3 秒）：

PRAGMA busy_timeout=3000;

1. 使用互斥锁：在多线程或多进程环境中，使用互斥锁确保同一时间只有一个连接尝试访问数据库。
2. 优化事务：尽量减少事务的持续时间，以减少冲突的可能性。在可能的情况下，将多个操作组合到一个事务中，以减少提交事务的次数。
3. 调整检查点策略：使用 PRAGMA wal_autocheckpoint 命令设置 WAL 文件的自动检查点阈值，或者在适当的时候手动执行检查点操作（PRAGMA wal_checkpoint）。这可以帮助减少检查点操作导致的 "busy" 错误。

三、在多线程读写并发下开启WAL时需要配置的参数

3.1 避免使用PRAGMA locking_mode=EXCLUSIVE

3.1.1 locking_mode的类型

PRAGMA locking_mode=EXCLUSIVE; 是一个 SQLite 命令，用于设置数据库的锁定模式为 Exclusive 模式。SQLite 支持三种锁定模式：

1. NORMAL：在这种模式下，SQLite 在事务开始时获取共享锁，当第一次写入时获取保留锁，当事务提交时获取排他锁。在事务结束后，SQLite 会释放所有的锁。
2. EXCLUSIVE：在这种模式下，SQLite 在事务开始时获取排他锁，并在事务结束后保持该锁。这意味着在事务进行期间，其他数据库连接不能进行读取或写入操作。
3. IMMEDIATE：在这种模式下，SQLite 在事务开始时获取保留锁，并在事务结束后保持该锁。这意味着在事务进行期间，其他数据库连接可以进行读取操作，但不能进行写入操作。

PRAGMA locking_mode=EXCLUSIVE; 这个命令会设置数据库的锁定模式为 Exclusive 模式。这意味着当你开始一个事务时，SQLite 会立即获取一个排他锁，并在事务结束后保持该锁。这可以防止其他数据库连接在你的事务进行期间进行任何操作。

然而，需要注意的是，Exclusive 模式可能会对并发性能产生影响，因为它阻止了其他数据库连接的所有操作。应该根据具体需求和环境来决定是否使用这种模式。

SQLite 的默认锁定模式是 NORMAL。在这种模式下，SQLite 在事务开始时获取共享锁，当第一次写入时获取保留锁，当事务提交时获取排他锁。在事务结束后，SQLite 会释放所有的锁。这种模式允许多个读取操作同时进行，但只允许一个写入操作在同一时间进行。这对于大多数应用来说是足够的，因为读取操作通常比写入操作更频繁。

然而，如果我们需要更高级的并发控制，我们可以使用 PRAGMA locking_mode 命令来改变锁定模式。例如，我们可以设置为 IMMEDIATE 模式或 EXCLUSIVE 模式，这两种模式在事务开始时就获取更高级别的锁，从而提供更严格的并发控制。

3.1.2 使用WAL读写并发时不应该使用EXCLUSIVE的原因

当开启 SQLite 的 WAL (Write-Ahead Logging) 模式后，SQLite 的并发性能会得到显著提升。在 WAL 模式下，多个读取操作和一个写入操作可以同时进行，这是因为写入操作不会阻塞读取操作，反之亦然。

在 WAL 模式下，SQLite 通常使用 NORMAL 锁定模式。在这种模式下，读取和写入操作可以并发进行，这正是 WAL 模式的优势所在。因此，通常情况下，我们不需要改变锁定模式。

然而，如果你有特殊的需求，比如你需要阻止其他连接进行读取或写入操作，你可以使用 PRAGMA locking_mode 命令来改变锁定模式。但是这可能会降低并发性能，因为它可能会阻止其他操作的进行。

开启 WAL 模式后，通常应该使用默认的 NORMAL 锁定模式，除非你有特殊的需求。

3.2 设置SQLITE_CONFIG_MULTITHREAD

3.2.1 SQLite 的三种线程模式

sqlite3_config(SQLITE_CONFIG_MULTITHREAD); 是一个 SQLite C API 的调用，用于设置 SQLite 的线程模式为多线程（multi-threaded）模式。

SQLite 支持三种线程模式：

1. Single-threaded：在这种模式下，SQLite 不会尝试使用任何线程安全机制，所有的操作都应该在同一个线程中进行。
2. Multi-threaded：在这种模式下，SQLite 会使用线程安全机制来允许多个线程同时访问同一个数据库连接。然而，每个数据库连接仍然只能被一个线程在同一时间使用。
3. Serialized：在这种模式下，SQLite 会使用更严格的线程安全机制来允许多个线程同时使用同一个数据库连接。

3.2.2 如何选择线程模式来支持读写并发

sqlite3_config(SQLITE_CONFIG_MULTITHREAD); 这个调用会设置 SQLite 为多线程模式。这意味着我们可以在多个线程中使用 SQLite，但是我们需要确保每个数据库连接在同一时间只被一个线程使用。

注意，这个调用应该在所有的 SQLite 操作之前进行，通常在程序启动时。另外，这个调用可能会失败，例如如果已经在其他地方使用了 SQLite。在这种情况下，需要检查这个调用的返回值来确定它是否成功。

设置 SQLite 为 Serialized 模式并开启 WAL（Write-Ahead Logging）模式，可以实现在多线程环境下的读写并发。在 Serialized 模式下，SQLite 会使用严格的线程安全机制，允许多个线程同时使用同一个数据库连接。这意味着你可以在多个线程中同时进行读取和写入操作，而不需要担心线程安全问题。

同时，开启 WAL 模式可以进一步提高并发性能。在 WAL 模式下，读取操作和写入操作可以同时进行。这是因为在 WAL 模式下，写入操作会被写入到一个单独的 WAL 文件中，而不是直接写入到数据库文件中。这意味着读取操作可以在不被写入操作阻塞的情况下进行。然而，需要注意的是，虽然 WAL 模式允许读取和写入操作同时进行，但是它仍然只允许一个写入操作在同一时间进行。如果你需要多个写入操作同时进行，你可能需要考虑其他的解决方案，如分片或者使用其他的数据库系统。

另外，使用 Serialized 模式和 WAL 模式可能会对性能产生影响，因为它们需要额外的线程同步和磁盘 I/O 操作。你应该根据你的具体需求和环境来决定是否使用这些模式。

四、如何实现SQLite的多线程并发读写

在设置了SQLITE_CONFIG_MULTITHREAD后，为了保持每个数据库连接只能被一个线程在同一时间使用，我们为每条线程分配一个数据库连接，以此保持线程安全。

理论上也可以设置SQLITE_CONFIG_SERIALIZED，在串行模式下，多个线程可以共享同一个数据库连接。然而，为了获得更好的性能和避免潜在的竞争条件，建议在可能的情况下为每个线程创建单独的数据库连接。

我们项目中总共有三种实现多线程读写DB的方式。

4.1 固定一条DB读线程，用来执行高优的读任务，由业务调用点控制是否要使用读线程。

void CSessionStorageService::GetUserListByDepartment(const pb::Department& d, const USER_CALLBACK_TYPE &c, bool top_alphabet, bool asynchronous) {
    auto& b2 = userBackend_;
    auto closure2 = base::BindLambda([=]{ b2->GetUserListByDepartmentTask(d, c, top_alphabet, 0); });
    if (asynchronous) {
        b2->PostTaskToDBReadThread(closure2);
    } else {
        b2->PostTaskToLonelyThread(closure2);
    }
}

缺点：如果想再扩展多条读线程不方便。

4.2 每次使用DB时都执行Open和Close，保证这个连接只被当下的线程使用。

std::unique_ptr<DataBase> DbInterface::InitDB(const std::string& db_path) {
    unique_ptr<DataBase> db = DataBase::Open(db_path, true);
    if (db != nullptr)
    {
      db->registerHook(this);
    }
    return db;
}

• 优点：实现简单安全。
• 缺点：每次都open db增加开销

4.3 以线程ID和DB路径作为key，从连接池中存取连接。

std::pair<std::shared_ptr<WWDBConnection>, std::size_t> WWDBConnectionPool::PickFreeConnection(const std::string& db_path) {

 auto current_thread_id = std::this_thread::get_id();
 boost::optional<std::size_t> picked_index;

 AUTO_LOCK(connection_items_lock_);

 for (std::size_t index = 0; index < connection_items_.size(); ++index) {

  auto& item = connection_items_[index];

  if ((item.using_thread_id == current_thread_id) && (item.using_db_path == db_path)) {
   //返回正在被当前线程使用的连接
   picked_index = index;
   break;
  }
 }

 if (!picked_index) {
  return {};
 }

 auto& picked_item = connection_items_[*picked_index];
 picked_item.used_count++;
 return std::make_pair(picked_item.connection, *picked_index);
}

在我们的连接池实现中，只有在线程ID和数据库路径都一致时，才会返回相同的connection。这样一个数据库连接在同一个时间点只会被一条线程操作，而且后续也只会被同一条线程操作。