Struct Appender 

pub struct Appender<'conn> { /* private fields */ }

Appender for fast import data

Error Reporting

DuckDB buffers appended rows and checks constraints (NOT NULL, foreign keys, …) when the buffered data is flushed to the table. That can happen through an explicit flush, through DuckDB’s internal appender flush while appending many rows, or when the appender is dropped. As a result, append_row may return Ok for a row that later fails a constraint check.

Always call flush explicitly and check its result before dropping the appender. Dropping an appender flushes any remaining rows, but errors raised during that implicit flush are discarded because Drop cannot report them.

Thread Safety

Appender is Sync but not Send:

• Sync because every method that touches the underlying DuckDB appender takes &mut self, so no mutation is reachable through a shared &Appender. This is in the spirit of std::sync::Exclusive.
• Not Send because it holds a reference to Connection, which is !Sync.

To use an appender in another thread, move the Connection to that thread and create the appender there.

See DuckDB concurrency documentation for more details.

Wide Tables (Many Columns)

Array literals [value; N] are supported for tables with up to 32 columns.

appender.append_row([0; 32])?;
appender.append_row([1, 2, 3, 4, 5])?;

For tables with more than 32 columns, use one of these alternatives:

1. Slice approach - convert values to &dyn ToSql

let values: Vec<i32> = vec![0; 100];
let params: Vec<&dyn ToSql> = values.iter().map(|v| v as &dyn ToSql).collect();
appender.append_row(params.as_slice())?;

2. params! macro - write values explicitly

appender.append_row(params![v1, v2, v3, ..., v50])?;

3. appender_params_from_iter - pass an iterator directly

use duckdb::appender_params_from_iter;
let values: Vec<i32> = vec![0; 100];
appender.append_row(appender_params_from_iter(values))?;

All three methods can be used interchangeably and mixed in the same appender.

Implementations

impl Appender<'_>

pub fn append_rows<P, I>(&mut self, rows: I) -> Result<()>

where I: IntoIterator<Item = P>, P: AppenderParams,

Append multiple rows from Iterator

Example

fn insert_rows(conn: &Connection) -> Result<()> {
    let mut app = conn.appender("foo")?;
    app.append_rows([[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]])?;
    Ok(())
}

Failure

Returns Err if a row cannot be appended.

pub fn append_row<P: AppenderParams>(&mut self, params: P) -> Result<()>

Append one row

Example

fn insert_row(conn: &Connection) -> Result<()> {
    let mut app = conn.appender("foo")?;
    app.append_row([1, 2])?;
    Ok(())
}

Failure

Returns Err if the row cannot be appended.

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

Flush buffered rows into the table.

Constraint violations (e.g. NOT NULL) in previously appended rows are reported when buffered rows are flushed. This method is the explicit way to observe those errors, although DuckDB may also surface them from an internal appender flush during append. Call this explicitly and check the result before dropping the appender: the implicit flush on drop discards any error.

Failure

Returns Err if the buffered rows cannot be written, e.g. because a row violates a table constraint. The appender is invalidated and the buffered rows are lost.

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

Add a column to the appender’s active column list.

When columns are added, only those columns need values during append. Other columns will use their DEFAULT value (or NULL if no default).

This flushes any pending data before modifying the column list.

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

Clear the appender’s active column list.

After clearing, all columns become active again and values must be provided for every column during append.

This flushes any pending data before clearing.

Trait Implementations

impl Debug for Appender<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

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.

impl Sync for Appender<'_>