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}