Skip to main content

quack_rs/table/
builder.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//! Builder for registering `DuckDB` table functions.
7//!
8//! Table functions are the backbone of "real" `DuckDB` extensions: they are
9//! SELECT-able, support projection pushdown, named parameters, and can
10//! produce arbitrary output schemas determined at query-parse time.
11//!
12//! # Table function lifecycle
13//!
14//! ```text
15//! 1. bind       — parse args, declare output columns, optionally set cardinality hint
16//! 2. init       — allocate global scan state (shared across threads)
17//! 3. local_init — allocate per-thread scan state (optional; parallelism itself
18//!    comes from `InitInfo::set_max_threads` in `init`)
19//! 4. scan       — fill one output chunk; set chunk size to 0 when exhausted
20//! ```
21//!
22//! # Example: A constant table function
23//!
24//! ```rust,no_run
25//! use quack_rs::table::{TableFunctionBuilder, FfiBindData, FfiInitData};
26//! use quack_rs::types::TypeId;
27//! use libduckdb_sys::{
28//!     duckdb_bind_info, duckdb_init_info, duckdb_function_info,
29//!     duckdb_data_chunk, duckdb_data_chunk_set_size,
30//! };
31//!
32//! struct Config { limit: u64 }
33//! struct State  { emitted: u64 }
34//!
35//! unsafe extern "C" fn bind(info: duckdb_bind_info) {
36//!     unsafe {
37//!         // Declare the output schema.
38//!         quack_rs::table::BindInfo::new(info)
39//!             .add_result_column("n", TypeId::BigInt);
40//!         // Store bind-time configuration.
41//!         FfiBindData::<Config>::set(info, Config { limit: 100 });
42//!     }
43//! }
44//!
45//! unsafe extern "C" fn init(info: duckdb_init_info) {
46//!     unsafe { FfiInitData::<State>::set(info, State { emitted: 0 }); }
47//! }
48//!
49//! unsafe extern "C" fn scan(info: duckdb_function_info, output: duckdb_data_chunk) {
50//!     // scan logic
51//! }
52//!
53//! // fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
54//! //     unsafe {
55//! //         TableFunctionBuilder::new("my_table_fn")
56//! //             .bind(bind)
57//! //             .init(init)
58//! //             .scan(scan)
59//! //             .register(con)
60//! //     }
61//! // }
62//! ```
63
64use std::ffi::CString;
65use std::os::raw::c_void;
66
67use libduckdb_sys::{
68    duckdb_bind_info, duckdb_connection, duckdb_create_table_function, duckdb_data_chunk,
69    duckdb_destroy_table_function, duckdb_function_info, duckdb_init_info,
70    duckdb_register_table_function, duckdb_table_function,
71    duckdb_table_function_add_named_parameter, duckdb_table_function_add_parameter,
72    duckdb_table_function_set_bind, duckdb_table_function_set_extra_info,
73    duckdb_table_function_set_function, duckdb_table_function_set_init,
74    duckdb_table_function_set_local_init, duckdb_table_function_set_name,
75    duckdb_table_function_supports_projection_pushdown, DuckDBSuccess,
76};
77
78use crate::error::ExtensionError;
79use crate::types::logical_type::SlotCheck;
80use crate::types::{LogicalType, TypeId};
81use crate::validate::validate_function_name;
82
83/// The bind callback: declare output columns, read parameters, store bind data.
84pub type BindFn = unsafe extern "C" fn(info: duckdb_bind_info);
85
86/// The init callback: allocate global scan state.
87pub type InitFn = unsafe extern "C" fn(info: duckdb_init_info);
88
89/// The scan callback: fill one output chunk; set chunk size to 0 when done.
90pub type ScanFn = unsafe extern "C" fn(info: duckdb_function_info, output: duckdb_data_chunk);
91
92/// The extra-info destructor callback: called by `DuckDB` to free function-level extra data.
93pub type ExtraDestroyFn = unsafe extern "C" fn(data: *mut c_void);
94
95/// A named parameter specification: (name, type).
96enum NamedParam {
97    Simple {
98        name: CString,
99        type_id: TypeId,
100    },
101    Logical {
102        name: CString,
103        logical_type: LogicalType,
104    },
105}
106
107/// Builder for registering a `DuckDB` table function.
108///
109/// Table functions are the most powerful extension type — they can return
110/// arbitrary result schemas, support named parameters, projection pushdown,
111/// and parallel execution.
112///
113/// # Required fields
114///
115/// - [`bind`][TableFunctionBuilder::bind]: must be set.
116/// - [`init`][TableFunctionBuilder::init]: must be set.
117/// - [`scan`][TableFunctionBuilder::scan]: must be set.
118///
119/// # Optional features
120///
121/// - [`param`][TableFunctionBuilder::param]: positional parameters.
122/// - [`named_param`][TableFunctionBuilder::named_param]: named parameters (`name := value`).
123/// - [`local_init`][TableFunctionBuilder::local_init]: per-thread scan state. It does not by
124///   itself make the scan parallel; [`InitInfo::set_max_threads`][crate::table::InitInfo::set_max_threads] does.
125/// - [`projection_pushdown`][TableFunctionBuilder::projection_pushdown]: hint projection info to `DuckDB`.
126/// - [`extra_info`][TableFunctionBuilder::extra_info]: function-level data available in all callbacks.
127#[must_use]
128pub struct TableFunctionBuilder {
129    name: CString,
130    params: Vec<TypeId>,
131    logical_params: Vec<(usize, LogicalType)>,
132    named_params: Vec<NamedParam>,
133    bind: Option<BindFn>,
134    init: Option<InitFn>,
135    local_init: Option<InitFn>,
136    scan: Option<ScanFn>,
137    projection_pushdown: bool,
138    /// Set by [`TypedTableFunctionBuilder::build`][crate::table::TypedTableFunctionBuilder::build]:
139    /// the scan is a typed closure, which cannot follow a projection.
140    typed: bool,
141    /// The first of `bind`, `init`, `local_init`, `scan` or `extra_info` set
142    /// after `typed`: the typed trampolines rely on each other and on their
143    /// `extra_info`, so replacing one is refused at registration.
144    replaced_after_typed: Option<&'static str>,
145    extra_info: Option<crate::extra_info::ExtraInfo>,
146}
147
148impl TableFunctionBuilder {
149    /// Creates a new builder for a table function with the given name.
150    ///
151    /// # Panics
152    ///
153    /// Panics if `name` contains an interior null byte.
154    pub fn new(name: &str) -> Self {
155        Self {
156            name: CString::new(name).expect("function name must not contain null bytes"),
157            params: Vec::new(),
158            logical_params: Vec::new(),
159            named_params: Vec::new(),
160            bind: None,
161            init: None,
162            local_init: None,
163            scan: None,
164            projection_pushdown: false,
165            typed: false,
166            replaced_after_typed: None,
167            extra_info: None,
168        }
169    }
170
171    /// Creates a new builder with function name validation.
172    ///
173    /// # Errors
174    ///
175    /// Returns `ExtensionError` if the name is invalid.
176    pub fn try_new(name: &str) -> Result<Self, ExtensionError> {
177        validate_function_name(name)?;
178        let c_name = CString::new(name)
179            .map_err(|_| ExtensionError::new("function name contains interior null byte"))?;
180        Ok(Self {
181            name: c_name,
182            params: Vec::new(),
183            logical_params: Vec::new(),
184            named_params: Vec::new(),
185            bind: None,
186            init: None,
187            local_init: None,
188            scan: None,
189            projection_pushdown: false,
190            typed: false,
191            replaced_after_typed: None,
192            extra_info: None,
193        })
194    }
195
196    /// Returns the function name.
197    ///
198    /// Useful for introspection and for [`MockRegistrar`][crate::testing::MockRegistrar].
199    pub fn name(&self) -> &str {
200        self.name.to_str().unwrap_or("")
201    }
202
203    /// Whether [`projection_pushdown`][Self::projection_pushdown] was enabled.
204    ///
205    /// The typed builder refuses a raw builder that has it on; see
206    /// [`TypedTableFunctionBuilder::build`][crate::table::TypedTableFunctionBuilder::build].
207    pub(crate) const fn projection_pushdown_enabled(&self) -> bool {
208        self.projection_pushdown
209    }
210
211    /// Records `what` if the builder is already wired to typed closures.
212    const fn note_replacement(&mut self, what: &'static str) {
213        if self.typed && self.replaced_after_typed.is_none() {
214            self.replaced_after_typed = Some(what);
215        }
216    }
217
218    /// Marks the builder as wired to a typed scan closure, so that
219    /// [`check_parts`][Self::check_parts] refuses projection pushdown switched
220    /// on after [`TypedTableFunctionBuilder::build`][crate::table::TypedTableFunctionBuilder::build].
221    pub(crate) const fn mark_typed(mut self) -> Self {
222        self.typed = true;
223        self
224    }
225
226    /// Adds a positional parameter with the given type.
227    pub fn param(mut self, type_id: TypeId) -> Self {
228        self.params.push(type_id);
229        self
230    }
231
232    /// Adds a positional parameter with a complex [`LogicalType`].
233    ///
234    /// Use this for parameterized types that [`TypeId`] cannot express, such as
235    /// `LIST(BIGINT)`, `MAP(VARCHAR, INTEGER)`, or `STRUCT(...)`.
236    #[cfg_attr(test, mutants::skip)] // position arithmetic tested via E2E (requires DuckDB runtime)
237    pub fn param_logical(mut self, logical_type: LogicalType) -> Self {
238        let position = self.params.len() + self.logical_params.len();
239        self.logical_params.push((position, logical_type));
240        self
241    }
242
243    /// Adds a named parameter (e.g., `my_fn(path := 'data.csv')`).
244    ///
245    /// Named parameters are accessed in the bind callback via
246    /// `duckdb_bind_get_named_parameter`.
247    ///
248    /// # Panics
249    ///
250    /// Panics if `name` contains an interior null byte.
251    pub fn named_param(mut self, name: &str, type_id: TypeId) -> Self {
252        self.named_params.push(NamedParam::Simple {
253            name: CString::new(name).expect("parameter name must not contain null bytes"),
254            type_id,
255        });
256        self
257    }
258
259    /// Adds a named parameter with a complex [`LogicalType`].
260    ///
261    /// Use this for parameterized types that [`TypeId`] cannot express.
262    ///
263    /// # Panics
264    ///
265    /// Panics if `name` contains an interior null byte.
266    pub fn named_param_logical(mut self, name: &str, logical_type: LogicalType) -> Self {
267        self.named_params.push(NamedParam::Logical {
268            name: CString::new(name).expect("parameter name must not contain null bytes"),
269            logical_type,
270        });
271        self
272    }
273
274    /// Sets the bind callback.
275    ///
276    /// The bind callback is called once at query-parse time. It must:
277    /// - Declare all output columns via [`crate::table::BindInfo::add_result_column`].
278    /// - Optionally read parameters and store bind data via [`crate::table::FfiBindData::set`].
279    ///
280    /// # At least one column
281    ///
282    /// A bind that returns without declaring a column (and without calling
283    /// [`BindInfo::set_error`][crate::table::BindInfo::set_error]) makes
284    /// `DuckDB` fail the query with an `INTERNAL Error` — "Table function must
285    /// return at least one column", with a C++ stack trace
286    /// (`src/planner/binder/tableref/bind_table_function.cpp`). A raw callback
287    /// cannot be checked after it returns, so report the problem yourself with
288    /// `set_error`. The [typed builder][crate::table::TypedTableFunctionBuilder]
289    /// does this for you.
290    pub fn bind(mut self, f: BindFn) -> Self {
291        self.note_replacement("bind");
292        self.bind = Some(f);
293        self
294    }
295
296    /// Sets the global init callback.
297    ///
298    /// Called once per query. Use [`crate::table::FfiInitData::set`] to store global scan state.
299    pub fn init(mut self, f: InitFn) -> Self {
300        self.note_replacement("init");
301        self.init = Some(f);
302        self
303    }
304
305    /// Sets the per-thread local init callback (optional).
306    ///
307    /// When set, `DuckDB` calls this once per worker thread that runs the scan.
308    /// Use [`crate::table::FfiLocalInitData::set`] to store thread-local scan state.
309    ///
310    /// Setting a local init does **not** make the scan parallel. `DuckDB`
311    /// schedules at most `MaxThreads` scanners, and a C API table function's
312    /// `MaxThreads` is exactly what the global init passed to
313    /// [`InitInfo::set_max_threads`][crate::table::InitInfo::set_max_threads] —
314    /// 1 when it was never called (`src/main/capi/table_function-c.cpp`,
315    /// `CTableGlobalInitData::MaxThreads`). Parallelism needs `set_max_threads`
316    /// above 1; `local_init` only gives each of those threads its own state.
317    pub fn local_init(mut self, f: InitFn) -> Self {
318        self.note_replacement("local_init");
319        self.local_init = Some(f);
320        self
321    }
322
323    /// Sets the scan callback.
324    ///
325    /// Called repeatedly until all rows are produced. Set the output chunk's size
326    /// to `0` (via `duckdb_data_chunk_set_size(output, 0)`) to signal end of stream.
327    pub fn scan(mut self, f: ScanFn) -> Self {
328        self.note_replacement("scan");
329        self.scan = Some(f);
330        self
331    }
332
333    /// Enables or disables projection pushdown support (default: disabled).
334    ///
335    /// When enabled, `DuckDB` informs the `init` callback which columns were
336    /// requested. Use `duckdb_init_get_column_count` and `duckdb_init_get_column_index`
337    /// in your init callback to skip producing unrequested columns.
338    ///
339    /// A builder returned by
340    /// [`TypedTableFunctionBuilder::build`][crate::table::TypedTableFunctionBuilder::build]
341    /// is refused at registration with pushdown on: its scan closure cannot
342    /// see the projection.
343    pub const fn projection_pushdown(mut self, enable: bool) -> Self {
344        self.projection_pushdown = enable;
345        self
346    }
347
348    /// Sets function-level extra info shared across all callbacks.
349    ///
350    /// This data is available via `duckdb_function_get_extra_info` and
351    /// `duckdb_bind_get_extra_info` in all callbacks. The `destroy` callback
352    /// is called by `DuckDB` when the function is dropped.
353    ///
354    /// # Safety
355    ///
356    /// - `data` must remain valid until `DuckDB` calls `destroy`. The typical
357    ///   pattern is to box your data: `Box::into_raw(Box::new(my_data)).cast()`.
358    /// - The pointee must be `Send + Sync`. `DuckDB` hands the same pointer to
359    ///   bind, init and scan on whichever threads run them — several at once
360    ///   when queries run concurrently or the scan is parallel
361    ///   ([`InitInfo::set_max_threads`][crate::table::InitInfo::set_max_threads]
362    ///   above 1) — and `destroy` runs on whichever thread releases the
363    ///   function. Shared mutable state behind the pointer needs a `Mutex` or
364    ///   atomics.
365    /// - `destroy` must not panic; wrap its body in
366    ///   [`catch_ffi_panic`][crate::callback::catch_ffi_panic].
367    /// - The pointee must be the type the installed callbacks read it as. A
368    ///   builder from
369    ///   [`TypedTableFunctionBuilder::build`][crate::table::TypedTableFunctionBuilder::build]
370    ///   carries its own `extra_info`; replacing it is refused at registration.
371    pub unsafe fn extra_info(mut self, data: *mut c_void, destroy: ExtraDestroyFn) -> Self {
372        self.note_replacement("extra_info");
373        // SAFETY: forwarded from this method's own contract.
374        self.extra_info = Some(unsafe { crate::extra_info::ExtraInfo::new(data, Some(destroy)) });
375        self
376    }
377
378    /// Registers the table function on the given connection.
379    ///
380    /// # A name can be registered once
381    ///
382    /// `duckdb_register_table_function` adds the function to the system
383    /// catalog, which keys table functions by name, and the C API has no table
384    /// function *sets*, so there is no way to add an overload to a name that
385    /// exists: the existing entry keeps answering. What the call reports about
386    /// the duplicate differs by release — v1.5.x asks for `ALTER_ON_CONFLICT`,
387    /// which keeps the existing entry, drops the new function and returns
388    /// success; v1.4.x leaves the default `ERROR_ON_CONFLICT`, so the catalog
389    /// throws and the call fails with no reason to report
390    /// (`DuckSchemaEntry::AddEntryInternal`,
391    /// `src/catalog/catalog_entry/duck_schema_entry.cpp`). A second `register`
392    /// under the same name, a name another extension registered, or a built-in's
393    /// name (`range`, `read_csv`) therefore does not take effect either way:
394    /// the old function keeps answering. So `register` checks
395    /// `duckdb_functions()` first and refuses a name that is already a
396    /// table function or table macro in the system catalog (compared
397    /// case-insensitively, as `DuckDB` resolves names).
398    ///
399    /// Registering through the entry point's
400    /// [`Connection`](crate::connection::Connection) checks against a snapshot
401    /// of the catalog listed on the first registration and kept up to date with
402    /// that connection's own registrations, so an extension with many table
403    /// functions lists the catalog once per `LOAD` rather than once per
404    /// function. Being a one-time copy, the snapshot does not see a table
405    /// function registered on the raw connection after it was listed — by
406    /// another extension's `LOAD`, or by a direct call to this method — so a
407    /// later `register_table` under that name passes the check and is left to
408    /// `DuckDB`, which drops it with a success report on v1.5.x and fails the
409    /// call with no reason on v1.4.x. The scalar check has the same gap.
410    ///
411    /// Table functions registered through the C API live only in the
412    /// in-memory system catalog and are never written to a database file, so
413    /// a name found there is always a live conflict — not a leftover from an
414    /// earlier session that the next `LOAD` would trip over.
415    ///
416    /// The check does not look in user databases. A table macro of the same
417    /// name there — `CREATE MACRO f() AS TABLE …`, persisted in the database
418    /// file — does not stop the registration, but it shadows the function
419    /// for unqualified calls from that database: `SELECT * FROM f()` runs the
420    /// macro, and only `system.main.f()` reaches the extension's function.
421    /// Refusing here would make the extension fail to load into any database
422    /// that happens to hold such a macro, so the name is left to the user.
423    ///
424    /// # Errors
425    ///
426    /// Returns `ExtensionError` if:
427    /// - The name is already taken (see above), or the check cannot run.
428    /// - A parameter or named parameter was given as a bare composite
429    ///   [`TypeId`] (`DECIMAL`, `ENUM`, `LIST`, `STRUCT`, `MAP`, `ARRAY`,
430    ///   `UNION`); build it as a [`LogicalType`] and use the `*_logical`
431    ///   method. The error names the slot.
432    /// - The bind, init, or scan callback was not set.
433    /// - The builder came from
434    ///   [`TypedTableFunctionBuilder::build`][crate::table::TypedTableFunctionBuilder::build]
435    ///   and [`projection_pushdown`][Self::projection_pushdown] was switched on,
436    ///   or `bind`, `init`, `local_init`, `scan` or `extra_info` replaced,
437    ///   afterwards.
438    /// - `DuckDB` reports a registration failure.
439    ///
440    /// # Cost
441    ///
442    /// Each call lists the catalog once — one scan of `duckdb_functions()`,
443    /// tens of milliseconds on `DuckDB` 1.5.x, hardware-dependent.
444    /// Registering through the entry point's
445    /// [`Connection`](crate::connection::Connection) instead (its
446    /// [`Registrar`](crate::connection::Registrar) methods) lists the catalog
447    /// once per extension load, so an extension with many table functions
448    /// pays for one scan rather than one per function.
449    ///
450    /// # Safety
451    ///
452    /// `con` must be a valid, open `duckdb_connection`.
453    pub unsafe fn register(self, con: duckdb_connection) -> Result<(), ExtensionError> {
454        // SAFETY: forwarded from this method's own contract.
455        unsafe { self.register_with(con, None) }
456    }
457
458    /// [`register`][Self::register], checking the name against `snapshot`
459    /// (listed on first use) instead of listing the catalog for this call.
460    ///
461    /// # Safety
462    ///
463    /// As [`register`][Self::register].
464    pub(crate) unsafe fn register_with(
465        self,
466        con: duckdb_connection,
467        snapshot: Option<&core::cell::RefCell<Option<super::collision::ExistingTableFunctions>>>,
468    ) -> Result<(), ExtensionError> {
469        let name = self.name().to_owned();
470        // SAFETY: forwarded from this method's own contract.
471        unsafe { super::collision::refuse_taken_table_function_name(con, snapshot, &name) }?;
472        // SAFETY: forwarded from this method's own contract.
473        let handle = unsafe { self.build_handle() }?;
474
475        // Register. DuckDB copies the function; the handle is still ours.
476        // SAFETY: `con` is valid per the caller's contract, `handle` is live.
477        let result = unsafe { duckdb_register_table_function(con, handle.as_raw()) };
478
479        if result == DuckDBSuccess {
480            super::collision::record_registered(snapshot, &name);
481            Ok(())
482        } else {
483            // The name and callbacks were checked above, which leaves two causes
484            // in `duckdb_register_table_function` (`table_function-c.cpp`): a
485            // parameter type containing `INVALID`, or the catalog throwing. The
486            // catalog throws on a duplicate name on v1.4.x only, and the check
487            // above cannot rule a duplicate out: a snapshot does not see a table
488            // function registered on the raw connection after it was listed. So
489            // the aggregate name-clash hint does not apply, and the message must
490            // not claim the name is free.
491            Err(ExtensionError::new(format!(
492                "duckdb_register_table_function failed for '{name}': the C API reports no \
493                 reason. The name was not taken when the catalog was last listed, so the \
494                 likely cause is an invalid parameter or named-parameter type or, on DuckDB \
495                 v1.4.x, a table function of the same name registered on the raw connection \
496                 since then (a direct TableFunctionBuilder::register, another extension's \
497                 LOAD or an autoload)"
498            )))
499        }
500    }
501
502    /// The checks that need no `DuckDB` call: the bind, init and scan
503    /// callbacks are set, and a builder from
504    /// [`TypedTableFunctionBuilder::build`][crate::table::TypedTableFunctionBuilder::build]
505    /// has neither projection pushdown on nor a callback or `extra_info`
506    /// replaced. [`MockRegistrar`][crate::testing::MockRegistrar] runs them too, so a
507    /// builder it accepts is not refused at `LOAD`.
508    pub(crate) fn check_parts(&self) -> Result<(), ExtensionError> {
509        let missing = [
510            ("bind", self.bind.is_none()),
511            ("init", self.init.is_none()),
512            ("scan", self.scan.is_none()),
513        ]
514        .into_iter()
515        .find_map(|(name, absent)| absent.then_some(name));
516        if let Some(callback) = missing {
517            return Err(ExtensionError::new(format!("{callback} callback not set")));
518        }
519        if let Some(what) = self.replaced_after_typed {
520            return Err(ExtensionError::new(format!(
521                "typed table function '{}': {what} was replaced after build(). The typed \
522                 bind, init and scan callbacks share state through their extra_info and each \
523                 other's data, so replacing one would read one type as another. Build the \
524                 function with the raw TableFunctionBuilder instead.",
525                self.name()
526            )));
527        }
528        if self.typed && self.projection_pushdown {
529            return Err(ExtensionError::new(format!(
530                "typed table function '{}': projection_pushdown was enabled after build(). \
531                 The typed scan closure writes columns in declaration order and cannot see \
532                 the projection, so pushdown would put one column's values under another's \
533                 name. Remove projection_pushdown(true), or use the raw TableFunctionBuilder \
534                 with InitInfo::projected_column_index.",
535                self.name()
536            )));
537        }
538        Ok(())
539    }
540
541    /// Refuses a type [`register`][Self::register] refuses before its first
542    /// `DuckDB` call; `slot` checks each `TypeId` (see [`SlotCheck`]).
543    pub(crate) fn check_types(&self, slot: SlotCheck) -> Result<(), ExtensionError> {
544        for (i, id) in self.params.iter().enumerate() {
545            slot(*id, &format!("table function parameter {i}"))?;
546        }
547        for np in &self.named_params {
548            if let NamedParam::Simple { name, type_id } = np {
549                slot(
550                    *type_id,
551                    &format!("table function named parameter {}", name.to_string_lossy()),
552                )?;
553            }
554        }
555        Ok(())
556    }
557
558    /// Builds a configured, unregistered `duckdb_table_function`.
559    ///
560    /// [`register`][Self::register] is this plus
561    /// `duckdb_register_table_function`. The handle is exposed separately
562    /// because `COPY … FROM` needs a table function that is *attached to a copy
563    /// function* rather than registered on its own — see
564    /// `CopyFunctionBuilder::copy_from` (`duckdb-1-5`).
565    ///
566    /// # Errors
567    ///
568    /// Returns `ExtensionError` if a parameter type is invalid, if the bind,
569    /// init or scan callback was not set, or if projection pushdown was
570    /// switched on, or a callback or `extra_info` replaced, after a typed
571    /// builder's `build` (see
572    /// [`register`][Self::register]).
573    ///
574    /// # Safety
575    ///
576    /// The `DuckDB` C API dispatch table must be initialised (it always is
577    /// inside an extension).
578    pub unsafe fn build_handle(self) -> Result<TableFunctionHandle, ExtensionError> {
579        // See `ScalarFunctionBuilder::register` -- validate before allocating.
580        self.check_parts()?;
581        self.check_types(LogicalType::check_slot)?;
582        let bind = self
583            .bind
584            .ok_or_else(|| ExtensionError::new("bind callback not set"))?;
585        let init = self
586            .init
587            .ok_or_else(|| ExtensionError::new("init callback not set"))?;
588        let scan = self
589            .scan
590            .ok_or_else(|| ExtensionError::new("scan callback not set"))?;
591
592        // SAFETY: creates a new table function handle.
593        let func = unsafe { duckdb_create_table_function() };
594        let mut param_types_for_copy_from: Vec<Option<TypeId>> = Vec::new();
595
596        // SAFETY: func is a valid newly created handle.
597        unsafe {
598            duckdb_table_function_set_name(func, self.name.as_ptr());
599        }
600
601        // Add positional parameters: merge simple TypeId params and complex LogicalType
602        // params in the order they were added (tracked by position).
603        {
604            let mut simple_idx = 0;
605            let mut logical_idx = 0;
606            let total = self.params.len() + self.logical_params.len();
607            for pos in 0..total {
608                if logical_idx < self.logical_params.len()
609                    && self.logical_params[logical_idx].0 == pos
610                {
611                    let logical = &self.logical_params[logical_idx].1;
612                    // SAFETY: `logical` is a live logical type.
613                    param_types_for_copy_from.push(TypeId::try_from_duckdb_type(unsafe {
614                        libduckdb_sys::duckdb_get_type_id(logical.as_raw())
615                    }));
616                    // SAFETY: `func` is the handle `duckdb_create_table_function` returned
617                    // above (a fresh `new TableFunction`, table_function-c.cpp) and not yet
618                    // handed on or destroyed. `logical` is a `LogicalType` owned by
619                    // `self.logical_params`, so its handle is live for this borrow;
620                    // `duckdb_table_function_add_parameter` copies it
621                    // (`arguments.push_back(*logical_type)`), keeping no pointer.
622                    unsafe {
623                        duckdb_table_function_add_parameter(func, logical.as_raw());
624                    }
625                    logical_idx += 1;
626                } else if simple_idx < self.params.len() {
627                    let lt = LogicalType::new(self.params[simple_idx]);
628                    param_types_for_copy_from.push(Some(self.params[simple_idx]));
629                    // SAFETY: `func` is the handle `duckdb_create_table_function` returned
630                    // above (a fresh `new TableFunction`, table_function-c.cpp) and not yet
631                    // handed on or destroyed. `lt` was created just above and is dropped
632                    // only after this call; `duckdb_table_function_add_parameter` copies
633                    // the type.
634                    unsafe {
635                        duckdb_table_function_add_parameter(func, lt.as_raw());
636                    }
637                    simple_idx += 1;
638                }
639            }
640        }
641
642        // Add named parameters.
643        for np in &self.named_params {
644            match np {
645                NamedParam::Simple { name, type_id } => {
646                    let lt = LogicalType::new(*type_id);
647                    // SAFETY: `func` is the handle `duckdb_create_table_function` returned
648                    // above (a fresh `new TableFunction`, table_function-c.cpp) and not yet
649                    // handed on or destroyed. `name` is a `CString` (non-null,
650                    // NUL-terminated; DuckDB does not null-check it) and `lt` was created
651                    // just above; both outlive the call, and
652                    // `duckdb_table_function_add_named_parameter` copies both into
653                    // `named_parameters`.
654                    unsafe {
655                        duckdb_table_function_add_named_parameter(func, name.as_ptr(), lt.as_raw());
656                    }
657                }
658                // SAFETY: `func` is the handle `duckdb_create_table_function` returned
659                // above (a fresh `new TableFunction`, table_function-c.cpp) and not yet
660                // handed on or destroyed. `name` is a `CString` (non-null, NUL-terminated;
661                // DuckDB does not null-check it) and `logical_type` is a live `LogicalType`
662                // owned by `self.named_params`; `duckdb_table_function_add_named_parameter`
663                // copies both.
664                NamedParam::Logical { name, logical_type } => unsafe {
665                    duckdb_table_function_add_named_parameter(
666                        func,
667                        name.as_ptr(),
668                        logical_type.as_raw(),
669                    );
670                },
671            }
672        }
673
674        // Set callbacks.
675        // SAFETY: func is valid; callbacks are valid extern "C" fn pointers.
676        unsafe {
677            duckdb_table_function_set_bind(func, Some(bind));
678            duckdb_table_function_set_init(func, Some(init));
679            duckdb_table_function_set_function(func, Some(scan));
680        }
681
682        // Set optional local init.
683        if let Some(local_init) = self.local_init {
684            // SAFETY: func is valid; local_init is a valid extern "C" fn pointer.
685            unsafe {
686                duckdb_table_function_set_local_init(func, Some(local_init));
687            }
688        }
689
690        // Configure projection pushdown.
691        // SAFETY: func is valid.
692        unsafe {
693            duckdb_table_function_supports_projection_pushdown(func, self.projection_pushdown);
694        }
695
696        // Set extra info if provided.
697        if let Some(info) = self.extra_info {
698            // SAFETY: func is valid; data and destroy are provided by caller.
699            unsafe {
700                duckdb_table_function_set_extra_info(func, info.data(), info.destroy());
701                // DuckDB owns the allocation from here.
702                info.mark_transferred();
703            }
704        }
705
706        Ok(TableFunctionHandle {
707            func,
708            name: self.name,
709            param_types: param_types_for_copy_from,
710        })
711    }
712}
713
714/// A configured `duckdb_table_function` that has not been registered.
715///
716/// Produced by
717/// [`TableFunctionBuilder::build_handle`][TableFunctionBuilder::build_handle].
718/// `DuckDB` copies the function when it is registered or attached to a copy
719/// function, so this always owns its handle and destroys it on drop.
720pub struct TableFunctionHandle {
721    func: duckdb_table_function,
722    name: CString,
723    /// Top-level type ids of the positional parameters, in order.
724    ///
725    /// Kept because `COPY … FROM` requires exactly one `VARCHAR` parameter and
726    /// `DuckDB` reports a violation by doing nothing at all — see
727    /// `CopyFunctionBuilder::copy_from` (`duckdb-1-5`).
728    param_types: Vec<Option<TypeId>>,
729}
730
731impl TableFunctionHandle {
732    /// The raw handle. Do not destroy it — this value still owns it.
733    #[must_use]
734    pub const fn as_raw(&self) -> duckdb_table_function {
735        self.func
736    }
737
738    /// The function's name.
739    #[must_use]
740    pub fn name(&self) -> std::borrow::Cow<'_, str> {
741        self.name.to_string_lossy()
742    }
743
744    /// Top-level type ids of the positional parameters, in declaration order.
745    ///
746    /// `None` for a type this build of quack-rs has no [`TypeId`] for.
747    #[must_use]
748    #[cfg_attr(test, mutants::skip)] // covered by tests/ffi_roundtrip.rs, which `--lib` does not run
749    pub fn param_types(&self) -> &[Option<TypeId>] {
750        &self.param_types
751    }
752}
753
754impl Drop for TableFunctionHandle {
755    #[cfg_attr(test, mutants::skip)] // frees a DuckDB handle; nothing observable without a runtime
756    fn drop(&mut self) {
757        // SAFETY: `self.func` was created by `duckdb_create_table_function` and
758        // is destroyed exactly once. DuckDB copies the function on register and
759        // on `set_copy_from_function`, so destroying ours never affects it.
760        unsafe { duckdb_destroy_table_function(&raw mut self.func) };
761    }
762}
763
764impl core::fmt::Debug for TableFunctionHandle {
765    #[cfg_attr(test, mutants::skip)] // Debug rendering is not a behavioural contract
766    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
767        f.debug_struct("TableFunctionHandle")
768            .field("func", &self.func)
769            .field("name", &self.name)
770            .field("param_types", &self.param_types)
771            .finish()
772    }
773}
774
775impl core::fmt::Debug for TableFunctionBuilder {
776    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
777        use crate::debug_repr::Callback;
778        f.debug_struct("TableFunctionBuilder")
779            .field("name", &self.name)
780            .field("params", &self.params)
781            .field("logical_params", &self.logical_params.len())
782            .field("named_params", &self.named_params.len())
783            .field("bind", &Callback::of(&self.bind))
784            .field("init", &Callback::of(&self.init))
785            .field("local_init", &Callback::of(&self.local_init))
786            .field("scan", &Callback::of(&self.scan))
787            .field("projection_pushdown", &self.projection_pushdown)
788            .field("typed", &self.typed)
789            .field("replaced_after_typed", &self.replaced_after_typed)
790            .field("extra_info", &Callback::of(&self.extra_info))
791            .finish()
792    }
793}
794
795#[cfg(test)]
796mod tests {
797    use super::*;
798
799    #[test]
800    fn builder_stores_name() {
801        let b = TableFunctionBuilder::new("my_table_fn");
802        assert_eq!(b.name.to_str().unwrap(), "my_table_fn");
803    }
804
805    #[test]
806    fn builder_stores_params() {
807        let b = TableFunctionBuilder::new("f")
808            .param(TypeId::Varchar)
809            .param(TypeId::BigInt);
810        assert_eq!(b.params.len(), 2);
811        assert_eq!(b.params[0], TypeId::Varchar);
812        assert_eq!(b.params[1], TypeId::BigInt);
813    }
814
815    #[test]
816    fn builder_stores_named_params() {
817        let b = TableFunctionBuilder::new("f")
818            .named_param("path", TypeId::Varchar)
819            .named_param("limit", TypeId::BigInt);
820        assert_eq!(b.named_params.len(), 2);
821        match &b.named_params[0] {
822            NamedParam::Simple { name, .. } => assert_eq!(name.to_str().unwrap(), "path"),
823            NamedParam::Logical { .. } => panic!("expected Simple"),
824        }
825        match &b.named_params[1] {
826            NamedParam::Simple { name, .. } => assert_eq!(name.to_str().unwrap(), "limit"),
827            NamedParam::Logical { .. } => panic!("expected Simple"),
828        }
829    }
830
831    #[test]
832    fn builder_stores_callbacks() {
833        unsafe extern "C" fn my_bind(_: duckdb_bind_info) {}
834        unsafe extern "C" fn my_init(_: duckdb_init_info) {}
835        unsafe extern "C" fn my_scan(_: duckdb_function_info, _: duckdb_data_chunk) {}
836
837        let b = TableFunctionBuilder::new("f")
838            .bind(my_bind)
839            .init(my_init)
840            .scan(my_scan);
841        assert!(b.bind.is_some());
842        assert!(b.init.is_some());
843        assert!(b.scan.is_some());
844    }
845
846    #[test]
847    fn builder_projection_pushdown() {
848        let b = TableFunctionBuilder::new("f").projection_pushdown(true);
849        assert!(b.projection_pushdown);
850    }
851
852    #[test]
853    fn try_new_valid_name() {
854        assert!(TableFunctionBuilder::try_new("read_csv_ext").is_ok());
855    }
856
857    #[test]
858    fn try_new_invalid_name() {
859        assert!(TableFunctionBuilder::try_new("").is_err());
860        assert!(TableFunctionBuilder::try_new("my-func").is_err());
861        assert!(TableFunctionBuilder::try_new("1func").is_err());
862        // Mixed case is legal: DuckDB ships `formatReadableSize`.
863        assert!(TableFunctionBuilder::try_new("MyFunc").is_ok());
864    }
865
866    #[test]
867    fn try_new_null_byte_rejected() {
868        assert!(TableFunctionBuilder::try_new("func\0name").is_err());
869    }
870
871    // Needs a real `LogicalType`, which needs a live DuckDB. The previous
872    // version of this test faked one from `NonNull::dangling()` and then
873    // `mem::forget`-ed the whole builder so `Drop` would not hand that address
874    // to `duckdb_destroy_logical_type` — a deliberate leak, and an invalid
875    // pointer sitting in a live struct, both of which Miri's leak checker and
876    // its pointer checks report. A real type costs one feature gate and makes
877    // the test honest.
878    #[test]
879    #[cfg(feature = "_duckdb-testing")]
880    fn param_logical_position_tracking() {
881        let _db = crate::testing::InMemoryDb::open().expect("dispatch table");
882
883        // One simple param followed by one logical param.
884        let b = TableFunctionBuilder::new("f")
885            .param(TypeId::Integer)
886            .param_logical(LogicalType::list(TypeId::Integer));
887
888        assert_eq!(b.params.len(), 1);
889        assert_eq!(b.logical_params.len(), 1);
890        assert_eq!(b.logical_params[0].0, 1, "position should be 1, not 0");
891    }
892}