Swift Driver Additions (#262)

Author: stevensJourney

CHANGELOG.md

@@ -12,8 +12,10 @@
 
 - Add `PowerSyncDatabase.inMemory` to create an in-memory SQLite database with PowerSync.
   This may be useful for testing.
-- The Supabase connector can now be subclassed to customize how rows are uploaded and how errors are handled.
+- The Supabase connector can now be subclassed to customize how rows are uploaded and how errors are
+  handled.
 - Experimental support for sync streams.
+- [Swift] Added helpers for creating Swift SQLite connection pools.
 
 ## 1.6.1
 

common/src/nativeMain/interop/sqlite3.def

@@ -1,3 +1,3 @@
 headers = sqlite3.h
 
-noStringConversion = sqlite3_prepare_v3
+noStringConversion = sqlite3_prepare_v3,sqlite3session_create

common/src/nativeMain/interop/sqlite3.h

@@ -3,36 +3,49 @@
 
 typedef struct sqlite3 sqlite3;
 typedef struct sqlite3_stmt sqlite3_stmt;
+typedef struct sqlite3_session sqlite3_session;
+typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
 
 int sqlite3_initialize();
 
 int sqlite3_open_v2(char *filename, sqlite3 **ppDb, int flags,
         char *zVfs);
+
 int sqlite3_close_v2(sqlite3 *db);
 
 // Error handling
 int sqlite3_extended_result_codes(sqlite3 *db, int onoff);
+
 int sqlite3_extended_errcode(sqlite3 *db);
+
 char *sqlite3_errmsg(sqlite3 *db);
+
 char *sqlite3_errstr(int code);
+
 int sqlite3_error_offset(sqlite3 *db);
+
 void sqlite3_free(void *ptr);
 
 // Versions
 char *sqlite3_libversion();
+
 char *sqlite3_sourceid();
+
 int sqlite3_libversion_number();
 
 // Database
 int sqlite3_get_autocommit(sqlite3 *db);
+
 int sqlite3_db_config(sqlite3 *db, int op, ...);
+
 int sqlite3_load_extension(
         sqlite3 *db,          /* Load the extension into this database connection */
         const char *zFile,    /* Name of the shared library containing extension */
         const char *zProc,    /* Entry point.  Derived from zFile if 0 */
         char **pzErrMsg       /* Put error message here if not 0 */
 );
-int sqlite3_extended_result_codes(sqlite3*, int onoff);
+
+int sqlite3_extended_result_codes(sqlite3 *, int onoff);
 
 // Statements
 int sqlite3_prepare16_v3(
@@ -43,27 +56,81 @@ int sqlite3_prepare16_v3(
         sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
         const void **pzTail     /* OUT: Pointer to unused portion of zSql */
 );
+
 int sqlite3_finalize(sqlite3_stmt *pStmt);
+
 int sqlite3_step(sqlite3_stmt *pStmt);
+
 int sqlite3_reset(sqlite3_stmt *pStmt);
-int sqlite3_clear_bindings(sqlite3_stmt*);
+
+int sqlite3_clear_bindings(sqlite3_stmt *);
 
 int sqlite3_column_count(sqlite3_stmt *pStmt);
+
 int sqlite3_bind_parameter_count(sqlite3_stmt *pStmt);
+
 char *sqlite3_column_name(sqlite3_stmt *pStmt, int N);
 
 int sqlite3_bind_blob64(sqlite3_stmt *pStmt, int index, void *data,
         uint64_t length, void *destructor);
+
 int sqlite3_bind_double(sqlite3_stmt *pStmt, int index, double data);
+
 int sqlite3_bind_int64(sqlite3_stmt *pStmt, int index, int64_t data);
+
 int sqlite3_bind_null(sqlite3_stmt *pStmt, int index);
+
 int sqlite3_bind_text16(sqlite3_stmt *pStmt, int index, char *data,
         int length, void *destructor);
 
 void *sqlite3_column_blob(sqlite3_stmt *pStmt, int iCol);
+
 double sqlite3_column_double(sqlite3_stmt *pStmt, int iCol);
+
 int64_t sqlite3_column_int64(sqlite3_stmt *pStmt, int iCol);
+
 void *sqlite3_column_text16(sqlite3_stmt *pStmt, int iCol);
+
 int sqlite3_column_bytes(sqlite3_stmt *pStmt, int iCol);
+
 int sqlite3_column_bytes16(sqlite3_stmt *pStmt, int iCol);
+
 int sqlite3_column_type(sqlite3_stmt *pStmt, int iCol);
+
+
+int sqlite3session_create(
+        sqlite3 *db,                    /* Database handle */
+        const char *zDb,                /* Name of db (e.g. "main") */
+        sqlite3_session **ppSession     /* OUT: New session object */
+);
+
+int sqlite3session_attach(
+        sqlite3_session *pSession,      /* Session object */
+        const char *zTab               /* Table name or NULL for all */
+);
+
+int sqlite3session_changeset(
+        sqlite3_session *pSession,      /* Session object */
+        int *pnChangeset,               /* OUT: Size of buffer at *ppChangeset */
+        void **ppChangeset              /* OUT: Buffer containing changeset */
+);
+
+int sqlite3changeset_start(
+        sqlite3_changeset_iter **pp,    /* OUT: New changeset iterator handle */
+        int nChangeset,                 /* Size of changeset blob in bytes */
+        void *pChangeset                /* Pointer to blob containing changeset */
+);
+
+int sqlite3changeset_op(
+        sqlite3_changeset_iter *pIter,  /* Iterator object */
+        const char **pzTab,             /* OUT: Pointer to table name */
+        int *pnCol,                     /* OUT: Number of columns in table */
+        int *pOp,                       /* OUT: SQLITE_INSERT, DELETE or UPDATE */
+        int *pbIndirect                 /* OUT: True for an 'indirect' change */
+);
+
+int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
+
+int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
+
+void sqlite3session_delete(sqlite3_session *pSession);

internal/PowerSyncKotlin/build.gradle.kts

@@ -48,6 +48,13 @@ kotlin {
             api(project(":core"))
             implementation(libs.ktor.client.logging)
         }
+
+        all {
+            languageSettings {
+                optIn("kotlinx.cinterop.ExperimentalForeignApi")
+                optIn("com.powersync.ExperimentalPowerSyncAPI")
+            }
+        }
     }
 }
 

internal/PowerSyncKotlin/src/appleMain/kotlin/com/powersync/pool/RawConnectionLease.kt

@@ -0,0 +1,37 @@
+package com.powersync.pool
+
+import androidx.sqlite.SQLiteStatement
+import com.powersync.db.driver.SQLiteConnectionLease
+import com.powersync.sqlite.Database
+
+internal class RawConnectionLease(
+    lease: SwiftLeaseAdapter,
+) : SQLiteConnectionLease {
+    private var isCompleted = false
+
+    private var db = Database(lease.pointer)
+
+    private fun checkNotCompleted() {
+        check(!isCompleted) { "Connection lease already closed" }
+    }
+
+    override suspend fun isInTransaction(): Boolean = isInTransactionSync()
+
+    override fun isInTransactionSync(): Boolean {
+        checkNotCompleted()
+        return db.inTransaction()
+    }
+
+    override suspend fun <R> usePrepared(
+        sql: String,
+        block: (SQLiteStatement) -> R,
+    ): R = usePreparedSync(sql, block)
+
+    override fun <R> usePreparedSync(
+        sql: String,
+        block: (SQLiteStatement) -> R,
+    ): R {
+        checkNotCompleted()
+        return db.prepare(sql).use(block)
+    }
+}

internal/PowerSyncKotlin/src/appleMain/kotlin/com/powersync/pool/SessionResult.kt

@@ -0,0 +1,173 @@
+package com.powersync.pool
+
+import cnames.structs.sqlite3
+import cnames.structs.sqlite3_changeset_iter
+import cnames.structs.sqlite3_session
+import com.powersync.PowerSyncException
+import com.powersync.PowerSyncResult
+import com.powersync.db.runWrapped
+import com.powersync.internal.sqlite3.sqlite3_free
+import com.powersync.internal.sqlite3.sqlite3changeset_finalize
+import com.powersync.internal.sqlite3.sqlite3changeset_next
+import com.powersync.internal.sqlite3.sqlite3changeset_op
+import com.powersync.internal.sqlite3.sqlite3changeset_start
+import com.powersync.internal.sqlite3.sqlite3session_attach
+import com.powersync.internal.sqlite3.sqlite3session_changeset
+import com.powersync.internal.sqlite3.sqlite3session_create
+import com.powersync.internal.sqlite3.sqlite3session_delete
+import kotlinx.cinterop.ByteVar
+import kotlinx.cinterop.COpaquePointerVar
+import kotlinx.cinterop.CPointer
+import kotlinx.cinterop.CPointerVar
+import kotlinx.cinterop.IntVar
+import kotlinx.cinterop.alloc
+import kotlinx.cinterop.memScoped
+import kotlinx.cinterop.ptr
+import kotlinx.cinterop.toKString
+import kotlinx.cinterop.value
+
+public data class SessionResult(
+    val blockResult: PowerSyncResult,
+    val affectedTables: Set<String>,
+)
+
+/**
+ * We typically have a few options for table update hooks:
+ * 1.) Registering a hook with SQLite
+ * 2.) Using our Rust core to register update hooks
+ * 3.) Receiving updates from an external API
+ *
+ * In some cases, particularly in the case of GRDB, none of these options are viable.
+ * GRDB dynamically registers (and unregisters) its own update hooks and its update hook logic
+ * does not report changes for operations made outside of its own APIs.
+ *
+ * 1.) We can't register our own hooks since GRDB might override it or our hook could conflict with GRDB's
+ * 2.) We can't register hooks due to above
+ * 3.) The GRDB APIs only report changes if made with their SQLite execution APIs. It's not trivial to implement [com.powersync.db.driver.SQLiteConnectionLease] with their APIs.
+ *
+ * This function provides an alternative method of obtaining table changes by using SQLite sessions.
+ * https://www.sqlite.org/sessionintro.html
+ *
+ * We start a session, execute a block of code, and then extract the changeset from the session.
+ * We then parse the changeset to extract the table names that were modified.
+ * This approach is more heavyweight than using update hooks, but it works in scenarios where
+ * update hooks are not currently feasible.
+ */
+@Throws(PowerSyncException::class)
+public fun withSession(
+    db: CPointer<sqlite3>,
+    block: () -> PowerSyncResult,
+): SessionResult =
+    runWrapped {
+        memScoped {
+            val sessionPtr = alloc<CPointerVar<sqlite3_session>>()
+
+            val rc =
+                sqlite3session_create(
+                    db,
+                    "main",
+                    sessionPtr.ptr,
+                ).checkResult("Could not create SQLite session")
+
+            val session =
+                sessionPtr.value ?: throw PowerSyncException(
+                    "Could not create SQLite session",
+                    cause = Error(),
+                )
+
+            try {
+                // Attach all tables to track changes
+                sqlite3session_attach(
+                    session,
+                    null,
+                ).checkResult("Could not attach all tables to session") // null means all tables
+
+                // Execute the block where changes happen
+                val result = block()
+
+                // Get the changeset
+                val changesetSizePtr = alloc<IntVar>()
+                val changesetPtr = alloc<COpaquePointerVar>()
+
+                sqlite3session_changeset(
+                    session,
+                    changesetSizePtr.ptr,
+                    changesetPtr.ptr,
+                ).checkResult("Could not get changeset from session")
+
+                val changesetSize = changesetSizePtr.value
+                val changeset = changesetPtr.value
+
+                if (changesetSize == 0 || changeset == null) {
+                    return@memScoped SessionResult(
+                        result,
+                        affectedTables = emptySet(),
+                    )
+                }
+
+                // Parse the changeset to extract table names
+                val changedTables = mutableSetOf<String>()
+                val iterPtr = alloc<CPointerVar<sqlite3_changeset_iter>>()
+
+                sqlite3changeset_start(
+                    iterPtr.ptr,
+                    changesetSize,
+                    changeset,
+                ).checkResult("Could not start changeset iterator")
+
+                val iter = iterPtr.value
+
+                if (iter == null) {
+                    return@memScoped SessionResult(
+                        result,
+                        affectedTables = emptySet(),
+                    )
+                }
+
+                try {
+                    // Iterate through all changes
+                    while (sqlite3changeset_next(iter) == 100) {
+                        val tableNamePtr = alloc<CPointerVar<ByteVar>>()
+                        val nColPtr = alloc<IntVar>()
+                        val opPtr = alloc<IntVar>()
+                        val indirectPtr = alloc<IntVar>()
+
+                        val opRc =
+                            sqlite3changeset_op(
+                                iter,
+                                tableNamePtr.ptr,
+                                nColPtr.ptr,
+                                opPtr.ptr,
+                                indirectPtr.ptr,
+                            )
+
+                        if (opRc == 0) {
+                            val tableNameCPtr = tableNamePtr.value
+                            if (tableNameCPtr != null) {
+                                val tableName = tableNameCPtr.toKString()
+                                changedTables.add(tableName)
+                            }
+                        }
+                    }
+                } finally {
+                    sqlite3changeset_finalize(iter)
+                    // Free the changeset memory
+                    sqlite3_free(changeset)
+                }
+
+                return@memScoped SessionResult(
+                    result,
+                    affectedTables = changedTables.toSet(),
+                )
+            } finally {
+                // Clean up the session
+                sqlite3session_delete(session)
+            }
+        }
+    }
+
+private fun Int.checkResult(message: String) {
+    if (this != 0) {
+        throw PowerSyncException("SQLite error code: $this", cause = Error(message))
+    }
+}