Skip to main content

ClientContext

Struct ClientContext 

Source
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

Source

pub unsafe fn from_connection( con: duckdb_connection, ) -> Result<Self, ExtensionError>

Obtain a client context from a duckdb_connection.

§Errors

Returns ExtensionError if the context cannot be obtained.

§Safety

con must be a valid, open duckdb_connection, and must stay open for as long as the returned context (or anything borrowed from it) is used — see Lifetime.

Source

pub const unsafe fn from_raw(ctx: duckdb_client_context) -> Self

Wrap a raw duckdb_client_context handle.

§Safety

ctx must be a valid, non-null duckdb_client_context that nothing else destroys, and the connection it belongs to must stay open for as long as the returned value is used — see Lifetime.

Source

pub const fn as_raw(&self) -> duckdb_client_context

Returns the raw handle.

Source

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:

  • name is empty. duckdb_client_context_get_catalog rejects that outright (strlen(name) == 0 is an explicit early return); it is not a way to ask for “the default”. The catalog of an in-memory database is named memory; a file database’s is the file’s stem.
  • No transaction is active. DuckDB checks transaction.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.

Source

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.

Source

pub fn connection_id(&self) -> u64

Returns the connection ID associated with this client context.

Trait Implementations§

Source§

impl Debug for ClientContext

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Drop for ClientContext

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more
Source§

impl Send for ClientContext

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.