quack_rs/appender/lifecycle.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//! Flushing, closing and (with `duckdb-1-5`) clearing an [`Appender`].
7
8#[cfg(feature = "duckdb-1-5")]
9use libduckdb_sys::duckdb_appender_clear;
10use libduckdb_sys::{duckdb_appender_close, duckdb_appender_flush};
11
12use super::{AppendError, Appender, Lifecycle};
13
14impl Appender {
15 // ── Lifecycle ───────────────────────────────────────────────────────
16
17 /// Flushes buffered rows to the table without closing the appender.
18 ///
19 /// # Errors
20 ///
21 /// Returns an [`AppendError`] if the flush fails — a constraint violation,
22 /// typically. On failure every buffered row is invalidated: up to `DuckDB`
23 /// 1.5.x they stay buffered and, with `duckdb-1-5`, can be discarded with
24 /// `clear`; from 2.0.0 `DuckDB` discards them itself. Also an error when
25 /// the appender is closed or poisoned, or a row is in progress. On 2.0.0
26 /// the flush also fails, losing the buffered rows, while a streaming
27 /// result is open on the appender's connection (see the
28 /// [module docs][crate::appender]).
29 pub fn flush(&self) -> Result<(), AppendError> {
30 self.usable()?;
31 // SAFETY: self.handle is valid.
32 let state = unsafe { duckdb_appender_flush(self.handle) };
33 self.flushed(state)
34 }
35
36 /// Flushes and closes the appender. Every later append, `row`, `end_row`,
37 /// `flush` and `append_chunk` returns an error; closing again is a no-op.
38 ///
39 /// # Errors
40 ///
41 /// Returns an [`AppendError`] if the final flush fails (the appender then
42 /// stays open; up to `DuckDB` 1.5.x the buffered rows can be discarded
43 /// with `clear` under `duckdb-1-5`, and from 2.0.0 `DuckDB` has already
44 /// discarded them, so closing again succeeds and writes nothing), and —
45 /// instead of `DuckDB`'s silent success — when a row
46 /// is unfinished or the appender is poisoned: `DuckDB`'s `Close` writes
47 /// nothing in that state, so the error says how many buffered rows were
48 /// not written. An unfinished row appended by hand can still be completed
49 /// and the appender closed again.
50 pub fn close(&self) -> Result<(), AppendError> {
51 match self.lifecycle.get() {
52 Lifecycle::Closed => return Ok(()),
53 Lifecycle::Poisoned => return Err(self.lost_rows_error("close")),
54 Lifecycle::Open if self.column.get() != 0 => {
55 return Err(self.lost_rows_error("close"));
56 }
57 Lifecycle::Open => {}
58 }
59 // SAFETY: self.handle is valid.
60 let state = unsafe { duckdb_appender_close(self.handle) };
61 self.flushed(state)?;
62 self.lifecycle.set(Lifecycle::Closed);
63 Ok(())
64 }
65
66 /// Discards all buffered, unflushed rows, and any half-written row.
67 ///
68 /// Useful for recovering after a [`flush`][Self::flush] error without
69 /// re-appending the rows that were already committed, and the only way
70 /// to make a poisoned appender (see the [module docs][crate::appender])
71 /// usable again. It does not reopen a closed one.
72 ///
73 /// # Errors
74 ///
75 /// Returns an [`AppendError`] if the appender state is invalid.
76 #[cfg(feature = "duckdb-1-5")]
77 pub fn clear(&self) -> Result<(), AppendError> {
78 // SAFETY: self.handle is valid.
79 let state = unsafe { duckdb_appender_clear(self.handle) };
80 self.check(state)?;
81 // `BaseAppender::Clear` resets the chunk, the buffered collection and
82 // the column counter.
83 self.column.set(0);
84 self.buffered.set(0);
85 if self.lifecycle.get() == Lifecycle::Poisoned {
86 self.lifecycle.set(Lifecycle::Open);
87 }
88 Ok(())
89 }
90}