Add docs

Author: simolus3

core/src/commonMain/kotlin/com/powersync/PowerSyncDatabase.kt

@@ -216,6 +216,11 @@ public interface PowerSyncDatabase : Queries {
          *
          * In this case, PowerSync will not open its own SQLite connections, but rather refer to
          * connections in the [pool].
+         *
+         * The `group` parameter should likely be teh result of calling [databaseGroup] - this is
+         * responsible for ensuring two instances of the same database file don't sync at the same
+         * time. So, a value that uniquely identifies the database should be passed to
+         * [databaseGroup].
          */
         @ExperimentalPowerSyncAPI
         public fun opened(
@@ -234,6 +239,7 @@ public interface PowerSyncDatabase : Queries {
             )
         }
 
+        @ExperimentalPowerSyncAPI
         public fun databaseGroup(logger: Logger, identifier: String): Pair<ActiveDatabaseResource, Any> {
             return ActiveDatabaseGroup.referenceDatabase(logger, identifier)
         }

core/src/commonMain/kotlin/com/powersync/db/driver/SQLiteConnectionPool.kt

@@ -5,18 +5,45 @@ import com.powersync.ExperimentalPowerSyncAPI
 import kotlinx.coroutines.flow.SharedFlow
 import kotlinx.coroutines.runBlocking
 
+/**
+ * An implementation of a connection pool providing asynchronous access to a single writer
+ * and multiple readers.
+ *
+ * This is the underlying pool implementation on which the higher-level PowerSync Kotlin SDK is
+ * built on. The SDK provides its own pool, but can also use existing implementations (via
+ * [com.powersync.PowerSyncDatabase.opened]).
+ */
 @ExperimentalPowerSyncAPI()
 public interface SQLiteConnectionPool {
+    /**
+     * Calls the callback with a read-only connection temporarily leased from the pool.
+     */
     public suspend fun <T> read(callback: suspend (SQLiteConnectionLease) -> T): T
+
+    /**
+     * Calls the callback with a read-write connection temporarily leased from the pool.
+     */
     public suspend fun <T> write(callback: suspend (SQLiteConnectionLease) -> T): T
 
+    /**
+     * Invokes the callback with all connections leased from the pool.
+     */
     public suspend fun <R> withAllConnections(action: suspend (
         writer: SQLiteConnectionLease,
         readers: List<SQLiteConnectionLease>
     ) -> R)
 
+    /**
+     * Returns a flow of table updates made on the [write] connection.
+     */
     public val updates: SharedFlow<Set<String>>
 
+    /**
+     * Closes the connection pool and associated resources.
+     *
+     * Calling [read], [write] and [withAllConnections] after calling [close] should result in an
+     * exception.
+     */
     public suspend fun close()
 }
 

gradle/libs.versions.toml

@@ -16,7 +16,7 @@ kotlinx-datetime = "0.7.1"
 kotlinx-io = "0.8.0"
 ktor = "3.2.3"
 uuid = "0.8.4"
-powersync-core = "0.4.4"
+powersync-core = "0.4.5"
 turbine = "1.2.1"
 kotest = "5.9.1" # we can't upgrade to 6.x because that requires Java 11 or above (we need Java 8 support)