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}