Skip to main content

Registrar

Trait Registrar 

Source
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§

Source

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.

Source

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.

Source

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”).

Source

unsafe fn register_aggregate_set( &self, builder: AggregateFunctionSetBuilder, ) -> Result<(), ExtensionError>

Register an aggregate function set (multiple overloads under one name).

§Safety

The underlying connection must be valid for the duration of this call, and within each overload the raw callbacks must all describe the same state (see Registrar’s “Why every method is unsafe”).

Source

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.

Source

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.

Source

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.

Source

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.

Source

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§

Source

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".

Implementors§