quack_rs/copy_function/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//! Copy function registration (`DuckDB` 1.5.0+).
7//!
8//! Extensions can register custom `COPY TO` handlers that define how data is
9//! exported to a specific file format. The lifecycle consists of four phases:
10//!
11//! 1. **Bind** — inspect the output columns and configure the export.
12//! 2. **Global init** — set up global state (open file, allocate buffers).
13//! 3. **Sink** — receive data chunks to write.
14//! 4. **Finalize** — flush and close.
15//!
16//! # Threads
17//!
18//! The data pointers this API passes around are untyped, so the compiler
19//! cannot check this for you. Treat each one as `&T` shared between threads:
20//!
21//! - **`extra_info`** ([`CopyFunctionBuilder::extra_info`]) lives as long as
22//! the database and is read from every connection's thread: `T: Send + Sync`.
23//! - **Bind data** ([`CopyBindInfo::set_bind_data`]) is read by every sink
24//! call. `COPY … TO` with `PER_THREAD_OUTPUT` or `PARTITION_BY` runs the sink
25//! on several threads **at once**, all sharing the one bind data:
26//! `T: Send + Sync`, and do not mutate it without a lock.
27//! - **Global state** ([`CopyGlobalInitInfo::set_global_state`]) is one per
28//! output file. With `PER_THREAD_OUTPUT` each thread gets its own; with
29//! `PARTITION_BY` a partition's state can be reached from more than one
30//! thread; with neither option the sink is not run in parallel. Mutating it
31//! through the raw pointer is only sound under a lock (`Mutex`) unless you
32//! know neither option is in play, so make it `T: Send` and guard mutation.
33//!
34//! All three may be dropped on a different thread from the one that created
35//! them.
36//!
37//! # Example
38//!
39//! ```rust,no_run
40//! use quack_rs::copy_function::CopyFunctionBuilder;
41//!
42//! let builder = CopyFunctionBuilder::try_new("my_format")?;
43//! // .bind(my_bind_fn)
44//! // .global_init(my_init_fn)
45//! // .sink(my_sink_fn)
46//! // .finalize(my_finalize_fn)
47//! # Ok::<(), quack_rs::error::ExtensionError>(())
48//! ```
49
50pub mod info;
51
52pub use info::{CopyBindInfo, CopyFinalizeInfo, CopyGlobalInitInfo, CopySinkInfo};
53
54use std::ffi::CString;
55use std::os::raw::c_void;
56
57use libduckdb_sys::{
58 duckdb_connection, duckdb_copy_function_bind_info, duckdb_copy_function_finalize_info,
59 duckdb_copy_function_global_init_info, duckdb_copy_function_set_bind,
60 duckdb_copy_function_set_copy_from_function, duckdb_copy_function_set_extra_info,
61 duckdb_copy_function_set_finalize, duckdb_copy_function_set_global_init,
62 duckdb_copy_function_set_name, duckdb_copy_function_set_sink, duckdb_copy_function_sink_info,
63 duckdb_create_copy_function, duckdb_data_chunk, duckdb_delete_callback_t,
64 duckdb_destroy_copy_function, duckdb_register_copy_function, DuckDBSuccess,
65};
66
67use crate::error::ExtensionError;
68use crate::table::TableFunctionHandle;
69use crate::types::TypeId;
70
71/// Callback type aliases for copy function phases.
72///
73/// Bind callback — called when the `COPY … TO` statement is bound.
74///
75/// It configures the export: once for a plain statement, and again on every
76/// `EXECUTE` of a prepared one.
77pub type CopyBindFn = unsafe extern "C" fn(info: duckdb_copy_function_bind_info);
78
79/// Global init callback — called once **per output file** to set up its state.
80///
81/// That is once for a plain `COPY … TO`, and once per file with
82/// `PER_THREAD_OUTPUT` or `PARTITION_BY`. With `USE_TMP_FILE` the path is the
83/// temporary name, which `DuckDB` renames afterwards.
84pub type CopyGlobalInitFn = unsafe extern "C" fn(info: duckdb_copy_function_global_init_info);
85
86/// Sink callback — called for each data chunk to write data. With
87/// `PER_THREAD_OUTPUT` or `PARTITION_BY` it runs on several threads at once;
88/// with neither, not in parallel (see the module docs).
89pub type CopySinkFn =
90 unsafe extern "C" fn(info: duckdb_copy_function_sink_info, chunk: duckdb_data_chunk);
91
92/// Finalize callback — called once per output file, after its last sink.
93///
94/// It flushes and closes. It is **not** called when a sink reports an error:
95/// release resources in the global state's destructor, which `DuckDB` runs
96/// either way, not only here.
97pub type CopyFinalizeFn = unsafe extern "C" fn(info: duckdb_copy_function_finalize_info);
98
99/// Builder for registering a custom `COPY TO` function.
100///
101/// All four lifecycle callbacks (bind, `global_init`, sink, finalize) should be
102/// set before calling [`register`][Self::register].
103#[must_use]
104pub struct CopyFunctionBuilder {
105 name: CString,
106 bind: Option<CopyBindFn>,
107 global_init: Option<CopyGlobalInitFn>,
108 sink: Option<CopySinkFn>,
109 finalize: Option<CopyFinalizeFn>,
110 copy_from: Option<TableFunctionHandle>,
111 extra_info: Option<crate::extra_info::ExtraInfo>,
112}
113
114impl CopyFunctionBuilder {
115 /// Creates a new copy function builder with the given format name.
116 ///
117 /// The name corresponds to the format identifier used in
118 /// `COPY table TO 'file' (FORMAT name)`.
119 ///
120 /// # Errors
121 ///
122 /// Returns `ExtensionError` if the name contains a null byte.
123 pub fn try_new(name: &str) -> Result<Self, ExtensionError> {
124 let c_name = CString::new(name)
125 .map_err(|_| ExtensionError::new("copy function name contains null byte"))?;
126 Ok(Self {
127 name: c_name,
128 bind: None,
129 global_init: None,
130 sink: None,
131 finalize: None,
132 copy_from: None,
133 extra_info: None,
134 })
135 }
136
137 /// Returns the name of this copy function.
138 #[must_use]
139 pub fn name(&self) -> &str {
140 self.name.to_str().unwrap_or("")
141 }
142
143 /// Sets the bind callback.
144 pub fn bind(mut self, f: CopyBindFn) -> Self {
145 self.bind = Some(f);
146 self
147 }
148
149 /// Sets the global init callback.
150 pub fn global_init(mut self, f: CopyGlobalInitFn) -> Self {
151 self.global_init = Some(f);
152 self
153 }
154
155 /// Sets the sink callback.
156 pub fn sink(mut self, f: CopySinkFn) -> Self {
157 self.sink = Some(f);
158 self
159 }
160
161 /// Sets the finalize callback.
162 pub fn finalize(mut self, f: CopyFinalizeFn) -> Self {
163 self.finalize = Some(f);
164 self
165 }
166
167 /// Attaches a table function that implements `COPY … FROM` for this format.
168 ///
169 /// Without it a copy function is export-only: `COPY t TO 'f' (FORMAT mine)`
170 /// works and `COPY t FROM 'f' (FORMAT mine)` reports that the format does
171 /// not support reading.
172 ///
173 /// # How `DuckDB` drives it
174 ///
175 /// The table function is not called the way a `FROM my_func(...)` one is.
176 /// `CCopyFromBind` synthesises the call:
177 ///
178 /// - the file path arrives as **positional parameter 0**, a `VARCHAR`;
179 /// - every option in `COPY … FROM 'f' (FORMAT mine, X 1, Y 'z')` arrives as
180 /// a **named parameter**. An option the table function did not declare is
181 /// a bind error, so declare each one with
182 /// [`named_param`][crate::table::TableFunctionBuilder::named_param];
183 /// - those options arrive **uncast**. `CCopyFromBind` stores each option's
184 /// value as written, not cast to the declared type: `SKIP 'abc'` reaches
185 /// a `BIGINT`-declared `skip` as the `VARCHAR` `'abc'`, and `SKIP 3` as
186 /// an `INTEGER`. An option written without a value (`… , FLAG)`) is not
187 /// passed at all, so it cannot be told from an absent one. Check the
188 /// value's [`type_id`][crate::value::Value::type_id] before trusting it:
189 /// an `as_i64_or(0)` on `'abc'` quietly yields the default;
190 /// - the **target table's schema is already fixed**, because `COPY … FROM`
191 /// loads into an existing table. `duckdb.h` is explicit that the bind
192 /// callback "should not define its own result columns using
193 /// `duckdb_bind_add_result_column`" and should read the expected schema
194 /// from [`BindInfo::result_column_count`][crate::table::BindInfo::result_column_count]
195 /// and its siblings instead. Nothing enforces that: `DuckDB` appends a
196 /// declared column to the `INSERT`'s own list of expected types, so its
197 /// chunks are wider than the table. A release `DuckDB` drops the extra
198 /// column; one built with assertions invalidates the database
199 /// (`docs/upstream-duckdb-reports.md`, item 37). A typed reader
200 /// ([`with_state`][crate::table::TableFunctionBuilder::with_state]) that
201 /// declares one fails its bind; a raw bind callback must not.
202 ///
203 /// `DuckDB` copies the table function here, so the handle may be dropped
204 /// immediately afterwards.
205 ///
206 /// # Name the reader after the format
207 ///
208 /// A bad `COPY … FROM` option is reported as
209 /// `'X' is not a supported option for copy function 'NAME'`. `X` is the
210 /// option as the query spelled it up to `DuckDB` 1.5.x, and lower-cased
211 /// from 2.0.0, whose parser lower-cases every `COPY` option name
212 /// (`transform_generic_copy_option.cpp`); the match against the declared
213 /// named parameters is case-insensitive on both. `NAME`
214 /// is the **table function's** name, not the copy function's:
215 /// `CCopyFromBind` reads `info.tf.name`, and
216 /// `duckdb_copy_function_set_copy_from_function` only substitutes the copy
217 /// function's name when the table function has none — which
218 /// [`TableFunctionBuilder`][crate::table::TableFunctionBuilder] never
219 /// produces. So a reader called `my_format_reader` attached to a format
220 /// called `csv2` tells the user about `csv2`'s options under the name
221 /// `my_format_reader`. Name the two alike.
222 ///
223 /// # Errors
224 ///
225 /// `duckdb.h` states the precondition plainly — "the table function must
226 /// take a single VARCHAR parameter (the file path)" — and nothing enforces
227 /// it. `duckdb_copy_function_set_copy_from_function` never looks at
228 /// `tf.arguments` beyond rejecting `INVALID` types, and `CCopyFromBind`
229 /// builds the argument list itself: it pushes exactly one `Value` holding
230 /// the path, whatever the function declared. So a reader that declares two
231 /// parameters, or one that is not `VARCHAR`, does not fail here — it fails
232 /// later, inside its own bind callback, reading an argument that is not what
233 /// it asked for. That is what this check turns into an error you get at
234 /// registration time.
235 ///
236 /// The other preconditions need no check here: `DuckDB` silently does
237 /// nothing if the table function is missing its bind, init or scan callback
238 /// — which
239 /// [`build_handle`][crate::table::TableFunctionBuilder::build_handle]
240 /// already refuses to produce — or if an argument or named-parameter type
241 /// contains `INVALID` anywhere, including nested inside a `LIST` or
242 /// `STRUCT`, which the builders reject at every reachable entry point (see
243 /// [`TypeId::is_composite`][crate::types::TypeId::is_composite]). Only a
244 /// type built from a raw handle could still smuggle one through.
245 ///
246 /// # Example
247 ///
248 /// ```rust,no_run
249 /// use quack_rs::copy_function::CopyFunctionBuilder;
250 /// use quack_rs::table::TableFunctionBuilder;
251 /// use quack_rs::types::TypeId;
252 ///
253 /// # fn demo(
254 /// # bind: quack_rs::table::BindFn,
255 /// # init: quack_rs::table::InitFn,
256 /// # scan: quack_rs::table::ScanFn,
257 /// # ) -> Result<(), quack_rs::error::ExtensionError> {
258 /// // SAFETY: the callbacks match their declared signatures.
259 /// let reader = unsafe {
260 /// TableFunctionBuilder::new("my_format_reader")
261 /// .param(TypeId::Varchar) // the file path
262 /// .named_param("skip_rows", TypeId::BigInt)
263 /// .bind(bind)
264 /// .init(init)
265 /// .scan(scan)
266 /// .build_handle()
267 /// }?;
268 ///
269 /// let _copy = CopyFunctionBuilder::try_new("my_format")?.copy_from(reader)?;
270 /// # Ok(())
271 /// # }
272 /// ```
273 // The parameter contract below is pinned by
274 // `copy_from_rejects_a_reader_whose_parameters_do_not_match_the_contract`
275 // in tests/ffi_roundtrip.rs, which the `--lib` mutants run does not execute.
276 #[cfg_attr(test, mutants::skip)]
277 pub fn copy_from(
278 mut self,
279 table_function: TableFunctionHandle,
280 ) -> Result<Self, ExtensionError> {
281 let params = table_function.param_types();
282 if params.len() != 1 || params[0] != Some(TypeId::Varchar) {
283 let described = if params.is_empty() {
284 String::from("none")
285 } else {
286 params
287 .iter()
288 .map(|p| p.map_or("<unknown>", TypeId::sql_name))
289 .collect::<Vec<_>>()
290 .join(", ")
291 };
292 return Err(ExtensionError::new(format!(
293 "copy_from: the table function '{}' declares {} positional parameter(s) ({described}), \
294 but DuckDB calls a COPY ... FROM reader with exactly one VARCHAR — the file path. \
295 Declare `.param(TypeId::Varchar)` and nothing else; COPY options arrive as named \
296 parameters. DuckDB does not check this itself, so it is checked here.",
297 table_function.name(),
298 params.len(),
299 )));
300 }
301 self.copy_from = Some(table_function);
302 Ok(self)
303 }
304
305 /// Attaches arbitrary data to this copy function.
306 ///
307 /// Available in every callback via `get_extra_info`. The allocation belongs
308 /// to the builder until [`register`][Self::register] hands it to `DuckDB`;
309 /// a builder that is dropped instead runs `destroy` itself rather than
310 /// leaking it.
311 ///
312 /// # Safety
313 ///
314 /// - `data` must be a pointer `destroy` can free exactly once.
315 /// - `destroy` must not panic: it is an `extern "C" fn`, so an unwind out of
316 /// it aborts the process at its own boundary. Use
317 /// [`catch_ffi_panic`][crate::callback::catch_ffi_panic] inside it.
318 pub unsafe fn extra_info(
319 mut self,
320 data: *mut c_void,
321 destroy: duckdb_delete_callback_t,
322 ) -> Self {
323 // SAFETY: forwarded from this method's own contract.
324 self.extra_info = Some(unsafe { crate::extra_info::ExtraInfo::new(data, destroy) });
325 self
326 }
327
328 /// Attaches `value` as this copy function's extra info: the safe, typed
329 /// form of [`extra_info`][Self::extra_info].
330 ///
331 /// quack-rs boxes `value` behind a type tag and generates its destructor,
332 /// which contains a panic in `T::drop` and runs once — when `DuckDB`
333 /// releases the function, or when this builder is dropped unregistered.
334 /// Read it in any callback with `extra_info_ref` (on
335 /// [`CopyBindInfo`][CopyBindInfo::extra_info_ref] and the other three
336 /// info types), which returns `None` for any other type instead of
337 /// reinterpreting memory. `T` is `Send + Sync` because every sink thread
338 /// reads the same value.
339 ///
340 /// For per-statement state, see `set_bind_data_typed` and
341 /// `set_global_state_typed` on the info types.
342 pub fn extra_info_typed<T: Send + Sync + 'static>(self, value: T) -> Self {
343 let (data, destroy) = crate::extra_info::into_tagged(value);
344 // SAFETY: `into_tagged` returns a fresh allocation, used by no one
345 // else, and the destructor that frees it exactly once without
346 // unwinding; `T: Send + Sync`.
347 unsafe { self.extra_info(data, Some(destroy)) }
348 }
349
350 /// The completeness checks that need no `DuckDB` call: all of bind, sink
351 /// and finalize for `COPY ... TO`, or a `copy_from` for `COPY ... FROM`,
352 /// or both. [`MockRegistrar`][crate::testing::MockRegistrar] runs them
353 /// too.
354 pub(crate) fn check_parts(&self) -> Result<(), ExtensionError> {
355 let writer_parts = [
356 self.bind.is_some(),
357 self.sink.is_some(),
358 self.finalize.is_some(),
359 ];
360 match (writer_parts, self.copy_from.is_some()) {
361 ([true, true, true], _) | ([false, false, false], true) => Ok(()),
362 (_, true) => Err(ExtensionError::new(
363 "copy function implements COPY ... TO only partially: bind, sink and finalize \
364 must all be set. Leave all three unset for a read-only format that supports \
365 COPY ... FROM alone.",
366 )),
367 (_, false) => Err(ExtensionError::new(
368 "copy function implements nothing: set bind, sink and finalize for \
369 COPY ... TO, or copy_from for COPY ... FROM, or both",
370 )),
371 }
372 }
373
374 /// Registers the copy function on the given connection.
375 ///
376 /// A copy function may implement either direction, or both:
377 ///
378 /// | Direction | Requires |
379 /// |---|---|
380 /// | `COPY … TO` | [`bind`][Self::bind] + [`sink`][Self::sink] + [`finalize`][Self::finalize] (and optionally [`global_init`][Self::global_init]) |
381 /// | `COPY … FROM` | [`copy_from`][Self::copy_from] |
382 ///
383 /// A read-only format sets only `copy_from` and leaves the writing
384 /// callbacks unset — `duckdb_register_copy_function` accepts that, because
385 /// it decides what a copy function supports from
386 /// `info.sink != nullptr` and `copy_from_bind != nullptr` independently.
387 ///
388 /// # A format name can be registered once
389 ///
390 /// `duckdb_register_copy_function` uses `ALTER_ON_CONFLICT`, and for a copy
391 /// function that means the new one is dropped while the call still
392 /// returns success (`DuckSchemaEntry::AddEntryInternal`). A second
393 /// registration of `my_format`, or a format called `csv`, would silently
394 /// leave the existing function in charge. `register` therefore refuses a
395 /// format name that already resolves.
396 ///
397 /// There is no catalog view of copy functions, so the check asks the
398 /// binder: it runs `COPY (SELECT <missing column>) TO '' (FORMAT '<name>')`.
399 /// `DuckDB` resolves the format before binding the query, so a *binder*
400 /// error (the column) means the format exists, and a *catalog* error
401 /// means it does not; nothing is ever written, and no copy callback runs.
402 /// A format name that belongs to an autoloadable extension (`parquet`,
403 /// `json`, ...) may be autoloaded by that lookup, exactly as the same
404 /// `COPY` typed by a user would; if that extension is then present, the
405 /// name counts as taken. Copy functions registered through the C API live
406 /// in the in-memory system catalog and never persist, so a name that
407 /// resolves is always a live conflict.
408 ///
409 /// The probe is a statement that fails, and `DuckDB` 2.0 aborts the
410 /// transaction a failed statement runs in. On the entry point's
411 /// registration connection, which runs the closure in a transaction
412 /// ([`Registration::Transactional`][crate::entry_point::Registration]), it
413 /// therefore runs on a short-lived connection of its own, and a format
414 /// registered earlier in the same transaction (which that connection
415 /// cannot see) is refused from the transaction's own record. On any other
416 /// connection it runs on `con`, so calling `register` on a connection of
417 /// yours inside a transaction you opened aborts that transaction on
418 /// `DuckDB` 2.0.
419 ///
420 /// # Errors
421 ///
422 /// Returns `ExtensionError` if neither direction is implemented, if
423 /// `COPY … TO` is only partly implemented, if the format name is already
424 /// taken (or the check cannot tell), or if registration fails.
425 ///
426 /// # Safety
427 ///
428 /// `con` must be a valid, open `duckdb_connection`.
429 pub unsafe fn register(self, con: duckdb_connection) -> Result<(), ExtensionError> {
430 // A copy function may implement `COPY ... TO`, `COPY ... FROM`, or both.
431 // `duckdb_register_copy_function` decides which by looking at the sink
432 // (`is_copy_to = info.sink != nullptr`) and the reader
433 // (`is_copy_from = copy_from_bind != nullptr`), and refuses — with no
434 // message — a function that implements neither. Hence the check here.
435 self.check_parts()?;
436 // `check_parts` left two shapes: all three writer callbacks, or none
437 // of them and a `copy_from`.
438 let writer = match (self.bind, self.sink, self.finalize) {
439 (Some(bind), Some(sink), Some(finalize)) => Some((bind, sink, finalize)),
440 _ => None,
441 };
442
443 let name = self.name.to_string_lossy().into_owned();
444 // SAFETY: `con` is valid per this function's contract.
445 unsafe { refuse_taken_format_name(con, &name) }?;
446
447 // SAFETY: duckdb_create_copy_function allocates a new handle.
448 let func = unsafe { duckdb_create_copy_function() };
449
450 // SAFETY: func is a valid newly created handle.
451 unsafe {
452 duckdb_copy_function_set_name(func, self.name.as_ptr());
453 }
454
455 if let Some((bind, sink, finalize)) = writer {
456 // SAFETY: func is a valid newly created handle.
457 unsafe {
458 duckdb_copy_function_set_bind(func, Some(bind));
459 duckdb_copy_function_set_sink(func, Some(sink));
460 duckdb_copy_function_set_finalize(func, Some(finalize));
461 }
462
463 if let Some(global_init) = self.global_init {
464 // SAFETY: func is valid.
465 unsafe {
466 duckdb_copy_function_set_global_init(func, Some(global_init));
467 }
468 }
469 }
470
471 // Attach the COPY ... FROM reader, if any. DuckDB copies the table
472 // function by value here, so `reader` can be dropped afterwards.
473 if let Some(ref reader) = self.copy_from {
474 // SAFETY: both handles are live and the preconditions were checked
475 // in `copy_from`.
476 unsafe {
477 duckdb_copy_function_set_copy_from_function(func, reader.as_raw());
478 }
479 }
480
481 if let Some(ref info) = self.extra_info {
482 // SAFETY: func is valid; data and destroy came from the caller.
483 unsafe {
484 duckdb_copy_function_set_extra_info(func, info.data(), info.destroy());
485 // DuckDB owns the allocation from here.
486 info.mark_transferred();
487 }
488 }
489
490 // SAFETY: con is valid, func is fully configured.
491 let result = unsafe { duckdb_register_copy_function(con, func) };
492
493 // SAFETY: func must be destroyed after registration.
494 let mut func_mut = func;
495 // SAFETY: `func_mut` holds the `new CopyFunction` from
496 // `duckdb_create_copy_function` above, destroyed nowhere else.
497 // `duckdb_register_copy_function` copies it into the catalog
498 // (`CreateCopyFunctionInfo(copy_function_ref)`, copy_function-c.cpp; the
499 // extra info is shared through `function_info`'s `shared_ptr`) and keeps
500 // no pointer to `func`, so this single `delete` is safe whether
501 // registration succeeded or not.
502 unsafe {
503 duckdb_destroy_copy_function(&raw mut func_mut);
504 }
505
506 if result == DuckDBSuccess {
507 crate::entry_point::record_copy_format(con, &name);
508 Ok(())
509 } else {
510 Err(ExtensionError::new(format!(
511 "duckdb_register_copy_function failed for '{name}'"
512 )))
513 }
514 }
515}
516
517/// Refuses `name` if `COPY ... (FORMAT '<name>')` already resolves to a copy
518/// function. See "A format name can be registered once" on
519/// [`CopyFunctionBuilder::register`].
520///
521/// # Safety
522///
523/// `con` must be a valid, open `duckdb_connection`.
524unsafe fn refuse_taken_format_name(
525 con: duckdb_connection,
526 name: &str,
527) -> Result<(), ExtensionError> {
528 use crate::error_data::DuckDbErrorType;
529
530 let taken = || {
531 ExtensionError::new(format!(
532 "copy function '{name}' already exists (a built-in format, another extension's, or \
533 an earlier registration). DuckDB would drop this registration and still report \
534 success, leaving the existing format in charge. Choose a different name."
535 ))
536 };
537 // Inside the entry point's registration transaction the probe below must
538 // not run on `con`: it fails on purpose, and DuckDB 2.0 aborts the
539 // transaction a failed statement runs in. It runs on a connection of its
540 // own instead, which cannot see the formats this transaction registered,
541 // so those are looked up in the transaction's own record.
542 let probe_connection = match crate::entry_point::copy_format_scope(con, name) {
543 Some((_, true)) => return Err(taken()),
544 Some((db, false)) => Some(
545 // SAFETY: the entry point keeps `db` valid while its transaction
546 // is open, which is while `copy_format_scope` returns it.
547 unsafe { crate::query::OwnedConnection::open(db) }.map_err(|e| {
548 ExtensionError::new(format!(
549 "copy function '{name}': cannot check whether the format name is taken \
550 (opening a connection for the check failed: {e})"
551 ))
552 })?,
553 ),
554 None => None,
555 };
556 let probe_con = probe_connection
557 .as_ref()
558 .map_or(con, crate::query::OwnedConnection::as_raw);
559
560 // The select references a column that cannot exist (there is no FROM
561 // clause), so binding always fails — after the format lookup, which
562 // happens first in `Binder::Bind(CopyStatement &)`.
563 let sql = format!(
564 "COPY (SELECT \"quack_rs_format_probe_no_such_column\") TO '' (FORMAT '{}')",
565 name.replace('\'', "''")
566 );
567 let c_sql = std::ffi::CString::new(sql)
568 .map_err(|_| ExtensionError::new("copy function name contains null byte"))?;
569 // SAFETY: duckdb_result is a C struct for which all-zero is a valid value.
570 let mut result: libduckdb_sys::duckdb_result = unsafe { std::mem::zeroed() };
571 // SAFETY: `probe_con` is `con`, valid per this function's contract, or a
572 // connection opened above and still alive; `c_sql` outlives the call.
573 let state = unsafe { libduckdb_sys::duckdb_query(probe_con, c_sql.as_ptr(), &raw mut result) };
574 let error_type = if state == DuckDBSuccess {
575 None
576 } else {
577 // SAFETY: `result` was populated by `duckdb_query`.
578 Some(DuckDbErrorType::from_raw(unsafe {
579 libduckdb_sys::duckdb_result_error_type(&raw mut result)
580 }))
581 };
582 // SAFETY: `result` was populated by `duckdb_query` and is destroyed once.
583 unsafe { libduckdb_sys::duckdb_destroy_result(&raw mut result) };
584 match error_type {
585 Some(DuckDbErrorType::Binder) => Err(taken()),
586 // Not found — including an autoloadable extension's format whose
587 // autoload failed.
588 Some(
589 DuckDbErrorType::Catalog
590 | DuckDbErrorType::Autoload
591 | DuckDbErrorType::MissingExtension,
592 ) => Ok(()),
593 other => Err(ExtensionError::new(format!(
594 "copy function '{name}': cannot check whether the format name is taken (the probe \
595 returned {other:?}, not a binder or catalog error)"
596 ))),
597 }
598}
599
600impl core::fmt::Debug for CopyFunctionBuilder {
601 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
602 use crate::debug_repr::Callback;
603 f.debug_struct("CopyFunctionBuilder")
604 .field("name", &self.name)
605 .field("bind", &Callback::of(&self.bind))
606 .field("global_init", &Callback::of(&self.global_init))
607 .field("sink", &Callback::of(&self.sink))
608 .field("finalize", &Callback::of(&self.finalize))
609 .field("copy_from", &self.copy_from)
610 .field("extra_info", &self.extra_info)
611 .finish()
612 }
613}
614
615#[cfg(test)]
616mod tests {
617 use super::*;
618
619 #[test]
620 fn try_new_valid_name() {
621 let builder = CopyFunctionBuilder::try_new("parquet").unwrap();
622 assert_eq!(builder.name(), "parquet");
623 }
624
625 #[test]
626 fn try_new_null_byte_rejected() {
627 let result = CopyFunctionBuilder::try_new("bad\0name");
628 assert!(result.is_err());
629 let err = result.err().unwrap();
630 assert!(
631 err.to_string().contains("null byte"),
632 "error should mention null byte"
633 );
634 }
635
636 #[test]
637 fn each_setter_stores_only_its_own_callback() {
638 unsafe extern "C" fn bind(_: duckdb_copy_function_bind_info) {}
639 unsafe extern "C" fn init(_: duckdb_copy_function_global_init_info) {}
640 unsafe extern "C" fn sink(_: duckdb_copy_function_sink_info, _: duckdb_data_chunk) {}
641 unsafe extern "C" fn finalize(_: duckdb_copy_function_finalize_info) {}
642
643 let b = CopyFunctionBuilder::try_new("fmt").unwrap().bind(bind);
644 assert!(b.bind.is_some() && b.global_init.is_none() && b.sink.is_none());
645 let b = CopyFunctionBuilder::try_new("fmt")
646 .unwrap()
647 .global_init(init);
648 assert!(b.global_init.is_some() && b.bind.is_none() && b.finalize.is_none());
649 let b = CopyFunctionBuilder::try_new("fmt").unwrap().sink(sink);
650 assert!(b.sink.is_some() && b.bind.is_none() && b.finalize.is_none());
651 let b = CopyFunctionBuilder::try_new("fmt")
652 .unwrap()
653 .finalize(finalize);
654 assert!(b.finalize.is_some() && b.bind.is_none() && b.sink.is_none());
655 }
656
657 /// The "implements nothing" check runs before `con` is used, so a null
658 /// connection is never dereferenced.
659 #[test]
660 fn register_without_callbacks_is_refused_before_duckdb_is_called() {
661 // SAFETY: `register` returns before using `con`.
662 let err = unsafe {
663 CopyFunctionBuilder::try_new("fmt")
664 .unwrap()
665 .register(std::ptr::null_mut())
666 }
667 .expect_err("a copy function with no callbacks must be refused");
668 assert!(err.as_str().contains("implements nothing"), "{err}");
669 }
670
671 #[test]
672 fn builder_stores_all_callbacks() {
673 unsafe extern "C" fn my_bind(_: duckdb_copy_function_bind_info) {}
674 unsafe extern "C" fn my_init(_: duckdb_copy_function_global_init_info) {}
675 unsafe extern "C" fn my_sink(_: duckdb_copy_function_sink_info, _: duckdb_data_chunk) {}
676 unsafe extern "C" fn my_finalize(_: duckdb_copy_function_finalize_info) {}
677
678 let b = CopyFunctionBuilder::try_new("f")
679 .unwrap()
680 .bind(my_bind)
681 .global_init(my_init)
682 .sink(my_sink)
683 .finalize(my_finalize);
684 assert!(b.bind.is_some());
685 assert!(b.global_init.is_some());
686 assert!(b.sink.is_some());
687 assert!(b.finalize.is_some());
688 }
689
690 #[test]
691 fn try_new_stores_name() {
692 let b = CopyFunctionBuilder::try_new("my_copy").unwrap();
693 assert_eq!(b.name(), "my_copy");
694 }
695
696 #[test]
697 fn callbacks_default_to_none() {
698 let b = CopyFunctionBuilder::try_new("fmt").unwrap();
699 assert!(b.bind.is_none());
700 assert!(b.global_init.is_none());
701 assert!(b.sink.is_none());
702 assert!(b.finalize.is_none());
703 }
704}