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}