PowerSync Core/com.powersync/PowerSyncDatabase

PowerSyncDatabase

A PowerSync managed database.

Use one instance per database file.

Use PowerSyncDatabase.connect to connect to the PowerSync service, to keep the local database in sync with the remote database.

All changes to local tables are automatically recorded, whether connected or not. Once connected, the changes are uploaded.

Properties

closed

abstract val closed: Boolean

Indicates if the PowerSync client has been closed. A new client is required after a client has been closed.

currentStatus

abstract val currentStatus: SyncStatus

The current sync status.

identifier

abstract val identifier: String

Identifies the database client. This is typically the database name.

Functions

abstract suspend fun close()

Close the database, releasing resources. Also disconnects any active connection.

connect

abstract suspend fun connect( connector: PowerSyncBackendConnector, crudThrottleMs: Long = 1000, retryDelayMs: Long = 5000, params: Map<String, JsonParam?> = emptyMap())

Connect to the PowerSync service, and keep the databases in sync.

disconnect

abstract suspend fun disconnect()

Close the sync connection.

disconnectAndClear

abstract suspend fun disconnectAndClear(clearLocal: Boolean = true)

Disconnect and clear the database. Use this when logging out. The database can still be queried after this is called, but the tables would be empty.

execute

abstract suspend fun execute(sql: String, parameters: List<Any?>? = listOf()): Long

Executes a write query (INSERT, UPDATE, DELETE).

get

abstract suspend fun <RowType : Any> get(sql: String, parameters: List<Any?>? = listOf(), mapper: (SqlCursor) -> RowType): RowType

Executes a read-only (SELECT) query and returns a single result.

getAll

abstract suspend fun <RowType : Any> getAll(sql: String, parameters: List<Any?>? = listOf(), mapper: (SqlCursor) -> RowType): List<RowType>

Executes a read-only (SELECT) query and returns all results.

getCrudBatch

abstract suspend fun getCrudBatch(limit: Int = 100): CrudBatch?

Get a batch of crud data to upload.

getNextCrudTransaction

abstract suspend fun getNextCrudTransaction(): CrudTransaction?

Get the next recorded transaction to upload.

getOptional

abstract suspend fun <RowType : Any> getOptional(sql: String, parameters: List<Any?>? = listOf(), mapper: (SqlCursor) -> RowType): RowType?

Executes a read-only (SELECT) query and returns a single optional result.

getPowerSyncVersion

abstract suspend fun getPowerSyncVersion(): String

Convenience method to get the current version of PowerSync.

onChange

abstract fun onChange( tables: Set<String>, throttleMs: Long = DEFAULT_THROTTLE.inWholeMilliseconds, triggerImmediately: Boolean = true): Flow<Set<String>>

Returns a Flow that emits whenever the source tables are modified.

readLock

abstract suspend fun <R> readLock(callback: ThrowableLockCallback<R>): R

Takes a read lock without starting a transaction.

readTransaction

abstract suspend fun <R> readTransaction(callback: ThrowableTransactionCallback<R>): R

Opens a read-only transaction.

updateSchema

abstract suspend fun updateSchema(schema: Schema)

Replace the schema with a new version. This is for advanced use cases - typically the schema should just be specified once in the constructor.

waitForFirstSync

abstract suspend fun waitForFirstSync()

Suspend function that resolves when the first sync has occurred

abstract suspend fun waitForFirstSync(priority: BucketPriority)

Suspend function that resolves when the first sync covering at least all buckets with the given priority (or a higher one, since those would be synchronized first) has completed.

watch

abstract fun <RowType : Any> watch( sql: String, parameters: List<Any?>? = listOf(), throttleMs: Long = DEFAULT_THROTTLE.inWholeMilliseconds, mapper: (SqlCursor) -> RowType): Flow<List<RowType>>

Executes a read-only (SELECT) query every time the source tables are modified and returns the results as a Flow of lists.

writeLock

abstract suspend fun <R> writeLock(callback: ThrowableLockCallback<R>): R

Takes a global lock without starting a transaction.

writeTransaction

abstract suspend fun <R> writeTransaction(callback: ThrowableTransactionCallback<R>): R

Opens a read-write transaction.