abstract AbstractPowerSyncDatabase
Extends
Constructors
new AbstractPowerSyncDatabase(options)
new AbstractPowerSyncDatabase(
options):AbstractPowerSyncDatabase
Parameters
| Parameter | Type |
|---|---|
options | PowerSyncDatabaseOptions |
Returns
Overrides
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:148
Properties
| Property | Modifier | Type | Description | Inherited from |
|---|---|---|---|---|
_isReadyPromise | protected | Promise< void > | - | - |
_schema | protected | Schema< SchemaType > | - | - |
bucketStorageAdapter | protected | BucketStorageAdapter | - | - |
closed | public | boolean | Returns true if the connection is closed. | - |
currentStatus | public | SyncStatus | Current connection status. | - |
hasSyncedWatchDisposer? | private | () => void | - | - |
listeners | protected | Set< Partial< PowerSyncDBListener > > | - | BaseObserver.listeners |
options | protected | PowerSyncDatabaseOptions | - | - |
ready | public | boolean | - | - |
sdkVersion | public | string | - | - |
syncStatusListenerDisposer? | private | () => void | - | - |
syncStreamImplementation? | public | StreamingSyncImplementation | - | - |
transactionMutex | static | Mutex | Transactions should be queued in the DBAdapter, but we also want to prevent calls to .execute while an async transaction is running. | - |
Accessors
connected
getconnected():boolean
Whether a connection to the PowerSync service is currently open.
Returns
boolean
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:180
database
getdatabase():DBAdapter
The underlying database.
For the most part, behavior is the same whether querying on the underlying database, or on AbstractPowerSyncDatabase.
Returns
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:173
schema
getschema():Schema<SchemaType>
Schema used for the local database.
Returns
Schema< SchemaType >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:164
Methods
_initialize()
abstract_initialize():Promise<void>
Allows for extended implementations to execute custom initialization logic as part of the total init process
Returns
Promise< void >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:229
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
| Parameter | Type | Default value |
|---|---|---|
options | PowerSyncCloseOptions | DEFAULT_POWERSYNC_CLOSE_OPTIONS |
Returns
Promise< void >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:402
connect()
connect(
connector,options?):Promise<void>
Connects to stream of events from the PowerSync instance.
Parameters
| Parameter | Type |
|---|---|
connector | PowerSyncBackendConnector |
options? | PowerSyncConnectionOptions |
Returns
Promise< void >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:317
disconnect()
disconnect():
Promise<void>
Close the sync connection.
Use connect to connect again.
Returns
Promise< void >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:347
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
| Parameter | Type | Default value |
|---|---|---|
options | DisconnectAndClearOptions | DEFAULT_DISCONNECT_CLEAR_OPTIONS |
Returns
Promise< void >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:363
execute()
execute(
sql,parameters?):Promise<QueryResult>
Execute a write (INSERT/UPDATE/DELETE) query and optionally return results.
Parameters
| Parameter | Type |
|---|---|
sql | string |
parameters? | any[] |
Returns
Promise< QueryResult >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:543
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
| Parameter | Type |
|---|---|
sql | string |
parameters? | any[][] |
Returns
Promise< QueryResult >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:553
generateBucketStorageAdapter()
protectedabstractgenerateBucketStorageAdapter():BucketStorageAdapter
Returns
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:188
generateSyncStreamImplementation()
protectedabstractgenerateSyncStreamImplementation(connector):AbstractStreamingSyncImplementation
Parameters
| Parameter | Type |
|---|---|
connector | PowerSyncBackendConnector |
Returns
AbstractStreamingSyncImplementation
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:184
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
| Parameter | Type |
|---|---|
sql | string |
parameters? | any[] |
Returns
Promise< T >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:577
getAll()
getAll<
T>(sql,parameters?):Promise<T[] >
Execute a read-only query and return results.
Type parameters
| Type parameter |
|---|
T |
Parameters
| Parameter | Type |
|---|---|
sql | string |
parameters? | any[] |
Returns
Promise< T[] >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:561
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
| Parameter | Type |
|---|---|
limit | number |
Returns
Promise< null | CrudBatch >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:453
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 >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:489
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
| Parameter | Type |
|---|---|
sql | string |
parameters? | any[] |
Returns
Promise< null | T >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:569
getUploadQueueStats()
getUploadQueueStats(
includeSize?):Promise<UploadQueueStats>
Get upload queue size estimate and count.
Parameters
| Parameter | Type |
|---|---|
includeSize? | boolean |
Returns
Promise< UploadQueueStats >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:419
handleCrudCheckpoint()
privatehandleCrudCheckpoint(lastClientId,writeCheckpoint?):Promise<void>
Parameters
| Parameter | Type |
|---|---|
lastClientId | number |
writeCheckpoint? | string |
Returns
Promise< void >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:521
handleTableChanges()
privatehandleTableChanges(changedTables,watchedTables,onDetectedChanges):void
Parameters
| Parameter | Type |
|---|---|
changedTables | Set< string > |
watchedTables | Set< string > |
onDetectedChanges | (changedTables) => void |
Returns
void
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:911
init()
init():
Promise<void>
Wait for initialization to complete. While initializing is automatic, this helps to catch and report initialization errors.
Returns
Promise< void >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:310
initialize()
protectedinitialize():Promise<void>
Entry point for executing initialization logic. This is to be automatically executed in the constructor.
Returns
Promise< void >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:235
iterateAsyncListeners()
iterateAsyncListeners(
cb):Promise<void>
Parameters
| Parameter | Type |
|---|---|
cb | (listener) => Promise< any > |
Returns
Promise< void >
Inherited from
BaseObserver.iterateAsyncListeners
Source
packages/common/src/utils/BaseObserver.ts:34
iterateListeners()
iterateListeners(
cb):void
Parameters
| Parameter | Type |
|---|---|
cb | (listener) => any |
Returns
void
Inherited from
Source
packages/common/src/utils/BaseObserver.ts:28
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
| Parameter | Type |
|---|---|
options? | SQLWatchOptions |
Returns
AsyncIterable< WatchOnChangeEvent >
Example
async monitorChanges() {
for await (const event of this.powersync.onChange({tables: ['todos']})) {
console.log('Detected change event:', event);
}
}
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:794
onChange(handler, options)
onChange(
handler?,options?): () =>void
See onChangeWithCallback.
Parameters
| Parameter | Type |
|---|---|
handler? | WatchOnChangeHandler |
options? | SQLWatchOptions |
Returns
Function
Returns
void
Example
monitorChanges() {
this.powersync.onChange({
onChange: (event) => {
console.log('Change detected:', event);
}
}, { tables: ['todos'] });
}
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:809
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
| Parameter | Type |
|---|---|
options? | SQLWatchOptions |
Returns
AsyncIterable< WatchOnChangeEvent >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:886
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
| Parameter | Type |
|---|---|
handler? | WatchOnChangeHandler |
options? | SQLWatchOptions |
Returns
Function
Returns
void
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:836
processTableUpdates()
privateprocessTableUpdates(updateNotification,rawTableNames,changedTables):void
Parameters
| Parameter | Type |
|---|---|
updateNotification | UpdateNotification | BatchedUpdateNotification |
rawTableNames | undefined | boolean |
changedTables | Set< string > |
Returns
void
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:925
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
| Parameter | Type |
|---|---|
callback | (db) => Promise< T > |
Returns
Promise< T >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:586
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
| Parameter | Type | Default value |
|---|---|---|
callback | (tx) => Promise< T > | undefined |
lockTimeout | number | DEFAULT_LOCK_TIMEOUT_MS |
Returns
Promise< T >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:608
registerListener()
registerListener(
listener): () =>void
Register a listener for updates to the PowerSync client.
Parameters
| Parameter | Type |
|---|---|
listener | Partial< PowerSyncDBListener > |
Returns
Function
Returns
void
Inherited from
Source
packages/common/src/utils/BaseObserver.ts:21
resolveTables()
resolveTables(
sql,parameters?,options?):Promise<string[] >
Parameters
| Parameter | Type |
|---|---|
sql | string |
parameters? | any[] |
options? | SQLWatchOptions |
Returns
Promise< string[] >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:762
updateHasSynced()
protectedupdateHasSynced():Promise<void>
Returns
Promise< void >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:247
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
| Parameter | Type |
|---|---|
schema | Schema< SchemaType > |
Returns
Promise< void >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:287
waitForFirstSync()
waitForFirstSync(
signal?):Promise<void>
Parameters
| Parameter | Type |
|---|---|
signal? | AbortSignal |
Returns
Promise< void >
A promise which will resolve once the first full sync has completed.
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:204
waitForReady()
waitForReady():
Promise<void>
Returns
Promise< void >
A promise which will resolve once initialization is completed.
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:193
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
| Parameter | Type |
|---|---|
sql | string |
parameters? | any[] |
options? | SQLWatchOptions |
Returns
AsyncIterable< QueryResult >
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
packages/common/src/client/AbstractPowerSyncDatabase.ts:659
watch(sql, parameters, handler, options)
watch(
sql,parameters?,handler?,options?):void
See watchWithCallback.
Parameters
| Parameter | Type |
|---|---|
sql | string |
parameters? | any[] |
handler? | WatchHandler |
options? | SQLWatchOptions |
Returns
void
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
packages/common/src/client/AbstractPowerSyncDatabase.ts:676
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
| Parameter | Type |
|---|---|
sql | string |
parameters? | any[] |
options? | SQLWatchOptions |
Returns
AsyncIterable< QueryResult >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:744
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
| Parameter | Type |
|---|---|
sql | string |
parameters? | any[] |
handler? | WatchHandler |
options? | SQLWatchOptions |
Returns
void
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:702
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
| Parameter | Type |
|---|---|
callback | (db) => Promise< T > |
Returns
Promise< T >
Source
packages/common/src/client/AbstractPowerSyncDatabase.ts:595
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
| Parameter | Type | Default value |
|---|---|---|
callback | (tx) => Promise< T > | undefined |
lockTimeout | number | DEFAULT_LOCK_TIMEOUT_MS |
Returns
Promise< T >