Remote

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

Reusable synchronization state for one remote.

A remote is the shared database copy described in Concepts. You own the Remote and can share it among databases and snapshots. Closing a database or snapshot never closes its remote. The remote refuses to close while any open database or snapshot uses it.

At a glance

Construct

• from_directory(): Open a directory remote rooted at path.
• from_storage(): Wrap a caller-supplied storage adapter as a remote.

Inspect

• status(): Return a typed RemoteStatus snapshot of remote-owned state only.

Maintain storage

• collect() Advanced: Collect retired revisions under an explicit retention policy and return a CollectionReport.
• recover_abandoned_collection() Advanced: Reopen a remote that an interrupted collection left cleaning.

Close

• close(): Close the remote.

Construct

Remote.from_directory

Open a directory remote rooted at path.

Remote.from_directory(
    path: str | os.PathLike[str],
    options: RemoteOptions | None = None,
) -> Remote

Parameters

• path: The directory used for remote storage.
• options: Remote concurrency and retention settings.

Returns

Remote. The reusable directory remote.

Errors

• invalid_argument: An argument has the wrong type or value.

Other errors can occur. See Errors for every code.

Example

import potluckdb
with potluckdb.Remote.from_directory("shared") as remote:
    print(remote.status().closed)

Details

The directory is created on first use. Default options use read_concurrency 32 and bounded retention.

Remote.from_storage

Wrap a caller-supplied storage adapter as a remote.

Remote.from_storage(
    storage: BucketStorage,
    options: RemoteOptions | None = None,
) -> Remote

Parameters

• storage: The caller-supplied bucket storage adapter.
• options: Remote concurrency and retention settings.

Returns

Remote. The remote that wraps the adapter.

Errors

• invalid_argument: An argument has the wrong type or value.

Other errors can occur. See Errors for every code.

Example

import potluckdb
from potluckdb.integrator import BucketCounterSnapshot, Unavailable
class OfflineStorage:
    counters = property(lambda self: self)
    def snapshot(self): return BucketCounterSnapshot()
    def __getattr__(self, name): return self.refuse
    def refuse(self, *args): raise Unavailable("demo storage is offline")
    def close(self): pass
with potluckdb.Remote.from_storage(OfflineStorage()) as remote:
    print(remote.status().closed)

Details

storage implements the bucket storage protocol beneath the storage entry points. This is an integrator API. The S3 adapter is one implementation. Closing the remote never closes the adapter’s underlying transport for you.

Integrator API. This member exists for code that supplies its own storage transport. Application code reaches a bucket through potluckdb.storage.from_s3, potluckdb.storage.from_gcs and potluckdb.storage.from_azure.

Inspect

Remote.status

Return a typed RemoteStatus snapshot of remote-owned state only.

Remote.status() -> RemoteStatus

Returns

RemoteStatus. The current remote-owned state.

Example

import potluckdb
with potluckdb.Remote.from_directory("shared") as remote:
    print(remote.status().maintenance_pending)

Maintain storage

Remote.collect

Advanced

Collect retired revisions under an explicit retention policy and return a CollectionReport.

Remote.collect(
    retention: RetentionPolicy,
) -> CollectionReport

Parameters

• retention: The bounded policy that selects retained history.

Returns

CollectionReport. The collection counts and retention floors.

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.

Example

import potluckdb
with potluckdb.Remote.from_directory("shared") as remote:
    policy = potluckdb.RetentionPolicy.bounded(keep_last=1, collect_at=2)
    report = remote.collect(policy)
    print(report.swept)

Details

Collection starts only above the retained target. It never touches the current head. Concepts explains retention and collection.

Remote.recover_abandoned_collection

Advanced

Reopen a remote that an interrupted collection left cleaning.

Remote.recover_abandoned_collection() -> CollectionReport

Returns

CollectionReport. The recovery counts and retention floors.

Errors

• remote_closed: The remote is closed.

Other errors can occur. See Errors for every code.

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.

Example

import potluckdb
with potluckdb.Remote.from_directory("shared") as remote:
    report = remote.recover_abandoned_collection()
    print(report.marked)

Details

Collection is interrupted if any of these occurs:

• Its process stops.
• It cannot learn whether its opening head swap took effect.
• Storage fails both a sweep step and its closing head swap.

Until the head reopens, every synchronization and new device initialization fails with temporarily_unavailable.

The next collection completes the sweep. If the head is open, this changes nothing and reports aborted. If there is no head, this changes nothing. It never retires a revision.

This operation is separate from collect. An accidental flag therefore cannot request recovery.

Close

Remote.close

Close the remote.

Remote.close() -> None

Errors

• invalid_state: An open database or snapshot still uses this remote.

Other errors can occur. See Errors for every code.

Example

import potluckdb
remote = potluckdb.Remote.from_directory("shared")
remote.close()
print(remote.status().closed)

Details

Repeated calls have the same effect.

close() fails with invalid_state while an open database or snapshot uses this remote. Refusal changes no state.