Skip to main content

ConfigOptionBuilder

Struct ConfigOptionBuilder 

Source
pub struct ConfigOptionBuilder { /* private fields */ }
Expand description

Builder for registering extension-defined configuration options.

After building, call register from your entry point to register the setting with DuckDB.

Implementations§

Source§

impl ConfigOptionBuilder

Source

pub fn try_new(name: &str) -> Result<Self, ExtensionError>

Creates a new config option builder with the given name.

§Errors

Returns ExtensionError if the name contains a null byte.

Source

pub fn name(&self) -> &str

Returns the name of this config option.

Source

pub fn description(self, desc: &str) -> Result<Self, ExtensionError>

Sets the human-readable description for this option.

§Errors

Returns ExtensionError if desc contains a null byte.

Source

pub const fn option_type(self, type_id: TypeId) -> Self

Sets the value type for this option (e.g. TypeId::BigInt, TypeId::Varchar).

Source

pub fn default_value(self, value: &str) -> Result<Self, ExtensionError>

Sets the default value as a string representation.

The string is converted to the option’s type at register time, with the same SQL cast SET uses; a string that does not convert is an error there. Every option needs a default — see register.

§Errors

Returns ExtensionError if value contains a null byte.

Source

pub const fn scope(self, scope: ConfigOptionScope) -> Self

Sets the scope for this option.

Source

pub unsafe fn register( self, con: duckdb_connection, ) -> Result<(), ExtensionError>

Registers this config option with DuckDB.

§The default is converted by SQL, never inside the C API

duckdb_config_option_set_default_value converts a default whose type differs from the option’s with Value::DefaultCastAs — a throwing cast with no try/catch around it — so a string default that does not convert would abort the process (“Rust cannot catch foreign exceptions”). Worse, DefaultCastAs uses only the built-in casts while SQL uses the connection’s, so a string one accepts can still make the other throw: with ICU loaded, '2020-01-01 10:00:00 America/New_York' is a valid TIMESTAMPTZ in SQL and an abort in DefaultCastAs.

register therefore converts the default itself, by running SELECT TRY_CAST($1::VARCHAR AS <type>) on con with the default bound as a parameter, and hands DuckDB a value that already has the option’s type. duckdb_config_option_set_default_value stores such a value as-is (it only casts when coption->type != cvalue->type(), src/main/capi/config_options-c.cpp), so no cast can run inside the C API. The stored default is exactly what TRY_CAST('<default>' AS <type>) produces in SQL on con.

Option types whose values the C API cannot construct from a query result (BIGNUM, GEOMETRY, VARIANT, …) are refused rather than sent down the throwing path.

§Errors

Returns ExtensionError, before anything is registered, if:

  • the option type was not set, or is a pseudo-type (ANY, SQLNULL, the literal types) that no setting can have;
  • no default value was set. DuckDB treats an extension option without a default as unset: current_setting reports it as an “unrecognized configuration parameter” until someone SETs it, and ClientContext::config_option on it takes the path a debug build of DuckDB asserts on;
  • the name is already a setting — built-in (threads), an alias of one (worker_threads), or another extension’s. Names are compared case-insensitively, as DuckDB resolves them. DuckDB itself only refuses a name another extension option has, and silently lets an extension option shadow a built-in one for current_setting;
  • the default does not convert to the option type (or the conversion query cannot run on con), or the type cannot carry a default;
  • duckdb_register_config_option fails.
§Safety

con must be a valid, open duckdb_connection.

Trait Implementations§

Source§

impl Debug for ConfigOptionBuilder

Source§

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

Formats the value using the given formatter. Read more

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.