Skip to main content

quack_rs/appender/
construct.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//! Creating an [`Appender`] and choosing the columns it appends to.
7
8use std::ffi::CStr;
9
10use libduckdb_sys::{
11    duckdb_appender, duckdb_appender_add_column, duckdb_appender_clear_columns,
12    duckdb_appender_column_count, duckdb_appender_column_type, duckdb_appender_create,
13    duckdb_appender_create_ext, duckdb_connection, idx_t, DuckDBSuccess,
14};
15
16use super::{AppendError, Appender};
17use crate::types::LogicalType;
18
19/// Converts an optional `&CStr` into a (possibly null) C string pointer.
20#[inline]
21fn opt_ptr(s: Option<&CStr>) -> *const std::os::raw::c_char {
22    s.map_or(std::ptr::null(), CStr::as_ptr)
23}
24
25impl Appender {
26    // ── Construction ────────────────────────────────────────────────────
27
28    /// Creates an appender for `table` in the given `schema` (or the default
29    /// schema when `schema` is `None`).
30    ///
31    /// # Errors
32    ///
33    /// Returns an [`AppendError`] if the appender cannot be created — most
34    /// often because the table does not exist.
35    ///
36    /// # Safety
37    ///
38    /// `con` must be a valid, open `duckdb_connection`. It need not outlive
39    /// the appender for memory safety (`DuckDB`'s appender holds only a weak
40    /// reference to the client context and checks it before writing), but rows still buffered when it closes are lost:
41    /// appends keep succeeding, and the next flush or `close` fails with
42    /// "Attempting to flush data to a closed connection". Close the appender
43    /// first.
44    pub unsafe fn new(
45        con: duckdb_connection,
46        schema: Option<&CStr>,
47        table: &CStr,
48    ) -> Result<Self, AppendError> {
49        let mut raw: duckdb_appender = std::ptr::null_mut();
50        // SAFETY: con is valid per caller's contract; the string pointers are
51        // valid for the call; raw is a valid out-pointer.
52        let state =
53            unsafe { duckdb_appender_create(con, opt_ptr(schema), table.as_ptr(), &raw mut raw) };
54        // DuckDB allocates the wrapper and writes it to `raw` *before* it can
55        // fail, precisely so the error is readable, so this must be constructed
56        // either way — and it must be dropped on the error path, which is what
57        // returning it inside `Err` via `last_error` arranges.
58        let appender = Self::wrap(raw);
59        if state == DuckDBSuccess {
60            Ok(appender)
61        } else {
62            Err(appender.last_error())
63        }
64    }
65
66    /// Creates an appender for `table`, fully qualified by optional `catalog`
67    /// and `schema`.
68    ///
69    /// # Errors
70    ///
71    /// Returns an [`AppendError`] if the appender cannot be created.
72    ///
73    /// # Safety
74    ///
75    /// `con` must be a valid, open `duckdb_connection`. It need not outlive
76    /// the appender for memory safety (`DuckDB`'s appender holds only a weak
77    /// reference to the client context and checks it before writing), but rows still buffered when it closes are lost:
78    /// appends keep succeeding, and the next flush or `close` fails with
79    /// "Attempting to flush data to a closed connection". Close the appender
80    /// first.
81    pub unsafe fn with_catalog(
82        con: duckdb_connection,
83        catalog: Option<&CStr>,
84        schema: Option<&CStr>,
85        table: &CStr,
86    ) -> Result<Self, AppendError> {
87        let mut raw: duckdb_appender = std::ptr::null_mut();
88        // SAFETY: con is valid per caller's contract; the string pointers are
89        // valid for the call; raw is a valid out-pointer.
90        let state = unsafe {
91            duckdb_appender_create_ext(
92                con,
93                opt_ptr(catalog),
94                opt_ptr(schema),
95                table.as_ptr(),
96                &raw mut raw,
97            )
98        };
99        let appender = Self::wrap(raw);
100        if state == DuckDBSuccess {
101            Ok(appender)
102        } else {
103            Err(appender.last_error())
104        }
105    }
106
107    /// Creates an appender whose rows feed `sql` instead of a table
108    /// (`DuckDB` 1.5.0+): each flush runs `sql` with the buffered rows
109    /// available as a table — an `INSERT … SELECT`, `UPDATE … FROM`,
110    /// `DELETE … USING`, `INSERT OR REPLACE` or `MERGE INTO` over the batch.
111    ///
112    /// `types` are the appended columns' types. The rows are visible to
113    /// `sql` as the table `table` (default `appended_data`) with the column
114    /// names `columns` (default `col1`, `col2`, …, 1-based). Rows are
115    /// appended exactly as for a table appender. `DuckDB` does not look at
116    /// `sql` until a flush runs it (`QueryAppender`'s constructor only stores
117    /// it), so a query that does not parse or bind, like a constraint it
118    /// violates, fails at [`flush`][Self::flush] or [`close`][Self::close],
119    /// and the rows buffered for it are lost as for any failed flush.
120    ///
121    /// Requires `duckdb-1-5`: `duckdb_appender_create_query` sits in the
122    /// unstable region of the C API struct.
123    ///
124    /// # Errors
125    ///
126    /// Before `DuckDB` is called: `types` is empty, `columns` does not have
127    /// one name per type (`duckdb_appender_create_query` would read past
128    /// the end of a short list), or `sql`, `table` or a column name contains
129    /// an interior NUL byte. Otherwise `DuckDB`'s error, if it refuses to
130    /// create the appender.
131    ///
132    /// # Safety
133    ///
134    /// `con` must be a valid, open `duckdb_connection`; see
135    /// [`new`][Self::new] for how long it must outlive the appender.
136    ///
137    /// # Example
138    ///
139    /// ```rust,no_run
140    /// use quack_rs::appender::Appender;
141    /// use quack_rs::types::{LogicalType, TypeId};
142    ///
143    /// # unsafe fn demo(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::appender::AppendError> {
144    /// let types = [LogicalType::new(TypeId::Integer), LogicalType::new(TypeId::Varchar)];
145    /// // SAFETY: `con` is open.
146    /// let upsert = unsafe {
147    ///     Appender::for_query(
148    ///         con,
149    ///         "INSERT OR REPLACE INTO users SELECT id, name FROM batch",
150    ///         &types,
151    ///         Some("batch"),
152    ///         Some(&["id", "name"]),
153    ///     )
154    /// }?;
155    /// upsert.row(|row| {
156    ///     row.append_i32(7)?;
157    ///     row.append_str("ada")
158    /// })?;
159    /// upsert.close()?;
160    /// # Ok(())
161    /// # }
162    /// ```
163    #[cfg(feature = "duckdb-1-5")]
164    pub unsafe fn for_query(
165        con: duckdb_connection,
166        sql: &str,
167        types: &[LogicalType],
168        table: Option<&str>,
169        columns: Option<&[&str]>,
170    ) -> Result<Self, AppendError> {
171        use std::ffi::CString;
172        let nul = |what: &str| {
173            super::append_error(&format!(
174                "Appender::for_query: {what} contains an interior NUL byte"
175            ))
176        };
177        if types.is_empty() {
178            return Err(super::append_error(
179                "Appender::for_query: at least one column type is needed",
180            ));
181        }
182        if let Some(names) = columns.filter(|names| names.len() != types.len()) {
183            return Err(super::append_error(&format!(
184                "Appender::for_query: {} column name(s) for {} column type(s); \
185                 duckdb_appender_create_query reads one name per type",
186                names.len(),
187                types.len()
188            )));
189        }
190        let c_sql = CString::new(sql).map_err(|_| nul("the SQL"))?;
191        let c_table = table
192            .map(CString::new)
193            .transpose()
194            .map_err(|_| nul("the table name"))?;
195        let c_columns = columns
196            .map(|names| {
197                names
198                    .iter()
199                    .map(|n| CString::new(*n))
200                    .collect::<Result<Vec<_>, _>>()
201            })
202            .transpose()
203            .map_err(|_| nul("a column name"))?;
204        let mut name_ptrs: Option<Vec<*const std::os::raw::c_char>> = c_columns
205            .as_ref()
206            .map(|names| names.iter().map(|n| n.as_ptr()).collect());
207        let mut raw_types: Vec<libduckdb_sys::duckdb_logical_type> =
208            types.iter().map(LogicalType::as_raw).collect();
209        let mut raw: duckdb_appender = std::ptr::null_mut();
210        // SAFETY: `con` is valid per the caller's contract. Every pointer
211        // outlives the call; `raw_types` and `name_ptrs` hold exactly
212        // `types.len()` live entries each (checked above), which is the
213        // count passed. DuckDB copies all of them, and catches every
214        // exception from creating the appender.
215        let state = unsafe {
216            libduckdb_sys::duckdb_appender_create_query(
217                con,
218                c_sql.as_ptr(),
219                types.len() as idx_t,
220                raw_types.as_mut_ptr(),
221                c_table.as_deref().map_or(std::ptr::null(), CStr::as_ptr),
222                name_ptrs
223                    .as_mut()
224                    .map_or(std::ptr::null_mut(), Vec::as_mut_ptr),
225                &raw mut raw,
226            )
227        };
228        // As in `new`: on a failure after allocation DuckDB still hands out
229        // the wrapper, so that its error is readable and it is destroyed.
230        let appender = Self::wrap(raw);
231        if state == DuckDBSuccess {
232            Ok(appender)
233        } else if appender.handle.is_null() {
234            Err(super::append_error(
235                "duckdb_appender_create_query refused its arguments",
236            ))
237        } else {
238            Err(appender.last_error())
239        }
240    }
241
242    /// Takes ownership of a raw appender, which is then closed and destroyed
243    /// (`duckdb_appender_destroy`) on drop: the way back into this crate's
244    /// RAII for an appender a raw call created.
245    ///
246    /// # Safety
247    ///
248    /// `handle` must come from a `duckdb_appender_create*` call, must not be
249    /// destroyed by anyone else, and must be at a row boundary (no values
250    /// appended since its last `duckdb_appender_end_row`): the row and
251    /// poisoning checks described in the [module docs][crate::appender]
252    /// start counting from here. See [`new`][Self::new] for how long its
253    /// connection must stay open.
254    #[must_use]
255    pub const unsafe fn from_raw(handle: duckdb_appender) -> Self {
256        Self::wrap(handle)
257    }
258
259    /// Gives up ownership and returns the raw appender without flushing or
260    /// closing it. The caller must destroy it (`duckdb_appender_destroy`,
261    /// which flushes) or hand it back to [`from_raw`][Self::from_raw]; this
262    /// wrapper's record of a half-written row or a poisoned state is lost.
263    #[must_use]
264    pub const fn into_raw(self) -> duckdb_appender {
265        let raw = self.handle;
266        std::mem::forget(self);
267        raw
268    }
269
270    // ── Schema ──────────────────────────────────────────────────────────
271
272    /// Number of columns the appender currently expects per row.
273    ///
274    /// This is the *active* column list, so it reflects any
275    /// [`add_column`][Self::add_column] calls rather than always matching the
276    /// table's width.
277    #[must_use]
278    pub fn column_count(&self) -> u64 {
279        // SAFETY: self.handle is valid; DuckDB returns 0 for a null or
280        // uninitialised appender.
281        unsafe { duckdb_appender_column_count(self.handle) }
282    }
283
284    /// Type of active column `index`, or `None` if the index is out of range.
285    #[must_use]
286    pub fn column_type(&self, index: u64) -> Option<LogicalType> {
287        // SAFETY: self.handle is valid; DuckDB bounds-checks `index` and
288        // returns null when it is out of range.
289        let raw = unsafe { duckdb_appender_column_type(self.handle, index as idx_t) };
290        if raw.is_null() {
291            None
292        } else {
293            // SAFETY: raw is a freshly allocated logical type that we now own.
294            Some(unsafe { LogicalType::from_raw(raw) })
295        }
296    }
297
298    /// Restricts appends to a named subset of the table's columns.
299    ///
300    /// Columns left out are filled with their `DEFAULT` (or NULL). Calling this
301    /// **flushes everything appended so far**.
302    ///
303    /// # Errors
304    ///
305    /// Returns an [`AppendError`] if the column does not exist, or if the
306    /// implicit flush fails.
307    pub fn add_column(&self, name: &CStr) -> Result<(), AppendError> {
308        self.usable()?;
309        // SAFETY: self.handle is valid and `name` is a NUL-terminated string
310        // that outlives the call.
311        let state = unsafe { duckdb_appender_add_column(self.handle, name.as_ptr()) };
312        self.flushed(state)
313    }
314
315    /// Resets the active column list so every table column is expected again.
316    ///
317    /// Also flushes everything appended so far.
318    ///
319    /// # Errors
320    ///
321    /// Returns an [`AppendError`] if the implicit flush fails.
322    pub fn clear_columns(&self) -> Result<(), AppendError> {
323        self.usable()?;
324        // SAFETY: self.handle is valid.
325        let state = unsafe { duckdb_appender_clear_columns(self.handle) };
326        self.flushed(state)
327    }
328}