Skip to main content

Module query

Module query 

Source
Expand description

Running SQL from inside an extension.

Extensions routinely need to talk SQL to the database that is loading them: checking whether a table exists before registering a replacement scan, creating a helper view or macro, reading a setting, or looking up a secret through duckdb_secrets(). The C API exposes all of that (duckdb_query, duckdb_prepare, duckdb_bind_*, duckdb_fetch_chunk), but every handle involved has a matching destroy that must run exactly once — including on the error paths, which is where hand-written FFI usually leaks.

This module wraps those handles in RAII types:

TypeOwnsReleased by
QueryResultduckdb_resultduckdb_destroy_result
OwnedDataChunkduckdb_data_chunkduckdb_destroy_data_chunk
PreparedStatementduckdb_prepared_statementduckdb_destroy_prepare
OwnedConnectionduckdb_connectionduckdb_disconnect

The types above, and running, preparing, binding and fetching, are in the stable prefix of the C extension API: they work on every DuckDB from v1.2.0 onwards and need no feature flag. Streaming execution (execute_streaming, is_streaming) needs duckdb-1-5, and a result’s Arrow options need duckdb-1-5-4. See crate::abi.

§When you can run a query

During extension load, inside your registration closure. The duckdb_connection DuckDB hands you there is a real connection, and Connection::query uses it directly.

Inside a scalar/table/aggregate callback you do not have a connection — the C API gives you a duckdb_client_context, and there is no duckdb_client_context_get_connection. If a callback needs to run SQL, open an OwnedConnection during registration and keep it: a connection created from the load-time duckdb_database holds a shared_ptr to the database instance, so it stays valid after loading finishes.

Do not reuse the borrowed registration connection after your closure returns — the entry point disconnects it.

§Example

use quack_rs::error::ExtensionError;
use quack_rs::query;

// SAFETY: `con` is the connection DuckDB passed to the entry point.
let mut result = unsafe { query::query(con, "SELECT 42 AS answer") }?;
while let Some(chunk) = result.next_chunk()? {
    let reader = unsafe { chunk.reader(0) };
    for row in 0..chunk.size() {
        assert_eq!(unsafe { reader.read_i32(row) }, 42);
    }
}

Structs§

InterruptHandle
A cancellation handle for an OwnedConnection, usable from another thread.
OwnedConnection
A duckdb_connection this crate opened and will disconnect on drop.
OwnedDataChunk
A duckdb_data_chunk owned by this crate.
PreparedStatement
A duckdb_prepared_statement, destroyed on drop.
QueryProgress
A snapshot of a running query’s progress.
QueryResult
A duckdb_result — materialised, or streaming when it came from PreparedStatement::execute_streaming (feature duckdb-1-5) — destroyed on drop.

Enums§

ResultKind
What kind of outcome a statement produced.
StatementType
What kind of SQL statement a PreparedStatement or QueryResult is, mirroring duckdb_statement_type.

Functions§

execute⚠
Runs sql on con for its side effects and returns the number of rows changed.
interrupt⚠
Requests cancellation of whatever con is currently running.
prepare⚠
Prepares sql on con.
query⚠
Runs sql on con and returns the materialised result.
query_progress⚠
Reads the progress of whatever con is currently running.
table_names⚠
The tables sql reads or writes, as DuckDB’s binder resolves them (DuckDB 1.5.0+).