Struct Appender 

pub struct Appender { /* private fields */ }

A DuckDB appender for bulk-inserting rows into a table. A DuckDB appender for bulk-inserting rows into a table without going through the SQL parser.

Lifecycle

Call append for each row, then either finish (consuming, reports flush errors) or let the appender drop (best-effort flush, errors logged). A failed append/save poisons the appender: DuckDB has invalidated all buffered data, so subsequent calls fail fast without touching the C handle, and drop skips the flush entirely (re-flushing an invalidated appender can deadlock DuckDB on indexed tables).

Implementations

impl Appender

pub fn column_count(&self) -> u64

The number of columns in the appender’s active column list (or, with no projection set, the receiving table’s column count).

pub fn column_type(&self, col_idx: u64) -> Option<LogicalType>

The logical type of the appender column at col_idx, or None if DuckDB returns no type (e.g. index out of range).

pub fn add_column(&mut self, name: &str) -> Result<()>

Adds name to the appender’s active column list, so subsequent rows supply only the projected columns (the rest take their DEFAULT).

Must be called before the first row is appended.

Errors

Returns an error if a row has already been appended, on an interior NUL in name, or if DuckDB rejects the column.

pub fn clear_columns(&mut self) -> Result<()>

Clears any active column-list projection, so subsequent rows supply every column of the receiving table again.

Must be called before the first row is appended.

Errors

Returns an error if a row has already been appended, or if DuckDB reports a failure.

pub fn append_default_row(&mut self) -> Result<()>

Appends one row in which every column takes its DEFAULT value.

Fills the active column list with duckdb_append_default (a column whose table has no DEFAULT becomes NULL). Opens and closes the row like append, so a failure part-way never leaves a half-open row.

Errors

Returns an error if the appender is poisoned/closed or DuckDB rejects a default.

pub fn append_chunk(&mut self, chunk: &DataChunk) -> Result<()>

Appends every row of chunk to the appender in one call (duckdb_append_data_chunk).

chunk is only read — the caller keeps ownership and it is destroyed on drop as usual. The chunk’s column count must match the appender’s active column list; this is validated Rust-side before the FFI call.

Errors

Returns an error if the appender is poisoned/closed, the chunk’s column count disagrees with the appender’s, or DuckDB rejects the chunk (e.g. type mismatch).

pub fn append_default_to_chunk( &mut self, chunk: &mut DataChunk, col: u64, row: u64, ) -> Result<()>

Writes the DEFAULT value of appender column col into chunk at (col, row) (duckdb_append_default_to_chunk); a column with no DEFAULT becomes NULL.

col must be within the chunk’s column count (validated Rust-side).

Errors

Returns an error if the appender is poisoned/closed, col is out of range, or DuckDB reports a failure.

pub fn append<T: AppendAble>(&mut self, row: &mut T) -> Result<()>

Appends a row to the table.

Opens a row (duckdb_appender_begin_row), appends the value, then closes it (duckdb_appender_end_row). A RowGuard closes the row even if appending the value returns early or panics, so a half-written row can never bleed into the next call.

Errors

Returns an error if the appender is poisoned or closed, or if the row cannot be appended. Engine-side failures carry DuckDB’s typed classification via Error::Engine; any failure poisons the appender.

pub fn save(&mut self) -> Result<()>

Flushes all buffered rows to the database.

Errors

Returns an error if the appender is poisoned or closed, or if the flush fails (which additionally poisons the appender).

pub fn finish(self) -> Result<()>

Flushes and closes the appender, consuming it and reporting any error.

Unlike dropping, this surfaces a flush/close failure to the caller. On success the handle is closed and its Drop becomes a bare destroy.

Errors

Returns an error if the appender is already poisoned, or if the final flush/close fails (which poisons it).

Trait Implementations

impl Drop for Appender

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.