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}