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

• AbstractPowerSyncDatabase

Constructors

new PowerSyncDatabase()

new PowerSyncDatabase(options): PowerSyncDatabase

Parameters

Parameter	Type
options	WebPowerSyncDatabaseOptionsWithAdapter

Returns

PowerSyncDatabase

Overrides

AbstractPowerSyncDatabase.constructor

new PowerSyncDatabase()

new PowerSyncDatabase(options): PowerSyncDatabase

Parameters

Parameter	Type
options	WebPowerSyncDatabaseOptionsWithOpenFactory

Returns

PowerSyncDatabase

Overrides

AbstractPowerSyncDatabase.constructor

new PowerSyncDatabase()

new PowerSyncDatabase(options): PowerSyncDatabase

Parameters

Parameter	Type
options	WebPowerSyncDatabaseOptionsWithSettings

Returns

PowerSyncDatabase

Overrides

AbstractPowerSyncDatabase.constructor

new PowerSyncDatabase()

new PowerSyncDatabase(options): PowerSyncDatabase

Parameters

Parameter	Type
options	WebPowerSyncDatabaseOptions

Returns

PowerSyncDatabase

Overrides

AbstractPowerSyncDatabase.constructor

Properties

Property	Modifier	Type	Description	Inherited from
closed	public	boolean	Returns true if the connection is closed.	AbstractPowerSyncDatabase.closed
currentStatus	public	SyncStatus	Current connection status.	AbstractPowerSyncDatabase.currentStatus
ready	public	boolean	-	AbstractPowerSyncDatabase.ready
sdkVersion	public	string	-	AbstractPowerSyncDatabase.sdkVersion
syncStreamImplementation?	public	StreamingSyncImplementation	-	AbstractPowerSyncDatabase.syncStreamImplementation
SHARED_MUTEX	static	Mutex	-	-

Accessors

connected

Get Signature

get connected(): boolean

Whether a connection to the PowerSync service is currently open.

Returns

boolean

Inherited from

AbstractPowerSyncDatabase.connected

---

connecting

Get Signature

get connecting(): boolean

Returns

boolean

Inherited from

AbstractPowerSyncDatabase.connecting

---

database

Get Signature

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

Inherited from

AbstractPowerSyncDatabase.database

---

schema

Get Signature

get schema(): Schema<{}>

Schema used for the local database.

Returns

Schema<{}>

Inherited from

AbstractPowerSyncDatabase.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

AbstractPowerSyncDatabase.get

---

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()

Call Signature

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);
  }
}

Inherited from

AbstractPowerSyncDatabase.onChange

Call Signature

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'] });
}

Inherited from

AbstractPowerSyncDatabase.onChange

---

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

---

resolvedConnectionOptions()

resolvedConnectionOptions(options?): Required<AdditionalConnectionOptions>

Parameters

Parameter	Type
options?	PowerSyncConnectionOptions

Returns

Required<AdditionalConnectionOptions>

Inherited from

AbstractPowerSyncDatabase.resolvedConnectionOptions

---

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

Returns

Promise<void>

Inherited from

AbstractPowerSyncDatabase.updateSchema

---

waitForFirstSync()

waitForFirstSync(request?): Promise<void>

Wait for the first sync operation to complete.

Parameters

Parameter	Type
request?	| AbortSignal | { priority: number; signal: AbortSignal; }

Returns

Promise<void>

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

Argument

request Either an abort signal (after which the promise will complete regardless of whether a full sync was completed) or an object providing an abort signal and a priority target. When a priority target is set, the promise may complete when all buckets with the given (or higher) priorities have been synchronized. This can be earlier than a complete sync.

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()

Call Signature

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) ?? [];
  }
}

Inherited from

AbstractPowerSyncDatabase.watch

Call Signature

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) ?? [])
    }
  );
}

Inherited from

AbstractPowerSyncDatabase.watch

---

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>

Inherited from

AbstractPowerSyncDatabase.writeTransaction