Results and types

Results and status records are grouped by task below.

The tables link to handle pages and Options and policies.

Synchronization results

SyncResult

One result from explicit synchronization.

One of: UpToDate, Pushed, Pulled, Conflict.

SyncOutcome

One outcome reported by automatic synchronization.

One of: SyncResult, Failed.

UpToDate

Synchronization found nothing new to publish or adopt.

• kind (Literal['up_to_date']): The value of kind: up_to_date.
• revision (str | None): The current published revision, if one exists.

Pushed

Synchronization published local writes.

• revision (str): The published revision.
• kind (Literal['pushed']): The value of kind: pushed.

Pulled

Synchronization adopted a remote revision.

• revision (str): The adopted revision.
• replayed (tuple[str, ...]): The transaction IDs replayed during adoption.
• quarantined (tuple[str, ...]): The transaction IDs quarantined during adoption.
• kind (Literal['pulled']): The value of kind: pulled.

Conflict

Synchronization found divergent local and remote history.

• remote_revision (str | None): The remote revision involved in the conflict.
• reason (str): Why synchronization stopped. One of:
  • remote head is not the prepared base: Another device published first.
  • publication retry limit was exhausted: Publication ran out of retries.
  • remote advanced while local changes were pending: Another device published while this device had unpublished work.
  • a conflict resolution was interrupted; resolve_conflict() completes it: Call resolve_conflict() to finish.
• kind (Literal['conflict']): The value of kind: conflict.

ConflictResolution

The adopted revision and results of replaying local work.

• revision (str): The adopted remote revision.
• already_published (tuple[str, ...]): The transaction IDs already present in published history.
• replayed (tuple[str, ...]): The transaction IDs replayed safely.
• quarantined (tuple[str, ...]): The transaction IDs moved into quarantine.
• pending (tuple[str, ...]): The transaction IDs still waiting for publication.

Failed

An automatic synchronization attempt that raised error.

• error (PotluckDBError): The error raised by the automatic attempt.
• kind (Literal['failed']): The value of kind: failed.

Statuses

DatabaseStatus

The current writable database state.

• revision (str | None): The current published base revision, if one exists.
• pending_writes (int): The number of pending local writes.
• local_bytes (int): The resident local bytes.
• local_budget_bytes (int): The configured local storage budget.
• connection_count (int): The number of open connections, including the convenience connection.
• sync_state (str): The scheduling state: manual, unbound, scheduled, synchronizing, idle, backoff, conflict, failed, or closed.
• next_sync_in_ms (int | None): The delay recorded at the last driver step, or None when nothing is scheduled.
• conflict_remote_revision (str | None): The remote revision awaiting conflict resolution.
• closed (bool): Whether the database is closed.

ConnectionStatus

The current connection-owned state.

• transaction_active (bool): Whether a managed transaction is active.
• checkpoint (object | None): The checkpoint runtime status, if enabled.
• prefetch (object | None): The prefetch runtime status, if enabled.
• closed (bool): Whether the connection is closed.

RemoteStatus

The current remote-owned state.

• retained_revisions (int | None): The retained revision count, or None when unknown.
• maintenance_pending (bool): Whether remote maintenance is pending.
• policy_failures (int): The number of retention policy failures.
• closed (bool): Whether the remote is closed.

SnapshotStatus

The pinned revision and local snapshot state.

• revision (str): The pinned revision.
• local_bytes (int): The resident local bytes.
• closed (bool): Whether the snapshot is closed.

Query results

Rows

A query’s answer: columns, the select list’s names in order, and its rows.

• columns (tuple[str, ...]): The select list’s column names, including results without rows.

Row

One result row, readable by position or by column name.

• columns (tuple[str, ...]): The select list’s column names in order.

ExecuteResult

The result of one state-changing SQLite statement.

• rows_affected (int): The number of rows changed by the statement.
• last_insert_id (int | None): The last inserted row ID reported by SQLite, if present.

Maintenance reports

CollectionReport

The result of remote collection or recovery.

• floor_before (str | None): The retention floor before maintenance.
• floor_after (str | None): The retention floor after maintenance.
• epoch (int): The collection epoch.
• marked (int): The number of stored objects that collection marked to keep.
• swept (int): The number of unneeded stored objects that collection tried to delete. Objects that were already gone also count.
• aborted (bool): Whether maintenance stopped without completing collection.

KeyRotationReport

The result of publishing a retained snapshot under a new key.

• source_revision (str): The retained source revision.
• target_revision (str): The target revision.
• source_key_id (str | None): The source encryption key ID, if encrypted.
• target_key_id (str): The target encryption key ID.
• piece_count (int): The number of pieces processed.
• published (bool): Whether the target head was published.

Errors

See Errors for public error codes and actions.

PotluckDBError

A public operation error with a code, category, message, and action.

• code (str): The stable public error code.
• category (ErrorCategory): The caller, temporary, permanent, or internal category.
• message (str): The message for this occurrence.
• action (str): The action for this occurrence.

ErrorCategory

The four public error categories.

One of: caller, temporary, permanent, internal.

Handles

Handles

Type	Summary
Database	The current writable database.
Connection	One independent SQLite connection owned by a Database.
Remote	Reusable synchronization state for one remote.
Snapshot	One exact retained read-only revision.
_Transaction	One managed transaction scope on one connection.

Options and policies

Options and policies

Type	Summary
OpenOptions	Options for open and open_revision.
RemoteOptions	Options owned by a Remote.
ConnectionOptions	Options owned by one connection: busy timeout, the Rows bound maximum_rows, and the prefetch and checkpoint policies.
SyncPolicy	When and how a database with a remote synchronizes.
PrefetchPolicy	Bounded prefetch during statements and in the background for connections with a remote.
CheckpointPolicy	Connection-local WAL checkpoint thresholds for writable databases.
RetentionPolicy	How many revisions a remote retains before collection.

Aliases

Aliases

Name	Definition	Meaning
Bindings	Sequence[Any] | Mapping[str, Any]	An ordered sequence or a mapping from parameter names to values.
QueryEngine	Literal['sqlite', 'duckdb']	SQLite or DuckDB.
TransactionMode	Literal['deferred', 'immediate', 'exclusive']	Deferred, immediate, or exclusive.

Python values

Python values

Type	Meaning
int	A Python integer value.
float	A Python floating-point value.
str	A Python text value.
bytes	A Python byte sequence.
bool	A Python Boolean value.
None	The Python null value.
tuple	An ordered immutable sequence.
Any	A value whose annotation does not restrict its Python type.