Database

The current writable database.

Database-level query, execute, and transaction lazily own one convenience connection; connect() creates further independent connections. A remote bound at open makes sync() available and, by default, starts automatic bidirectional synchronization.

Database.query(self, sql: 'str', params: 'Bindings' = ()) -> 'Rows'

Run exactly one observational statement on the convenience connection. See :meth:Connection.query for intent rules.

Database.execute(self, sql: 'str', params: 'Bindings' = ()) -> 'ExecuteResult'

Run exactly one state-changing statement on the convenience connection. See :meth:Connection.execute for intent rules.

Database.transaction(self, *, mode: 'TransactionMode' = 'immediate') -> '_Transaction'

Begin one managed transaction on the convenience connection. The default mode is immediate.

Database.connect(self, options: 'ConnectionOptions | None' = None) -> 'Connection'

Create another independent SQLite connection to this database.

Each explicit connection takes its own ConnectionOptions. Closing any connection leaves the database and siblings usable; at most one writer proceeds under ordinary SQLite locking.

Database.sync(self) -> 'SyncResult'

Run one complete bidirectional synchronization cycle.

Publishes pending local work first, otherwise validates the remote head and pulls a change. Returns exactly one tagged result: UpToDate, Pushed, Pulled, or Conflict. Conflict is data, not an exception — automatic synchronization pauses at the same state until :meth:resolve_conflict runs. Fails clearly when no remote is bound.

Database.resolve_conflict(self) -> 'ConflictResolution'

Adopt the authenticated remote winner and replay local work.

Downloads and durably stages the winner, applies it behind a database-wide barrier that restarts attached connections, replays safe pending statements, and returns named already-published, replayed, quarantined, and still-pending transaction IDs. Never silently drops or overwrites local work; prepared state survives a crash and a restart.

Database.status(self) -> 'DatabaseStatus'

Return a typed DatabaseStatus: current revision, pending writes, residency and budget, connection count, sync state, next delay, conflict revision, and lifecycle.

Database.close(self) -> 'None'

Close every owned connection, then local storage. Idempotent. Refused while a managed transaction is active. Never closes the caller-owned Remote.