Connection
C++: also in Python · Node · Go · Rust · Swift · Dart · Java and Kotlin · .NET · Objective-C
One independent SQLite connection owned by a Database.
Connections have independent transactions, read snapshots, TEMP schemas, busy timeouts and connection-local PRAGMAs. Closing one leaves its database and sibling connections usable.
A pull or resolve_conflict() replaces the underlying SQLite connection. The replacement keeps its configured busy timeout and these settings:
cache_size, case_sensitive_like, cell_size_check, foreign_keys, ignore_check_constraints, query_only, recursive_triggers, temp_store, trusted_schema.
TEMP objects and all other settings are lost. Conflicts replay pending transactions with the settings under which they committed.
Once a connection creates or drops a TEMP object, replay cannot reproduce that connection’s transactions. After a connection creates or drops a TEMP object, or changes another setting that can change a statement’s result, a conflict quarantines that connection’s transactions instead of replaying them. This continues until the connection is next replaced.
Settings that govern only storage, memory and lock waits, such as secure_delete, journal_size_limit and busy_timeout, leave transactions replayable. See production considerations for replay limitations.
Operations
Section titled “Operations”checkpoint
Section titled “checkpoint”Run an explicit WAL checkpoint and report checkpointed and total frame counts.
Writable databases support this even when CheckpointPolicy::disabled() disables automatic checkpoints.
Close only this connection. Repeated calls have the same effect.
close() fails with invalid_state while this connection has an active managed transaction.
execute
Section titled “execute”Run exactly one state-changing SQLite statement.
Use query for reads. SQLite can apply effects during statement preparation even if the call refuses execution. The returned ExecuteResult contains last_insert_id whenever this direct INSERT or REPLACE inserted a row.
This call never accepts transaction-control SQL. Use transaction() to manage that lifecycle.
Run one SQLite statement with read execution intent and return rows.
Use execute for writes. Use transaction() for transaction control. SQLite can apply effects during statement preparation, including a PRAGMA or EXPLAIN, even if the call refuses execution.
The connection’s maximum_rows bounds results. The check runs after the statement completes. It limits returned rows rather than execution memory or time. Give a query that could grow without end its own SQL LIMIT.
status
Section titled “status”Return a typed ConnectionStatus of connection-owned state only.
transaction
Section titled “transaction”Begin one managed transaction.
The default mode is immediate. The scope commits only on successful completion and always attempts rollback after a failure.
Which engine answers a read
Section titled “Which engine answers a read”Use query to choose the engine. Default reads use SQLite. Select DuckDB with potluckdb::QueryEngine::DuckDb. Only these two engines are supported. An invalid selection fails instead of selecting the default.
The native SDK loads DuckDB when you first request an analytical read. OpenOptions.analytical_engine selects the library for one database or snapshot. It takes priority over POTLUCKDB_DUCKDB_LIBRARY, package discovery where available, and the platform’s library search. An explicit selection, including an empty string, never uses a fallback.
See analytics engine installation for your platform. Without an implicit library, the read fails with analytical_engine_unavailable. If an explicit library cannot load, the read reports its loader error.
The analytics engine page lists each platform’s library URL and SHA-256 digest.
- Download the library for your platform.
- Verify its digest.
- Name the library in this language’s open option.
potluckdb::OpenOptions options;options.analytical_engine = "/opt/potluckdb/lib/libduckdb.so";DuckDB rejects the named binding forms :name and @name. Both engines accept $name and positional ? bindings. Booleans bind as INTEGER 0/1 on both. IS therefore asks the same question on either engine, unlike a DuckDB BOOLEAN binding.
Bare table names read the database’s main schema. Qualifiers such as temp. are not seen. For table names ending in .csv, .parquet or .json, use potluckdb_scan('name'). DuckDB otherwise treats those names as files.
NUMERIC and DECIMAL columns read as doubles. A value that a double cannot hold exactly fails the query instead of arriving rounded.
A storage failure during an analytical read reports analytical_engine_error, with the failure named in its message. The same query succeeds when storage answers.
Either engine runs one read per query. The analytical engine reads a snapshot of the same data through its own in-memory database. A statement sent to this engine therefore cannot change the stored data.
An engine can remain for the session’s lifetime. Changing its settings or catalog would change later queries on that session. Only SELECT and EXPLAIN are accepted. CREATE, SET, ATTACH, PREPARE and EXPLAIN ANALYZE are refused. EXPLAIN ANALYZE is refused because it executes the explained statement.
Use execute for writes to the stored data.