PowerSyncDatabase class abstract

A PowerSync managed database.

Use one instance per database file.

Use PowerSyncDatabase.connect to connect to the PowerSync service, to keep the local database in sync with the remote database.

All changes to local tables are automatically recorded, whether connected or not. Once connected, the changes are uploaded.

Implemented types
Mixed-in types

Constructors

PowerSyncDatabase.new({required Schema schema, required String path, Logger? logger, @Deprecated("Use [PowerSyncDatabase.withFactory] instead.") SqliteConnectionSetup? sqliteSetup})
Open a PowerSyncDatabase.
factory
PowerSyncDatabase.withDatabase({required Schema schema, required SqliteDatabase database, Logger? loggers})
Open a PowerSyncDatabase on an existing SqliteDatabase.
factory
PowerSyncDatabase.withFactory(DefaultSqliteOpenFactory openFactory, {required Schema schema, int maxReaders = SqliteDatabase.defaultMaxReaders, Logger? logger})
Open a PowerSyncDatabase with a PowerSyncOpenFactory.
factory

Properties

clientParams ↔ Map<String, dynamic>?
getter/setter pairinherited
closed → bool
Returns true if the connection is closed
no setterinherited
connected → bool
Whether a connection to the PowerSync service is currently open.
no setterinherited
currentStatus ↔ SyncStatus
Current connection status.
getter/setter pairinherited
database → SqliteDatabase
The underlying database.
no setterinherited
group → ActiveDatabaseGroup
An ActiveDatabaseGroup sharing mutexes for the sync client.
no setterinherited
hashCode → int
The hash code for this object.
no setterinherited
isInitialized → Future<void>
no setterinherited
logger → Logger
The Logger used by this PowerSyncDatabase.
no setterinherited
retryDelay ↔ Duration
Delay between retrying failed requests. Defaults to 5 seconds. Only has an effect if changed before calling connect.
getter/setter pairinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
schema ↔ Schema
Schema used for the local database.
getter/setter pairinherited
statusStream ↔ Stream<SyncStatus>
Use this stream to subscribe to connection status updates.
latefinalinherited
statusStreamController ↔ StreamController<SyncStatus>
getter/setter pairinherited
updates ↔ Stream<UpdateNotification>
Broadcast stream that is notified of any table updates.
latefinalinherited

Methods

baseInit() → Future<void>
inherited
close() → Future<void>
Close the database, releasing resources.
inherited
computeWithDatabase<T>(Future<T> compute(CommonDatabase db)) → Future<T>
See SqliteReadContext.computeWithDatabase.
inherited
connect({required PowerSyncBackendConnector connector, Duration crudThrottleTime = const Duration(milliseconds: 10), Map<String, dynamic>? params}) → Future<void>
Connect to the PowerSync service, and keep the databases in sync.
inherited
connectInternal({required PowerSyncBackendConnector connector, required Duration crudThrottleTime, required AbortController abort, Map<String, dynamic>? params}) → Future<void>
Internal method to establish a sync client connection.
inherited
disconnect() → Future<void>
Close the sync connection.
inherited
disconnectAndClear({bool clearLocal = true}) → Future<void>
Disconnect and clear the database.
inherited
disconnectedAndClear() → Future<void>
inherited
execute(String sql, [List<Object?> parameters = const []]) → Future<ResultSet>
Execute a write query (INSERT, UPDATE, DELETE) and return the results (if any).
inherited
executeBatch(String sql, List<List<Object?>> parameterSets) → Future<void>
Execute a write query (INSERT, UPDATE, DELETE) multiple times with each parameter set. This is more faster than executing separately with each parameter set.
inherited
get(String sql, [List<Object?> parameters = const []]) → Future<Row>
Execute a read-only (SELECT) query and return a single result.
inherited
getAll(String sql, [List<Object?> parameters = const []]) → Future<ResultSet>
Execute a read-only (SELECT) query and return the results.
inherited
getAutoCommit() → Future<bool>
Returns true if auto-commit is enabled. This means the database is not currently in a transaction. This may be true even if a transaction lock is still held, when the transaction has been committed or rolled back.
inherited
getClientId() → Future<String>
Get an unique id for this client. This id is only reset when the database is deleted.
inherited
getCrudBatch({int limit = 100}) → Future<CrudBatch?>
Get a batch of crud data to upload.
inherited
getNextCrudTransaction() → Future<CrudTransaction?>
Get the next recorded transaction to upload.
inherited
getOptional(String sql, [List<Object?> parameters = const []]) → Future<Row?>
Execute a read-only (SELECT) query and return a single optional result.
inherited
getUploadQueueStats({bool includeSize = false}) → Future<UploadQueueStats>
Get upload queue size estimate and count.
inherited
initialize() → Future<void>
Wait for initialization to complete.
inherited
isolateConnectionFactory() → IsolateConnectionFactory<CommonDatabase>
A connection factory that can be passed to different isolates.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onChange(Iterable<String>? tables, {Duration throttle = const Duration(milliseconds: 30), bool triggerImmediately = true}) → Stream<UpdateNotification>
Create a Stream of changes to any of the specified tables.
inherited
readLock<T>(Future<T> callback(SqliteReadContext tx), {String? debugContext, Duration? lockTimeout}) → Future<T>
Takes a read lock, without starting a transaction.
inherited
readTransaction<T>(Future<T> callback(SqliteReadContext tx), {Duration? lockTimeout}) → Future<T>
Open a read-only transaction.
inherited
refreshSchema() → Future<void>
Ensures that all connections are aware of the latest schema changes applied (if any). Queries and watch calls can potentially use outdated schema information after a schema update.
inherited
setStatus(SyncStatus status) → void
inherited
toString() → String
A string representation of this object.
inherited
updateSchema(Schema schema) → Future<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.
inherited
waitForFirstSync({BucketPriority? priority}) → Future<void>
Returns a Future which will resolve once at least one full sync cycle has completed (meaninng that the first consistent checkpoint has been reached across all buckets).
inherited
watch(String sql, {List<Object?> parameters = const [], Duration throttle = const Duration(milliseconds: 30), Iterable<String>? triggerOnTables}) → Stream<ResultSet>
Execute a read query every time the source tables are modified.
inherited
writeLock<T>(Future<T> callback(SqliteWriteContext tx), {String? debugContext, Duration? lockTimeout}) → Future<T>
Takes a global lock, without starting a transaction.
inherited
writeTransaction<T>(Future<T> callback(SqliteWriteContext tx), {Duration? lockTimeout}) → Future<T>
Open a read-write transaction.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited