Skip to main content

quack_rs/appender/
rows.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//! Row-at-a-time appends: `row`, `end_row` and the non-numeric `append_*` methods.
7
8use libduckdb_sys::{
9    duckdb_append_blob, duckdb_append_date, duckdb_append_default, duckdb_append_interval,
10    duckdb_append_null, duckdb_append_time, duckdb_append_timestamp, duckdb_append_value,
11    duckdb_append_varchar_length, duckdb_appender_end_row, duckdb_date, duckdb_interval,
12    duckdb_time, duckdb_timestamp, idx_t,
13};
14
15use super::{append_error, AppendError, Appender, Lifecycle};
16use crate::interval::DuckInterval;
17use crate::value::Value;
18
19/// `duckdb_append_varchar_length` narrows its length argument to `uint32_t`
20/// with `UnsafeNumericCast`, which is a plain `static_cast` in the release
21/// builds `DuckDB` ships. A longer string would be silently truncated to its
22/// low 32 bits, so it is refused here instead.
23const MAX_VARCHAR_LEN: usize = u32::MAX as usize;
24
25/// Whether `len` bytes fit `duckdb_append_varchar_length`'s `uint32_t`.
26const fn fits_append_length(len: usize) -> bool {
27    len <= MAX_VARCHAR_LEN
28}
29
30impl Appender {
31    // ── Row-at-a-time appends ───────────────────────────────────────────
32
33    /// Appends one row, calling [`end_row`][Self::end_row] afterwards.
34    ///
35    /// The closure appends one value per active column. `end_row` runs only if
36    /// the closure succeeded.
37    ///
38    /// If the closure (or `end_row`, for a missing column) fails after the
39    /// row's first value went in, `DuckDB` is left holding a half-written row
40    /// it can neither finish nor drop, and every row buffered since the last
41    /// flush is lost. The appender is then *poisoned*: see the
42    /// [module docs][crate::appender]. A closure that panics after the row's
43    /// first value poisons it too. A failure of the automatic flush inside
44    /// `end_row` does not poison it (see [`end_row`][Self::end_row]).
45    ///
46    /// # Errors
47    ///
48    /// Returns whatever the closure returned, or the [`AppendError`] from
49    /// `end_row` — most often "call to `EndRow` before all columns have been
50    /// appended to". Also an error, before the closure runs, when the appender
51    /// is closed or poisoned, or when a row appended by hand is still open.
52    pub fn row<F>(&self, append: F) -> Result<(), AppendError>
53    where
54        F: FnOnce(&Self) -> Result<(), AppendError>,
55    {
56        self.usable()?;
57        if self.column.get() != 0 {
58            return Err(append_error(&format!(
59                "row: a row appended by hand is still open ({} value(s) without end_row); \
60                 finish it before starting another",
61                self.column.get()
62            )));
63        }
64        let unwinding = PoisonOnUnwind(self);
65        let result = append(self).and_then(|()| self.end_row());
66        core::mem::forget(unwinding);
67        if result.is_err() && self.column.get() != 0 {
68            self.lifecycle.set(Lifecycle::Poisoned);
69        }
70        result
71    }
72
73    /// Finishes the current row.
74    ///
75    /// # Errors
76    ///
77    /// Returns an [`AppendError`] if fewer values were appended than the
78    /// appender has active columns (append the rest and call it again), or if
79    /// the appender is closed or poisoned. Also when the automatic flush
80    /// `DuckDB` runs every 204,800 rows fails — a constraint violation in any
81    /// buffered row. The row has then ended and the appender stays usable.
82    /// Up to `DuckDB` 1.5.x the rows that failed stay buffered: the next flush
83    /// reports the same error until `clear` (`duckdb-1-5`) discards them. From
84    /// 2.0.0 a failed flush discards every buffered row itself, so the next
85    /// flush writes only the rows appended after it.
86    pub fn end_row(&self) -> Result<(), AppendError> {
87        self.usable()?;
88        // SAFETY: self.handle is valid.
89        let state = unsafe { duckdb_appender_end_row(self.handle) };
90        let result = self.check(state);
91        // `BaseAppender::EndRow` throws before ending the row only when a
92        // column is missing; with every column in, it resets its counter and
93        // counts the row first, and only the automatic flush that follows
94        // (`Flush`, reached through `FlushChunk` once 204,800 rows are
95        // buffered: `DEFAULT_FLUSH_COUNT`, `appender.hpp`) can fail. The C API
96        // sets no memory threshold, so no other flush runs from here in
97        // 1.4.4 through 2.0.0. Such a failure leaves
98        // no half-written row, so it must not look like one.
99        if result.is_ok() || self.column.get() == self.column_count() {
100            self.column.set(0);
101            self.buffered.set(self.buffered.get().saturating_add(1));
102        }
103        result
104    }
105
106    /// Appends SQL `NULL` to the current row, whatever the column's type.
107    ///
108    /// # Errors
109    ///
110    /// Returns an [`AppendError`] if the append fails.
111    pub fn append_null(&self) -> Result<(), AppendError> {
112        // SAFETY: self.handle is valid.
113        self.append_one(|| unsafe { duckdb_append_null(self.handle) })
114    }
115
116    /// Appends the column's `DEFAULT` value to the current row.
117    ///
118    /// A column declared without a `DEFAULT` gets `NULL`, as it would from an
119    /// `INSERT` that leaves it out.
120    ///
121    /// # Errors
122    ///
123    /// Returns an [`AppendError`] if the column's `DEFAULT` is not a constant
124    /// the appender can evaluate up front — `nextval('seq')`, `random()`,
125    /// `now()`: `DuckDB`'s appender evaluates defaults once, when it is
126    /// created, and keeps none for an expression that is not foldable
127    /// (`Appender::InitializeChunk`, `appender.cpp`), so appending it fails
128    /// with "`AppendDefault` is not supported". Also if the append itself fails.
129    pub fn append_default(&self) -> Result<(), AppendError> {
130        // SAFETY: self.handle is valid.
131        self.append_one(|| unsafe { duckdb_append_default(self.handle) })
132    }
133
134    /// Appends a `VARCHAR`.
135    ///
136    /// Uses `duckdb_append_varchar_length`, so **interior NUL bytes are
137    /// preserved** — unlike the NUL-terminated `duckdb_append_varchar`, which
138    /// would stop at the first one.
139    ///
140    /// # Errors
141    ///
142    /// Returns an [`AppendError`] if the append fails, or if `value` is longer
143    /// than `u32::MAX` bytes — a length `DuckDB` narrows to 32 bits without
144    /// checking in its release builds.
145    pub fn append_str(&self, value: &str) -> Result<(), AppendError> {
146        self.append_bytes_as(value.as_bytes(), true)
147    }
148
149    /// Appends a `BLOB`.
150    ///
151    /// # Errors
152    ///
153    /// Returns an [`AppendError`] if the append fails, or if `value` is longer
154    /// than `u32::MAX` bytes. `duckdb_append_blob` stores the length through a
155    /// 32-bit narrowing with no check in release builds: a 4 GiB + 3 byte blob
156    /// was stored as 3 bytes, with no error.
157    pub fn append_bytes(&self, value: &[u8]) -> Result<(), AppendError> {
158        self.append_bytes_as(value, false)
159    }
160
161    /// Refuses a 64-bit temporal payload `DuckDB` cannot render, before it is
162    /// appended.
163    fn check_temporal(
164        &self,
165        type_id: crate::types::TypeId,
166        v: i64,
167        what: &str,
168    ) -> Result<(), AppendError> {
169        self.usable()?;
170        if crate::value::temporal_checks::temporal_in_range(type_id, v) {
171            Ok(())
172        } else {
173            Err(append_error(&format!(
174                "{what}({v}) is outside DuckDB's range for {}; DuckDB would store it \
175                 unchecked and then crash or fail reading it",
176                type_id.sql_name()
177            )))
178        }
179    }
180
181    fn append_bytes_as(&self, value: &[u8], varchar: bool) -> Result<(), AppendError> {
182        self.usable()?;
183        if varchar {
184            if !fits_append_length(value.len()) {
185                return Err(append_error(&format!(
186                    "VARCHAR of {} bytes exceeds DuckDB's {MAX_VARCHAR_LEN}-byte appender limit",
187                    value.len()
188                )));
189            }
190            // SAFETY: self.handle is valid; the pointer/length pair describes
191            // `value`, which outlives the call.
192            let state = unsafe {
193                duckdb_append_varchar_length(
194                    self.handle,
195                    value.as_ptr().cast::<std::os::raw::c_char>(),
196                    value.len() as idx_t,
197                )
198            };
199            return self.record_append(state);
200        }
201        if !fits_append_length(value.len()) {
202            return Err(append_error(&format!(
203                "BLOB of {} bytes exceeds DuckDB's {MAX_VARCHAR_LEN}-byte appender limit",
204                value.len()
205            )));
206        }
207        // SAFETY: as above; DuckDB copies the bytes into a BLOB value.
208        let state = unsafe {
209            duckdb_append_blob(
210                self.handle,
211                value.as_ptr().cast::<std::os::raw::c_void>(),
212                value.len() as idx_t,
213            )
214        };
215        self.record_append(state)
216    }
217
218    /// Appends a `DATE` as days since 1970-01-01.
219    ///
220    /// Every `i32` is accepted, as by [`Value::date`][crate::value::Value::date];
221    /// days outside the range `DuckDB`'s SQL produces render as text it cannot
222    /// parse again.
223    ///
224    /// # Errors
225    ///
226    /// Returns an [`AppendError`] if the append fails.
227    pub fn append_date(&self, days: i32) -> Result<(), AppendError> {
228        // SAFETY: self.handle is valid.
229        self.append_one(|| unsafe { duckdb_append_date(self.handle, duckdb_date { days }) })
230    }
231
232    /// Appends a `TIME` as microseconds since midnight.
233    ///
234    /// # Errors
235    ///
236    /// Returns an [`AppendError`] if the append fails, or — before `DuckDB` is
237    /// called — if `micros` is outside `0..=86_400_000_000` (`00:00:00` to
238    /// `24:00:00`). `duckdb_append_time` checks nothing; appending `i64::MIN`
239    /// crashed the process when the row was read, and `i64::MAX` invalidated
240    /// the database.
241    pub fn append_time(&self, micros: i64) -> Result<(), AppendError> {
242        self.check_temporal(crate::types::TypeId::Time, micros, "append_time")?;
243        // SAFETY: self.handle is valid.
244        self.append_one(|| unsafe { duckdb_append_time(self.handle, duckdb_time { micros }) })
245    }
246
247    /// Appends a `TIMESTAMP` as microseconds since the epoch.
248    ///
249    /// # Errors
250    ///
251    /// Returns an [`AppendError`] if the append fails, or — before `DuckDB` is
252    /// called — if `micros` is below `290309-12-22 (BC)` and not `-infinity`,
253    /// the range of [`Value::timestamp`][crate::value::Value::timestamp].
254    /// `DuckDB` stores such a value unchecked, and every later read of the row
255    /// fails with "Date out of range".
256    pub fn append_timestamp(&self, micros: i64) -> Result<(), AppendError> {
257        self.check_temporal(crate::types::TypeId::Timestamp, micros, "append_timestamp")?;
258        // SAFETY: self.handle is valid.
259        self.append_one(|| unsafe {
260            duckdb_append_timestamp(self.handle, duckdb_timestamp { micros })
261        })
262    }
263
264    /// Appends an `INTERVAL`.
265    ///
266    /// # Errors
267    ///
268    /// Returns an [`AppendError`] if the append fails.
269    pub fn append_interval(&self, value: DuckInterval) -> Result<(), AppendError> {
270        let raw = duckdb_interval {
271            months: value.months,
272            days: value.days,
273            micros: value.micros,
274        };
275        // SAFETY: self.handle is valid.
276        self.append_one(|| unsafe { duckdb_append_interval(self.handle, raw) })
277    }
278
279    /// Appends an arbitrary [`Value`], letting `DuckDB` cast it to the column's
280    /// type.
281    ///
282    /// This is the escape hatch for types with no dedicated `append_*`:
283    /// `LIST`, `STRUCT`, `MAP`, `UUID`, `DECIMAL`, `ENUM`.
284    ///
285    /// # Errors
286    ///
287    /// Returns an [`AppendError`] if `value` holds a null handle — which
288    /// `duckdb_append_value` would dereference — or if the append fails.
289    pub fn append_value(&self, value: &Value) -> Result<(), AppendError> {
290        self.usable()?;
291        if value.as_raw().is_null() {
292            // duckdb_append_value dereferences its argument with no null check.
293            return Err(append_error("cannot append a null duckdb_value handle"));
294        }
295        // SAFETY: self.handle is valid and value.as_raw() is non-null.
296        self.record_append(unsafe { duckdb_append_value(self.handle, value.as_raw()) })
297    }
298}
299
300/// Poisons the appender if a [`row`][Appender::row] closure panics after the
301/// row's first value, as an error there does. Forgotten on the normal path,
302/// so its `drop` runs only while unwinding.
303struct PoisonOnUnwind<'a>(&'a Appender);
304
305impl Drop for PoisonOnUnwind<'_> {
306    fn drop(&mut self) {
307        if self.0.column.get() != 0 {
308            self.0.lifecycle.set(Lifecycle::Poisoned);
309        }
310    }
311}
312
313#[cfg(test)]
314mod tests {
315    use super::fits_append_length;
316
317    /// The limit is `u32::MAX` bytes inclusive: a string of exactly that
318    /// length is passed to `DuckDB` intact, one byte more would be truncated.
319    #[test]
320    fn the_append_length_limit_is_u32_max_inclusive() {
321        assert!(fits_append_length(0));
322        assert!(fits_append_length(u32::MAX as usize));
323        #[cfg(target_pointer_width = "64")]
324        assert!(!fits_append_length(u32::MAX as usize + 1));
325    }
326}