chore: release beta 1

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 1.0.0-BETA1
+
+* Improve API by changing from Builder pattern to simply instantiating the database `PowerSyncDatabase`
+  E.g. `val db = PowerSyncDatabase(factory, schema)`
+* Use callback context in transactions
+  E.g. `db.writeTransaction{ ctx -> ctx.execute(...) }`
+* Removed unnecessary expiredAt field
+* Added table max column validation as there is a hard limit of 63 columns
+* Moved SQLDelight models to a separate module to reduce export size
+* Replaced default Logger with [Kermit Logger](https://kermit.touchlab.co/) which allows users to more easily use and/or change Logger settings
+* Add `retryDelay` and `crudThrottle` options when setting up database connection
+* Changed `_viewNameOverride` to `viewNameOverride`

README.md

@@ -6,22 +6,14 @@
 
 # PowerSync Kotlin Multiplatform SDK
 
-## Alpha release
+This is the PowerSync client SDK for Kotlin Mutliplatform. This SDK currently supports Android and iOS as targets.
 
-This SDK is currently in an alpha release. If you find a bug or issue, please open a [GitHub issue](https://github.com/powersync-ja/powersync-kotlin/issues). Questions or feedback can be posted on
-our [community Discord](https://discord.gg/powersync) - we'd love to hear from you.
-
-## SDK Features
+See a summary of features [here](https://docs.powersync.com/client-sdk-references/kotlin-multiplatform-alpha#sdk-features).
 
-* Provides real-time streaming of database changes, using Kotlin Coroutines and Flows.
-* Offers direct access to the SQLite database, enabling the use of SQL on both client and server
-  sides.
-* Operations are asynchronous, ensuring the user interface remains unblocked.
-* Supports concurrent database operations, allowing one write and multiple reads simultaneously.
-* Enables subscription to queries for receiving live updates.
-* Eliminates the need for client-side database migrations as these are managed automatically.
+## Beta release
 
-Supported KMP targets: Android and iOS.
+This SDK is currently in a beta release. If you find a bug or issue, please open a [GitHub issue](https://github.com/powersync-ja/powersync-kotlin/issues). Questions or feedback can be posted on
+our [community Discord](https://discord.gg/powersync) - we'd love to hear from you.
 
 ## Structure: Packages
 
@@ -45,16 +37,14 @@ Demo applications are located in the [`demos/`](./demos) directory. See their re
 
 - [demos/hello-powersync](./demos/hello-powersync/README.md): A minimal example demonstrating the use of the PowerSync Kotlin Multiplatform SDK and the Supabase connector.
 
-- [demos/supabase-todolist](./demos/supabase-todolist/README.md): ** Currently a work in progress **
-  A simple to-do list application demonstrating the use of the PowerSync Kotlin Multiplatform SDK and the Supabase connector.
+- [demos/supabase-todolist](./demos/supabase-todolist/README.md): A simple to-do list application demonstrating the use of the PowerSync Kotlin Multiplatform SDK and the Supabase connector.
 
 ## Current Limitations / Future work
 
-The PowerSync Kotlin Multiplatform SDK is currently in an alpha release and is not yet suitable for production use.
+The PowerSync Kotlin Multiplatform SDK is currently in a beta release. It can be used in production if you’ve tested your use cases.
 
 Current limitations:
 
-- Debugging via configurable logging is not yet implemented.
 - Integration with SQLDelight schema and API generation (ORM) is not yet supported.
 - Supports only a single database file.
 
@@ -65,9 +55,7 @@ Future work/ideas:
 - Management of DB connections on each platform natively.
 - Supporting additional targets (JVM, Wasm).
 
-## Getting Started
-
-### Installation
+## Installation
 
 Add the PowerSync Kotlin Multiplatform SDK to your project by adding the following to your `build.gradle.kts` file:
 
@@ -90,7 +78,7 @@ If want to use the Supabase Connector, also add the following to `commonMain.dep
     implementation("com.powersync:connector-supabase:$powersyncVersion")
 ```
 
-#### Cocoapods
+### Cocoapods
 
 We recommend using Cocoapods (as opposed to SMP) for iOS targets. Add the following to the `cocoapods` config in your `build.gradle.kts`
 
@@ -111,163 +99,10 @@ cocoapods {
 
 Note: The `linkOnly` attribute is set to `true` and framework is set to `isStatic = true` to ensure that the `powersync-sqlite-core` binaries are only statically linked.
 
-### Usage
-
-The first step is creating a PowerSync account and setting up a PowerSync instance. If you are using Supabase, we have a step-by-step tutorial
-available [here](https://docs.powersync.com/integration-guides/supabase-+-powersync).
-
-For other Postgres backend providers, follow these steps:
-
-* Sign up for a free PowerSync account
-  here [https://www.powersync.com/](https://www.powersync.com/).
-* Visit the [PowerSync dashboard](https://powersync.journeyapps.com/) to create a PowerSync instance. After signing up you will be prompted to start the onboarding wizard which guides your though the
-  steps required for this, and find database specific
-  instructions [here](https://docs.powersync.com/usage/installation/database-setup). Existing users: start the onboarding wizard by navigating to Help > Start guide in the top-right corner.
-* Developer documentation for PowerSync is available [here](https://docs.powersync.com/).
-
-#### 1. Define the schema for the on-device SQLite database.
-
-You need to set up your schema in your app project. This involves defining your schema in code using the PowerSync syntax.
-This schema represents a "view" of the downloaded data. No migrations are required — the schema is applied directly when the PowerSync database is constructed.
-
-```kotlin
-import com.powersync.db.schema.Column
-import com.powersync.db.schema.Schema
-import com.powersync.db.schema.Table
-
-val schema: Schema = Schema(
-    Table(
-        name = "customers",
-        columns = listOf(
-            Column.text("name"),
-            Column.text("email")
-        )
-    )
-)
-
-```
-
-Note: No need to declare a primary key `id` column, as PowerSync will automatically create this.
-
-#### 2. Implement a backend connector to define how PowerSync communicates with your backend.
-
-The PowerSync backend connector provides the connection between your application backend and the PowerSync managed database.
-It is used to:
-
-1. Retrieve a token to connect to the PowerSync instance.
-2. Apply local changes on your backend application server (and from there, to Postgres)
-
-If you are using Supabase, you can use [SupabaseConnector.kt](./connectors/supabase/src/commonMain/kotlin/com/powersync/connector/supabase/SupabaseConnector.kt) as a starting point.
-
-```kotlin
-class MyConnector : PowerSyncBackendConnector() {
-    override suspend fun fetchCredentials(): PowerSyncCredentials {
-        // implement fetchCredentials to obtain the necessary credentials to connect to your backend
-        // See an example implementation in connectors/supabase/src/commonMain/kotlin/com/powersync/connector/supabase/SupabaseConnector.kt
-    }
-
-    override suspend fun uploadData(database: PowerSyncDatabase) {
-        // Implement uploadData to send local changes to your backend service
-        // You can omit this method if you only want to sync data from the server to the client
-        // See an example implementation in connectors/supabase/src/commonMain/kotlin/com/powersync/connector/supabase/SupabaseConnector.kt
-        // See https://docs.powersync.com/usage/installation/app-backend-setup/writing-client-changes for considerations.
-    }
-}
-```
-
-#### 3. Initialize the PowerSync database and connect it to the connector, using `PowerSyncBuilder`:
-
-You need to instantiate the PowerSync database — this is the core managed database.
-Its primary functions are to record all changes in the local database, whether online or offline. In addition, it automatically uploads changes to your app backend when connected.
-
-a. Create platform specific `DatabaseDriverFactory` to be used by the `PowerSyncBuilder` to create the SQLite database driver.
-
-  ```kotlin
-// Android
-val driverFactory = DatabaseDriverFactory(this)
-
-// iOS
-val driverFactory = DatabaseDriverFactory()
-  ```
-
-b. Build a `PowerSyncDatabase` instance using the `PowerSyncBuilder` and the `DatabaseDriverFactory`. The schema you created in a previous step is also used as a parameter:
-
-  ```kotlin
-// commonMain
-val database = PowerSyncBuilder.from(driverFactory, schema).build()
-  ```
-
-c. Connect the `PowerSyncDatabase` to the backend connector:
-
-  ```kotlin
-// commonMain
-database.connect(MyConnector())
-  ```
-
-**Special case: Compose Multiplatform**
-
-The artifact `com.powersync:powersync-compose` provides a simpler API:
-
-```kotlin
-// commonMain
-val database = rememberPowerSyncDatabase(schema)
-remember {
-    database.connect(MyConnector())
-}
-```
-
-#### 4. Subscribe to changes in data
-
-```kotlin
-// You can watch any SQL query. This excutes a read query every time the source tables are modified.
-fun watchCustomers(): Flow<List<User>> {
-    // TODO: implement your UI based on the result set
-    return database.watch("SELECT * FROM customers", mapper = { cursor ->
-        User(
-            id = cursor.getString(0)!!,
-            name = cursor.getString(1)!!,
-            email = cursor.getString(2)!!
-        )
-    })
-}
-```
-
-#### 5. Insert, update, and delete data in the local database
-
-The `execute` method executes a write query (INSERT, UPDATE, DELETE) and returns the results (if any).
+## Getting Started
 
-```kotlin
-suspend fun insertCustomer(name: String, email: String) {
-    database.writeTransaction { tx ->
-        tx.execute(
-            sql = "INSERT INTO customers (id, name, email) VALUES (uuid(), ?, ?)",
-            parameters = listOf(name, email)
-        )
-    }
-}
+Our [full SDK reference](https://docs.powersync.com/client-sdk-references/kotlin-multiplatform-alpha#getting-started) contains everything you need to know to get started implementing PowerSync in your project.
 
-suspend fun updateCustomer(id: String, name: String, email: String) {
-    database.execute(
-        sql = "UPDATE customers SET name = ? WHERE email = ?",
-        parameters = listOf(name, email)
-    )
-}
+## Examples
 
-suspend fun deleteCustomer(id: String? = null) {
-    // If no id is provided, delete the first customer in the database
-    val targetId =
-        id ?: database.getOptional(
-            sql = "SELECT id FROM customers LIMIT 1",
-            mapper = { cursor ->
-                cursor.getString(0)!!
-            }
-        ) ?: return
-
-    database.writeTransaction { tx ->
-        tx.execute(
-            sql = "DELETE FROM customers WHERE id = ?",
-            parameters = listOf(targetId)
-        )
-    }
-}
-```
+For example projects built with PowerSync and Kotlin Multiplatform, see our [Demo Apps / Example Projects](https://docs.powersync.com/resources/demo-apps-example-projects#kotlin-multiplatform) gallery. Most of these projects can also be found in the [`demos/`](demos/) directory.

core/README.md

@@ -14,6 +14,6 @@ This is a Kotlin Multiplatform project targeting Android, iOS platforms, with th
 
 ## Note on SQLDelight
 
-The PowerSync core module, internally makes use of [SQLDelight](https://cashapp.github.io/sqldelight) for it database API and typesafe database query generation. 
+The PowerSync core module, internally makes use of [SQLDelight](https://cashapp.github.io/sqldelight) for it database API and typesafe database query generation.
 
-With the Alpha release, the PowerSync core module does not support integrating with SQLDelight from client applications.
+With the Beta release, the PowerSync core module does not support integrating with SQLDelight from client applications.

demos/hello-powersync/README.md

@@ -1,16 +1,16 @@
 # Hello-PowerSync Demo App
 
 This is a minimal demo app demonstrating use of the PowerSync Kotlin Mutiplatform SDK together
-with [Supabase](https://supabase.com/) in a basic Kotlin Multiplatform Compose App. 
+with [Supabase](https://supabase.com/) in a basic Kotlin Multiplatform Compose App.
 
 The app lists customers and allows you to add or delete rows.
 Data is [synced to users globally](https://docs.powersync.com/usage/sync-rules/example-global-data). For more advanced sync rules and functionality, see the [PowerSync+Supabase Todo-List](../supabase-todolist/README.md) demo application.
 
 Supported KMP targets: Android and iOS.
 
-## Alpha release
+## Beta release
 
-The Kotlin Multiplatform SDK is currently in an alpha release. If you find a bug or issue, please
+The Kotlin Multiplatform SDK is currently in a beta release. If you find a bug or issue, please
 open a [GitHub issue](https://github.com/powersync-ja/powersync-kotlin/issues). Questions or
 feedback can be posted on our [community Discord](https://discord.gg/powersync) - we'd love to hear
 from you.
@@ -67,7 +67,7 @@ create publication powersync for table customers;
 2. Open the repo in Android Studio. This creates a `local.properties` file in root and should contain a `sdk.dir=/path/to/android/sdk` line.
 3. Sync the project with Gradle (this should happen automatically, or choose File > Sync project with Gradle Files).
 4. Open the `demos/hello-powersync` directory in Android Studio and sync this project with Gradle.
-5. Insert your Supabase project, auth user, and PowerSync project credentials into the `local.properties` file:
+5. Insert your Supabase project URL, Supabase Anon Key, and PowerSync instance URL into the `local.properties` file:
 
 ```
 # local.properties
@@ -102,4 +102,4 @@ Choose a run configuration for the Android (`composeApp`) or iOS (`iosApp`) targ
 
 * `/iosApp` contains iOS applications. Even if you’re sharing your UI with Compose Multiplatform,
   you need this entry point for your iOS app. This is also where you should add SwiftUI code for
-  your project.
+  your project.

demos/supabase-todolist/README.md

@@ -1,7 +1,5 @@
 # PowerSync + Supabase Kotlin Multiplatform Demo: Todo List App
 
-*** This demo app is a work in progress. It can be run, but certain functionality does not yet work. ***
-
 It is a simple to-do list application demonstrating use of the PowerSync Kotlin Mutiplatform SDK together
 with [Supabase](https://supabase.com/) in a basic Kotlin Multiplatform Compose App.
 
@@ -21,7 +19,7 @@ A step-by-step guide on Supabase<>PowerSync integration is available [here](http
 2. Open the repo in Android Studio. This creates a `local.properties` file in root and should contain a `sdk.dir=/path/to/android/sdk` line.
 3. Sync the project with Gradle (this should happen automatically, or choose File > Sync project with Gradle Files).
 4. Open the `demos/supabase-todolist` directory in Android Studio and sync this project with Gradle.
-5. Insert your Supabase project, auth user, and PowerSync project credentials into the `local.properties` file:
+5. Insert your Supabase project URL, Supabase Anon Key, and PowerSync instance URL into the `local.properties` file:
 
 ```bash
 # local.properties
@@ -32,10 +30,6 @@ POWERSYNC_URL=https://foo.powersync.journeyapps.com
 # Enter your Supabase project's URL and public anon key (Project settings > API)
 SUPABASE_URL=https://foo.supabase.co
 SUPABASE_ANON_KEY=foo
-
-# Enter your Supabase auth user's details
-[email protected]
-SUPABASE_USER_PASSWORD=foo
 ```
 
 ## Run the app

demos/supabase-todolist/shared/build.gradle.kts

@@ -102,7 +102,5 @@ buildkonfig {
         stringConfigField("POWERSYNC_URL")
         stringConfigField("SUPABASE_URL")
         stringConfigField("SUPABASE_ANON_KEY")
-        stringConfigField("SUPABASE_USER_EMAIL")
-        stringConfigField("SUPABASE_USER_PASSWORD")
     }
 }

gradle.properties

@@ -17,7 +17,7 @@ development=true
 RELEASE_SIGNING_ENABLED=true
 # Library config
 GROUP=com.powersync
-LIBRARY_VERSION=0.0.1-ALPHA17
+LIBRARY_VERSION=1.0.0-BETA1
 GITHUB_REPO=https://github.com/powersync-ja/powersync-kotlin.git
 # POM
 POM_URL=https://github.com/powersync-ja/powersync-kotlin/