Skip to main content

quack_rs/arrow/
options.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//! `ArrowOptions` — the Arrow production settings of a connection or a result.
7
8use std::marker::PhantomData;
9use std::ptr;
10
11use libduckdb_sys::{
12    duckdb_arrow_options, duckdb_connection, duckdb_connection_get_arrow_options,
13    duckdb_destroy_arrow_options, duckdb_result_get_arrow_options,
14};
15
16use super::ArrowOptions;
17use crate::error::ExtensionError;
18use crate::query::{OwnedConnection, QueryResult};
19
20impl<'conn> ArrowOptions<'conn> {
21    /// Reads the Arrow options of a connection, borrowing it for as long as
22    /// the options live.
23    ///
24    /// # Errors
25    ///
26    /// `duckdb_connection_get_arrow_options` has no error channel: it writes
27    /// null when the allocation throws. That is reported here as an
28    /// [`ExtensionError`].
29    #[cfg_attr(test, mutants::skip)] // FFI wrapper — needs a live DuckDB connection
30    pub fn from_connection(connection: &'conn OwnedConnection) -> Result<Self, ExtensionError> {
31        // SAFETY: `connection` is open, and the borrow keeps it open for all of
32        // 'conn, which is as long as the returned options can be used.
33        unsafe { Self::from_raw_connection(connection.as_raw()) }
34    }
35
36    /// Reads the Arrow options of a raw connection — for extension code that
37    /// holds a `duckdb_connection` rather than an [`OwnedConnection`].
38    ///
39    /// # Errors
40    ///
41    /// Returns an [`ExtensionError`] when the connection is null or `DuckDB`
42    /// cannot allocate the options (it writes null in both cases).
43    ///
44    /// # Safety
45    ///
46    /// `connection` must be a live `duckdb_connection`, and it must not be
47    /// disconnected for all of `'conn` (the caller picks `'conn`; choose one no
48    /// longer than the connection stays open). See the type-level
49    /// [lifetime](Self#lifetime) docs.
50    #[cfg_attr(test, mutants::skip)] // FFI wrapper — needs a live DuckDB connection
51    pub unsafe fn from_raw_connection(
52        connection: duckdb_connection,
53    ) -> Result<Self, ExtensionError> {
54        let mut raw: duckdb_arrow_options = ptr::null_mut();
55        // SAFETY: `connection` is live per this function's contract and `raw` is
56        // a valid out-parameter.
57        unsafe { duckdb_connection_get_arrow_options(connection, &raw mut raw) };
58        if raw.is_null() {
59            return Err(ExtensionError::new(
60                "duckdb_connection_get_arrow_options returned null: the connection was null or \
61                 DuckDB could not allocate its client properties",
62            ));
63        }
64        Ok(Self {
65            raw,
66            _conn: PhantomData,
67        })
68    }
69
70    /// Reads the Arrow options a result was produced with.
71    ///
72    /// Prefer this over [`from_connection`][Self::from_connection] when
73    /// exporting that result's chunks: a result carries the client properties
74    /// captured when it ran, which is what its chunks were built against.
75    ///
76    /// # Errors
77    ///
78    /// Returns an [`ExtensionError`] when `DuckDB` returns null, which it does
79    /// for a result with no internal data.
80    ///
81    /// # Safety
82    ///
83    /// The connection that ran the query producing `result` must stay open for
84    /// all of `'conn`. The captured client properties point at that
85    /// connection's `ClientContext`, and a [`QueryResult`] can outlive its
86    /// connection, so nothing checks this. See the type-level
87    /// [lifetime](Self#lifetime) docs.
88    #[cfg_attr(test, mutants::skip)] // FFI wrapper — needs a live DuckDB result
89    pub unsafe fn from_result(result: &QueryResult) -> Result<Self, ExtensionError> {
90        // `duckdb_result_get_arrow_options` takes a `duckdb_result *` but only
91        // reads `internal_data`, so a copy of the POD struct is enough — the
92        // same pattern every accessor in `crate::query` uses.
93        let mut copy = *result.as_raw();
94        // SAFETY: `copy` aliases a live result owned by `result`; DuckDB only
95        // reads through the pointer.
96        let raw = unsafe { duckdb_result_get_arrow_options(&raw mut copy) };
97        if raw.is_null() {
98            return Err(ExtensionError::new(
99                "duckdb_result_get_arrow_options returned null: the result carries no data",
100            ));
101        }
102        Ok(Self {
103            raw,
104            _conn: PhantomData,
105        })
106    }
107
108    /// Takes ownership of a raw `duckdb_arrow_options`.
109    ///
110    /// # Safety
111    ///
112    /// `raw` must be a non-null handle the caller is responsible for
113    /// destroying, and nobody else may destroy it. The connection it was read
114    /// from must stay open for all of `'conn`.
115    #[inline]
116    #[must_use]
117    pub const unsafe fn from_raw(raw: duckdb_arrow_options) -> Self {
118        Self {
119            raw,
120            _conn: PhantomData,
121        }
122    }
123
124    /// The raw handle, still owned by this value.
125    #[inline]
126    #[must_use]
127    pub const fn as_raw(&self) -> duckdb_arrow_options {
128        self.raw
129    }
130
131    /// Relinquishes ownership, returning the raw handle.
132    ///
133    /// The caller becomes responsible for `duckdb_destroy_arrow_options`, and
134    /// for not using the handle after the connection closes.
135    #[inline]
136    #[must_use]
137    pub const fn into_raw(self) -> duckdb_arrow_options {
138        let raw = self.raw;
139        std::mem::forget(self);
140        raw
141    }
142}
143
144impl Drop for ArrowOptions<'_> {
145    #[cfg_attr(test, mutants::skip)] // frees a DuckDB handle; nothing observable without a runtime
146    fn drop(&mut self) {
147        if self.raw.is_null() {
148            return;
149        }
150        // SAFETY: `self.raw` was owned by this value and is destroyed once;
151        // DuckDB nulls it. Destruction does not touch the client context.
152        unsafe { duckdb_destroy_arrow_options(&raw mut self.raw) };
153    }
154}
155
156impl core::fmt::Debug for ArrowOptions<'_> {
157    #[cfg_attr(test, mutants::skip)] // Debug rendering is not a behavioural contract
158    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
159        f.debug_struct("ArrowOptions")
160            .field("raw", &self.raw)
161            .finish()
162    }
163}