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}