Skip to main content

quack_rs/replacement_scan/
mod.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` replacement scans.
7//!
8//! Replacement scans enable the `SELECT * FROM 'my_file.xyz'` pattern.
9//! When `DuckDB` encounters an unrecognized table reference (including a string
10//! literal like `'data.parquet'`), it calls all registered replacement scan
11//! callbacks in registration order, giving each a chance to redirect the scan
12//! to a known table function.
13//!
14//! # How replacement scans work
15//!
16//! ```text
17//! SELECT * FROM 'data.myformat'
18//!   ↓
19//! `DuckDB` does not know 'data.myformat' as a table
20//!   ↓
21//! Calls each registered replacement scan callback with:
22//!   - info: duckdb_replacement_scan_info   (use to redirect or error)
23//!   - table_name: *const c_char            (the unrecognized identifier, e.g. "data.myformat")
24//!   - data: *mut c_void                    (your extra_data, if any)
25//!   ↓
26//! Callback either:
27//!   - Redirects: duckdb_replacement_scan_set_function_name + add_parameter
28//!   - Ignores: returns without calling any scan API (`DuckDB` tries the next callback)
29//!   - Errors: duckdb_replacement_scan_set_error
30//! ```
31//!
32//! # The callback sees only the table name
33//!
34//! `table_name` is the last part of the reference, with any catalog or schema
35//! stripped: `SELECT * FROM nosuchschema."s.xyz"` and
36//! `SELECT * FROM memory.main."s.xyz"` both reach the callback as `s.xyz`,
37//! and a redirect answers either. A callback that must honour a schema cannot
38//! tell it from here.
39//!
40//! # Example: Route all `.xyz` files to a custom table function
41//!
42//! ```rust,no_run
43//! use quack_rs::replacement_scan::{ReplacementScanBuilder, ReplacementScanInfo};
44//! use libduckdb_sys::duckdb_replacement_scan_info;
45//! use std::os::raw::c_char;
46//!
47//! unsafe extern "C" fn my_scan(
48//!     info: duckdb_replacement_scan_info,
49//!     table_name: *const c_char,
50//!     _data: *mut std::os::raw::c_void,
51//! ) {
52//!     let name = unsafe { std::ffi::CStr::from_ptr(table_name).to_string_lossy() };
53//!     if !name.ends_with(".xyz") {
54//!         return; // not ours — let `DuckDB` try other callbacks
55//!     }
56//!     // Redirect to our table function and pass the filename as a parameter.
57//!     unsafe {
58//!         ReplacementScanInfo::new(info)
59//!             .set_function("read_xyz")
60//!             .add_varchar_parameter(name.as_ref());
61//!     }
62//! }
63//!
64//! // fn register(db: libduckdb_sys::duckdb_database) {
65//! //     unsafe { ReplacementScanBuilder::register(db, my_scan, std::ptr::null_mut(), None); }
66//! // }
67//! ```
68
69use std::ffi::CString;
70use std::os::raw::{c_char, c_void};
71
72use crate::table::cstr::str_to_cstring;
73
74use libduckdb_sys::{
75    duckdb_add_replacement_scan, duckdb_create_varchar_length, duckdb_database,
76    duckdb_delete_callback_t, duckdb_destroy_value, duckdb_replacement_scan_add_parameter,
77    duckdb_replacement_scan_info, duckdb_replacement_scan_set_error,
78    duckdb_replacement_scan_set_function_name, duckdb_value,
79};
80
81/// The replacement scan callback signature.
82///
83/// - `info` — use to redirect the scan or report an error.
84/// - `table_name` — the unrecognized table identifier from the query.
85/// - `data` — your `extra_data` pointer, if any.
86pub type ReplacementScanFn = unsafe extern "C" fn(
87    info: duckdb_replacement_scan_info,
88    table_name: *const c_char,
89    data: *mut c_void,
90);
91
92/// Ergonomic wrapper around `duckdb_replacement_scan_info`.
93///
94/// Provides safe methods for the common replacement scan operations.
95pub struct ReplacementScanInfo {
96    info: duckdb_replacement_scan_info,
97}
98
99impl ReplacementScanInfo {
100    /// Wraps a raw `duckdb_replacement_scan_info`.
101    ///
102    /// # Safety
103    ///
104    /// `info` must be a valid `duckdb_replacement_scan_info` provided by `DuckDB`.
105    #[inline]
106    #[must_use]
107    pub const unsafe fn new(info: duckdb_replacement_scan_info) -> Self {
108        Self { info }
109    }
110
111    /// Redirects this scan to the named table function.
112    ///
113    /// Call this first to name the table function that will handle the scan,
114    /// then use `add_varchar_parameter` or `add_parameter_raw` to pass arguments.
115    ///
116    /// If `function_name` contains an interior null byte it is truncated at that point.
117    pub fn set_function(&self, function_name: &str) -> &Self {
118        let c_name = str_to_cstring(function_name);
119        // SAFETY: self.info is valid per constructor's contract.
120        unsafe {
121            duckdb_replacement_scan_set_function_name(self.info, c_name.as_ptr());
122        }
123        self
124    }
125
126    /// Adds a VARCHAR string parameter to the redirected function call.
127    ///
128    /// This is the most common use case: passing the original file path/name
129    /// to the underlying table function.
130    pub fn add_varchar_parameter(&self, value: &str) -> &Self {
131        // SAFETY: creates a DuckDB VARCHAR value.
132        let duckdb_val = unsafe {
133            duckdb_create_varchar_length(
134                value.as_ptr().cast::<std::os::raw::c_char>(),
135                value.len() as u64,
136            )
137        };
138        // SAFETY: self.info is valid; duckdb_val is a valid newly created value.
139        unsafe {
140            duckdb_replacement_scan_add_parameter(self.info, duckdb_val);
141        }
142        let mut val = duckdb_val;
143        // SAFETY: `val` is the value created above; DuckDB copied it when the
144        // parameter was added, so destroying it here is correct and it is not
145        // used afterwards.
146        unsafe {
147            duckdb_destroy_value(&raw mut val);
148        }
149        self
150    }
151
152    /// Adds a raw `duckdb_value` parameter to the redirected function call.
153    ///
154    /// Use this when you need to pass non-VARCHAR parameters (INTEGER, BIGINT,
155    /// BOOLEAN, etc.) that aren't covered by [`add_varchar_parameter`][Self::add_varchar_parameter].
156    ///
157    /// `DuckDB` copies the value; the caller still owns `value` and must destroy
158    /// it after this call.
159    ///
160    /// # Safety
161    ///
162    /// `value` must be a valid `duckdb_value` created via a `duckdb_create_*` function.
163    pub unsafe fn add_parameter_raw(&self, value: duckdb_value) -> &Self {
164        // SAFETY: self.info is valid; value is a valid duckdb_value per caller's contract.
165        unsafe {
166            duckdb_replacement_scan_add_parameter(self.info, value);
167        }
168        self
169    }
170
171    /// Adds a BIGINT (i64) parameter to the redirected function call.
172    ///
173    /// Convenience method that creates a `DuckDB` BIGINT value, adds it as a
174    /// parameter, and destroys the temporary value.
175    pub fn add_i64_parameter(&self, value: i64) -> &Self {
176        // SAFETY: duckdb_create_int64 always returns a valid value.
177        let duckdb_val = unsafe { libduckdb_sys::duckdb_create_int64(value) };
178        // SAFETY: `self.info` is the handle DuckDB passed to the callback, and
179        // `duckdb_val` was just created.
180        unsafe {
181            duckdb_replacement_scan_add_parameter(self.info, duckdb_val);
182        }
183        let mut val = duckdb_val;
184        // SAFETY: `val` is that same value; DuckDB copied it when the parameter
185        // was added, so destroying it here is correct and it is not used
186        // afterwards.
187        unsafe {
188            duckdb_destroy_value(&raw mut val);
189        }
190        self
191    }
192
193    /// Adds a BOOLEAN parameter to the redirected function call.
194    ///
195    /// Convenience method that creates a `DuckDB` BOOLEAN value, adds it as a
196    /// parameter, and destroys the temporary value.
197    pub fn add_bool_parameter(&self, value: bool) -> &Self {
198        // SAFETY: duckdb_create_bool always returns a valid value.
199        let duckdb_val = unsafe { libduckdb_sys::duckdb_create_bool(value) };
200        // SAFETY: `self.info` is the handle DuckDB passed to the callback, and
201        // `duckdb_val` was just created.
202        unsafe {
203            duckdb_replacement_scan_add_parameter(self.info, duckdb_val);
204        }
205        let mut val = duckdb_val;
206        // SAFETY: `val` is that same value; DuckDB copied it when the parameter
207        // was added, so destroying it here is correct and it is not used
208        // afterwards.
209        unsafe {
210            duckdb_destroy_value(&raw mut val);
211        }
212        self
213    }
214
215    /// Reports an error, causing `DuckDB` to abort this replacement scan attempt.
216    ///
217    /// An interior null byte in `message` is replaced by `?`.
218    ///
219    /// `DuckDB` only raises the error when the stored message is non-empty, so
220    /// an empty message would be silently ignored and the query would fall through
221    /// to "table does not exist". It is replaced with
222    /// [`EMPTY_ERROR_PLACEHOLDER`][Self::EMPTY_ERROR_PLACEHOLDER] instead.
223    #[cfg_attr(test, mutants::skip)] // FFI call requires DuckDB runtime; `error_cstring` is unit-tested
224    pub fn set_error(&self, message: &str) {
225        let c_msg = error_cstring(message);
226        // SAFETY: self.info is valid.
227        unsafe {
228            duckdb_replacement_scan_set_error(self.info, c_msg.as_ptr());
229        }
230    }
231
232    /// Returns the raw `duckdb_replacement_scan_info` handle.
233    #[must_use]
234    #[inline]
235    pub const fn as_raw(&self) -> duckdb_replacement_scan_info {
236        self.info
237    }
238
239    /// The message [`set_error`][Self::set_error] reports in place of an empty
240    /// one.
241    pub const EMPTY_ERROR_PLACEHOLDER: &'static str =
242        "replacement scan reported an error without a message";
243}
244
245/// Converts an error message for `duckdb_replacement_scan_set_error`, never
246/// producing an empty string (which `DuckDB` treats as "no error").
247fn error_cstring(message: &str) -> CString {
248    crate::table::cstr::error_cstring(message, ReplacementScanInfo::EMPTY_ERROR_PLACEHOLDER)
249}
250
251/// Builder / registration helper for `DuckDB` replacement scans.
252///
253/// Unlike other builders in quack-rs, registration is a single static call
254/// because the replacement scan API takes a raw function pointer and optional
255/// extra data directly — there is no handle to configure step-by-step.
256#[derive(Debug)]
257pub struct ReplacementScanBuilder;
258
259impl ReplacementScanBuilder {
260    /// Registers a replacement scan callback on the given database.
261    ///
262    /// # Arguments
263    ///
264    /// - `db` — a valid `duckdb_database`. Obtain this via
265    ///   `access.get_database(info)` in the extension entry point.
266    /// - `callback` — your replacement scan function.
267    /// - `extra_data` — user data passed as the third argument to `callback`.
268    ///   Pass `std::ptr::null_mut()` if you need no extra data.
269    /// - `delete_callback` — called by `DuckDB` with `extra_data` when the
270    ///   replacement scan is removed (e.g., database closed). Pass `None` if
271    ///   `extra_data` needs no special cleanup. Unlike `DuckDB`'s other
272    ///   destructor slots, it is called even when `extra_data` is null.
273    ///
274    /// # Safety
275    ///
276    /// - `db` must be a valid, open `duckdb_database`.
277    /// - `extra_data` must remain valid until `delete_callback` is called
278    ///   (or until the database is closed if `delete_callback` is `None`).
279    /// - `delete_callback`, if set, must accept a null argument when
280    ///   `extra_data` is null.
281    /// - `extra_data` must be safe to share between threads: `DuckDB` passes it
282    ///   to `callback` from any connection's thread, concurrently, and calls
283    ///   `delete_callback` from whichever thread closes the database. Treat it
284    ///   as `&T` where `T: Send + Sync`.
285    pub unsafe fn register(
286        db: duckdb_database,
287        callback: ReplacementScanFn,
288        extra_data: *mut c_void,
289        delete_callback: duckdb_delete_callback_t,
290    ) {
291        // SAFETY: db is valid per caller; callback is a valid extern "C" fn.
292        unsafe {
293            duckdb_add_replacement_scan(db, Some(callback), extra_data, delete_callback);
294        }
295    }
296
297    /// Registers a replacement scan with owned extra data.
298    ///
299    /// Boxes `data` and registers a drop destructor automatically.
300    /// This is the safe, ergonomic way to attach Rust data to a replacement scan.
301    ///
302    /// `T` must be `Send + Sync`: the data lives in the database-wide
303    /// configuration, is handed (as `&T` behind the `data` pointer) to the
304    /// callback on whichever connection's thread is binding a query — possibly
305    /// several at once — and is dropped on whichever thread closes the
306    /// database.
307    ///
308    /// # Safety
309    ///
310    /// `db` must be a valid, open `duckdb_database`.
311    pub unsafe fn register_with_data<T: Send + Sync + 'static>(
312        db: duckdb_database,
313        callback: ReplacementScanFn,
314        data: T,
315    ) {
316        // Define the destructor before any statement so clippy is satisfied.
317        //
318        // PITFALL L3: `T::drop` is arbitrary user code and `DuckDB` calls this
319        // through an `extern "C"` pointer with no error channel, where an
320        // unwind is a process abort. Contain it.
321        /// Drops the boxed `T` `DuckDB` hands back when it removes the scan.
322        ///
323        /// # Safety
324        ///
325        /// `ptr` must be null or the `Box<T>` pointer registered with it, not
326        /// yet freed (`DuckDB` calls this once, with the registered pointer).
327        unsafe extern "C" fn drop_box<T>(ptr: *mut c_void) {
328            if !ptr.is_null() {
329                // SAFETY: `ptr` came from `Box::into_raw` just below.
330                drop(crate::callback::catch_ffi_panic(|| unsafe {
331                    drop(Box::from_raw(ptr.cast::<T>()));
332                }));
333            }
334        }
335
336        let raw = Box::into_raw(Box::new(data)).cast::<c_void>();
337
338        // SAFETY: db is valid; raw is a heap allocation; drop_box is a valid destructor.
339        unsafe {
340            duckdb_add_replacement_scan(db, Some(callback), raw, Some(drop_box::<T>));
341        }
342    }
343}
344
345crate::debug_repr::impl_handle_debug!(ReplacementScanInfo.info);
346
347#[cfg(test)]
348mod tests {
349    use super::*;
350
351    #[test]
352    fn replacement_scan_info_round_trips_its_handle() {
353        let raw = std::ptr::NonNull::<u8>::dangling().as_ptr().cast();
354        // SAFETY: the handle is only stored and read back, never passed to DuckDB.
355        let info = unsafe { ReplacementScanInfo::new(raw) };
356        assert_eq!(info.as_raw(), raw);
357    }
358
359    /// `DuckDB` ignores an empty replacement-scan error, so an empty message —
360    /// must be replaced; a NUL inside a message is kept as `?`.
361    #[test]
362    fn error_cstring_is_never_empty() {
363        let placeholder = ReplacementScanInfo::EMPTY_ERROR_PLACEHOLDER;
364        assert_eq!(super::error_cstring("").to_str().unwrap(), placeholder);
365        assert_eq!(
366            super::error_cstring("\0hidden").to_str().unwrap(),
367            "?hidden"
368        );
369        assert_eq!(super::error_cstring("boom").to_str().unwrap(), "boom");
370    }
371}