PowerSyncTauriDatabase

A PowerSync database backed by a Rust-owned structure for Tauri apps.

Extends

BasePowerSyncDatabase<TauriPowerSyncOpenOptions>

Constructors

new PowerSyncTauriDatabase()

new PowerSyncTauriDatabase(options): PowerSyncTauriDatabase

Parameters

Parameter	Type
`options`	`TauriPowerSyncOpenOptions`

Returns

PowerSyncTauriDatabase

Overrides

BasePowerSyncDatabase<TauriPowerSyncOpenOptions>.constructor

Properties

Property	Modifier	Type	Description	Inherited from
`closed`	`public`	`boolean`	Returns true if the connection is closed.	`BasePowerSyncDatabase.closed`
`currentStatus`	`public`	`SyncStatusSnapshot`	Current connection status.	`BasePowerSyncDatabase.currentStatus`
`logger`	`public`	`PowerSyncLogger`	-	`BasePowerSyncDatabase.logger`
`ready`	`public`	`boolean`	-	`BasePowerSyncDatabase.ready`
`sdkVersion`	`public`	`string`	-	`BasePowerSyncDatabase.sdkVersion`
`triggers`	`readonly`	`TriggerManager`	`Experimental` Allows creating SQLite triggers which can be used to track various operations on SQLite tables.	`BasePowerSyncDatabase.triggers`

Accessors

connected

Get Signature

get connected(): boolean

Whether a connection to the PowerSync service is currently open.

Returns

boolean

Inherited from

BasePowerSyncDatabase.connected

connecting

Get Signature

get connecting(): boolean

Returns

boolean

Inherited from

BasePowerSyncDatabase.connecting

connectionOptions

Get Signature

get connectionOptions(): null | Required<SyncOptions>

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

Returns

null | Required<SyncOptions>

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

Inherited from

BasePowerSyncDatabase.connectionOptions

connector

Get Signature

get connector(): null | PowerSyncBackendConnector

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

BasePowerSyncDatabase.connector

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

BasePowerSyncDatabase.database

rustHandle

Get Signature

get rustHandle(): number

The id of the wrapped Rust database instance.

This can be used together with custom Rust code to share a PowerSync database between JavaScript and Rust.

Returns

number

schema

Get Signature

get schema(): Schema<{}>

Schema used for the local database.

Returns

Schema<{}>

Inherited from

BasePowerSyncDatabase.schema

syncStreamImplementation

Get Signature

get syncStreamImplementation(): null | StreamingSyncImplementation

Returns

null | StreamingSyncImplementation

Inherited from

BasePowerSyncDatabase.syncStreamImplementation

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

BasePowerSyncDatabase._initialize

close()

close(options?): Promise<void>

Parameters

Parameter	Type
`options`?	`PowerSyncCloseOptions`

Returns

Promise<void>

Overrides

BasePowerSyncDatabase.close

connect()

connect(): Promise<void>

Returns

Promise<void>

Overrides

BasePowerSyncDatabase.connect

createMutex()

createMutex(): Mutex

Internal

Returns

Mutex

Inherited from

BasePowerSyncDatabase.createMutex

customQuery()

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

Allows building a WatchedQuery using an existing WatchCompatibleQuery. The watched query will use the provided WatchCompatibleQuery.execute method to query results.

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

BasePowerSyncDatabase.customQuery

disconnect()

disconnect(): Promise<void>

Returns

Promise<void>

Overrides

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

BasePowerSyncDatabase.disconnectAndClear

dispose()

dispose(): void

Returns

void

Inherited from

BasePowerSyncDatabase.dispose

execute()

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

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

When using the default client-side JSON-based view system, the returned result's rowsAffected may be 0 for successful UPDATE and DELETE statements. Use a RETURNING clause and inspect result.rows when you need to confirm which rows changed.

Type Parameters

Type Parameter	Default type
`T`	`SqliteRecord`

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<T>>

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

Inherited from

BasePowerSyncDatabase.execute

executeBatch()

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

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	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<never>>

The query result

Inherited from

BasePowerSyncDatabase.executeBatch

executeRaw()

executeRaw(sql, parameters?): Promise<RawQueryResult>

Execute a SQL write (INSERT/UPDATE/DELETE) query directly on the database without any PowerSync processing. This bypasses certain PowerSync abstractions and is useful for accessing the raw database results.

Parameters

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

Returns

Promise<RawQueryResult>

The RawQueryResult representing each row as an array.

Inherited from

BasePowerSyncDatabase.executeRaw

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

BasePowerSyncDatabase.get

getAll()

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

Execute a read-only query and return results.

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

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

A unique identifier for the database instance

Inherited from

BasePowerSyncDatabase.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 the limit parameter 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	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

BasePowerSyncDatabase.getCrudBatch

getCrudTransactions()

getCrudTransactions(): AsyncIterable<CrudTransaction, null>

Returns an async iterator of completed transactions with local writes against the database.

This is typically used from the PowerSyncBackendConnector.uploadData callback. Each entry emitted by the returned iterator is a full transaction containing all local writes made while that transaction was active.

Unlike CommonPowerSyncDatabase.getNextCrudTransaction, which always returns the oldest transaction that hasn't been CrudTransaction.completed yet, this iterator can be used to receive multiple transactions. Calling CrudTransaction.complete will mark that and all prior transactions emitted by the iterator as completed.

This can be used to upload multiple transactions in a single batch, e.g with:

let lastTransaction = null;
let batch = [];

for await (const transaction of database.getCrudTransactions()) {
  batch.push(...transaction.crud);
  lastTransaction = transaction;

  if (batch.length > 10) {
    break;
   }
}

If there is no local data to upload, the async iterator complete without emitting any items.

Note that iterating over async iterables requires a polyfill for React Native.

Returns

AsyncIterable<CrudTransaction, null>

Inherited from

BasePowerSyncDatabase.getCrudTransactions

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

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

Inherited from

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

BasePowerSyncDatabase.getOptional

getUploadQueueStats()

getUploadQueueStats(includeSize?): Promise<UploadQueueStats>

Get upload queue size estimate and count.

Parameters

Parameter	Type
`includeSize`?	`boolean`

Returns

Promise<UploadQueueStats>

Inherited from

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

BasePowerSyncDatabase.init

iterateAsyncListeners()

iterateAsyncListeners(cb): Promise<void>

Parameters

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

Returns

Promise<void>

Inherited from

BasePowerSyncDatabase.iterateAsyncListeners

iterateListeners()

iterateListeners(cb): void

Parameters

Parameter	Type
`cb`	(`listener`) => `any`

Returns

void

Inherited from

BasePowerSyncDatabase.iterateListeners

onChange()

Call Signature

onChange(options?): AsyncIterable<WatchOnChangeEvent>

This version of onChange uses AsyncGenerator, for documentation see CommonPowerSyncDatabase.onChangeWithAsyncGenerator. Can be overloaded to use a callback handler instead, for documentation see CommonPowerSyncDatabase.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

BasePowerSyncDatabase.onChange

Call Signature

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

See CommonPowerSyncDatabase.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

BasePowerSyncDatabase.onChange

onChangeWithAsyncGenerator()

onChangeWithAsyncGenerator(options?): AsyncIterable<WatchOnChangeEvent>

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

This is preferred over CommonPowerSyncDatabase.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	Description
`options`?	`SQLWatchOptions`	Options for configuring watch behavior

Returns

AsyncIterable<WatchOnChangeEvent>

An AsyncIterable that yields change events whenever the specified tables change

Inherited from

BasePowerSyncDatabase.onChangeWithAsyncGenerator

onChangeWithCallback()

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

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

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

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

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

BasePowerSyncDatabase.onChangeWithCallback

query()

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

Allows defining a query which can be used to build a WatchedQuery. The defined query will be executed with CommonPowerSyncDatabase#getAll. An optional mapper function can be provided to transform the results.

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

BasePowerSyncDatabase.query

readLock()

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

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

Type Parameters

Type Parameter
`T`

Parameters

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

Returns

Promise<T>

Inherited from

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

BasePowerSyncDatabase.readTransaction

registerListener()

registerListener(listener): () => void

Parameters

Parameter	Type
`listener`	`Partial`<`PowerSyncDBListener`>

Returns

Function

Returns

void

Inherited from

BasePowerSyncDatabase.registerListener

resolveTables()

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

Resolves the list of tables that are used in a SQL query. If tables are specified in the options, those are used directly. Otherwise, analyzes the query using EXPLAIN to determine which tables are accessed.

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

BasePowerSyncDatabase.resolveTables

syncStream()

syncStream(name, params?): SyncStream

Parameters

Parameter	Type
`name`	`string`
`params`?	`Record`<`string`, `any`>

Returns

SyncStream

Overrides

BasePowerSyncDatabase.syncStream

updateSchema()

updateSchema(): Promise<void>

Returns

Promise<void>

Overrides

BasePowerSyncDatabase.updateSchema

waitForFirstSync()

waitForFirstSync(request?): Promise<void>

Wait for the first sync operation to complete.

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

BasePowerSyncDatabase.waitForFirstSync

waitForReady()

waitForReady(): Promise<void>

Returns

Promise<void>

A promise which will resolve once initialization is completed.

Inherited from

BasePowerSyncDatabase.waitForReady

waitForStatus()

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

Waits for the first sync status for which the status callback returns a truthy value.

Parameters

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

Returns

Promise<void>

Inherited from

BasePowerSyncDatabase.waitForStatus

watch()

Call Signature

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

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

Parameters

Parameter	Type
`sql`	`string`
`parameters`?	`any`[]
`options`?	`SQLWatchOptions`

Returns

AsyncIterable<QueryResult<SqliteRecord>>

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

BasePowerSyncDatabase.watch

Call Signature

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

See CommonPowerSyncDatabase.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

BasePowerSyncDatabase.watch

watchWithAsyncGenerator()

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

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

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<SqliteRecord>>

An AsyncIterable that yields QueryResults whenever the data changes

Inherited from

BasePowerSyncDatabase.watchWithAsyncGenerator

watchWithCallback()

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

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

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

BasePowerSyncDatabase.watchWithCallback

writeLock()

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

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

Type Parameters

Type Parameter
`T`

Parameters

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

Returns

Promise<T>

Inherited from

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

BasePowerSyncDatabase.writeTransaction

Extends​

Constructors​

new PowerSyncTauriDatabase()​

Parameters​

Returns​

Overrides​

Properties​

Accessors​

connected​

Get Signature​

Returns​

Inherited from​

connecting​

Get Signature​

Returns​

Inherited from​

connectionOptions​

Get Signature​

Returns​

Inherited from​

connector​

Get Signature​

Returns​

Inherited from​

database​

Get Signature​

Returns​

Inherited from​

rustHandle​

Get Signature​

Returns​

schema​

Get Signature​

Returns​

Inherited from​

syncStreamImplementation​

Get Signature​

Returns​

Inherited from​

Methods​

_initialize()​

Returns​

Overrides​

close()​

Parameters​

Returns​

Overrides​

connect()​

Returns​

Overrides​

createMutex()​

Returns​

Inherited from​

customQuery()​

Type Parameters​

Parameters​

Returns​

Example​

Inherited from​

disconnect()​

Returns​

Overrides​

disconnectAndClear()​

Parameters​

Returns​

Inherited from​

dispose()​

Returns​

Inherited from​

execute()​

Type Parameters​

Parameters​

Returns​

Inherited from​

executeBatch()​

Parameters​

Returns​

Inherited from​

executeRaw()​

Parameters​

Extends

Constructors

new PowerSyncTauriDatabase()

Parameters

Returns

Overrides

Properties

Accessors

connected

Get Signature

Returns

Inherited from

connecting

Get Signature

Returns

Inherited from

connectionOptions

Get Signature

Returns

Inherited from

connector

Get Signature

Returns

Inherited from

database

Get Signature

Returns

Inherited from

rustHandle

Get Signature

Returns

schema

Get Signature

Returns

Inherited from

syncStreamImplementation

Get Signature

Returns

Inherited from

Methods

_initialize()

Returns

Overrides

close()

Parameters

Returns

Overrides

connect()

Returns

Overrides

createMutex()

Returns

Inherited from

customQuery()

Type Parameters

Parameters

Returns

Example

Inherited from

disconnect()

Returns

Overrides

disconnectAndClear()

Parameters

Returns

Inherited from

dispose()

Returns

Inherited from

execute()

Type Parameters

Parameters

Returns

Inherited from

executeBatch()

Parameters

Returns

Inherited from

executeRaw()

Parameters