Open and construct

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

potluckdb::open

Open one writable local database, creating it if absent.

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. 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 SyncResult::UpToDate or SyncResult::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 SyncResult::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.

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.

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.

How much lands there follows 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 suits extended work but is expensive for a glance.

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.