pub trait Registrar {
// Required methods
unsafe fn register_scalar(
&self,
builder: ScalarFunctionBuilder,
) -> Result<(), ExtensionError>;
unsafe fn register_scalar_set(
&self,
builder: ScalarFunctionSetBuilder,
) -> Result<(), ExtensionError>;
unsafe fn register_aggregate(
&self,
builder: AggregateFunctionBuilder,
) -> Result<(), ExtensionError>;
unsafe fn register_aggregate_set(
&self,
builder: AggregateFunctionSetBuilder,
) -> Result<(), ExtensionError>;
unsafe fn register_table(
&self,
builder: TableFunctionBuilder,
) -> Result<(), ExtensionError>;
unsafe fn register_sql_macro(
&self,
sql_macro: SqlMacro,
) -> Result<(), ExtensionError>;
unsafe fn register_cast(
&self,
builder: CastFunctionBuilder,
) -> Result<(), ExtensionError>;
unsafe fn register_copy_function(
&self,
builder: CopyFunctionBuilder,
) -> Result<(), ExtensionError>;
unsafe fn register_config_option(
&self,
builder: ConfigOptionBuilder,
) -> Result<(), ExtensionError>;
// Provided method
unsafe fn register_typed_scalar(
&self,
builder: TypedScalarFunctionBuilder,
) -> Result<(), ExtensionError> { ... }
}Expand description
Version-agnostic trait for registering DuckDB extension components.
Implemented by Connection. Writing registration code against this trait
means the same code compiles and runs on DuckDB 1.4.x and 1.5.x without
modification.
§Why every method is unsafe
Each method requires that the implementor’s underlying duckdb_connection
is valid for the call, and that the raw callbacks installed on the builder
fit the calls DuckDB will make to them: each callback’s own # Safety
preconditions must hold where it is installed. For a raw aggregate that
means state_size, init, destructor and the data callbacks all
describe the same state (AggregateFunctionBuilder::ffi_state
installs FfiState<T>’s three together); scalar and table bind/init
callbacks are kept apart by their argument types. Builders whose callbacks
quack-rs installs itself — a closure-built TypedScalarFunctionBuilder,
a typed table function — add no obligation.
For the Connection handed to your registration closure, the connection
requirement always holds: quack-rs builds it from the handles DuckDB
passed the entry point and only lends it to the closure, so it cannot
outlive them.
They stay unsafe because Registrar is a safe trait: any type can
implement it around any handle, so a safe method could not rely on the
handle being valid. Making them safe would mean unsafe trait Registrar, a
breaking change for every implementor (including test doubles like
MockRegistrar) that buys nothing for the
one implementation the entry point hands out.
§Example
use quack_rs::connection::Registrar;
use quack_rs::error::ExtensionError;
use quack_rs::scalar::ScalarFunctionBuilder;
/// Register all functions for this extension.
///
/// # Safety
///
/// `reg` must provide a valid `DuckDB` connection for the duration of this call.
unsafe fn register_all(reg: &impl Registrar) -> Result<(), ExtensionError> {
let builder = ScalarFunctionBuilder::map1("my_fn", |x: i64| x + 1)?;
unsafe { reg.register_typed_scalar(builder) }
}Required Methods§
Sourceunsafe fn register_scalar(
&self,
builder: ScalarFunctionBuilder,
) -> Result<(), ExtensionError>
unsafe fn register_scalar( &self, builder: ScalarFunctionBuilder, ) -> Result<(), ExtensionError>
Register a scalar function.
§Safety
The underlying connection must be valid for the duration of this call.
Sourceunsafe fn register_scalar_set(
&self,
builder: ScalarFunctionSetBuilder,
) -> Result<(), ExtensionError>
unsafe fn register_scalar_set( &self, builder: ScalarFunctionSetBuilder, ) -> Result<(), ExtensionError>
Register a scalar function set (multiple overloads under one name).
§Safety
The underlying connection must be valid for the duration of this call.
Sourceunsafe fn register_aggregate(
&self,
builder: AggregateFunctionBuilder,
) -> Result<(), ExtensionError>
unsafe fn register_aggregate( &self, builder: AggregateFunctionBuilder, ) -> Result<(), ExtensionError>
Register an aggregate function.
§Safety
The underlying connection must be valid for the duration of this call,
and the builder’s raw callbacks must fit the calls DuckDB makes: its
state_size, init, destructor and data callbacks must all describe
the same state (see Registrar’s “Why every method is unsafe”).
Sourceunsafe fn register_aggregate_set(
&self,
builder: AggregateFunctionSetBuilder,
) -> Result<(), ExtensionError>
unsafe fn register_aggregate_set( &self, builder: AggregateFunctionSetBuilder, ) -> Result<(), ExtensionError>
Sourceunsafe fn register_table(
&self,
builder: TableFunctionBuilder,
) -> Result<(), ExtensionError>
unsafe fn register_table( &self, builder: TableFunctionBuilder, ) -> Result<(), ExtensionError>
Register a table function.
§Safety
The underlying connection must be valid for the duration of this call.
Sourceunsafe fn register_sql_macro(
&self,
sql_macro: SqlMacro,
) -> Result<(), ExtensionError>
unsafe fn register_sql_macro( &self, sql_macro: SqlMacro, ) -> Result<(), ExtensionError>
Register a SQL macro (scalar or table-returning).
§Safety
The underlying connection must be valid for the duration of this call.
Sourceunsafe fn register_cast(
&self,
builder: CastFunctionBuilder,
) -> Result<(), ExtensionError>
unsafe fn register_cast( &self, builder: CastFunctionBuilder, ) -> Result<(), ExtensionError>
Register a custom type cast function.
§Safety
The underlying connection must be valid for the duration of this call.
Sourceunsafe fn register_copy_function(
&self,
builder: CopyFunctionBuilder,
) -> Result<(), ExtensionError>
unsafe fn register_copy_function( &self, builder: CopyFunctionBuilder, ) -> Result<(), ExtensionError>
Register a custom COPY TO function (DuckDB 1.5.0+).
§Safety
The underlying connection must be valid for the duration of this call.
Sourceunsafe fn register_config_option(
&self,
builder: ConfigOptionBuilder,
) -> Result<(), ExtensionError>
unsafe fn register_config_option( &self, builder: ConfigOptionBuilder, ) -> Result<(), ExtensionError>
Registers an extension-defined configuration option.
§Errors
Returns ExtensionError if DuckDB rejects the option.
§Safety
The underlying connection must be valid.
Provided Methods§
Sourceunsafe fn register_typed_scalar(
&self,
builder: TypedScalarFunctionBuilder,
) -> Result<(), ExtensionError>
unsafe fn register_typed_scalar( &self, builder: TypedScalarFunctionBuilder, ) -> Result<(), ExtensionError>
Register a scalar function built from a Rust closure
(ScalarFunctionBuilder::map1 and friends).
The default implementation hands the underlying builder to
register_scalar, so existing implementations
(including MockRegistrar) need no
change. An implementation must register that builder as it receives it:
the closure’s trampoline refuses to run, with a SQL error, if the
signature was edited on the way.
§Errors
Returns whatever register_scalar returns.
§Safety
The underlying connection must be valid for the duration of this call.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".