PowerSyncDatabase
A PowerSync database which provides SQLite functionality which is automatically synced.
Example
export const db = new PowerSyncDatabase({
schema: AppSchema,
database: {
dbFilename: 'example.db'
}
});
Extends
Constructors
new PowerSyncDatabase()
new PowerSyncDatabase(options): PowerSyncDatabase
Parameters
Parameter | Type |
---|---|
options | WebPowerSyncDatabaseOptionsWithAdapter |
Returns
Overrides
AbstractPowerSyncDatabase
.constructor
new PowerSyncDatabase()
new PowerSyncDatabase(options): PowerSyncDatabase
Parameters
Parameter | Type |
---|---|
options | WebPowerSyncDatabaseOptionsWithOpenFactory |
Returns
Overrides
AbstractPowerSyncDatabase
.constructor
new PowerSyncDatabase()
new PowerSyncDatabase(options): PowerSyncDatabase
Parameters
Parameter | Type |
---|---|
options | WebPowerSyncDatabaseOptionsWithSettings |
Returns
Overrides
AbstractPowerSyncDatabase
.constructor
new PowerSyncDatabase()
new PowerSyncDatabase(options): PowerSyncDatabase
Parameters
Parameter | Type |
---|---|
options | WebPowerSyncDatabaseOptions |
Returns
Overrides
AbstractPowerSyncDatabase
.constructor
Properties
Property | Modifier | Type | Default value | Description | Inherited from |
---|---|---|---|---|---|
closed | public | boolean | undefined | Returns true if the connection is closed. | AbstractPowerSyncDatabase .closed |
currentStatus | public | SyncStatus | undefined | Current connection status. | AbstractPowerSyncDatabase .currentStatus |
ready | public | boolean | undefined | - | AbstractPowerSyncDatabase .ready |
sdkVersion | public | string | undefined | - | AbstractPowerSyncDatabase .sdkVersion |
syncStreamImplementation? | public | StreamingSyncImplementation | undefined | - | AbstractPowerSyncDatabase .syncStreamImplementation |
SHARED_MUTEX | static | Mutex | ... | - | - |
Accessors
connected
get connected(): boolean
Whether a connection to the PowerSync service is currently open.
Returns
boolean
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
schema
get schema(): Schema<{}>
Schema used for the local database.
Returns
Schema
<{}>
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
close()
close(options): Promise<void>
Closes the database connection. By default the sync stream client is only disconnected if multiple tabs are not enabled.
Parameters
Parameter | Type | Default value |
---|---|---|
options | PowerSyncCloseOptions | DEFAULT_POWERSYNC_CLOSE_OPTIONS |
Returns
Promise
<void
>
Overrides
AbstractPowerSyncDatabase
.close
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
>
Overrides
AbstractPowerSyncDatabase
.connect
disconnect()
disconnect(): Promise<void>
Close the sync connection.
Use connect to connect again.
Returns
Promise
<void
>
Inherited from
AbstractPowerSyncDatabase
.disconnect
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 |
---|---|
options ? | DisconnectAndClearOptions |
Returns
Promise
<void
>
Inherited from
AbstractPowerSyncDatabase
.disconnectAndClear
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
>
Inherited from
AbstractPowerSyncDatabase
.execute
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
>
Inherited from
AbstractPowerSyncDatabase
.executeBatch
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
>
Inherited from
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
[]>
Inherited from
AbstractPowerSyncDatabase
.getAll
getClientId()
getClientId(): Promise<string>
Get an unique client id for this database.
The id is not reset when the database is cleared, only when the database is deleted.
Returns
Promise
<string
>
Inherited from
AbstractPowerSyncDatabase
.getClientId
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
>
Inherited from
AbstractPowerSyncDatabase
.getCrudBatch
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
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
>
Inherited from
AbstractPowerSyncDatabase
.getOptional
getUploadQueueStats()
getUploadQueueStats(includeSize?): Promise<UploadQueueStats>
Get upload queue size estimate and count.
Parameters
Parameter | Type |
---|---|
includeSize ? | boolean |
Returns
Promise
<UploadQueueStats
>
Inherited from
AbstractPowerSyncDatabase
.getUploadQueueStats
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
iterateAsyncListeners()
iterateAsyncListeners(cb): Promise<void>
Parameters
Parameter | Type |
---|---|
cb | (listener ) => Promise <any > |
Returns
Promise
<void
>
Inherited from
AbstractPowerSyncDatabase
.iterateAsyncListeners
iterateListeners()
iterateListeners(cb): void
Parameters
Parameter | Type |
---|---|
cb | (listener ) => any |
Returns
void
Inherited from
AbstractPowerSyncDatabase
.iterateListeners
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
>
Inherited from
AbstractPowerSyncDatabase
.onChange
Example
async monitorChanges() {
for await (const event of this.powersync.onChange({tables: ['todos']})) {
console.log('Detected change event:', event);
}
}
onChange(handler, options)
onChange(handler?, options?): () => void
See onChangeWithCallback.
Parameters
Parameter | Type |
---|---|
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'] });
}
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
>
Inherited from
AbstractPowerSyncDatabase
.onChangeWithAsyncGenerator
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
Inherited from
AbstractPowerSyncDatabase
.onChangeWithCallback
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
>
Inherited from
AbstractPowerSyncDatabase
.readLock
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 |
---|---|
callback | (tx ) => Promise <T > |
lockTimeout ? | number |
Returns
Promise
<T
>
Inherited from
AbstractPowerSyncDatabase
.readTransaction
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
AbstractPowerSyncDatabase
.registerListener
resolveTables()
resolveTables(
sql,
parameters?,
options?): Promise<string[]>
Parameters
Parameter | Type |
---|---|
sql | string |
parameters ? | any [] |
options ? | SQLWatchOptions |
Returns
Promise
<string
[]>
Inherited from
AbstractPowerSyncDatabase
.resolveTables
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
>
Inherited from
AbstractPowerSyncDatabase
.updateSchema
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.
Inherited from
AbstractPowerSyncDatabase
.waitForFirstSync
waitForReady()
waitForReady(): Promise<void>
Returns
Promise
<void
>
A promise which will resolve once initialization is completed.
Inherited from
AbstractPowerSyncDatabase
.waitForReady
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
>
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) ?? [];
}
}
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
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) ?? [])
}
);
}
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
>
Inherited from
AbstractPowerSyncDatabase
.watchWithAsyncGenerator
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
Inherited from
AbstractPowerSyncDatabase
.watchWithCallback
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
>
Inherited from
AbstractPowerSyncDatabase
.writeLock
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 |
---|---|
callback | (tx ) => Promise <T > |
lockTimeout ? | number |
Returns
Promise
<T
>