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}