Skip to main content

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}