Usage Examples

Code snippets and guidelines for common scenarios

Using transactions to group changes

This section is a work-in-progress. An example is coming soon.

Subscribe to changes in data

Use the watch method to watch for changes to the dependent tables of any SQL query.

// You can watch any SQL query
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)!!
        )
    })
}

Insert, update, and delete data in the local database

Use execute to run INSERT, UPDATE or DELETE queries.

suspend fun updateCustomer(id: String, name: String, email: String) {
    database.execute(
        "UPDATE customers SET name = ? WHERE email = ?",
        listOf(name, email)
    )
}

Send changes in local data to your backend service

Override uploadData to send local updates to your backend service. If you are using Supabase, see SupabaseConnector.kt for a complete implementation.

/**
 * This function is called whenever there is data to upload, whether the device is online or offline.
 * If this call throws an error, it is retried periodically.
 */
override suspend fun uploadData(database: PowerSyncDatabase) {

    val transaction = database.getNextCrudTransaction() ?: return;

    var lastEntry: CrudEntry? = null;
    try {

        for (entry in transaction.crud) {
            lastEntry = entry;

            val table = supabaseClient.from(entry.table)
            when (entry.op) {
                UpdateType.PUT -> {
                    val data = entry.opData?.toMutableMap() ?: mutableMapOf()
                    data["id"] = entry.id
                    table.upsert(data)
                }

                UpdateType.PATCH -> {
                    table.update(entry.opData!!) {
                        filter {
                            eq("id", entry.id)
                        }
                    }
                }

                UpdateType.DELETE -> {
                    table.delete {
                        filter {
                            eq("id", entry.id)
                        }
                    }
                }
            }
        }

        transaction.complete(null);

    } catch (e: Exception) {
        println("Data upload error - retrying last entry: ${lastEntry!!}, $e")
        throw e
    }
}

Accessing PowerSync connection status information

This section is a work-in-progress. An example is coming soon.

Wait for the initial sync to complete

This section is a work-in-progress. An example is coming soon.

Using logging to troubleshoot issues

This is not yet implemented in the alpha release, but is on the roadmap for the beta release.