Skip to main content

quack_rs/
query.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! Running SQL from inside an extension.
7//!
8//! Extensions routinely need to talk SQL to the database that is loading them:
9//! checking whether a table exists before registering a replacement scan,
10//! creating a helper view or macro, reading a setting, or looking up a secret
11//! through `duckdb_secrets()`. The C API exposes all of that
12//! (`duckdb_query`, `duckdb_prepare`, `duckdb_bind_*`, `duckdb_fetch_chunk`),
13//! but every handle involved has a matching `destroy` that must run exactly once
14//! — including on the error paths, which is where hand-written FFI usually leaks.
15//!
16//! This module wraps those handles in RAII types:
17//!
18//! | Type | Owns | Released by |
19//! |------|------|-------------|
20//! | [`QueryResult`] | `duckdb_result` | `duckdb_destroy_result` |
21//! | [`OwnedDataChunk`] | `duckdb_data_chunk` | `duckdb_destroy_data_chunk` |
22//! | [`PreparedStatement`] | `duckdb_prepared_statement` | `duckdb_destroy_prepare` |
23//! | [`OwnedConnection`] | `duckdb_connection` | `duckdb_disconnect` |
24//!
25//! The types above, and running, preparing, binding and fetching, are in the
26//! **stable** prefix of the C extension API: they work on every `DuckDB` from
27//! v1.2.0 onwards and need no feature flag. Streaming execution
28//! (`execute_streaming`, `is_streaming`) needs `duckdb-1-5`, and a result's
29//! Arrow options need `duckdb-1-5-4`. See [`crate::abi`].
30//!
31//! # When you can run a query
32//!
33//! During extension load, inside your registration closure. The
34//! `duckdb_connection` `DuckDB` hands you there is a real connection, and
35//! [`Connection::query`][crate::connection::Connection::query] uses it directly.
36//!
37//! Inside a scalar/table/aggregate **callback** you do not have a connection —
38//! the C API gives you a `duckdb_client_context`, and there is no
39//! `duckdb_client_context_get_connection`. If a callback needs to run SQL, open
40//! an [`OwnedConnection`] during registration and keep it: a connection created
41//! from the load-time `duckdb_database` holds a `shared_ptr` to the database
42//! instance, so it stays valid after loading finishes.
43//!
44//! Do not reuse the *borrowed* registration connection after your closure
45//! returns — the entry point disconnects it.
46//!
47//! # Example
48//!
49//! ```rust,no_run
50//! use quack_rs::error::ExtensionError;
51//! use quack_rs::query;
52//!
53//! # unsafe fn demo(con: libduckdb_sys::duckdb_connection) -> Result<(), ExtensionError> {
54//! // SAFETY: `con` is the connection DuckDB passed to the entry point.
55//! let mut result = unsafe { query::query(con, "SELECT 42 AS answer") }?;
56//! while let Some(chunk) = result.next_chunk()? {
57//!     let reader = unsafe { chunk.reader(0) };
58//!     for row in 0..chunk.size() {
59//!         assert_eq!(unsafe { reader.read_i32(row) }, 42);
60//!     }
61//! }
62//! # Ok(())
63//! # }
64//! ```
65
66mod bind;
67mod chunk;
68mod connection;
69mod cstr;
70mod metadata;
71mod prepared;
72mod result;
73
74#[cfg(feature = "duckdb-1-5")]
75pub use metadata::table_names;
76pub use metadata::StatementType;
77
78use libduckdb_sys::{
79    duckdb_connection, duckdb_destroy_prepare, duckdb_destroy_result, duckdb_prepare,
80    duckdb_prepare_error, duckdb_prepared_statement, duckdb_query, duckdb_result,
81    duckdb_result_error, DuckDBSuccess,
82};
83
84use self::cstr::{c_str_to_owned, to_c_sql};
85use crate::data_chunk::DataChunk;
86use crate::error::ExtensionError;
87
88// ─── Data chunk ──────────────────────────────────────────────────────────────
89
90/// A `duckdb_data_chunk` owned by this crate.
91///
92/// [`QueryResult::next_chunk`] hands out chunks that the caller owns and must
93/// destroy. This type does that on drop and derefs to the borrowing
94/// [`DataChunk`] wrapper, so all the usual readers apply.
95pub struct OwnedDataChunk {
96    chunk: libduckdb_sys::duckdb_data_chunk,
97    view: DataChunk,
98}
99
100// ─── Query result ────────────────────────────────────────────────────────────
101
102/// What kind of outcome a statement produced.
103///
104/// Mirrors `duckdb_result_type`. A `SELECT` yields [`QueryResult`][Self::Rows];
105/// `INSERT` / `UPDATE` / `DELETE` yield [`ChangedRows`][Self::ChangedRows], for
106/// which [`QueryResult::rows_changed`] is meaningful; `CREATE` / `SET` and
107/// friends yield [`Nothing`][Self::Nothing].
108#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
109#[non_exhaustive]
110pub enum ResultKind {
111    /// The statement produced rows.
112    Rows,
113    /// The statement changed rows; see [`QueryResult::rows_changed`].
114    ChangedRows,
115    /// The statement produced neither rows nor row counts.
116    Nothing,
117    /// `DuckDB` reported `DUCKDB_RESULT_TYPE_INVALID`, or a value this build
118    /// does not know.
119    Invalid,
120}
121
122/// A `duckdb_result` — materialised, or streaming when it came from
123/// `PreparedStatement::execute_streaming` (feature `duckdb-1-5`) — destroyed
124/// on drop.
125///
126/// Iterate the rows with [`next_chunk`][Self::next_chunk] until it returns
127/// `Ok(None)`; an `Err` means the rows stopped early.
128pub struct QueryResult {
129    result: duckdb_result,
130    fetch: FetchState,
131}
132
133/// Whether [`QueryResult::next_chunk`] may still call `duckdb_fetch_chunk`.
134#[derive(Debug)]
135enum FetchState {
136    Open,
137    /// `duckdb_fetch_chunk` returned null with no error recorded.
138    Ended,
139    /// It returned null and `DuckDB` recorded this error on the result.
140    Failed(String),
141}
142
143impl QueryResult {
144    const fn new(result: duckdb_result) -> Self {
145        Self {
146            result,
147            fetch: FetchState::Open,
148        }
149    }
150}
151
152/// Runs `sql` on `con` and returns the materialised result.
153///
154/// # Several statements in one string
155///
156/// `sql` may hold several `;`-separated statements, and `DuckDB` runs **every**
157/// one of them, in order. The result returned is the first statement that
158/// produces rows (a `SELECT`, …), or — when none does — the last statement's.
159/// Results of later row-producing statements are discarded (`DuckDB` chains
160/// them where the C API cannot reach them). The first statement that fails
161/// fails the call, but the statements before it have already run and, outside
162/// an explicit transaction, committed. A string with no statement at all
163/// (`""`, `";"`) succeeds with an empty result.
164///
165/// # Errors
166///
167/// Returns [`ExtensionError`] carrying `DuckDB`'s own message if a statement
168/// fails, or if `sql` contains an interior NUL byte.
169///
170/// # Safety
171///
172/// `con` must be a valid, open `duckdb_connection`.
173pub unsafe fn query(con: duckdb_connection, sql: &str) -> Result<QueryResult, ExtensionError> {
174    let c_sql = to_c_sql(sql)?;
175    // SAFETY: `duckdb_result` is a `#[repr(C)]` struct of three `idx_t`
176    // integers and three raw pointers; all-zero bits are a valid value of each
177    // (null pointers included). DuckDB overwrites it as an out-parameter.
178    let mut result: duckdb_result = unsafe { std::mem::zeroed() };
179    // SAFETY: `con` is valid per the caller's contract; `c_sql` outlives the call.
180    let state = unsafe { duckdb_query(con, c_sql.as_ptr(), &raw mut result) };
181    if state == DuckDBSuccess {
182        return Ok(QueryResult::new(result));
183    }
184    // SAFETY: on an ordinary failure DuckDB populated `result`, so the error
185    // message is readable and the result must be destroyed. On its
186    // `catch (...)` path it returns without touching `result`, which is still
187    // zeroed: `duckdb_result_error` then returns null and
188    // `duckdb_destroy_result` is a no-op on a zeroed result.
189    let message = unsafe { c_str_to_owned(duckdb_result_error(&raw mut result)) }
190        .unwrap_or_else(|| no_error_message("duckdb_query"));
191    // SAFETY: `result` is destroyed exactly once, here, on the error path.
192    unsafe { duckdb_destroy_result(&raw mut result) };
193    Err(ExtensionError::new(message))
194}
195
196/// Runs `sql` on `con` for its side effects and returns the number of rows
197/// changed.
198///
199/// With several statements in `sql`, every one runs, but the count is that
200/// of the statement whose result [`query`] returns — the first that produces
201/// rows, or else the last: `"SELECT 1; INSERT …"` reports `0`.
202///
203/// # Errors
204///
205/// See [`query`].
206///
207/// # Safety
208///
209/// `con` must be a valid, open `duckdb_connection`.
210pub unsafe fn execute(con: duckdb_connection, sql: &str) -> Result<u64, ExtensionError> {
211    // SAFETY: forwarded from this function's own contract.
212    let result = unsafe { query(con, sql) }?;
213    Ok(result.rows_changed())
214}
215
216/// The message for a failure `DuckDB` reported without one.
217///
218/// `duckdb_query`, `duckdb_execute_prepared` and
219/// `duckdb_execute_prepared_streaming` return `DuckDBError` from a
220/// `catch (...)` block without filling in the result, so there is no message
221/// to read (`duckdb-c.cpp`, `prepared-c.cpp`).
222fn no_error_message(api_func: &str) -> String {
223    format!(
224        "{api_func} reported failure without an error message: DuckDB caught an exception \
225         that is not a std::exception (its `catch (...)` path), which records nothing"
226    )
227}
228
229// ─── Prepared statements ─────────────────────────────────────────────────────
230
231/// A `duckdb_prepared_statement`, destroyed on drop.
232///
233/// Prepared statements are how an extension runs SQL with values it did not
234/// author. Interpolating a table name or a user-supplied string into SQL text is
235/// an injection bug; binding it is not.
236///
237/// Parameters are 1-indexed, matching the C API.
238pub struct PreparedStatement {
239    statement: duckdb_prepared_statement,
240}
241
242/// Prepares `sql` on `con`.
243///
244/// `sql` must hold exactly one statement; unlike [`query`], a string with
245/// several is an error.
246///
247/// # Errors
248///
249/// Returns [`ExtensionError`] carrying `DuckDB`'s parse/bind error, or if `sql`
250/// contains an interior NUL byte.
251///
252/// An allocation failure inside `DuckDB` while it prepares a statement with
253/// parameters can leave its output pointing at a statement it has already
254/// freed, which this then reads and frees again; nothing on this side can
255/// tell. See `docs/upstream-duckdb-reports.md`, item 36.
256///
257/// # Safety
258///
259/// `con` must be a valid, open `duckdb_connection`.
260pub unsafe fn prepare(
261    con: duckdb_connection,
262    sql: &str,
263) -> Result<PreparedStatement, ExtensionError> {
264    let c_sql = to_c_sql(sql)?;
265    let mut statement: duckdb_prepared_statement = std::ptr::null_mut();
266    // SAFETY: `con` is valid per the caller's contract; `c_sql` outlives the call.
267    let state = unsafe { duckdb_prepare(con, c_sql.as_ptr(), &raw mut statement) };
268    if state == DuckDBSuccess {
269        return Ok(PreparedStatement { statement });
270    }
271    // SAFETY: on failure DuckDB still allocates the statement so the error is
272    // readable; it must be destroyed either way. (Except after an allocation
273    // failure, which can leave a freed statement here: upstream item 36.)
274    let message = unsafe { c_str_to_owned(duckdb_prepare_error(statement)) }
275        .unwrap_or_else(|| String::from("prepare failed without an error message"));
276    // SAFETY: destroyed exactly once, here, on the error path.
277    unsafe { duckdb_destroy_prepare(&raw mut statement) };
278    Err(ExtensionError::new(message))
279}
280
281// ─── Cancellation and progress ───────────────────────────────────────────────
282
283/// A snapshot of a running query's progress.
284///
285/// `percentage` is `-1.0` when `DuckDB` cannot report progress — the progress
286/// bar is disabled (`SET enable_progress_bar = true` turns it on), no query is
287/// running, or the connection handle was null.
288///
289/// On `DuckDB` 1.x it is also `-1.0` for as long as any pipeline of the
290/// running query cannot estimate its progress: `ProgressBar::Update`
291/// (`progress_bar.cpp`, 1.5.6) leaves the percentage untouched while one
292/// reports none, and the value is refreshed only between the executor tasks
293/// the querying thread runs (`ClientContext::ExecuteTaskInternal`).
294/// A `-1.0` was read throughout a query on 1.5.6 where 2.0.0 reported
295/// 1.18 %, 1.34 %, 1.47 % for the same one (observed in a review, not
296/// re-run for this documentation). Treat `-1.0` as "unknown", not as an error.
297///
298/// The three fields are read from separate atomics, so they are individually
299/// current but not a consistent snapshot of one instant.
300#[derive(Debug, Clone, Copy, PartialEq)]
301pub struct QueryProgress {
302    /// Percent complete in `0.0..=100.0`, or `-1.0` when unavailable.
303    pub percentage: f64,
304    /// Rows processed so far.
305    pub rows_processed: u64,
306    /// Rows the plan expects to process in total.
307    pub total_rows_to_process: u64,
308}
309
310/// Requests cancellation of whatever `con` is currently running.
311///
312/// The call itself is non-blocking: it sets `ClientContext::interrupted`, an
313/// `atomic<bool>` the executor polls, so the running query fails with an
314/// interrupt error at its next check rather than immediately. Calling it while
315/// no query is running arms nothing — `DuckDB` clears the flag when a query
316/// starts.
317///
318/// # Safety
319///
320/// `con` must be a valid, open `duckdb_connection` **for the duration of this
321/// call**. It is sound to call this from a different thread than the one
322/// running the query — that is the point of the API — but it is not sound to
323/// race it against `duckdb_disconnect`. Prefer
324/// [`OwnedConnection::interrupt_handle`], whose lifetime enforces that.
325pub unsafe fn interrupt(con: duckdb_connection) {
326    // SAFETY: `con` is valid per the caller's contract; DuckDB null-checks it
327    // itself, and the flag it sets is atomic.
328    unsafe { libduckdb_sys::duckdb_interrupt(con) };
329}
330
331/// Reads the progress of whatever `con` is currently running.
332///
333/// # Safety
334///
335/// Same contract as [`interrupt`].
336#[must_use]
337pub unsafe fn query_progress(con: duckdb_connection) -> QueryProgress {
338    // SAFETY: `con` is valid per the caller's contract; every field DuckDB
339    // reads is an atomic.
340    let raw = unsafe { libduckdb_sys::duckdb_query_progress(con) };
341    QueryProgress {
342        percentage: raw.percentage,
343        rows_processed: raw.rows_processed,
344        total_rows_to_process: raw.total_rows_to_process,
345    }
346}
347
348/// A cancellation handle for an [`OwnedConnection`], usable from another thread.
349///
350/// Both operations reach `DuckDB` through atomics — `ClientContext::interrupted`
351/// is an `atomic<bool>`, and every field of `QueryProgress` is an atomic — so
352/// this is `Send + Sync`. The borrow of the connection is what keeps it sound:
353/// the handle cannot outlive the `duckdb_disconnect` in
354/// [`OwnedConnection`]'s `Drop`.
355///
356/// # Example
357///
358/// ```rust,no_run
359/// # use quack_rs::query::OwnedConnection;
360/// # fn demo(con: &OwnedConnection) -> Result<(), quack_rs::error::ExtensionError> {
361/// use std::sync::mpsc::{channel, RecvTimeoutError};
362/// use std::time::Duration;
363///
364/// let watchdog = con.interrupt_handle();
365/// let (done, finished) = channel::<()>();
366/// std::thread::scope(|scope| {
367///     // Cancels the query only if it is still running after 30 s; returns
368///     // as soon as it finishes.
369///     scope.spawn(move || {
370///         if finished.recv_timeout(Duration::from_secs(30)) == Err(RecvTimeoutError::Timeout) {
371///             watchdog.cancel();
372///         }
373///     });
374///     let result = con.query("SELECT count(*) FROM huge_table");
375///     drop(done);
376///     result
377/// })?;
378/// # Ok(())
379/// # }
380/// ```
381#[derive(Debug, Clone, Copy)]
382pub struct InterruptHandle<'a> {
383    con: duckdb_connection,
384    _borrow: core::marker::PhantomData<&'a OwnedConnection>,
385}
386
387// SAFETY: the only operations are `duckdb_interrupt` and
388// `duckdb_query_progress`. The first sets `ClientContext::interrupted`, an
389// `atomic<bool>`; the second copy-constructs a `QueryProgress` whose three
390// fields are `atomic<double>` / `atomic<uint64_t>`. Neither touches
391// non-atomic connection state, and the `'a` borrow rules out a concurrent
392// disconnect.
393unsafe impl Send for InterruptHandle<'_> {}
394// SAFETY: as above — both operations take `&self` and are atomic.
395unsafe impl Sync for InterruptHandle<'_> {}
396
397// ─── Owned connection ────────────────────────────────────────────────────────
398
399/// A `duckdb_connection` this crate opened and will disconnect on drop.
400///
401/// Open one during registration when the extension needs to run SQL later —
402/// from a background thread, or from a callback, where the C API offers no way
403/// back to a connection. A connection created from the load-time
404/// `duckdb_database` holds a `shared_ptr` to the database instance, so it
405/// outlives extension loading.
406///
407/// This is *not* the connection `DuckDB` passes to your entry point; that one is
408/// borrowed and is disconnected when registration returns.
409pub struct OwnedConnection {
410    con: duckdb_connection,
411}
412
413// SAFETY: a duckdb_connection is a `duckdb::Connection *`, which holds its
414// ClientContext through a shared_ptr and has no state tied to the thread that
415// created it (DuckDB 1.5.5's two `thread_local`s are a per-thread allocator
416// cache and a settings cache keyed by the settings' owner and version), so it
417// may be used from, and disconnected on, another thread; the test
418// `an_owned_connection_is_used_and_dropped_on_another_thread` does both.
419// `Sync` is not implemented. DuckDB itself serialises concurrent calls on one
420// connection with the ClientContext's lock, but a query on one thread would
421// then end a result another thread is streaming (1.x) or be refused while it
422// is open (2.0), and this type's API was not designed for that; share one
423// behind a `Mutex`.
424unsafe impl Send for OwnedConnection {}
425
426#[cfg(test)]
427mod tests {
428    use super::*;
429
430    #[test]
431    fn owned_connection_is_send() {
432        // A connection may move between threads (see the `unsafe impl Send`).
433        // This module carries no `unsafe impl Sync`, so `&OwnedConnection`
434        // cannot cross a thread boundary and two threads cannot reach the same
435        // connection through this type.
436        const fn assert_send<T: Send>() {}
437        assert_send::<OwnedConnection>();
438    }
439
440    /// Reached only through `DuckDB`'s `catch (...)` paths, which no SQL can
441    /// take, so the text is checked here.
442    #[test]
443    fn a_failure_without_a_message_names_the_call_and_the_reason() {
444        let message = no_error_message("duckdb_query");
445        assert!(
446            message.starts_with("duckdb_query reported failure"),
447            "{message}"
448        );
449        assert!(message.contains("catch (...)"), "{message}");
450    }
451}
452
453/// Tests that need a live `DuckDB`.
454#[cfg(all(test, feature = "_duckdb-testing"))]
455mod live_tests;