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:
| Type | Owns | Released by |
|---|---|---|
QueryResult | duckdb_result | duckdb_destroy_result |
OwnedDataChunk | duckdb_data_chunk | duckdb_destroy_data_chunk |
PreparedStatement | duckdb_prepared_statement | duckdb_destroy_prepare |
OwnedConnection | duckdb_connection | duckdb_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§
- Interrupt
Handle - A cancellation handle for an
OwnedConnection, usable from another thread. - Owned
Connection - A
duckdb_connectionthis crate opened and will disconnect on drop. - Owned
Data Chunk - A
duckdb_data_chunkowned by this crate. - Prepared
Statement - A
duckdb_prepared_statement, destroyed on drop. - Query
Progress - A snapshot of a running query’s progress.
- Query
Result - A
duckdb_result— materialised, or streaming when it came fromPreparedStatement::execute_streaming(featureduckdb-1-5) — destroyed on drop.
Enums§
- Result
Kind - What kind of outcome a statement produced.
- Statement
Type - What kind of SQL statement a
PreparedStatementorQueryResultis, mirroringduckdb_statement_type.
Functions§
- execute⚠
- Runs
sqlonconfor its side effects and returns the number of rows changed. - interrupt⚠
- Requests cancellation of whatever
conis currently running. - prepare⚠
- Prepares
sqloncon. - query⚠
- Runs
sqlonconand returns the materialised result. - query_
progress ⚠ - Reads the progress of whatever
conis currently running. - table_
names ⚠ - The tables
sqlreads or writes, asDuckDB’s binder resolves them (DuckDB1.5.0+).