pub struct ClientContext { /* private fields */ }Expand description
RAII wrapper for a duckdb_client_context.
Provides access to the connection’s catalog, configuration, and file system. Automatically destroyed when dropped.
§Lifetime
The handle does not keep the connection alive. DuckDB’s
CClientContextWrapper holds a plain reference to the ClientContext the
connection owns (src/include/duckdb/main/capi/capi_internal.hpp), so a
ClientContext — and a FileSystem
borrowed from it — must not be used after that connection is closed.
Every constructor is unsafe and states this in its # Safety section.
§Threads
A ClientContext is Send: it may be moved to, used on and dropped on
another thread — into a table function’s bind data, for one, to open
files in init or scan, where the C API has no client context of its
own. It is not Sync; data that several scan threads read at once
needs it behind a Mutex.
Implementations§
Source§impl ClientContext
impl ClientContext
Sourcepub unsafe fn from_connection(
con: duckdb_connection,
) -> Result<Self, ExtensionError>
pub unsafe fn from_connection( con: duckdb_connection, ) -> Result<Self, ExtensionError>
Sourcepub unsafe fn catalog(&self, name: &CStr) -> Option<Catalog>
pub unsafe fn catalog(&self, name: &CStr) -> Option<Catalog>
Retrieves a database catalog by name.
Returns None when there is no such catalog — and in two cases that are
easy to mistake for one:
nameis empty.duckdb_client_context_get_catalogrejects that outright (strlen(name) == 0is an explicit early return); it is not a way to ask for “the default”. The catalog of an in-memory database is namedmemory; a file database’s is the file’s stem.- No transaction is active.
DuckDBcheckstransaction.HasActiveTransaction()and returns null otherwise, so this works inside a function callback but not on an idle auto-commit connection.
§Safety
Must be called from within an active transaction context.
Sourcepub fn config_option(&self, name: &CStr) -> Option<String>
pub fn config_option(&self, name: &CStr) -> Option<String>
Retrieves a configuration option value by name, rendered as text.
Returns None when the option does not exist or its value is SQL
NULL — the two are not distinguished. Several built-in settings are
NULL until set (enable_profiling, for one), and so is an extension
option after SET my_option = NULL. DuckDB’s duckdb_get_varchar
throws on a NULL value from inside the C API, which used to abort the
process; this checks duckdb_is_null_value first. A value that is not
valid UTF-8 is also None.
§Do not use this to probe for a setting that may not exist
DuckDB 1.5.5’s duckdb_client_context_get_config_option reads the
lookup’s scope before checking the lookup succeeded:
// src/main/capi/config_options-c.cpp
switch (ctx.TryGetCurrentSetting(option_name, result).GetScope()) {
// src/include/duckdb/main/setting_info.hpp
SettingScope GetScope() {
D_ASSERT(scope != SettingScope::INVALID);A missing setting yields SettingScope::INVALID, so GetScope() trips
that assertion. In a release DuckDB — what users run — D_ASSERT
compiles out, the function’s own default: branch handles INVALID,
and this returns None as documented. Against a DuckDB built with
debug assertions, the process aborts. Verified against 1.5.5.
So this is safe for a setting you registered or know exists, and unsafe as an existence check. To ask whether a setting exists, use SQL, which has no such path:
SELECT count(*) FROM duckdb_settings() WHERE name = 'my_setting';The C function has no try, so a built-in setting whose getter threw
would abort the process too. None does in practice: every setting
duckdb_settings() lists was read this way on 1.5.0 (150) and 1.5.5
(157) without a throw, and the two 1.5.5 getters that can throw do so
only for a state their SET handlers never store. An extension’s own
option has no getter.
Sourcepub fn connection_id(&self) -> u64
pub fn connection_id(&self) -> u64
Returns the connection ID associated with this client context.