libsql-sqlite3: Add libsql_wal_checkpoint_seq_count() API

This adds libsql_wal_checkpoint_seq_count() API function for determining
the checkpoint sequence counter of a database WAL.

Author: penberg

libsql-sqlite3/doc/libsql_extensions.md

@@ -362,6 +362,7 @@ The libSQL has the following WAL API functions, which are useful for
 syncing the WAL between databases:
 
 * `libsql_wal_disable_checkpoint` -- Disable checkpointing, including on database close.
+* `libsql_wal_checkpoint_seq_count` -- Return the checkpoint sequence number of the WAL.
 * `libsql_wal_frame_count` -- Get the number of frames in the WAL.
 * `libsql_wal_get_frame` -- Get a frame from the WAL.
 * `libsql_wal_insert_begin` -- Begin WAL insertion.

libsql-sqlite3/src/main.c

@@ -2449,6 +2449,30 @@ int libsql_wal_disable_checkpoint(sqlite3 *db) {
   return SQLITE_OK;
 }
 
+/*
+** Return the checkpoint sequence counter of the given database.
+*/
+int libsql_wal_checkpoint_seq_count(sqlite3 *db, unsigned int *pnCkpt) {
+  int rc = SQLITE_OK;
+  Pager *pPager;
+
+#ifdef SQLITE_OMIT_WAL
+  *pnFrame = 0;
+  return SQLITE_OK;
+#else
+#ifdef SQLITE_ENABLE_API_ARMOR
+  if( !sqlite3SafetyCheckOk(db) ) return SQLITE_MISUSE_BKPT;
+#endif
+
+  sqlite3_mutex_enter(db->mutex);
+  pPager = sqlite3BtreePager(db->aDb[0].pBt);
+  rc = sqlite3PagerWalCheckpointSeqCount(pPager, pnCkpt);
+  sqlite3Error(db, rc);
+  sqlite3_mutex_leave(db->mutex);
+  return rc;
+#endif
+}
+
 /*
 ** Return the number of frames in the WAL of the given database.
 */

libsql-sqlite3/src/pager.c

@@ -7771,6 +7771,18 @@ int sqlite3PagerCloseWal(Pager *pPager, sqlite3 *db){
   return rc;
 }
 
+/**
+** Return the current checkpoint generation in the WAL file.
+**/
+int sqlite3PagerWalCheckpointSeqCount(Pager *pPager, unsigned int *pnCkpt){
+  if( pagerUseWal(pPager) ){
+    return pPager->wal->methods.xCheckpointSeqCount(pPager->wal->pData, pnCkpt);
+  } else {
+    *pnCkpt = 0;
+    return SQLITE_OK;
+  }
+}
+
 /**
 ** Return the number of frames in the WAL file.
 **

libsql-sqlite3/src/sqlite.h.in

@@ -10564,6 +10564,15 @@ void *libsql_close_hook(sqlite3 *db, void (*xClose)(void *pCtx, sqlite3 *db), vo
 */
 int libsql_wal_disable_checkpoint(sqlite3 *db);
 
+/*
+** CAPI3REF: Get the checkpoint sequence counter of the WAL file
+** METHOD: sqlite3
+**
+** ^The [libsql_wal_checkpoint_seq_count(D,P)] interface returns the checkpoint sequence counter
+** of the WAL file for [database connection] D into *P.
+*/
+int libsql_wal_checkpoint_seq_count(sqlite3 *db, unsigned int *pnCkpt);
+
 /*
 ** CAPI3REF: Get the number of frames in the WAL file
 ** METHOD: sqlite3

libsql-sqlite3/src/test_walapi.c

@@ -145,6 +145,34 @@ void test_sync_while_reading() {
     cmp_data(db_primary, db_backup); 
 }
 
+// This test case writes to a local database, force checkpoint, and then
+//verifies that checkpoint sequence number incremented, and the WAL is
+//truncated.
+static void test_checkpoint(void) {
+    sqlite3 *db_primary;
+    unsigned int max_frame, ckpt_seq;
+
+    open_db("primary_test_checkpoint.db", &db_primary);
+
+    ensure(sqlite3_exec(db_primary, "CREATE TABLE t (x)", 0, 0, 0) == SQLITE_OK, "failed to insert data\n");
+    ensure(sqlite3_exec(db_primary, "INSERT INTO t VALUES (randomblob(4 * 1024))", 0, 0, 0) == SQLITE_OK, "failed to insert data\n");
+    ensure(sqlite3_exec(db_primary, "INSERT INTO t VALUES (randomblob(1 * 1024))", 0, 0, 0) == SQLITE_OK, "failed to insert data\n");
+    ensure(sqlite3_exec(db_primary, "INSERT INTO t VALUES (randomblob(1 * 1024))", 0, 0, 0) == SQLITE_OK, "failed to insert data\n");
+
+    ensure(libsql_wal_checkpoint_seq_count(db_primary, &ckpt_seq) == SQLITE_OK, "failed to get checkpoint sequence count: %s\n", sqlite3_errmsg(db_primary));
+    assert(ckpt_seq == 0);
+    ensure(libsql_wal_frame_count(db_primary, &max_frame) == SQLITE_OK, "failed to get frames count: %s\n", sqlite3_errmsg(db_primary));
+    assert(max_frame == 7);
+
+    // force checkpoint
+    ensure(sqlite3_wal_checkpoint_v2(db_primary, NULL, SQLITE_CHECKPOINT_TRUNCATE, NULL, NULL) == SQLITE_OK, "failed to checkpoint: %s\n", sqlite3_errmsg(db_primary));
+
+    ensure(libsql_wal_checkpoint_seq_count(db_primary, &ckpt_seq) == SQLITE_OK, "failed to get checkpoint sequence count: %s\n", sqlite3_errmsg(db_primary));
+    assert(ckpt_seq == 1);
+    ensure(libsql_wal_frame_count(db_primary, &max_frame) == SQLITE_OK, "failed to get frames count: %s\n", sqlite3_errmsg(db_primary));
+    assert(max_frame == 0);
+}
+
 int main(int argc, char *argv[])
 {
     test_huge_payload();
@@ -156,5 +184,8 @@ int main(int argc, char *argv[])
     test_sync_while_reading();
     printf("============= OK test_sync_while_reading\n");
 
+    test_checkpoint();
+    printf("============= OK test_checkpoint\n");
+
     return 0;
 }

libsql-sqlite3/src/wal.c

@@ -4024,6 +4024,11 @@ static int walFrames(
   return rc;
 }
 
+int sqlite3WalCheckpointSeqCount(Wal *pWal, unsigned int *pnCkpt){
+  *pnCkpt = pWal->nCkpt;
+  return SQLITE_OK;
+}
+
 int sqlite3WalFrameCount(Wal *pWal, int locked, unsigned int *pnFrames){
   int rc = SQLITE_OK;
   if( locked==0 ) {
@@ -4543,6 +4548,7 @@ static int sqlite3WalOpen(
     out->methods.xUndo = (int (*)(wal_impl *, int (*)(void *, unsigned int), void *))sqlite3WalUndo;
     out->methods.xSavepoint = (void (*)(wal_impl *, unsigned int *))sqlite3WalSavepoint;
     out->methods.xSavepointUndo = (int (*)(wal_impl *, unsigned int *))sqlite3WalSavepointUndo;
+    out->methods.xCheckpointSeqCount = (int (*)(wal_impl *, unsigned int *))sqlite3WalCheckpointSeqCount;
     out->methods.xFrameCount = (int (*)(wal_impl *, int, unsigned int *))sqlite3WalFrameCount;
     out->methods.xFrames = (int (*)(wal_impl *, int, libsql_pghdr *, unsigned int, int, int, int *))sqlite3WalFrames;
     out->methods.xCheckpoint = (int (*)(wal_impl *, sqlite3 *, int, int (*)(void *), void *, int, int, unsigned char *, int *, int *, int (*)(void*, int, const unsigned char*, int, int, int), void*))sqlite3WalCheckpoint;

libsql-sqlite3/src/wal.h

@@ -76,6 +76,9 @@ typedef struct libsql_wal_methods {
   ** response to a ROLLBACK TO command. */
   int (*xSavepointUndo)(wal_impl* pWal, unsigned int *aWalData);
 
+  /* Return the current checkpoint generation in the WAL file. */
+  int (*xCheckpointSeqCount)(wal_impl* pWal, unsigned int *pnCkpt);
+
   /* Return the number of frames in the WAL */
   int (*xFrameCount)(wal_impl* pWal, int, unsigned int *);