PowerSyncDatabase

Experimental Alpha

PowerSyncDatabase class for managing database connections and sync implementations. This extends the WebPowerSyncDatabase to provide platform-specific implementations for Capacitor environments (iOS and Android).

Extends

• PowerSyncDatabase

Constructors

new PowerSyncDatabase()

new PowerSyncDatabase(options): PowerSyncDatabase

Alpha Experimental

Parameters

Parameter	Type
options	WebPowerSyncDatabaseOptionsWithAdapter

Returns

PowerSyncDatabase

Inherited from

WebPowerSyncDatabase.constructor

new PowerSyncDatabase()

new PowerSyncDatabase(options): PowerSyncDatabase

Alpha Experimental

Parameters

Parameter	Type
options	WebPowerSyncDatabaseOptionsWithOpenFactory

Returns

PowerSyncDatabase

Inherited from

WebPowerSyncDatabase.constructor

new PowerSyncDatabase()

new PowerSyncDatabase(options): PowerSyncDatabase

Alpha Experimental

Parameters

Parameter	Type
options	WebPowerSyncDatabaseOptionsWithSettings

Returns

PowerSyncDatabase

Inherited from

WebPowerSyncDatabase.constructor

new PowerSyncDatabase()

new PowerSyncDatabase(options): PowerSyncDatabase

Alpha Experimental

Parameters

Parameter	Type
options	WebPowerSyncDatabaseOptions

Returns

PowerSyncDatabase

Inherited from

WebPowerSyncDatabase.constructor

Properties

Property	Modifier	Type	Description	Inherited from
closed	public	boolean	Alpha Returns true if the connection is closed.	WebPowerSyncDatabase.closed
currentStatus	public	SyncStatus	Alpha Current connection status.	WebPowerSyncDatabase.currentStatus
logger	public	ILogger	Alpha Experimental	WebPowerSyncDatabase.logger
ready	public	boolean	Alpha Experimental	WebPowerSyncDatabase.ready
sdkVersion	public	string	Alpha Experimental	WebPowerSyncDatabase.sdkVersion
triggers	readonly	TriggerManager	Experimental Allows creating SQLite triggers which can be used to track various operations on SQLite tables.	WebPowerSyncDatabase.triggers
SHARED_MUTEX	static	Mutex	Alpha Experimental	WebPowerSyncDatabase.SHARED_MUTEX

Accessors

connected

Get Signature

get connected(): boolean

Alpha

Whether a connection to the PowerSync service is currently open.

Returns

boolean

Inherited from

WebPowerSyncDatabase.connected

---

connecting

Get Signature

get connecting(): boolean

Alpha Experimental

Returns

boolean

Inherited from

WebPowerSyncDatabase.connecting

---

connectionOptions

Get Signature

get connectionOptions(): null | InternalConnectionOptions

Alpha

The resolved connection options used to connect to the PowerSync service.

Returns

null | InternalConnectionOptions

The resolved connection options used to connect to the PowerSync service or null if connect() has not been called.

Inherited from

WebPowerSyncDatabase.connectionOptions

---

connector

Get Signature

get connector(): null | PowerSyncBackendConnector

Alpha

The connector used to connect to the PowerSync service.

Returns

null | PowerSyncBackendConnector

The connector used to connect to the PowerSync service or null if connect() has not been called.

Inherited from

WebPowerSyncDatabase.connector

---

database

Get Signature

get database(): DBAdapter

Alpha

The underlying database.

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

Returns

DBAdapter

Inherited from

WebPowerSyncDatabase.database

---

schema

Get Signature

get schema(): Schema<{}>

Alpha

Schema used for the local database.

Returns

Schema<{}>

Inherited from

WebPowerSyncDatabase.schema

---

syncStreamImplementation

Get Signature

get syncStreamImplementation(): null | StreamingSyncImplementation

Alpha Experimental

Returns

null | StreamingSyncImplementation

Inherited from

WebPowerSyncDatabase.syncStreamImplementation

Methods

_initialize()

_initialize(): Promise<void>

Alpha

Returns

Promise<void>

Inherited from

WebPowerSyncDatabase._initialize

---

close()

close(options?): Promise<void>

Alpha

Parameters

Parameter	Type
options?	PowerSyncCloseOptions

Returns

Promise<void>

Inherited from

WebPowerSyncDatabase.close

---

connect()

connect(connector, options?): Promise<void>

Alpha

Parameters

Parameter	Type
connector	PowerSyncBackendConnector
options?	PowerSyncConnectionOptions

Returns

Promise<void>

Inherited from

WebPowerSyncDatabase.connect

---

customQuery()

customQuery<RowType>(query): Query<RowType>

Alpha

Type Parameters

Type Parameter
RowType

Parameters

Parameter	Type
query	WatchCompatibleQuery<RowType[]>

Returns

Query<RowType>

Example

// Potentially a query from an ORM like Drizzle
const query = db.select().from(lists);

const watchedTodos = powersync.customQuery(query)
.watch()
// OR use .differentialWatch() for fine-grained watches.

Inherited from

WebPowerSyncDatabase.customQuery

---

disconnect()

disconnect(): Promise<void>

Alpha

Returns

Promise<void>

Inherited from

WebPowerSyncDatabase.disconnect

---

disconnectAndClear()

disconnectAndClear(options?): Promise<void>

Alpha

Parameters

Parameter	Type
options?	DisconnectAndClearOptions

Returns

Promise<void>

Inherited from

WebPowerSyncDatabase.disconnectAndClear

---

dispose()

dispose(): void

Alpha

Returns

void

Deprecated

Use AbstractPowerSyncDatabase#close instead. Clears all listeners registered by AbstractPowerSyncDatabase#registerListener.

Inherited from

WebPowerSyncDatabase.dispose

---

execute()

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

Alpha

Parameters

Parameter	Type	Description
sql	string	The SQL query to execute
parameters?	any[]	Optional array of parameters to bind to the query

Returns

Promise<QueryResult>

The query result as an object with structured key-value pairs

Inherited from

WebPowerSyncDatabase.execute

---

executeBatch()

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

Alpha

Parameters

Parameter	Type	Description
sql	string	The SQL query to execute
parameters?	any[][]	Optional 2D array of parameter sets, where each inner array is a set of parameters for one execution

Returns

Promise<QueryResult>

The query result

Inherited from

WebPowerSyncDatabase.executeBatch

---

executeRaw()

executeRaw(sql, parameters?): Promise<any[][]>

Alpha

Parameters

Parameter	Type	Description
sql	string	The SQL query to execute
parameters?	any[]	Optional array of parameters to bind to the query

Returns

Promise<any[][]>

The raw query result from the underlying database as a nested array of raw values, where each row is represented as an array of column values without field names.

Inherited from

WebPowerSyncDatabase.executeRaw

---

get()

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

Alpha

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
sql	string	The SQL query to execute
parameters?	any[]	Optional array of parameters to bind to the query

Returns

Promise<T>

The first result matching the query

Throws

Error if no rows are returned

Inherited from

WebPowerSyncDatabase.get

---

getAll()

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

Alpha

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
sql	string	The SQL query to execute
parameters?	any[]	Optional array of parameters to bind to the query

Returns

Promise<T[]>

An array of results

Inherited from

WebPowerSyncDatabase.getAll

---

getClientId()

getClientId(): Promise<string>

Alpha

Returns

Promise<string>

A unique identifier for the database instance

Inherited from

WebPowerSyncDatabase.getClientId

---

getCrudBatch()

getCrudBatch(limit?): Promise<null | CrudBatch>

Alpha

Parameters

Parameter	Type	Description
limit?	number	Maximum number of CRUD entries to include in the batch

Returns

Promise<null | CrudBatch>

A batch of CRUD operations to upload, or null if there are none

Inherited from

WebPowerSyncDatabase.getCrudBatch

---

getCrudTransactions()

getCrudTransactions(): AsyncIterable<CrudTransaction, null>

Alpha

Returns

AsyncIterable<CrudTransaction, null>

Inherited from

WebPowerSyncDatabase.getCrudTransactions

---

getNextCrudTransaction()

getNextCrudTransaction(): Promise<null | CrudTransaction>

Alpha

Returns

Promise<null | CrudTransaction>

A transaction of CRUD operations to upload, or null if there are none

Inherited from

WebPowerSyncDatabase.getNextCrudTransaction

---

getOptional()

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

Alpha

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
sql	string	The SQL query to execute
parameters?	any[]	Optional array of parameters to bind to the query

Returns

Promise<null | T>

The first result if found, or null if no results are returned

Inherited from

WebPowerSyncDatabase.getOptional

---

getUploadQueueStats()

getUploadQueueStats(includeSize?): Promise<UploadQueueStats>

Alpha

Parameters

Parameter	Type
includeSize?	boolean

Returns

Promise<UploadQueueStats>

Inherited from

WebPowerSyncDatabase.getUploadQueueStats

---

init()

init(): Promise<void>

Alpha

Returns

Promise<void>

Inherited from

WebPowerSyncDatabase.init

---

iterateAsyncListeners()

iterateAsyncListeners(cb): Promise<void>

Alpha Experimental

Parameters

Parameter	Type
cb	(listener) => Promise<any>

Returns

Promise<void>

Inherited from

WebPowerSyncDatabase.iterateAsyncListeners

---

iterateListeners()

iterateListeners(cb): void

Alpha Experimental

Parameters

Parameter	Type
cb	(listener) => any

Returns

void

Inherited from

WebPowerSyncDatabase.iterateListeners

---

onChange()

Call Signature

onChange(options?): AsyncIterable<WatchOnChangeEvent>

Alpha

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?	SQLOnChangeOptions

Returns

AsyncIterable<WatchOnChangeEvent>

Example

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

Inherited from

WebPowerSyncDatabase.onChange

Call Signature

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

Alpha

See onChangeWithCallback.

Parameters

Parameter	Type
handler?	WatchOnChangeHandler
options?	SQLOnChangeOptions

Returns

Function

Returns

void

Example

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

Inherited from

WebPowerSyncDatabase.onChange

---

onChangeWithAsyncGenerator()

onChangeWithAsyncGenerator(options?): AsyncIterable<WatchOnChangeEvent>

Alpha

Parameters

Parameter	Type	Description
options?	SQLWatchOptions	Options for configuring watch behavior

Returns

AsyncIterable<WatchOnChangeEvent>

An AsyncIterable that yields change events whenever the specified tables change

Inherited from

WebPowerSyncDatabase.onChangeWithAsyncGenerator

---

onChangeWithCallback()

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

Alpha

Parameters

Parameter	Type	Description
handler?	WatchOnChangeHandler	Callbacks for handling change events and errors
options?	SQLOnChangeOptions	Options for configuring watch behavior

Returns

Function

A dispose function to stop watching for changes

Returns

void

Inherited from

WebPowerSyncDatabase.onChangeWithCallback

---

query()

query<RowType>(query): Query<RowType>

Alpha

Type Parameters

Type Parameter
RowType

Parameters

Parameter	Type
query	ArrayQueryDefinition<RowType>

Returns

Query<RowType>

Example

const watchedTodos = powersync.query({
 sql: `SELECT photo_id as id FROM todos WHERE photo_id IS NOT NULL`,
 parameters: [],
 mapper: (row) => ({
   ...row,
   created_at: new Date(row.created_at as string)
 })
})
.watch()
// OR use .differentialWatch() for fine-grained watches.

Inherited from

WebPowerSyncDatabase.query

---

readLock()

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

Alpha

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
callback	(db) => Promise<T>

Returns

Promise<T>

Inherited from

WebPowerSyncDatabase.readLock

---

readTransaction()

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

Alpha

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
callback	(tx) => Promise<T>	Function to execute within the transaction
lockTimeout?	number	Time in milliseconds to wait for a lock before throwing an error

Returns

Promise<T>

The result of the callback

Throws

Error if the lock cannot be obtained within the timeout period

Inherited from

WebPowerSyncDatabase.readTransaction

---

registerListener()

registerListener(listener): () => void

Alpha

Parameters

Parameter	Type
listener	Partial<PowerSyncDBListener>

Returns

Function

Returns

void

Inherited from

WebPowerSyncDatabase.registerListener

---

resolveTables()

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

Alpha

Parameters

Parameter	Type	Description
sql	string	The SQL query to analyze
parameters?	any[]	Optional parameters for the SQL query
options?	SQLWatchOptions	Optional watch options that may contain explicit table list

Returns

Promise<string[]>

Array of table names that the query depends on

Inherited from

WebPowerSyncDatabase.resolveTables

---

syncStream()

syncStream(name, params?): SyncStream

Experimental

Parameters

Parameter	Type	Description
name	string	The name of the stream to subscribe to.
params?	Record<string, any>	Optional parameters for the stream subscription.

Returns

SyncStream

A SyncStream instance that can be subscribed to. Sync streams are currently in alpha.

Inherited from

WebPowerSyncDatabase.syncStream

---

updateSchema()

updateSchema(schema): Promise<void>

Alpha

Parameters

Parameter	Type
schema	Schema

Returns

Promise<void>

Inherited from

WebPowerSyncDatabase.updateSchema

---

waitForFirstSync()

waitForFirstSync(request?): Promise<void>

Alpha

Parameters

Parameter	Type	Description
request?	| AbortSignal | { priority: number; signal: AbortSignal; }	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.

Returns

Promise<void>

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

Inherited from

WebPowerSyncDatabase.waitForFirstSync

---

waitForReady()

waitForReady(): Promise<void>

Alpha

Returns

Promise<void>

A promise which will resolve once initialization is completed.

Inherited from

WebPowerSyncDatabase.waitForReady

---

waitForStatus()

waitForStatus(predicate, signal?): Promise<void>

Alpha

Parameters

Parameter	Type
predicate	(status) => any
signal?	AbortSignal

Returns

Promise<void>

Inherited from

WebPowerSyncDatabase.waitForStatus

---

watch()

Call Signature

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

Alpha

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

WebPowerSyncDatabase.watch

Call Signature

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

Alpha

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

WebPowerSyncDatabase.watch

---

watchWithAsyncGenerator()

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

Alpha

Parameters

Parameter	Type	Description
sql	string	The SQL query to execute
parameters?	any[]	Optional array of parameters to bind to the query
options?	SQLWatchOptions	Options for configuring watch behavior

Returns

AsyncIterable<QueryResult>

An AsyncIterable that yields QueryResults whenever the data changes

Inherited from

WebPowerSyncDatabase.watchWithAsyncGenerator

---

watchWithCallback()

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

Alpha

Parameters

Parameter	Type	Description
sql	string	The SQL query to execute
parameters?	any[]	Optional array of parameters to bind to the query
handler?	WatchHandler	Callbacks for handling results and errors
options?	SQLWatchOptions	Options for configuring watch behavior

Returns

void

Inherited from

WebPowerSyncDatabase.watchWithCallback

---

writeLock()

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

Alpha

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
callback	(db) => Promise<T>

Returns

Promise<T>

Inherited from

WebPowerSyncDatabase.writeLock

---

writeTransaction()

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

Alpha

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
callback	(tx) => Promise<T>	Function to execute within the transaction
lockTimeout?	number	Time in milliseconds to wait for a lock before throwing an error

Returns

Promise<T>

The result of the callback

Throws

Error if the lock cannot be obtained within the timeout period

Inherited from

WebPowerSyncDatabase.writeTransaction