Open and construct

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

potluckdb.open

Open one writable local database, creating it if absent.

potluckdb.open(
    path: str | os.PathLike[str],
    remote: Remote | None = None,
    options: OpenOptions | None = None,
) -> Database

Parameters

• path: The local database directory, created if absent.
• remote: The optional remote used for synchronization.
• options: Settings for this database and its convenience connection.

Returns

Database. The writable local database.

Errors

• invalid_argument: An argument has the wrong type or value.
• remote_closed: The remote is closed.
• license_required: No accepted license key or active trial is available. Install a license key to create databases.

Other errors can occur. See Errors for every code.

Example

import potluckdb
with potluckdb.open("notes") as db:
    print(db.query("SELECT 7 AS answer")[0]["answer"])

Details

With a remote, a pristine directory initializes from the authenticated current head. Synchronization defaults to automatic exchange in both directions unless options select otherwise. A database with a base revision or pending local writes opens without consulting the remote. Omitting options selects ordinary behavior. Concepts explains the remote and revision model.

A new database persists a generated client identity beside its data. OpenOptions.client_id lets deployment tools choose a deterministic identity. On later opens, it must agree with the persisted identity.

Opening writes no local data and creates no connection. With no history to copy, the first statement, including a read, materializes the database. This records initialization as a pending write. A database with no statements has nothing to publish. Its sync() returns UpToDate or Pulled.

Adding a second device. Initialization copies the head present at open, including its schema. A device initialized from a published head already has the tables. CREATE TABLE therefore fails with table already exists. CREATE TABLE IF NOT EXISTS does nothing. Neither creates a pending write or anything to publish.

Devices can open in any order. A device that opens before any revision exists copies nothing. If that device runs no statement before its first sync(), it has nothing to publish, and that sync() pulls the first published history normally.

In this release, a statement before any revision exists, including a read, gives the device initialization to publish. Creating a connection in Python or Node.js does the same. If another device publishes first, this device’s first sync() returns Conflict. resolve_conflict() adopts published history and lists initialization as replayed. Nothing is lost. If this device publishes first, it publishes an empty revision, and the other device meets the conflict.

Two devices creating the schema before either publishes diverge in the same way. The second publisher adopts the remote revision. Its own CREATE TABLE is quarantined because the table already exists.

potluckdb.open_revision

Pin exactly one retained revision from remote and return a read-only Snapshot.

potluckdb.open_revision(
    path: str | os.PathLike[str],
    revision: str,
    remote: Remote,
    options: OpenOptions | None = None,
) -> Snapshot

Parameters

• path: The snapshot’s local database directory.
• revision: The retained revision to pin.
• remote: The remote that holds the retained revision.
• options: Settings for the snapshot and its sole read connection.

Returns

Snapshot. A read-only view of the retained revision.

Errors

• invalid_argument: An argument has the wrong type or value.
• remote_closed: The remote is closed.

Other errors can occur. See Errors for every code.

Directory removal

Open no database in this directory or below it until the snapshot’s close() returns. If this call created the directory, close() or a failed open deletes the directory and everything in it.

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.query("SELECT count(*) FROM note")[0][0])

Details

OpenOptions.connection configures its sole read connection. The snapshot stores the revision as a local database at path. The remote holds the data needed to reconstruct every page. A separate copy per viewed revision consumes local space. This call leaves an existing directory in place.

To retain the local store, create its directory before this call. You can then read the same revision again without downloading it again. Use a separate directory per snapshot. One directory holds only one open database at a time.

This call refuses directories with an open database or unpublished changes. In a closed database’s directory with fully published changes, it replaces the local copy. The remote retains that database’s published commits.

How much lands there follows OpenOptions.connection.prefetch. A pinned revision fetches pages through the same path as a writable database. The default background target is zero, which fetches the full revision within local capacity. Reading one row therefore costs the whole revision. This is good for long work. It is slow for one row.

For targeted reads, pass PrefetchPolicy.disabled() or a bounded background target. Only pages the query reads are fetched with prefetch disabled. A bounded target also permits prefetch within its bound.