Skip to main content

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}