Open and construct

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

Open (creating if absent) one writable local database.

With a remote, the database bootstraps a pristine directory from the authenticated current head and selects automatic bidirectional synchronization unless the options say otherwise; an already based or locally pending database opens without consulting the remote. Omitting options selects the ordinary behavior. A generated client identity is persisted beside a new database; OpenOptions.client_id exists for deterministic deployment tooling and must agree with the durable identity on later opens.

Opening performs no local write and creates no connection: the first statement is what materializes a new database. A database nobody has written to therefore has nothing to publish, and sync() on it returns UpToDate or pulls.

Adding a second device. Bootstrapping copies whatever head the remote has at the moment of opening. Devices may be opened in any order: one that opens before any revision exists has nothing to copy and nothing of its own to publish, so its first sync() pulls the first published history as an ordinary pull.

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

Pin exactly one retained revision from remote and return a read-only Snapshot. OpenOptions.connection configures its sole read connection.

path is where the revision materializes as a local database, and who owns it is decided by whether it already exists. A path this call creates is removed when the Snapshot closes: the materialization is derived, every page rebuildable from remote, so keeping it past the read that needed it only accumulates one local database per revision anyone views. A directory that already exists belongs to the caller and is left in place — pre-create one to keep a materialization and read the same revision again without paying for it twice. Either way give it a directory of its own: a directory already open as a database refuses, because one directory holds one open database at a time.

How much lands there follows OpenOptions.connection.prefetch, because a pinned revision reads through the same page path as a writable database. The default policy carries a zero background target, which means the full pinned revision within local capacity: reading one row of an old revision costs the whole revision. That suits working with a revision, and is expensive for glancing at one. For a targeted look pass PrefetchPolicy.disabled(), or a bounded background target, and only the pages the query reads are fetched.