Appender — Bulk Insert

The Appender (better_duck_core::Appender) is DuckDB’s fast bulk-ingest path — far faster than row-by-row INSERT. Create one from a Connection. This page covers the everyday lifecycle; see appender advanced for projected columns, catalog/query appenders, raw chunk ingestion, and poisoning.

Lifecycle at a glance

Create

conn.appender("items", "main")? — (table, schema).

Append rows

One append call per column value, left to right, row by row.

Flush

save() (flush, keep using) or finish() (flush, close, report errors).

use better_duck_core::types::value::DuckValue;

conn.execute_batch("CREATE TABLE items (id INTEGER, name VARCHAR)")?;

let mut app = conn.appender("items", "main")?;    // (table, schema)
app.append(&mut DuckValue::Int(1))?;               // row 1, column 0
app.append(&mut DuckValue::text("a"))?;            // row 1, column 1
app.append(&mut DuckValue::Int(2))?;               // row 2, column 0
app.append(&mut DuckValue::text("b"))?;            // row 2, column 1
app.save()?;                                        // flush buffered rows

Rows map to columns in order; supply exactly one value per column per row.

Appending rows

append<T: AppendAble>(&mut self, row: &mut T) -> Result<()> (#[must_use]). Every DuckValue and the primitive Rust types implement AppendAble. Internally the call opens a row, appends the value, and closes the row with a guard that ends the row even on an early return or panic — so a half-written row can never bleed into the next call.

For a struct-per-row path, derive #[derive(ToRow)] and append the whole struct at once:

use better_duck_core::ToRow;
#[derive(ToRow)]
struct NewItem { id: i32, name: String }

app.append(&mut NewItem { id: 3, name: "c".into() })?;

Flushing: save vs finish vs drop

Call	Behavior
`save(&mut self) -> Result<()>`	Flush buffered rows; the appender stays usable. `#[must_use]`.
`finish(self) -> Result<()>`	Flush, close, and report any error; consumes the appender. `#[must_use]`.
drop	Best-effort flush; a failure is only logged, not returned.

app.append(&mut DuckValue::Int(4))?;
app.finish()?;                                      // surfaces a flush/close error

Prefer finish() over relying on drop when you need the flush/close error reported — drop cannot return a Result, so it swallows failures (logging only).

Appenders and the connection

An Appender keeps its originating connection alive and appends inside any transaction open on that connection.
A second connection (try_clone) can read the rows after save().
Connection::close errors while an appender from that connection is still alive; the connection closes once the last appender drops.

Connecting

Querying

Values & Types

Parameters & Statements

Writing Data

Columnar

Concurrency

Interop

Errors & Extensions

User-Defined Functions

Derives & Helpers

Appender — Bulk Insert

Lifecycle at a glance

Appending rows

Flushing: save vs finish vs drop

Appenders and the connection

See also

​Lifecycle at a glance

​Appending rows

​Flushing: save vs finish vs drop

​Appenders and the connection

​See also

Lifecycle at a glance

Appending rows

Flushing: save vs finish vs drop

Appenders and the connection

See also