Skip to main content

quack_rs/
connection.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! [`Connection`] — version-agnostic extension registration facade.
7//!
8//! [`Connection`] wraps the `duckdb_connection` and `duckdb_database` handles
9//! provided to your extension during initialization. It implements the
10//! [`Registrar`] trait, which provides a uniform API for registering all
11//! extension components that works identically across `DuckDB` 1.4.x and 1.5.x.
12//!
13//! # Obtaining a `Connection`
14//!
15//! Use [`init_extension_v2`][crate::entry_point::init_extension_v2] or the
16//! [`entry_point_v2!`][crate::entry_point_v2] macro. These pass a `&Connection`
17//! to your registration callback instead of the raw `duckdb_connection`.
18//!
19//! ```rust,no_run
20//! use quack_rs::connection::{Connection, Registrar};
21//! use quack_rs::error::ExtensionError;
22//! use quack_rs::scalar::ScalarFunctionBuilder;
23//!
24//! unsafe fn register_all(reg: &impl Registrar) -> Result<(), ExtensionError> {
25//!     let builder = ScalarFunctionBuilder::map1("my_fn", |x: i64| x + 1)?;
26//!     unsafe { reg.register_typed_scalar(builder) }
27//! }
28//!
29//! quack_rs::entry_point_v2!(my_extension_init_c_api, |con| {
30//!     unsafe { register_all(con) }
31//! });
32//! ```
33//!
34//! # `DuckDB` version compatibility
35//!
36//! [`Connection`] and [`Registrar`] provide a stable API across `DuckDB` 1.4.x,
37//! 1.5.x and 2.0.0. The underlying C API version string (`"v1.2.0"`) loads in every
38//! one of them: E2E tests confirm it for `DuckDB` 1.4.4, 1.5.0 and 2.0.0, and 1.5.6
39//! and 2.0.0, which declare `v1.5.6`, accept any earlier C API version (their
40//! `VersioningUtils::IsSupportedCAPIVersion`).
41//!
42//! When a future `DuckDB` release changes the C API version or adds new
43//! registration surface, additional methods will be added to [`Connection`]
44//! behind a version-specific feature flag (e.g. `duckdb-1-5`).
45
46use core::ffi::c_void;
47
48use libduckdb_sys::{duckdb_connection, duckdb_database, duckdb_delete_callback_t};
49
50use crate::aggregate::{AggregateFunctionBuilder, AggregateFunctionSetBuilder};
51use crate::cast::CastFunctionBuilder;
52#[cfg(feature = "duckdb-1-5")]
53use crate::copy_function::CopyFunctionBuilder;
54use crate::error::ExtensionError;
55use crate::replacement_scan::{ReplacementScanBuilder, ReplacementScanFn};
56use crate::scalar::{ScalarFunctionBuilder, ScalarFunctionSetBuilder, TypedScalarFunctionBuilder};
57use crate::sql_macro::SqlMacro;
58use crate::table::TableFunctionBuilder;
59
60/// Version-agnostic trait for registering `DuckDB` extension components.
61///
62/// Implemented by [`Connection`]. Writing registration code against this trait
63/// means the same code compiles and runs on `DuckDB` 1.4.x and 1.5.x without
64/// modification.
65///
66/// # Why every method is `unsafe`
67///
68/// Each method requires that the implementor's underlying `duckdb_connection`
69/// is valid for the call, and that the raw callbacks installed on the builder
70/// fit the calls `DuckDB` will make to them: each callback's own `# Safety`
71/// preconditions must hold where it is installed. For a raw aggregate that
72/// means `state_size`, `init`, `destructor` and the data callbacks all
73/// describe the same state ([`AggregateFunctionBuilder::ffi_state`][crate::aggregate::AggregateFunctionBuilder::ffi_state]
74/// installs `FfiState<T>`'s three together); scalar and table bind/init
75/// callbacks are kept apart by their argument types. Builders whose callbacks
76/// quack-rs installs itself — a closure-built [`TypedScalarFunctionBuilder`],
77/// a typed table function — add no obligation.
78///
79/// For the [`Connection`] handed to your registration closure, the connection
80/// requirement always holds: quack-rs builds it from the handles `DuckDB`
81/// passed the entry point and only lends it to the closure, so it cannot
82/// outlive them.
83///
84/// They stay `unsafe` because `Registrar` is a *safe* trait: any type can
85/// implement it around any handle, so a safe method could not rely on the
86/// handle being valid. Making them safe would mean `unsafe trait Registrar`, a
87/// breaking change for every implementor (including test doubles like
88/// [`MockRegistrar`][crate::testing::MockRegistrar]) that buys nothing for the
89/// one implementation the entry point hands out.
90///
91/// # Example
92///
93/// ```rust,no_run
94/// use quack_rs::connection::Registrar;
95/// use quack_rs::error::ExtensionError;
96/// use quack_rs::scalar::ScalarFunctionBuilder;
97///
98/// /// Register all functions for this extension.
99/// ///
100/// /// # Safety
101/// ///
102/// /// `reg` must provide a valid `DuckDB` connection for the duration of this call.
103/// unsafe fn register_all(reg: &impl Registrar) -> Result<(), ExtensionError> {
104///     let builder = ScalarFunctionBuilder::map1("my_fn", |x: i64| x + 1)?;
105///     unsafe { reg.register_typed_scalar(builder) }
106/// }
107/// ```
108pub trait Registrar {
109    /// Register a scalar function.
110    ///
111    /// # Safety
112    ///
113    /// The underlying connection must be valid for the duration of this call.
114    unsafe fn register_scalar(&self, builder: ScalarFunctionBuilder) -> Result<(), ExtensionError>;
115
116    /// Register a scalar function built from a Rust closure
117    /// ([`ScalarFunctionBuilder::map1`] and friends).
118    ///
119    /// The default implementation hands the underlying builder to
120    /// [`register_scalar`][Self::register_scalar], so existing implementations
121    /// (including [`MockRegistrar`][crate::testing::MockRegistrar]) need no
122    /// change. An implementation must register that builder as it receives it:
123    /// the closure's trampoline refuses to run, with a SQL error, if the
124    /// signature was edited on the way.
125    ///
126    /// # Errors
127    ///
128    /// Returns whatever [`register_scalar`][Self::register_scalar] returns.
129    ///
130    /// # Safety
131    ///
132    /// The underlying connection must be valid for the duration of this call.
133    unsafe fn register_typed_scalar(
134        &self,
135        builder: TypedScalarFunctionBuilder,
136    ) -> Result<(), ExtensionError> {
137        // SAFETY: forwarded from this method's own contract.
138        unsafe { self.register_scalar(builder.into_inner()) }
139    }
140
141    /// Register a scalar function set (multiple overloads under one name).
142    ///
143    /// # Safety
144    ///
145    /// The underlying connection must be valid for the duration of this call.
146    unsafe fn register_scalar_set(
147        &self,
148        builder: ScalarFunctionSetBuilder,
149    ) -> Result<(), ExtensionError>;
150
151    /// Register an aggregate function.
152    ///
153    /// # Safety
154    ///
155    /// The underlying connection must be valid for the duration of this call,
156    /// and the builder's raw callbacks must fit the calls `DuckDB` makes: its
157    /// `state_size`, `init`, `destructor` and data callbacks must all describe
158    /// the same state (see [`Registrar`]'s "Why every method is `unsafe`").
159    unsafe fn register_aggregate(
160        &self,
161        builder: AggregateFunctionBuilder,
162    ) -> Result<(), ExtensionError>;
163
164    /// Register an aggregate function set (multiple overloads under one name).
165    ///
166    /// # Safety
167    ///
168    /// The underlying connection must be valid for the duration of this call,
169    /// and within each overload the raw callbacks must all describe the same
170    /// state (see [`Registrar`]'s "Why every method is `unsafe`").
171    unsafe fn register_aggregate_set(
172        &self,
173        builder: AggregateFunctionSetBuilder,
174    ) -> Result<(), ExtensionError>;
175
176    /// Register a table function.
177    ///
178    /// # Safety
179    ///
180    /// The underlying connection must be valid for the duration of this call.
181    unsafe fn register_table(&self, builder: TableFunctionBuilder) -> Result<(), ExtensionError>;
182
183    /// Register a `SQL` macro (scalar or table-returning).
184    ///
185    /// # Safety
186    ///
187    /// The underlying connection must be valid for the duration of this call.
188    unsafe fn register_sql_macro(&self, sql_macro: SqlMacro) -> Result<(), ExtensionError>;
189
190    /// Register a custom type cast function.
191    ///
192    /// # Safety
193    ///
194    /// The underlying connection must be valid for the duration of this call.
195    unsafe fn register_cast(&self, builder: CastFunctionBuilder) -> Result<(), ExtensionError>;
196
197    /// Register a custom `COPY TO` function (`DuckDB` 1.5.0+).
198    ///
199    /// # Safety
200    ///
201    /// The underlying connection must be valid for the duration of this call.
202    #[cfg(feature = "duckdb-1-5")]
203    unsafe fn register_copy_function(
204        &self,
205        builder: CopyFunctionBuilder,
206    ) -> Result<(), ExtensionError>;
207
208    /// Registers an extension-defined configuration option.
209    ///
210    /// # Errors
211    ///
212    /// Returns [`ExtensionError`] if `DuckDB` rejects the option.
213    ///
214    /// # Safety
215    ///
216    /// The underlying connection must be valid.
217    #[cfg(feature = "duckdb-1-5")]
218    unsafe fn register_config_option(
219        &self,
220        builder: crate::config_option::ConfigOptionBuilder,
221    ) -> Result<(), ExtensionError>;
222}
223
224/// Wraps the `duckdb_connection` and `duckdb_database` provided to your
225/// extension at load time.
226///
227/// `Connection` implements [`Registrar`], offering a single, uniform API for
228/// registering all extension components. It also exposes
229/// [`register_replacement_scan`][Self::register_replacement_scan] and
230/// [`register_replacement_scan_with_data`][Self::register_replacement_scan_with_data],
231/// which require the `duckdb_database` handle and therefore cannot be part of
232/// the `Registrar` trait.
233///
234/// # Obtaining a `Connection`
235///
236/// Use [`init_extension_v2`][crate::entry_point::init_extension_v2] (or the
237/// [`entry_point_v2!`][crate::entry_point_v2] macro). Both pass a `&Connection`
238/// to your registration callback.
239///
240/// # Version compatibility
241///
242/// `Connection` provides a uniform API across `DuckDB` 1.4.x and 1.5.x.
243/// When future `DuckDB` releases add new C API surface, additional methods will
244/// be gated on the corresponding feature flag.
245///
246/// # What the collision checks cost
247///
248/// Before the first scalar and the first table function it registers, a
249/// `Connection` lists the catalog once each (see the field docs below), so
250/// that a registration that would silently replace a built-in, or be dropped,
251/// is refused instead. Each listing is a scan of `duckdb_functions()`, which
252/// builds a row for **every function and macro in every attached database**
253/// before any `WHERE` applies: the table function has no filter or projection
254/// pushdown (`src/function/table/system/duckdb_functions.cpp`), so narrowing
255/// the query to the names being registered, or to the name column, does not
256/// make it cheaper. Measured with the `DuckDB` CLI on a shared 4-vCPU machine:
257/// one scan takes about 20 ms on 1.5.6 and 13 ms on 2.0.0 in an empty
258/// database, and about 110 ms on both with 20,000 user macros, so a `LOAD`
259/// into a database with that many macros spends about 0.2 s more on its two
260/// scans. Registering on the raw connection (`register(con)` on a builder)
261/// scans once per call instead of once per load.
262#[derive(Debug)]
263pub struct Connection {
264    con: duckdb_connection,
265    db: duckdb_database,
266    /// The catalog's scalar signatures, listed on the first scalar
267    /// registration and kept up to date with this connection's own, so the
268    /// collision check costs one catalog scan per extension load rather than
269    /// one per function (see [`ScalarFunctionBuilder::register`]).
270    ///
271    /// SQL run directly on the raw handle during registration — a
272    /// `CREATE MACRO`, another extension's `LOAD` — is not seen by it. A macro
273    /// name cannot take a scalar signature (`DuckDB` refuses the scalar
274    /// instead), so what can go unseen is a scalar function registered by
275    /// other code in between, whose collision the check would then miss.
276    scalars: core::cell::RefCell<Option<crate::scalar::builder::collision::ExistingScalars>>,
277    /// The catalog's table function and table macro names, listed on the first
278    /// table function registration and kept up to date with this connection's
279    /// own, so the collision check costs one catalog scan per extension load
280    /// rather than one per function (see
281    /// [`TableFunctionBuilder::register`]).
282    ///
283    /// It is a one-time copy, so a table function registered on the raw handle
284    /// afterwards — another extension's `LOAD`, or a direct call to
285    /// [`TableFunctionBuilder::register`] — is not seen by it. A later
286    /// `register_table` under that name then passes the check and `DuckDB`
287    /// deals with the duplicate itself — dropping it with a success report on
288    /// v1.5.x, failing the call with no reason on v1.4.x — which is the failure
289    /// the check exists to prevent. The scalar snapshot above has the same gap.
290    ///
291    /// [`TableFunctionBuilder::register`]: crate::table::TableFunctionBuilder::register
292    tables: core::cell::RefCell<Option<crate::table::collision::ExistingTableFunctions>>,
293}
294
295impl Connection {
296    /// Create a `Connection` from raw `DuckDB` handles.
297    ///
298    /// [`init_extension_v2`][crate::entry_point::init_extension_v2] makes the
299    /// one an extension registers through. This constructor lets other code —
300    /// a test of an extension's registration function against a real
301    /// database, say — drive the same [`Registrar`] implementation.
302    ///
303    /// # Safety
304    ///
305    /// Both `con` and `db` must be valid, non-null handles for the duration of
306    /// the `Connection`'s lifetime, and `con` must be a connection to `db`.
307    #[inline]
308    #[must_use]
309    pub const unsafe fn from_raw(con: duckdb_connection, db: duckdb_database) -> Self {
310        Self {
311            con,
312            db,
313            scalars: core::cell::RefCell::new(None),
314            tables: core::cell::RefCell::new(None),
315        }
316    }
317
318    /// Return the raw `duckdb_connection` handle.
319    ///
320    /// Use this to call C API functions that `quack-rs` does not yet wrap.
321    #[inline]
322    pub const fn as_raw_connection(&self) -> duckdb_connection {
323        self.con
324    }
325
326    /// Return the raw `duckdb_database` handle.
327    ///
328    /// Use this to call C API functions that require the database handle, such
329    /// as replacement scan registration or (with `duckdb-1-5`) config option
330    /// registration.
331    ///
332    /// # The handle dies when `LOAD` returns
333    ///
334    /// `DuckDB` hands the entry point a database handle that belongs to the
335    /// load: it is freed when `LOAD` finishes. Use it inside the registration
336    /// closure only, and **never store it** (in a `static`, in `extra_info`, in
337    /// a function's state). A connection opened from a stored handle later is a
338    /// use after free: valgrind reports it, and it fails or segfaults at random
339    /// depending on what reuses the memory. To run SQL after loading, open an
340    /// [`OwnedConnection`][crate::query::OwnedConnection] during registration
341    /// with [`open_connection`][Self::open_connection] and keep that (it holds
342    /// its own reference to the database instance), mindful of what keeping
343    /// one costs (see there).
344    #[inline]
345    pub const fn as_raw_database(&self) -> duckdb_database {
346        self.db
347    }
348
349    /// Runs `sql` on this connection and returns the materialised result.
350    ///
351    /// Only valid inside your registration closure: the entry point disconnects
352    /// this connection once the closure returns. For SQL that must run later,
353    /// open an [`OwnedConnection`][crate::query::OwnedConnection] with
354    /// [`open_connection`][Self::open_connection] and keep it.
355    ///
356    /// # Errors
357    ///
358    /// Returns [`ExtensionError`] carrying `DuckDB`'s own message if the
359    /// statement fails.
360    ///
361    /// # Safety
362    ///
363    /// The underlying connection must be valid for the duration of this call.
364    pub unsafe fn query(&self, sql: &str) -> Result<crate::query::QueryResult, ExtensionError> {
365        // SAFETY: self.con is valid per Connection invariant.
366        unsafe { crate::query::query(self.con, sql) }
367    }
368
369    /// Runs `sql` for its side effects, returning the number of rows changed.
370    ///
371    /// # Errors
372    ///
373    /// See [`query`][Self::query].
374    ///
375    /// # Safety
376    ///
377    /// The underlying connection must be valid for the duration of this call.
378    pub unsafe fn execute(&self, sql: &str) -> Result<u64, ExtensionError> {
379        // SAFETY: self.con is valid per Connection invariant.
380        unsafe { crate::query::execute(self.con, sql) }
381    }
382
383    /// Prepares `sql` on this connection.
384    ///
385    /// Use this rather than interpolating values into SQL text.
386    ///
387    /// # Errors
388    ///
389    /// See [`query`][Self::query].
390    ///
391    /// # Safety
392    ///
393    /// The underlying connection must be valid for the duration of this call.
394    pub unsafe fn prepare(
395        &self,
396        sql: &str,
397    ) -> Result<crate::query::PreparedStatement, ExtensionError> {
398        // SAFETY: self.con is valid per Connection invariant.
399        unsafe { crate::query::prepare(self.con, sql) }
400    }
401
402    /// The tables `sql` reads or writes, without running it; see
403    /// [`query::table_names`][crate::query::table_names] (`DuckDB` 1.5.0+).
404    ///
405    /// # Errors
406    ///
407    /// See [`query::table_names`][crate::query::table_names].
408    ///
409    /// # Safety
410    ///
411    /// The underlying connection must be valid for the duration of this call.
412    // One FFI call; covered by tests/ffi_roundtrip/query_metadata.rs.
413    #[cfg_attr(test, mutants::skip)]
414    #[cfg(feature = "duckdb-1-5")]
415    pub unsafe fn table_names(
416        &self,
417        sql: &str,
418        qualified: bool,
419    ) -> Result<Vec<String>, ExtensionError> {
420        // SAFETY: self.con is valid per Connection invariant.
421        unsafe { crate::query::table_names(self.con, sql, qualified) }
422    }
423
424    /// Opens a second, independently owned connection to the same database.
425    ///
426    /// Unlike the borrowed registration connection, the returned
427    /// [`OwnedConnection`][crate::query::OwnedConnection] stays valid after
428    /// extension loading finishes — a `duckdb_connection` holds its own
429    /// reference to the database instance. Keep one when a callback or a
430    /// background thread needs to run SQL.
431    ///
432    /// # What keeping a connection costs
433    ///
434    /// The retained connection keeps the **database instance** alive, so
435    /// closing the host's own connection does not shut the database down: a
436    /// file database is not checkpointed (its `.wal` stays) and its lock is
437    /// held until the process exits, which makes a second process fail with
438    /// "Could not set lock on file". If the connection is owned by state the
439    /// extension registers (a closure captured by a function, say), the
440    /// instance also references that function, and the cycle means it is never
441    /// freed. A process-wide `static` holding the connection is first-wins:
442    /// with several database instances in one process (a Python program that
443    /// calls `duckdb.connect()` repeatedly), every instance's functions would
444    /// run on the first instance's connection. Prefer opening a connection per
445    /// instance, held by that instance's own registered state, and decide
446    /// whether the extension really needs to run SQL from a callback at all.
447    ///
448    /// # Errors
449    ///
450    /// Returns [`ExtensionError`] if `DuckDB` refuses to open the connection.
451    ///
452    /// # Safety
453    ///
454    /// The underlying `duckdb_database` must be valid for the duration of this
455    /// call.
456    pub unsafe fn open_connection(&self) -> Result<crate::query::OwnedConnection, ExtensionError> {
457        // SAFETY: self.db is valid per Connection invariant.
458        unsafe { crate::query::OwnedConnection::open(self.db) }
459    }
460
461    /// Register a replacement scan backed by a raw function pointer and extra
462    /// data.
463    ///
464    /// For the ergonomic owned-data variant, see
465    /// [`register_replacement_scan_with_data`][Self::register_replacement_scan_with_data].
466    ///
467    /// # Safety
468    ///
469    /// - The underlying `duckdb_database` must be valid.
470    /// - `extra_data` must remain valid until `delete_callback` is called (or
471    ///   until the database is closed if `delete_callback` is `None`).
472    pub unsafe fn register_replacement_scan(
473        &self,
474        callback: ReplacementScanFn,
475        extra_data: *mut c_void,
476        delete_callback: duckdb_delete_callback_t,
477    ) {
478        // SAFETY: self.db is valid per Connection invariant.
479        unsafe {
480            ReplacementScanBuilder::register(self.db, callback, extra_data, delete_callback);
481        }
482    }
483
484    /// Register a replacement scan with owned extra data.
485    ///
486    /// Boxes `data` and registers a drop destructor automatically. This is the
487    /// safe, ergonomic alternative to
488    /// [`register_replacement_scan`][Self::register_replacement_scan].
489    ///
490    /// `T` must be `Send + Sync`; see
491    /// [`ReplacementScanBuilder::register_with_data`].
492    ///
493    /// # Safety
494    ///
495    /// The underlying `duckdb_database` must be valid.
496    pub unsafe fn register_replacement_scan_with_data<T: Send + Sync + 'static>(
497        &self,
498        callback: ReplacementScanFn,
499        data: T,
500    ) {
501        // SAFETY: self.db is valid per Connection invariant.
502        unsafe {
503            ReplacementScanBuilder::register_with_data(self.db, callback, data);
504        }
505    }
506}
507
508impl Registrar for Connection {
509    unsafe fn register_scalar(&self, builder: ScalarFunctionBuilder) -> Result<(), ExtensionError> {
510        // SAFETY: self.con is valid per Connection invariant; caller upholds builder contract.
511        unsafe { builder.register_with(self.con, Some(&self.scalars)) }
512    }
513
514    unsafe fn register_typed_scalar(
515        &self,
516        builder: TypedScalarFunctionBuilder,
517    ) -> Result<(), ExtensionError> {
518        // SAFETY: self.con is valid per Connection invariant.
519        unsafe {
520            builder
521                .into_inner()
522                .register_with(self.con, Some(&self.scalars))
523        }
524    }
525
526    unsafe fn register_scalar_set(
527        &self,
528        builder: ScalarFunctionSetBuilder,
529    ) -> Result<(), ExtensionError> {
530        // SAFETY: self.con is valid per Connection invariant.
531        unsafe { builder.register_with(self.con, Some(&self.scalars)) }
532    }
533
534    unsafe fn register_aggregate(
535        &self,
536        builder: AggregateFunctionBuilder,
537    ) -> Result<(), ExtensionError> {
538        // SAFETY: self.con is valid per Connection invariant.
539        unsafe { builder.register(self.con) }
540    }
541
542    unsafe fn register_aggregate_set(
543        &self,
544        builder: AggregateFunctionSetBuilder,
545    ) -> Result<(), ExtensionError> {
546        // SAFETY: self.con is valid per Connection invariant.
547        unsafe { builder.register(self.con) }
548    }
549
550    unsafe fn register_table(&self, builder: TableFunctionBuilder) -> Result<(), ExtensionError> {
551        // SAFETY: self.con is valid per Connection invariant.
552        unsafe { builder.register_with(self.con, Some(&self.tables)) }
553    }
554
555    unsafe fn register_sql_macro(&self, sql_macro: SqlMacro) -> Result<(), ExtensionError> {
556        // SAFETY: self.con is valid per Connection invariant.
557        unsafe { sql_macro.register(self.con) }
558    }
559
560    unsafe fn register_cast(&self, builder: CastFunctionBuilder) -> Result<(), ExtensionError> {
561        // SAFETY: self.con is valid per Connection invariant.
562        unsafe { builder.register(self.con) }
563    }
564
565    #[cfg(feature = "duckdb-1-5")]
566    unsafe fn register_copy_function(
567        &self,
568        builder: CopyFunctionBuilder,
569    ) -> Result<(), ExtensionError> {
570        // SAFETY: self.con is valid per Connection invariant.
571        unsafe { builder.register(self.con) }
572    }
573
574    #[cfg(feature = "duckdb-1-5")]
575    unsafe fn register_config_option(
576        &self,
577        builder: crate::config_option::ConfigOptionBuilder,
578    ) -> Result<(), ExtensionError> {
579        // SAFETY: self.con is valid per Connection invariant.
580        unsafe { builder.register(self.con) }
581    }
582}