Options and policies

Every option object and policy factory. Options and calls use Python spellings. Each language’s reference gives its own spellings.

`OpenOptions`

Options for open and open_revision.

local_budget_bytes (int, default 1073741824): The local storage budget in bytes.
minimum_local_budget_bytes (int, default 10485760): The minimum permitted local storage budget.
local_compaction_bytes (int, default 268435456): The local compaction threshold in bytes.
encryption_key (bytes | None, default None): The 32-byte encryption key, or None for an unencrypted database.
sync_policy (SyncPolicy, default SyncPolicy.automatic()): The database synchronization policy.
client_id (str | None, default None): The requested durable client identity, or None to generate one.
connection (ConnectionOptions, default ConnectionOptions()): Settings for the convenience connection or sole snapshot connection.
on_sync (Callable[[SyncOutcome], None] | None, default None): The callback for completed automatic synchronization attempts.
license_key (str | None, default None): The license key supplied for this open.
analytical_engine (str | None, default None): The analytical engine selection, if supplied.

Omitting options selects ordinary behavior. Each setting has exactly one owner. connection configures the database’s convenience connection or a snapshot’s sole read connection.

local_budget_bytes bounds what the local store keeps on the device. In this release, it holds every version of a 64 KiB piece changed by a transaction until synchronization publishes it. A database without a remote never publishes. If every transaction changes one piece, it refuses writes with local_budget_exceeded after about local_budget_bytes divided by 65,536 transactions. Open again with a larger budget, or with a remote and then synchronize, to resume writes.

on_sync reports each automatic attempt’s outcome: UpToDate, Pushed, Pulled, Conflict, or Failed with its PotluckDBError. The hook runs on the synchronization thread in the process. Do not call the database there. Transfer the outcome to your program’s thread.

Explicit sync() and resolve_conflict() return outcomes without invoking the hook. An exception from the hook is reported through sys.unraisablehook without changing the schedule. A hook supplied without a remote is accepted but never invoked.

license_key supplies the license key for this open. It takes precedence over POTLUCKDB_LICENSE_KEY and the configuration directory’s license-key file. An unaccepted license key is reported, and opening proceeds on the trial. After the trial, only database creation needs an accepted license key.

`RemoteOptions`

Options owned by a Remote.

read_concurrency (int, default 32): The maximum number of concurrent authenticated reads.
write_concurrency (int, default 16): The maximum number of concurrent publication writes.
retention (RetentionPolicy, default RetentionPolicy.bounded()): The remote retention policy.

They control authenticated read concurrency, publication write concurrency and retention. Read concurrency defaults to 32 and is capped at 256. Retention defaults to bounded.

`ConnectionOptions`

Options owned by one connection: busy timeout, the Rows bound maximum_rows, and the prefetch and checkpoint policies.

timeout_ms (int, default 5000): The SQLite busy timeout in milliseconds.
maximum_rows (int, default 1000000): The maximum number of returned rows; a larger result raises result_limit_exceeded.
prefetch (PrefetchPolicy, default PrefetchPolicy.automatic()): The connection prefetch policy.
checkpoint (CheckpointPolicy, default CheckpointPolicy.automatic()): The connection checkpoint policy.

`SyncPolicy`

When and how a database with a remote synchronizes.

mode (Literal['automatic', 'manual']): The automatic or manual synchronization mode.
outbound_debounce_ms (int): The delay before publishing local changes.
active_pull_interval_ms (int): The active follow-up interval.
idle_pull_interval_ms (int): The idle remote polling interval.
retry_initial_ms (int): The initial retry delay after a transient failure.
retry_max_ms (int): The maximum retry delay.

Construct only through automatic or manual. A writable database with a remote defaults to automatic.

`SyncPolicy.automatic`

Synchronize automatically in both directions with bounded timers.

SyncPolicy.automatic(
    *,
    outbound_debounce_ms: int = 30,
    active_pull_interval_ms: int = 200,
    idle_pull_interval_ms: int = 1000,
    retry_initial_ms: int = 250,
    retry_max_ms: int = 30000,
) -> SyncPolicy

Parameters

outbound_debounce_ms: The delay before publishing local changes.
active_pull_interval_ms: The active follow-up interval.
idle_pull_interval_ms: The idle remote polling interval.
retry_initial_ms: The initial retry delay after a transient failure.
retry_max_ms: The maximum retry delay.

Returns

SyncPolicy. The policy contains the selected settings.

Details

Sets mode to "automatic" and each timer to its validated argument.

Timer	Default
Outbound debounce	30 ms
Active follow-up	200 ms
Idle poll	1,000 ms
Exponential retry after transient failure	250 ms to 30,000 ms

Timers are positive and cannot exceed one day. Idle polling cannot be faster than active polling. The retry maximum cannot be below its initial delay.

While nothing changes, each open database reads the remote head once per idle_pull_interval_ms. Divide the device population by the interval to find the remote’s request rate in the same time unit. Increase the interval where requests are priced.

`SyncPolicy.manual`

Disable automatic synchronization work.

SyncPolicy.manual() -> SyncPolicy

Returns

SyncPolicy. The policy contains the selected settings.

Details

Explicit sync() and resolve_conflict() remain available.

Sets mode to "manual" and keeps the automatic factory’s default timers.

`PrefetchPolicy`

Bounded prefetch during statements and in the background for connections with a remote.

enabled (bool): Whether automatic prefetch is enabled.
background_target_bytes (int): The background target; zero selects the full revision within local capacity.
memory_budget_bytes (int): The memory budget for one prefetch wave.

Construct through automatic or disabled. With automatic, a snapshot from open_revision fetches its whole revision within local capacity. This suits extended work but is expensive for reading one row. With disabled, it fetches only pages the query touches.

`PrefetchPolicy.automatic`

Enable prefetch.

PrefetchPolicy.automatic(
    *,
    background_target_bytes: int = 0,
    memory_budget_bytes: int = 67108864,
) -> PrefetchPolicy

Parameters

background_target_bytes: The background target; zero selects the full revision within local capacity.
memory_budget_bytes: The memory budget for one prefetch wave.

Returns

PrefetchPolicy. The policy contains the selected settings.

Details

Sets enabled to True and both byte limits to their validated arguments.

A zero background_target_bytes means the full pinned database within local capacity. The memory budget bounds one wave rather than total durable residency.

`PrefetchPolicy.disabled`

Create no prefetch runtime for the connection.

PrefetchPolicy.disabled() -> PrefetchPolicy

Returns

PrefetchPolicy. The policy contains the selected settings.

Details

Sets enabled to False and both byte limits to zero.

`CheckpointPolicy`

Connection-local WAL checkpoint thresholds for writable databases.

enabled (bool): Whether automatic checkpoints are enabled.
soft_limit_bytes (int): The threshold for low-priority checkpoint work.
forced_limit_bytes (int): The threshold for a checkpoint attempt before later writes.

Construct through automatic or disabled.

`CheckpointPolicy.automatic`

Enable automatic WAL checkpoints.

CheckpointPolicy.automatic(
    *,
    soft_limit_bytes: int = 67108864,
    forced_limit_bytes: int = 134217728,
) -> CheckpointPolicy

Parameters

soft_limit_bytes: The threshold for low-priority checkpoint work.
forced_limit_bytes: The threshold for a checkpoint attempt before later writes.

Returns

CheckpointPolicy. The policy contains the selected settings.

Details

Sets enabled to True and both thresholds to their validated arguments.

Above soft_limit_bytes, checkpoint work runs at low priority. Above forced_limit_bytes, a checkpoint attempt is guaranteed before later work that can write. The forced limit cannot be below the soft limit.

`CheckpointPolicy.disabled`

Remove automatic checkpoint work without removing explicit Connection.checkpoint().

CheckpointPolicy.disabled() -> CheckpointPolicy

Returns

CheckpointPolicy. The policy contains the selected settings.

Details

Sets enabled to False and both thresholds to zero.

`RetentionPolicy`

How many revisions a remote retains before collection.

keep_last (int | None): The newest revisions to retain, or None for unbounded retention.
collect_at (int | None): The retained count that starts collection, or None for unbounded retention.

Construct through bounded or unbounded. RemoteOptions defaults to bounded, keeping the newest ten revisions and collecting once twenty exist. Advancing the floor is irreversible. Every context sharing a namespace must use the same bound. Concepts explains the floor and collection.

`RetentionPolicy.bounded`

Keep the newest keep_last retained revisions and begin collection only at collect_at or more.

RetentionPolicy.bounded(
    *,
    keep_last: int = 10,
    collect_at: int = 20,
) -> RetentionPolicy

Parameters

keep_last: The newest revisions to retain, or None for unbounded retention.
collect_at: The retained count that starts collection, or None for unbounded retention.

Returns

RetentionPolicy. The policy contains the selected settings.

Details

Sets keep_last and collect_at to their validated arguments.

`RetentionPolicy.unbounded`

Keep every revision.

RetentionPolicy.unbounded() -> RetentionPolicy

Returns

RetentionPolicy. The policy contains the selected settings.

Details

Sets keep_last and collect_at to None.

No collection runs until Remote.collect uses a bounded policy. The remote grows with every publication.