Function write_rows 

pub fn write_rows<I>(
    dst: &mut dyn Connection,
    backend: Backend,
    table: &str,
    columns: &[ColumnInfo],
    rows: I,
    opts: &WriteOptions,
) -> Result<WriteReport, SqlError>
where
    I: IntoIterator<Item = Row>,

Write rows into table on dst in bounded back-pressured batches, returning a structured WriteReport.

columns is the destination column order; every row must match it positionally. SQL generation, bulk dispatch, and transaction control are all delegated to the existing copy/transaction machinery (see the module docs). Rows are pulled from rows one batch at a time, so an unbounded iterator is written at O(batch_size) memory.

Blocking: issues synchronous statements through dst; blocks until the write completes (or the outer transaction rolls back under atomic).

Atomicity: with WriteOptions::atomic, all batches run inside one BEGIN/COMMIT (MSSQL SET XACT_ABORT ON, Oracle explicit COMMIT); the first failing batch rolls the whole write back and is recorded. Without it, each batch is independent — earlier committed batches stay, later ones still run, and failures are collected.

Examples found in repository

examples/embed.rs (lines 114-121)

fn main() -> Result<(), Box<dyn Error>> {
    // A throwaway on-disk fixture in the temp dir. Using a file (rather
    // than `:memory:`) keeps a single shared database across the two
    // statements we run; the example removes it on the way out.
    let path =
        std::env::temp_dir().join(format!("ferrule-embed-example-{}.db", std::process::id()));
    let _ = std::fs::remove_file(&path);
    let url = DatabaseUrl::parse(&format!("sqlite://{}", path.display()))?;

    // Step 1 — connect with a caller-resolved credential.
    //
    // `ConnectOptions::password` carries a `SecretString` the *host*
    // resolved (env var, OS keyring, interactive prompt, …); `ferrule-sql`
    // does no credential resolution of its own. The secret is redacted in
    // `Debug` and zeroized on drop. SQLite ignores it (no auth), but a
    // networked backend would consume it here.
    let opts = ConnectOptions {
        insecure: false,
        password: Some(SecretString::from("unused-for-sqlite")),
    };
    let mut conn = ferrule_sql::connect(&url, &opts, None)?;

    // Seed a fixture table to read back. `execute` blocks until the
    // statement completes.
    conn.execute("CREATE TABLE widget (id INTEGER PRIMARY KEY, name TEXT)")?;
    conn.execute(
        "INSERT INTO widget (id, name) VALUES \
         (1, 'alpha'), (2, 'beta'), (3, 'gamma'), (4, 'delta'), (5, 'epsilon')",
    )?;

    // Step 2 — streaming read at bounded memory.
    //
    // `query_cursor` opens a native cursor; `next_batch(n)` pulls at most
    // `n` rows at a time, so peak memory is `O(batch)` no matter how large
    // the table is. The cursor borrows the connection for its lifetime, so
    // it is scoped here and dropped before we write.
    println!("streaming read (batched, bounded memory):");
    let mut streamed = 0u64;
    {
        let mut cursor = conn.query_cursor("SELECT id, name FROM widget ORDER BY id")?;
        loop {
            let batch = cursor.next_batch(2)?; // 2 rows per pull
            if batch.is_empty() {
                break; // end of stream
            }
            for row in &batch {
                println!("  row: {} = {}", render(&row[0]), render(&row[1]));
                streamed += 1;
            }
        }
    }
    println!("  streamed {streamed} rows total\n");

    // Step 3 — batched write with a structured report.
    //
    // `write_rows` consumes any `IntoIterator<Item = Row>` and flushes it
    // in fixed-size batches (`WriteOptions::batch_size`), buffering only
    // one batch at a time. The iterator below is materialized for brevity,
    // but it could be a lazy generator over millions of rows — memory
    // stays `O(batch_size)`. Pair it with the `query_cursor` above for an
    // end-to-end bounded-memory pipe.
    conn.execute("CREATE TABLE sink (id INTEGER PRIMARY KEY, label TEXT)")?;
    let columns = [
        ColumnInfo {
            name: "id".into(),
            type_hint: TypeHint::Int64,
            nullable: false,
        },
        ColumnInfo {
            name: "label".into(),
            type_hint: TypeHint::String,
            nullable: true,
        },
    ];
    let rows: Vec<Row> = (1..=2500)
        .map(|i| vec![Value::Int64(i), Value::String(format!("item-{i}"))])
        .collect();
    let write_opts = WriteOptions {
        mode: WriteMode::Insert,
        batch_size: 500, // 5 batches of 500; only one buffered at a time
        ..Default::default()
    };
    let report = write_rows(
        &mut *conn,
        ferrule_sql::Backend::Sqlite,
        "sink",
        &columns,
        rows,
        &write_opts,
    )?;
    println!("batched write report:");
    println!("  rows attempted : {}", report.rows_attempted);
    println!("  rows written   : {}", report.rows_written);
    println!("  batches        : {}", report.batches_committed);
    println!("  complete       : {}", report.is_complete());

    // Confirm the write landed.
    let count = conn.query("SELECT COUNT(*) FROM sink")?;
    if let Some(Value::Int64(n)) = count.rows.first().and_then(|r| r.first()) {
        println!("  verified count : {n}");
    }

    let _ = std::fs::remove_file(&path);
    Ok(())
}