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