Function cbm_store_checkpoint

src/store/store.c:1249–1282

/* ── Checkpoint ─────────────────────────────────────────────────── */

int cbm_store_checkpoint(cbm_store_t *s) {
    if (!s) {
        return CBM_STORE_ERR;
    }
    /* PASSIVE never blocks readers and never ftruncate()s either file.
     * SQLite recommends PASSIVE for shared databases — TRUNCATE shrinks
     * the WAL via ftruncate(fd, 0) on success, which on macOS can raise
     * SIGBUS in a sibling process that has the DB mmap'd through SQLite
     * when it next faults a page in the now-shorter region.
     * See https://www.sqlite.org/c3ref/c_checkpoint_full.html */
    int wal_frames = 0;
    int checkpointed = 0;
    int rc = sqlite3_wal_checkpoint_v2(s->db, NULL, SQLITE_CHECKPOINT_PASSIVE, &wal_frames,
                                       &checkpointed);
    if (rc != SQLITE_OK) {
        store_set_error_sqlite(s, "checkpoint");
        return CBM_STORE_ERR;
    }
    /* #1083: a large WAL that a PASSIVE checkpoint can't fully reset — because
     * concurrent readers hold marks — is the checkpoint-starvation signal. Warn
     * so an operator can see it (and the driving processes) before the -wal file
     * fills the disk; journal_size_limit only reclaims once a reset succeeds.
     * wal_frames = frames in the WAL, checkpointed = frames reclaimed this pass. */
    if (wal_frames >= ST_WAL_STARVE_WARN_FRAMES && checkpointed < wal_frames) {
        char frames_buf[ST_BUF_16];
        char ckpt_buf[ST_BUF_16];
        snprintf(frames_buf, sizeof(frames_buf), "%d", wal_frames);
        snprintf(ckpt_buf, sizeof(ckpt_buf), "%d", checkpointed);
        cbm_log_warn("store.wal.starving", "wal_frames", frames_buf, "checkpointed", ckpt_buf,
                     "hint",
                     "concurrent readers block the WAL reset — the -wal file keeps growing");
    }
    return exec_sql(s, "PRAGMA optimize;");
}

static int prepare_sqlite_for_publish(sqlite3 *db) {
    if (!db) {