Snapshot

Python: also in Node · Go · Rust · Swift · Dart · Java and Kotlin · .NET · C++ · Objective-C

One exact retained read-only revision.

A snapshot has no mutation, transaction, connection, checkpoint, synchronization or conflict API. Reads fetch and authenticate pages on demand, as on a writable database. Concepts explains revisions and retention.

At a glance

Read

• query(): Run one statement with read execution intent against the pinned revision.
• status(): Return a typed SnapshotStatus of snapshot-owned state only.

Close

• close(): Close the snapshot.

Read

Snapshot.query

Run one statement with read execution intent against the pinned revision.

Snapshot.query(
    sql: str,
    params: Bindings = (),
    *,
    engine: QueryEngine = 'sqlite',
) -> Rows

Parameters

• sql: One SQLite statement.
• params: Values for the statement’s placeholders.
• engine: The SQLite or DuckDB read engine.

Returns

Rows. The result rows from the pinned revision.

Errors

• read_only_snapshot: The statement tries to write to the snapshot. Use a writable database for changes.
• snapshot_closed: The snapshot is closed.
• invalid_argument: An argument has the wrong type or value.
• result_limit_exceeded: The result has more rows than ConnectionOptions.maximum_rows.
• analytical_engine_unavailable: The analytics package is not installed and no library is named or found.
• transaction_control_sql: The statement starts with BEGIN, COMMIT, END, RELEASE, ROLLBACK, or SAVEPOINT. Use a writable database and its transaction() method instead.

Other errors can occur. See Errors for every code.

Example

import potluckdb
options = potluckdb.OpenOptions(sync_policy=potluckdb.SyncPolicy.manual())
with potluckdb.Remote.from_directory("shared") as remote:
    with potluckdb.open("writer", remote, options) as db:
        db.execute("CREATE TABLE note (id INTEGER PRIMARY KEY)")
        db.execute("INSERT INTO note VALUES (?)", (13,))
        revision = db.sync().revision
    with potluckdb.open_revision("view", revision, remote) as snapshot:
        print(snapshot.query("SELECT id FROM note")[0]["id"])

Details

Bounded by the snapshot connection’s maximum_rows.

Snapshot.status

Return a typed SnapshotStatus of snapshot-owned state only.

Snapshot.status() -> SnapshotStatus

Returns

SnapshotStatus. The pinned revision and local snapshot state.

Example

import potluckdb
options = potluckdb.OpenOptions(sync_policy=potluckdb.SyncPolicy.manual())
with potluckdb.Remote.from_directory("shared") as remote:
    with potluckdb.open("writer", remote, options) as db:
        db.execute("CREATE TABLE note (id INTEGER PRIMARY KEY)")
        revision = db.sync().revision
    with potluckdb.open_revision("view", revision, remote) as snapshot:
        print(snapshot.status().revision == revision)

Close

Snapshot.close

Close the snapshot.

Snapshot.close() -> None

Example

import potluckdb
options = potluckdb.OpenOptions(sync_policy=potluckdb.SyncPolicy.manual())
with potluckdb.Remote.from_directory("shared") as remote:
    with potluckdb.open("writer", remote, options) as db:
        db.execute("CREATE TABLE note (id INTEGER PRIMARY KEY)")
        revision = db.sync().revision
    with potluckdb.open_revision("view", revision, remote) as snapshot:
        snapshot.close()
        print(snapshot.status().closed)

Details

Repeated calls have the same effect.

This never closes your Remote.

Which engine answers a read

Use query to choose the engine. Default reads use SQLite. Select DuckDB with engine="duckdb". Only these two engines are supported. An invalid selection fails instead of selecting the default.

The packaged Python SDK supports SQLite and DuckDB.

The native SDK loads DuckDB when you first request an analytical read. OpenOptions.analytical_engine selects the library for one database or snapshot. It takes priority over POTLUCKDB_DUCKDB_LIBRARY, package discovery where available, and the platform’s library search. An explicit selection, including an empty string, never uses a fallback.

See analytics engine installation for your platform. Without an implicit library, the read fails with analytical_engine_unavailable. If an explicit library cannot load, the read reports its loader error.

Install it with pip install potluckdb-analytics, which resolves the wheel built for this platform.

DuckDB rejects the named binding forms :name and @name. Both engines accept $name and positional ? bindings. Booleans bind as INTEGER 0/1 on both. IS therefore asks the same question on either engine, unlike a DuckDB BOOLEAN binding.

Bare table names read the database’s main schema. Qualifiers such as temp. are not seen. For table names ending in .csv, .parquet or .json, use potluckdb_scan('name'). DuckDB otherwise treats those names as files.

NUMERIC and DECIMAL columns read as doubles. A value that a double cannot hold exactly fails the query instead of arriving rounded.

A storage failure during an analytical read reports analytical_engine_error, with the failure named in its message. The same query succeeds when storage answers.

Either engine runs one read per query. The analytical engine reads a snapshot of the same data through its own in-memory database. A statement sent to this engine therefore cannot change the stored data.

An engine can remain for the session’s lifetime. Changing its settings or catalog would change later queries on that session. Only SELECT and EXPLAIN are accepted. CREATE, SET, ATTACH, PREPARE and EXPLAIN ANALYZE are refused. EXPLAIN ANALYZE is refused because it executes the explained statement.

Use execute for writes to the stored data.