Advanced

Advanced operations remain typed and separate from the ordinary path. Options and calls use Python spellings. Each language’s reference gives its own spellings.

• Connection.checkpoint(): Run an explicit WAL checkpoint and return (checkpointed, total) frame counts.
• Database.set_sync_policy(): Replace the synchronization policy and return the new status.
• Database.clear_quarantine_records(): Discard full quarantine records and return the number cleared.
• Remote.collect(): Collect retired revisions under an explicit retention policy and return a CollectionReport.
• Remote.recover_abandoned_collection(): Reopen a remote that an interrupted collection left cleaning.

Active collectors

Call Remote.recover_abandoned_collection only after every collector on this remote has stopped. A collector that still deletes objects can remove data that a new publication needs after recovery reopens the remote.

admin.reencrypt

Publish a verified retained source snapshot into an unpublished target namespace under a new encryption key.

admin.reencrypt(
    source: Remote,
    target: Remote,
    new_key: bytes,
    *,
    source_key: bytes | None = None,
    revision: str | None = None,
) -> KeyRotationReport

Parameters

• source: The remote holding the retained source revision.
• target: The distinct, unpublished target remote.
• new_key: The new 32-byte encryption key for the target.
• source_key: The source revision’s encryption key, if encrypted.
• revision: The retained source revision, or the current head if omitted.

Returns

KeyRotationReport. The source and target revisions and publication result.

Errors

• invalid_argument: An argument has the wrong type or value.
• remote_closed: The remote is closed.
• invalid_state: The source has no published revision, both keys are equal, or the target cannot accept the rotated data.
• integrity_failure: A record failed its integrity check during the rotation.
• wrong_key_or_corrupt: The current key is wrong, or encrypted data is damaged. Check source_key and preserve damaged data.
• encryption_key_required: The source is encrypted, but its key was not supplied. Pass its current key as source_key.

Other errors can occur. See Errors for every code.

Example

from potluckdb import OpenOptions, Remote, SyncPolicy, admin, open
import secrets
options = OpenOptions(sync_policy=SyncPolicy.manual())
directory = Remote.from_directory
with directory("source") as src, directory("target") as dst:
    with open("notes", src, options) as db:
        db.execute("CREATE TABLE note (id INTEGER PRIMARY KEY)")
        db.sync()
    report = admin.reencrypt(src, dst, secrets.token_bytes(32))
    print(report.published)

Details

Supply distinct source and target remotes that you own. The operation uses bounded transfers. After partial immutable uploads, retry with the same new encryption key. Once the target head is published, repeated calls have the same effect. The target head publishes only after every object write completes.

This call does not close either remote. Both remotes stay reserved until the call returns, whether it succeeds or fails.

integrator namespace

The integrator namespace holds the low-level runtime and storage entry points for cooperative hosts.

The files in a database directory

A database is a directory, not a single file. Inside it:

File	What it is
potluckdb_runtime-local-v1.bin	Your data. Every page lives here.
potluckdb_runtime-engine	Empty, and the one to know about (below).
potluckdb_runtime-engine-wal, potluckdb_runtime-engine-journal	Empty, for the same reason.
potluckdb_runtime-local-v1.lock	Coordination between processes.
.potluckdb-client-id	This device’s identity.

potluckdb_runtime-engine is the name SQLite opens the database under, and it is always zero bytes. Nothing is ever written through it: a custom virtual file system intercepts every read and write and serves them from potluckdb_runtime-local-v1.bin. The real file exists because SQLite’s locking protocol needs something on disk to lock.

Opening it with the sqlite3 command line tool reports no such table even for existing tables. You are reading the lock file. Your data is in potluckdb_runtime-local-v1.bin. Query through the SDK.

Deleting these empty files loses nothing, and they come back on the next open.