Skip to main content

PowerSyncDatabase

Extends

Constructors

new PowerSyncDatabase(options)

new PowerSyncDatabase(options): PowerSyncDatabase

Parameters

ParameterType
optionsPowerSyncDatabaseOptions

Returns

PowerSyncDatabase

Inherited from

AbstractPowerSyncDatabase.constructor

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:104

Properties

PropertyModifierTypeDescriptionInherited from
_isReadyPromiseprotectedPromise< void >-AbstractPowerSyncDatabase._isReadyPromise
_schemaprotectedSchema< SchemaType >-AbstractPowerSyncDatabase._schema
bucketStorageAdapterprotectedBucketStorageAdapter-AbstractPowerSyncDatabase.bucketStorageAdapter
closedpublicbooleanReturns true if the connection is closed.AbstractPowerSyncDatabase.closed
currentStatuspublicSyncStatusCurrent connection status.AbstractPowerSyncDatabase.currentStatus
listenersprotectedobject-AbstractPowerSyncDatabase.listeners
optionsprotectedPowerSyncDatabaseOptions-AbstractPowerSyncDatabase.options
readypublicboolean-AbstractPowerSyncDatabase.ready
sdkVersionpublicstring-AbstractPowerSyncDatabase.sdkVersion
syncStreamImplementation?publicStreamingSyncImplementation-AbstractPowerSyncDatabase.syncStreamImplementation
transactionMutexstaticMutexTransactions should be queued in the DBAdapter, but we also want to prevent
calls to .execute while an async transaction is running.
AbstractPowerSyncDatabase.transactionMutex

Accessors

connected

get connected(): boolean

Whether a connection to the PowerSync service is currently open.

Returns

boolean

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:120


database

get database(): DBAdapter

The underlying database.

For the most part, behavior is the same whether querying on the underlying database, or on AbstractPowerSyncDatabase.

Returns

DBAdapter

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:116


schema

get schema(): Schema< object >

Schema used for the local database.

Returns

Schema< object >

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:108

Methods

_initialize()

_initialize(): Promise< void >

Allows for extended implementations to execute custom initialization logic as part of the total init process

Returns

Promise< void >

Overrides

AbstractPowerSyncDatabase._initialize

Source

react-native/src/db/PowerSyncDatabase.ts:12


close()

close(options?): Promise< void >

Close the database, releasing resources.

Also disconnects any active connection.

Once close is called, this connection cannot be used again - a new one must be constructed.

Parameters

ParameterType
options?PowerSyncCloseOptions

Returns

Promise< void >

Inherited from

AbstractPowerSyncDatabase.close

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:180


connect()

connect(connector): Promise< void >

Connects to stream of events from the PowerSync instance.

Parameters

ParameterType
connectorPowerSyncBackendConnector

Returns

Promise< void >

Inherited from

AbstractPowerSyncDatabase.connect

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:156


disconnect()

disconnect(): Promise< void >

Close the sync connection.

Use connect to connect again.

Returns

Promise< void >

Inherited from

AbstractPowerSyncDatabase.disconnect

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:162


disconnectAndClear()

disconnectAndClear(options?): Promise< void >

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.

To preserve data in local-only tables, set clearLocal to false.

Parameters

ParameterType
options?DisconnectAndClearOptions

Returns

Promise< void >

Inherited from

AbstractPowerSyncDatabase.disconnectAndClear

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:171


execute()

execute(sql, parameters?): Promise< QueryResult >

Execute a write (INSERT/UPDATE/DELETE) query and optionally return results.

Parameters

ParameterType
sqlstring
parameters?any[]

Returns

Promise< QueryResult >

Inherited from

AbstractPowerSyncDatabase.execute

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:222


executeBatch()

executeBatch(sql, parameters?): Promise< QueryResult >

Execute a write query (INSERT/UPDATE/DELETE) multiple times with each parameter set and optionally return results. This is faster than executing separately with each parameter set.

Parameters

ParameterType
sqlstring
parameters?any[][]

Returns

Promise< QueryResult >

Inherited from

AbstractPowerSyncDatabase.executeBatch

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:228


generateBucketStorageAdapter()

protected generateBucketStorageAdapter(): BucketStorageAdapter

Returns

BucketStorageAdapter

Overrides

AbstractPowerSyncDatabase.generateBucketStorageAdapter

Source

react-native/src/db/PowerSyncDatabase.ts:14


generateSyncStreamImplementation()

protected generateSyncStreamImplementation(connector): AbstractStreamingSyncImplementation

Parameters

ParameterType
connectorPowerSyncBackendConnector

Returns

AbstractStreamingSyncImplementation

Overrides

AbstractPowerSyncDatabase.generateSyncStreamImplementation

Source

react-native/src/db/PowerSyncDatabase.ts:18


get()

get<T>(sql, parameters?): Promise< T >

Execute a read-only query and return the first result, error if the ResultSet is empty.

Type parameters

Type parameter
T

Parameters

ParameterType
sqlstring
parameters?any[]

Returns

Promise< T >

Inherited from

AbstractPowerSyncDatabase.get

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:240


getAll()

getAll<T>(sql, parameters?): Promise< T[] >

Execute a read-only query and return results.

Type parameters

Type parameter
T

Parameters

ParameterType
sqlstring
parameters?any[]

Returns

Promise< T[] >

Inherited from

AbstractPowerSyncDatabase.getAll

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:232


getCrudBatch()

getCrudBatch(limit): Promise< null | CrudBatch >

Get a batch of crud data to upload.

Returns null if there is no data to upload.

Use this from the PowerSyncBackendConnector.uploadData callback.

Once the data have been successfully uploaded, call CrudBatch.complete before requesting the next batch.

Use limit to specify the maximum number of updates to return in a single batch.

This method does include transaction ids in the result, but does not group data by transaction. One batch may contain data from multiple transactions, and a single transaction may be split over multiple batches.

Parameters

ParameterType
limitnumber

Returns

Promise< null | CrudBatch >

Inherited from

AbstractPowerSyncDatabase.getCrudBatch

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:202


getNextCrudTransaction()

getNextCrudTransaction(): Promise< null | CrudTransaction >

Get the next recorded transaction to upload.

Returns null if there is no data to upload.

Use this from the PowerSyncBackendConnector.uploadData callback.

Once the data have been successfully uploaded, call CrudTransaction.complete before requesting the next transaction.

Unlike getCrudBatch, this only returns data from a single transaction at a time. All data for the transaction is loaded into memory.

Returns

Promise< null | CrudTransaction >

Inherited from

AbstractPowerSyncDatabase.getNextCrudTransaction

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:216


getOptional()

getOptional<T>(sql, parameters?): Promise< null | T >

Execute a read-only query and return the first result, or null if the ResultSet is empty.

Type parameters

Type parameter
T

Parameters

ParameterType
sqlstring
parameters?any[]

Returns

Promise< null | T >

Inherited from

AbstractPowerSyncDatabase.getOptional

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:236


getUploadQueueStats()

getUploadQueueStats(includeSize?): Promise< UploadQueueStats >

Get upload queue size estimate and count.

Parameters

ParameterType
includeSize?boolean

Returns

Promise< UploadQueueStats >

Inherited from

AbstractPowerSyncDatabase.getUploadQueueStats

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:184


init()

init(): Promise< void >

Wait for initialization to complete. While initializing is automatic, this helps to catch and report initialization errors.

Returns

Promise< void >

Inherited from

AbstractPowerSyncDatabase.init

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:152


initialize()

protected initialize(): Promise< void >

Entry point for executing initialization logic. This is to be automatically executed in the constructor.

Returns

Promise< void >

Inherited from

AbstractPowerSyncDatabase.initialize

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:140


iterateListeners()

iterateListeners(cb): void

Parameters

ParameterType
cb(listener) => any

Returns

void

Inherited from

AbstractPowerSyncDatabase.iterateListeners

Source

common/lib/utils/BaseObserver.d.ts:19


onChange()

onChange(options)

onChange(options?): AsyncIterable< WatchOnChangeEvent >

This version of onChange uses AsyncGenerator, for documentation see onChangeWithAsyncGenerator. Can be overloaded to use a callback handler instead, for documentation see onChangeWithCallback.

Parameters
ParameterType
options?SQLWatchOptions
Returns

AsyncIterable< WatchOnChangeEvent >

Inherited from

AbstractPowerSyncDatabase.onChange

Example
async monitorChanges() {
for await (const event of this.powersync.onChange({tables: ['todos']})) {
console.log('Detected change event:', event);
}
}
Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:325

onChange(handler, options)

onChange(handler?, options?): () => void

See onChangeWithCallback.

Parameters
ParameterType
handler?WatchOnChangeHandler
options?SQLWatchOptions
Returns

Function

Returns

void

Inherited from

AbstractPowerSyncDatabase.onChange

Example
monitorChanges() {
this.powersync.onChange({
onChange: (event) => {
console.log('Change detected:', event);
}
}, { tables: ['todos'] });
}
Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:340


onChangeWithAsyncGenerator()

onChangeWithAsyncGenerator(options?): AsyncIterable< WatchOnChangeEvent >

Create a Stream of changes to any of the specified tables.

This is preferred over watchWithAsyncGenerator when multiple queries need to be performed together when data is changed.

Note, do not declare this as async *onChange as it will not work in React Native

Parameters

ParameterType
options?SQLWatchOptions

Returns

AsyncIterable< WatchOnChangeEvent >

Inherited from

AbstractPowerSyncDatabase.onChangeWithAsyncGenerator

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:360


onChangeWithCallback()

onChangeWithCallback(handler?, options?): () => void

Invoke the provided callback on any changes to any of the specified tables.

This is preferred over watchWithCallback when multiple queries need to be performed together when data is changed.

Note that the onChange callback member of the handler is required.

Returns dispose function to stop watching.

Parameters

ParameterType
handler?WatchOnChangeHandler
options?SQLWatchOptions

Returns

Function

Returns

void

Inherited from

AbstractPowerSyncDatabase.onChangeWithCallback

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:351


readLock()

readLock<T>(callback): Promise< T >

Takes a read lock, without starting a transaction. In most cases, readTransaction should be used instead.

Type parameters

Type parameter
T

Parameters

ParameterType
callback(db) => Promise< T >

Returns

Promise< T >

Inherited from

AbstractPowerSyncDatabase.readLock

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:245


readTransaction()

readTransaction<T>(callback, lockTimeout?): Promise< T >

Open a read-only transaction. Read transactions can run concurrently to a write transaction. Changes from any write transaction are not visible to read transactions started before it.

Type parameters

Type parameter
T

Parameters

ParameterType
callback(tx) => Promise< T >
lockTimeout?number

Returns

Promise< T >

Inherited from

AbstractPowerSyncDatabase.readTransaction

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:256


registerListener()

registerListener(listener): () => void

Register a listener for updates to the PowerSync client.

Parameters

ParameterType
listenerPartial< PowerSyncDBListener >

Returns

Function

Returns

void

Inherited from

AbstractPowerSyncDatabase.registerListener

Source

common/lib/utils/BaseObserver.d.ts:18


resolveTables()

resolveTables(sql, parameters?, options?): Promise< string[] >

Parameters

ParameterType
sqlstring
parameters?any[]
options?SQLWatchOptions

Returns

Promise< string[] >

Inherited from

AbstractPowerSyncDatabase.resolveTables

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:311


updateHasSynced()

protected updateHasSynced(): Promise< void >

Returns

Promise< void >

Inherited from

AbstractPowerSyncDatabase.updateHasSynced

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:141


updateSchema()

updateSchema(schema): Promise< void >

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

Cannot be used while connected - this should only be called before AbstractPowerSyncDatabase.connect.

Parameters

ParameterType
schemaSchema< SchemaType >

Returns

Promise< void >

Inherited from

AbstractPowerSyncDatabase.updateSchema

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:147


waitForFirstSync()

waitForFirstSync(signal?): Promise< void >

Parameters

ParameterType
signal?AbortSignal

Returns

Promise< void >

A promise which will resolve once the first full sync has completed.

Inherited from

AbstractPowerSyncDatabase.waitForFirstSync

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:130


waitForReady()

waitForReady(): Promise< void >

Returns

Promise< void >

A promise which will resolve once initialization is completed.

Inherited from

AbstractPowerSyncDatabase.waitForReady

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:126


watch()

watch(sql, parameters, options)

watch(sql, parameters?, options?): AsyncIterable< QueryResult >

This version of watch uses AsyncGenerator, for documentation see watchWithAsyncGenerator. Can be overloaded to use a callback handler instead, for documentation see watchWithCallback.

Parameters
ParameterType
sqlstring
parameters?any[]
options?SQLWatchOptions
Returns

AsyncIterable< QueryResult >

Inherited from

AbstractPowerSyncDatabase.watch

Example
async *attachmentIds() {
for await (const result of this.powersync.watch(
`SELECT photo_id as id FROM todos WHERE photo_id IS NOT NULL`,
[]
)) {
yield result.rows?._array.map((r) => r.id) ?? [];
}
}
Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:279

watch(sql, parameters, handler, options)

watch(sql, parameters?, handler?, options?): void

See watchWithCallback.

Parameters
ParameterType
sqlstring
parameters?any[]
handler?WatchHandler
options?SQLWatchOptions
Returns

void

Inherited from

AbstractPowerSyncDatabase.watch

Example
onAttachmentIdsChange(onResult) {
this.powersync.watch(
`SELECT photo_id as id FROM todos WHERE photo_id IS NOT NULL`,
[],
{
onResult: (result) => onResult(result.rows?._array.map((r) => r.id) ?? [])
}
);
}
Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:296


watchWithAsyncGenerator()

watchWithAsyncGenerator(sql, parameters?, options?): AsyncIterable< QueryResult >

Execute a read query every time the source tables are modified. Use SQLWatchOptions.throttleMs to specify the minimum interval between queries. Source tables are automatically detected using EXPLAIN QUERY PLAN.

Parameters

ParameterType
sqlstring
parameters?any[]
options?SQLWatchOptions

Returns

AsyncIterable< QueryResult >

Inherited from

AbstractPowerSyncDatabase.watchWithAsyncGenerator

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:310


watchWithCallback()

watchWithCallback(sql, parameters?, handler?, options?): void

Execute a read query every time the source tables are modified. Use SQLWatchOptions.throttleMs to specify the minimum interval between queries. Source tables are automatically detected using EXPLAIN QUERY PLAN.

Note that the onChange callback member of the handler is required.

Parameters

ParameterType
sqlstring
parameters?any[]
handler?WatchHandler
options?SQLWatchOptions

Returns

void

Inherited from

AbstractPowerSyncDatabase.watchWithCallback

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:304


writeLock()

writeLock<T>(callback): Promise< T >

Takes a global lock, without starting a transaction. In most cases, writeTransaction should be used instead.

Type parameters

Type parameter
T

Parameters

ParameterType
callback(db) => Promise< T >

Returns

Promise< T >

Inherited from

AbstractPowerSyncDatabase.writeLock

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:250


writeTransaction()

writeTransaction<T>(callback, lockTimeout?): Promise< T >

Open a read-write transaction. This takes a global lock - only one write transaction can execute against the database at a time. Statements within the transaction must be done on the provided Transaction interface.

Type parameters

Type parameter
T

Parameters

ParameterType
callback(tx) => Promise< T >
lockTimeout?number

Returns

Promise< T >

Inherited from

AbstractPowerSyncDatabase.writeTransaction

Source

common/lib/client/AbstractPowerSyncDatabase.d.ts:262