quack_rs/lib.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//! A Rust SDK for building `DuckDB` loadable extensions on the `DuckDB` C Extension API.
7//!
8//! ## Overview
9//!
10//! `quack-rs` encapsulates the hard-won FFI knowledge required to build `DuckDB`
11//! community extensions in Rust. It provides:
12//!
13//! - A correct, panic-free entry point helper via the [`entry_point`](mod@entry_point) module
14//! - Type-safe builders for registering aggregate functions ([`aggregate`])
15//! - Safe vector reading and writing helpers ([`vector`])
16//! - A generic [`FfiState<T>`][aggregate::state::FfiState] that eliminates raw pointer management
17//! - Documentation of every known `DuckDB` Rust FFI pitfall, with API designs that
18//! prevent most of them
19//!
20//! ## Quick Start
21//!
22//! ```rust,no_run
23//! // In your extension's src/lib.rs:
24//! use quack_rs::entry_point;
25//! use quack_rs::error::ExtensionError;
26//!
27//! fn register(_con: libduckdb_sys::duckdb_connection) -> Result<(), ExtensionError> {
28//! // register_my_function(con)?;
29//! Ok(())
30//! }
31//!
32//! // Generates the `#[unsafe(no_mangle)] extern "C"` entry point. Pass the full symbol
33//! // name DuckDB looks up: `{extension_name}_init_c_api`.
34//! entry_point!(my_extension_init_c_api, |con| register(con));
35//! ```
36//!
37//! To write the entry point by hand instead, call
38//! [`init_extension`][entry_point::init_extension] directly; the
39//! [`entry_point`](mod@entry_point) module documentation shows how.
40//!
41//! ## Architecture
42//!
43//! The SDK is organized into focused modules:
44//!
45//! | Module | Purpose |
46//! |--------|---------|
47//! | [`abi`] | `DuckDB` C extension API layout verification (stable vs unstable region) |
48//! | [`callback`] | Panic-safe `extern "C"` callback wrapper macros for every callback kind |
49//! | [`chunk_writer`] | Auto-sizing chunk writer for table scan callbacks (auto `set_size` on drop) |
50//! | [`data_chunk`] | Ergonomic wrapper for `DuckDB` data chunks |
51//! | [`entry_point`](mod@entry_point) | Helper for the correct `{name}_init_c_api` C entry point |
52//! | [`connection`] | `Connection` facade + `Registrar` trait for version-agnostic registration |
53//! | [`aggregate`] | Builders for aggregate function registration |
54//! | [`scalar`] | Builder for scalar function registration |
55//! | [`cast`] | Builder for custom type cast functions |
56//! | [`table`] | Builders for table function registration (raw `TableFunctionBuilder` + closure-based `TypedTableFunctionBuilder<S>`) |
57//! | [`replacement_scan`] | `SELECT * FROM 'file.xyz'` replacement scan registration |
58//! | [`sql_macro`] | SQL macro registration (`CREATE MACRO`) — no FFI callbacks |
59//! | [`vector`] | Safe helpers for reading/writing `DuckDB` data vectors |
60//! | [`vector::complex`] | STRUCT / LIST / MAP / ARRAY vector access (child vectors, offsets) |
61//! | [`vector::struct_reader`] | Batched [`StructReader`][vector::StructReader] for STRUCT input vectors |
62//! | `vector::ops` | Whole-vector operations driven by a selection vector (`duckdb-1-5` feature) |
63//! | [`vector::struct_writer`] | Batched [`StructWriter`][vector::StructWriter] for STRUCT output vectors |
64//! | [`types`] | `DuckDB` type system wrappers (`TypeId`, `LogicalType`) |
65//! | [`datetime`] | `DATE`/`TIME`/`TIMESTAMP` calendar conversions, `HUGEINT`/`DECIMAL` helpers |
66//! | [`interval`] | `INTERVAL` → microseconds conversion with overflow checking |
67//! | [`error`] | `ExtensionError` for FFI error propagation |
68//! | [`config`] | RAII wrapper for `DuckDB` database configuration |
69//! | [`value`] | RAII wrapper for `DuckDB` values with typed extraction |
70//! | [`tls`] | Type-erased TLS configuration provider for HTTP-capable extensions |
71//! | [`warning`] | Structured security warning API (`ExtensionWarning`, `WarningCollector`) |
72//! | [`secrets`] | Secrets manager bridge trait (`SecretsManager`, `SecretEntry`) |
73//! | [`validate`] | Community extension compliance validators |
74//! | [`validate::description_yml`] | Parse and validate `description.yml` metadata |
75//! | [`scaffold`] | Project generator for new extensions (no C++ glue needed) |
76//! | [`testing`] | Test utilities: `AggregateTestHarness`, mock vectors (`MockVectorReader`, `MockVectorWriter`), `MockRegistrar`, and `InMemoryDb` (`bundled-test` feature) |
77//! | [`query`] | Running SQL from an extension (`QueryResult`, `PreparedStatement`, `OwnedConnection`) |
78//! | [`prelude`] | Convenience re-exports of the most commonly used items |
79//! | [`appender`] | Bulk row appender (`Appender`) |
80//! | [`table_description`] | Table metadata (column names, `DEFAULT`s) |
81//! | `arrow` | Arrow C Data Interface bridge, no `arrow` crate dependency (`duckdb-1-5-4` feature) |
82//! | `catalog` | Catalog entry lookup (`duckdb-1-5` feature) |
83//! | `client_context` | Client context access (`duckdb-1-5` feature) |
84//! | `config_option` | Extension-defined configuration options (`duckdb-1-5` feature) |
85//! | `copy_function` | Custom `COPY TO` handlers and `COPY … FROM` readers (`duckdb-1-5` feature) |
86//! | `error_data` | Structured error type + UTF-8 validation (`duckdb-1-5` feature) |
87//! | `expression` | Bound expression inspection / constant folding (`duckdb-1-5` feature) |
88//! | `file_system` | `DuckDB` virtual file system access (`duckdb-1-5` feature) |
89//! | `instance_cache` | Shared database instance cache (`duckdb-1-5` feature) |
90//! | `selection_vector` | Zero-copy row-index selection vectors (`duckdb-1-5` feature) |
91//!
92//! ## Safety
93//!
94//! All `unsafe` code within this SDK is intended to be sound, and each block is
95//! documented. It has been audited; [`AUDIT.md`](https://github.com/tomtom215/quack-rs/blob/main/AUDIT.md)
96//! records the passes and the defects they found. Extension authors
97//! must write `unsafe extern "C"` callback functions (required by `DuckDB`'s C API),
98//! but the SDK's helpers minimize the surface area of unsafe code within those
99//! callbacks.
100//!
101//! The documentation convention is:
102//!
103//! - Every `unsafe fn` states what the caller must guarantee under `# Safety`;
104//! a trait's `unsafe` methods state it once, on the trait.
105//! - Every `unsafe` block **inside a safe function** carries a `// SAFETY:`
106//! comment, because there the crate — not the caller — is asserting the
107//! invariant.
108//! - Every `unsafe` block **inside an `unsafe fn`** carries one too, even when
109//! it only forwards the function's own contract (`unsafe_op_in_unsafe_fn` is
110//! denied crate-wide, so the block is required syntax); the comment then says
111//! which clause of the contract it relies on.
112//!
113//! `clippy::undocumented_unsafe_blocks` is enabled for library code and CI runs
114//! clippy with `-D warnings`, so an unannotated block fails the build. Test
115//! code is exempt: its invariants are the test's own setup.
116//!
117//! ## Design Principles
118//!
119//! 1. **Thin wrapper**: every abstraction must pay for itself in reduced boilerplate
120//! or improved safety. When in doubt, prefer simplicity.
121//! 2. **No panics across FFI**: the entry point macros, the `*_callback!` macros in
122//! [`callback`], the closure-based builders and [`FfiState`][aggregate::state::FfiState]'s
123//! callbacks run user code under `catch_unwind`, so a panic becomes a SQL error. A raw
124//! `unsafe extern "C" fn` that you pass to a builder yourself is installed as written,
125//! with no guard; define it with the matching `*_callback!` macro or wrap its body in
126//! [`catch_ffi_panic`][callback::catch_ffi_panic]. Library code panics only where a
127//! `# Panics` section says so.
128//! 3. **Bounded version range**: `libduckdb-sys` uses `>=1.4.4, <1.20100`, and the crate
129//! supports `DuckDB` 1.4.4 through 2.0.x. `libduckdb-sys` numbers `DuckDB` 2.0.0 `1.20000.0`
130//! (published 2026-10-22) and `DuckDB` 2.1.0 will be `1.20100.0`, so the bound admits the 2.0
131//! bindings and stops before 2.1. The upper bound is deliberate: see `CONTRIBUTING.md`,
132//! "Releasing".
133//! CI tests against 1.4.4, 1.4.5, 1.5.0, 1.5.3, 1.5.4, 1.5.5, 1.5.6 and 2.0.0, and loads an
134//! extension into 1.4.4, 1.5.0, 1.5.5, 1.5.6, 2.0.0 and the latest `DuckDB` release.
135//! 4. **Testable business logic**: state structs have zero FFI dependencies.
136//!
137//! ## Pitfalls
138//!
139//! See [`LESSONS.md`](https://github.com/tomtom215/quack-rs/blob/main/LESSONS.md)
140//! for every known `DuckDB` Rust FFI pitfall, with symptoms, root causes, and fixes.
141//!
142//! One of them, Pitfall L1 (COMBINE must propagate config fields), produces
143//! silently wrong results rather than an error:
144//!
145//! `DuckDB`'s segment tree creates fresh target states with `state_init` —
146//! `T::default()` for an [`FfiState<T>`][aggregate::state::FfiState] — and then
147//! calls `combine` to merge source states into them. So your `combine` callback
148//! MUST copy ALL configuration fields from source to target, not just
149//! accumulated data: a field left at its `Default` value will be wrong at
150//! finalize time, producing silently incorrect results.
151//!
152//! See [`aggregate::callbacks::CombineFn`] for details.
153
154#![deny(unsafe_op_in_unsafe_fn)]
155#![warn(missing_docs)]
156// docs.rs documents the crate on a nightly with the `docsrs` cfg set, where
157// `doc_cfg` labels every `cfg`-gated item ("Available on crate feature
158// `duckdb-1-5` only") from its `#[cfg]` alone (current nightlies removed
159// `doc_auto_cfg` and do this under `doc_cfg`). A stable build never sets `docsrs`,
160// so this line is inert there. Locally:
161// `RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --features duckdb-1-5-4`.
162#![cfg_attr(docsrs, feature(doc_cfg))]
163#![cfg_attr(test, allow(clippy::undocumented_unsafe_blocks))]
164
165// quack-rs supports 64-bit targets and `wasm32-unknown-emscripten` (the
166// DuckDB-WASM target). The `duckdb_string_t` layout reserves 8 bytes for the
167// heap pointer regardless of pointer width — see `vector::string` for details.
168#[cfg(not(any(target_pointer_width = "64", target_arch = "wasm32")))]
169compile_error!("quack-rs supports 64-bit targets and wasm32-unknown-emscripten.");
170
171pub mod abi;
172pub mod aggregate;
173pub mod callback;
174pub mod cast;
175pub mod chunk_writer;
176pub mod config;
177pub mod connection;
178pub mod data_chunk;
179pub mod datetime;
180mod debug_repr;
181pub mod entry_point;
182pub mod error;
183mod extra_info;
184pub mod interval;
185pub mod prelude;
186pub mod query;
187pub mod replacement_scan;
188pub mod scaffold;
189pub mod scalar;
190pub mod secrets;
191pub mod sql_macro;
192pub mod table;
193pub mod testing;
194pub mod tls;
195pub mod types;
196pub mod validate;
197pub mod value;
198pub mod vector;
199pub mod warning;
200
201// Stable C API; a few methods need `duckdb-1-5`, the module does not.
202pub mod appender;
203
204// DuckDB 1.5.0+ modules — gated behind a `duckdb-1-5*` feature flag.
205#[cfg(feature = "duckdb-1-5-4")]
206pub mod arrow;
207#[cfg(feature = "duckdb-1-5")]
208pub mod catalog;
209#[cfg(feature = "duckdb-1-5")]
210pub mod client_context;
211#[cfg(feature = "duckdb-1-5")]
212pub mod config_option;
213#[cfg(feature = "duckdb-1-5")]
214pub mod copy_function;
215#[cfg(feature = "duckdb-1-5")]
216pub mod error_data;
217#[cfg(feature = "duckdb-1-5")]
218pub mod expression;
219#[cfg(feature = "duckdb-1-5")]
220pub mod file_system;
221#[cfg(feature = "duckdb-1-5")]
222pub mod instance_cache;
223#[cfg(feature = "duckdb-1-5")]
224pub mod selection_vector;
225pub mod table_description;
226
227/// The `DuckDB` C API version string required by [`duckdb_rs_extension_api_init`][libduckdb_sys::duckdb_rs_extension_api_init].
228///
229/// Every `DuckDB` release from v1.4.x through v1.5.5 declares C extension API
230/// version `v1.2.0` (`DUCKDB_EXTENSION_API_VERSION_{MAJOR,MINOR,PATCH}` in
231/// v1.5.5's `duckdb_extension.h` are 1, 2, 0). v1.5.6 declares `v1.5.6` and,
232/// like every release, loads any C API version up to its own, so `v1.2.0`
233/// works across the whole supported range. If you are targeting a different
234/// `DuckDB` release, read that value from its `duckdb_extension.h`.
235///
236/// # Pitfall P2: C API version ≠ `DuckDB` release version
237///
238/// The `-dv` flag passed to `append_extension_metadata.py` must be this value
239/// (`"v1.2.0"`), **not** the `DuckDB` release version (`"v1.4.4"` / `"v1.5.0"` /
240/// `"v1.5.3"`). With the wrong value the metadata script still succeeds, and
241/// `LOAD` then refuses the file: "The file was built for `DuckDB` C API version
242/// 'v1.5.5', but we can only load extensions built for `DuckDB` C API 'v1.2.0'
243/// and lower".
244///
245/// See [Pitfall P2](https://quack-rs.com/reference/pitfalls.html#p2-metadata-version-is-c-api-version-not-duckdb-version) for full details.
246pub const DUCKDB_API_VERSION: &str = "v1.2.0";
247
248/// The C extension API version to stamp an extension that uses the
249/// `duckdb-1-5` features with: `--abi-type C_STRUCT --duckdb-version v1.5.6`.
250///
251/// `DuckDB` v1.5.6 declared every slot of `duckdb_ext_api_v1` stable for an
252/// extension targeting C API v1.5.6, and v2.0.0 still declares v1.5.6 as its
253/// V1 C API version, only appending to that layout. So a binary stamped with
254/// this version is refused by `DuckDB` v1.2.0 – v1.5.5 (whose C API is
255/// [`DUCKDB_API_VERSION`]) and loads into v1.5.6 and v2.0.0.
256///
257/// It replaces `C_STRUCT_UNSTABLE` for that purpose: `DuckDB` 2.0 loads a
258/// `C_STRUCT_UNSTABLE` binary only through the C API v2 entry point
259/// (`<name>_init_c_api_v2`), which quack-rs does not generate.
260pub const DUCKDB_API_VERSION_1_5_6: &str = "v1.5.6";