Skip to main content

quack_rs/
prelude.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//! Convenience re-exports for the most commonly used `quack-rs` items.
7//!
8//! This prelude covers the types and functions needed in the `src/lib.rs`
9//! of a typical `DuckDB` Rust extension. Import it with:
10//!
11//! ```rust,no_run
12//! use quack_rs::prelude::*;
13//!
14//! fn register(con: libduckdb_sys::duckdb_connection) -> Result<(), ExtensionError> {
15//!     let _ = con;
16//!     Ok(())
17//! }
18//!
19//! // The entry-point macros come with the glob import.
20//! entry_point!(my_extension_init_c_api, |con| register(con));
21//! ```
22//!
23//! # What is included
24//!
25//! | Item | From |
26//! |------|------|
27//! | [`init_extension`] | `entry_point` module |
28//! | [`init_extension_v2`] | `entry_point` module |
29//! | `entry_point!` | `entry_point` module (macro) |
30//! | `entry_point_v2!` | `entry_point` module (macro) |
31//! | [`AbiPolicy`] | `abi` module |
32//! | [`Connection`] | `connection` module |
33//! | [`Registrar`] | `connection` module |
34//! | [`CastFn`] | `cast` module |
35//! | [`CastFunctionBuilder`] | `cast` module |
36//! | [`CastFunctionInfo`] | `cast` module |
37//! | [`CastMode`] | `cast` module |
38//! | [`AggregateFunctionBuilder`] | `aggregate` module |
39//! | [`AggregateFunctionInfo`] | `aggregate` module |
40//! | [`AggregateFunctionSetBuilder`] | `aggregate` module |
41//! | [`AggregateOverloadBuilder`] | `aggregate` module |
42//! | [`AggregateState`] | `aggregate` module |
43//! | [`FfiState`] | `aggregate` module |
44//! | [`ScalarFunctionBuilder`] | `scalar` module |
45//! | [`ScalarFunctionInfo`] | `scalar` module |
46//! | [`ScalarFunctionSetBuilder`] | `scalar` module |
47//! | [`ScalarOverloadBuilder`] | `scalar` module |
48//! | [`TypedScalarFunctionBuilder`] | `scalar` module |
49//! | [`TableFunctionBuilder`] | `table` module |
50//! | [`TypedTableFunctionBuilder`] | `table` module |
51//! | [`BindInfo`] | `table` module |
52//! | [`InitInfo`] | `table` module |
53//! | [`FunctionInfo`] | `table` module |
54//! | [`FfiBindData`] | `table` module |
55//! | [`FfiInitData`] | `table` module |
56//! | [`FfiLocalInitData`] | `table` module |
57//! | [`ReplacementScanBuilder`] | `replacement_scan` module |
58//! | [`ReplacementScanInfo`] | `replacement_scan` module |
59//! | [`SqlMacro`] | `sql_macro` module |
60//! | [`ChunkWriter`] | `chunk_writer` module |
61//! | [`DataChunk`] | `data_chunk` module |
62//! | [`Value`] | `value` module |
63//! | [`VectorReader`] | `vector` module |
64//! | [`VectorWriter`] | `vector` module |
65//! | [`ListBuilder`] | `vector` module |
66//! | [`ValidityBitmap`] | `vector::validity` module |
67//! | [`ArrayVector`] | `vector::complex` module |
68//! | [`StructReader`] | `vector::struct_reader` module |
69//! | [`StructWriter`] | `vector::struct_writer` module |
70//! | [`StructVector`] | `vector::complex` module |
71//! | [`ListVector`] | `vector::complex` module |
72//! | [`MapVector`] | `vector::complex` module |
73//! | [`TypeId`] | `types` module |
74//! | [`LogicalType`] | `types` module |
75//! | [`NullHandling`] | `types` module |
76//! | [`DuckInterval`] | `interval` module |
77//! | [`interval_to_micros`] | `interval` module |
78//! | [`Date`] / [`Time`] / [`TimeTz`] / [`Timestamp`] | `datetime` module |
79//! | [`OwnedConnection`] / [`OwnedDataChunk`] / [`PreparedStatement`] / [`QueryResult`] | `query` module |
80//! | [`ExtensionError`] | `error` module |
81//! | [`ExtResult`] | `error` module |
82//! | [`SecretEntry`] | `secrets` module |
83//! | [`SecretsManager`] | `secrets` module |
84//! | [`TlsConfigProvider`] | `tls` module |
85//! | [`TlsVersion`] | `tls` module |
86//! | [`audit_tls_provider`] | `tls` module |
87//! | [`ExtensionWarning`] | `warning` module |
88//! | [`WarningCollector`] | `warning` module |
89//! | [`WarningSeverity`] | `warning` module |
90//! | [`DUCKDB_API_VERSION`] | crate root |
91//! | [`DUCKDB_API_VERSION_1_5_6`] | crate root |
92//! | [`Appender`] | `appender` module |
93//!
94//! ## `DuckDB` 1.5.0+ items (require the `duckdb-1-5` feature)
95//!
96//! | Item | From |
97//! |------|------|
98//! | `ScalarBindInfo` / `ScalarInitInfo` | `scalar` module |
99//! | `ScalarBindData` / `ScalarLocalState` | `scalar` module |
100//! | `CopyFunctionBuilder` and its callback types: `CopyBindFn` / `CopyBindInfo`, `CopyGlobalInitFn` / `CopyGlobalInitInfo`, `CopySinkFn` / `CopySinkInfo`, `CopyFinalizeFn` / `CopyFinalizeInfo` | `copy_function` module |
101//! | `ErrorData` / `DuckDbErrorType` | `error_data` module |
102//! | `Expression` | `expression` module |
103//! | `FileSystem` / `FileHandle` / `FileOpenOptions` / `FileFlag` | `file_system` module |
104//! | `SelectionVector` | `selection_vector` module |
105//! | `InstanceCache` | `instance_cache` module |
106//!
107//! # What is NOT included
108//!
109//! The following items are intentionally excluded from the prelude because they
110//! are used less frequently and benefit from explicit import paths:
111//!
112//! - [`crate::config::DbConfig`] — RAII wrapper for opening secondary `DuckDB` databases;
113//!   import explicitly via `use quack_rs::config::DbConfig` when needed
114//! - `validate::*` — validation utilities (use explicitly to make intent clear)
115//! - `scaffold::*` — project generation (use explicitly)
116//! - `testing::*` — test harness (typically imported only in `#[cfg(test)]`)
117//! - `interval::read_interval_at` — low-level; use [`VectorReader::read_interval`] instead
118//!
119
120//! # Example
121//!
122//! ```rust,no_run
123//! use quack_rs::prelude::*;
124//!
125//! // Your state struct
126//! #[derive(Default)]
127//! struct MyState { count: i64 }
128//! impl AggregateState for MyState {}
129//!
130//! // Registration (called from your entry point)
131//! fn register(con: libduckdb_sys::duckdb_connection) -> ExtResult<()> {
132//!     let _ = AggregateFunctionBuilder::try_new("my_count")?
133//!         .param(TypeId::BigInt)
134//!         .returns(TypeId::BigInt)
135//!         .ffi_state::<MyState>()
136//!         // ... callbacks ...
137//!         ;
138//!     Ok(())
139//! }
140//! ```
141
142// Entry point
143pub use crate::entry_point::{init_extension, init_extension_v2};
144
145/// C extension API layout policy for the entry point.
146pub use crate::abi::AbiPolicy;
147
148// Connection facade and Registrar trait
149pub use crate::connection::{Connection, Registrar};
150
151// Cast functions
152pub use crate::cast::{CastFn, CastFunctionBuilder, CastFunctionInfo, CastMode};
153
154// Aggregate functions
155pub use crate::aggregate::{
156    AggregateFunctionBuilder, AggregateFunctionInfo, AggregateFunctionSetBuilder,
157    AggregateOverloadBuilder, AggregateState, FfiState,
158};
159
160// Scalar functions
161#[cfg(feature = "duckdb-1-5")]
162pub use crate::scalar::{ScalarBindData, ScalarBindInfo, ScalarInitInfo, ScalarLocalState};
163pub use crate::scalar::{
164    ScalarFunctionBuilder, ScalarFunctionInfo, ScalarFunctionSetBuilder, ScalarOverloadBuilder,
165    TypedScalarFunctionBuilder,
166};
167
168// Copy functions
169#[cfg(feature = "duckdb-1-5")]
170pub use crate::copy_function::{
171    CopyBindFn, CopyBindInfo, CopyFinalizeFn, CopyFinalizeInfo, CopyFunctionBuilder,
172    CopyGlobalInitFn, CopyGlobalInitInfo, CopySinkFn, CopySinkInfo,
173};
174
175// The appender itself is in the stable C API and needs no feature (only a
176// few of its methods do), so it is exported unconditionally.
177pub use crate::appender::Appender;
178
179// DuckDB 1.5.0+ API surfaces (require the `duckdb-1-5` feature).
180#[cfg(feature = "duckdb-1-5")]
181pub use crate::error_data::{DuckDbErrorType, ErrorData};
182#[cfg(feature = "duckdb-1-5")]
183pub use crate::expression::Expression;
184#[cfg(feature = "duckdb-1-5")]
185pub use crate::file_system::{FileFlag, FileHandle, FileOpenOptions, FileSystem};
186#[cfg(feature = "duckdb-1-5")]
187pub use crate::instance_cache::InstanceCache;
188#[cfg(feature = "duckdb-1-5")]
189pub use crate::selection_vector::SelectionVector;
190
191// Table functions
192pub use crate::table::{
193    BindInfo, FfiBindData, FfiInitData, FfiLocalInitData, FunctionInfo, InitInfo,
194    TableFunctionBuilder, TypedTableFunctionBuilder,
195};
196
197// Replacement scans
198pub use crate::replacement_scan::{ReplacementScanBuilder, ReplacementScanInfo};
199
200// SQL macros
201pub use crate::sql_macro::SqlMacro;
202
203// Chunk writer
204pub use crate::chunk_writer::ChunkWriter;
205
206// Data chunks
207pub use crate::data_chunk::DataChunk;
208
209// Value
210pub use crate::value::Value;
211
212// Vector I/O
213pub use crate::vector::complex::{ArrayVector, ListVector, MapVector, StructVector};
214pub use crate::vector::{
215    ListBuilder, StructReader, StructWriter, ValidityBitmap, VectorReader, VectorWriter,
216};
217
218// Types
219pub use crate::types::{LogicalType, NullHandling, TypeId};
220
221// Interval
222pub use crate::interval::{interval_to_micros, DuckInterval};
223
224/// Calendar conversions for `DATE` / `TIME` / `TIMESTAMP`.
225pub use crate::datetime::{Date, Time, TimeTz, Timestamp};
226
227/// Running SQL from inside an extension.
228pub use crate::query::{OwnedConnection, OwnedDataChunk, PreparedStatement, QueryResult};
229
230// Error
231pub use crate::error::{ExtResult, ExtensionError};
232
233// Secrets manager
234pub use crate::secrets::{SecretEntry, SecretsManager};
235
236// TLS config provider
237pub use crate::tls::{audit_tls_provider, TlsConfigProvider, TlsVersion};
238
239// Warnings
240pub use crate::warning::{ExtensionWarning, WarningCollector, WarningSeverity};
241
242// API version constant
243pub use crate::{DUCKDB_API_VERSION, DUCKDB_API_VERSION_1_5_6};
244
245// `#[macro_export]` places the entry-point macros at the crate root only; a glob
246// import of this module does not reach them unless they are re-exported here.
247// (`crate::entry_point` also names the module; this re-exports both, which is
248// harmless: the macro and module namespaces are separate.)
249pub use crate::{entry_point, entry_point_v2};
250
251#[cfg(test)]
252mod tests {
253    /// Every name this module re-exports appears in one of the tables in the
254    /// module documentation, so the tables cannot drift from the code again.
255    #[test]
256    fn the_module_docs_list_every_re_export() {
257        let source = include_str!("prelude.rs");
258        let (docs, code) = source
259            .split_once("// Entry point")
260            .expect("the re-exports start at the entry-point section");
261        let code = code.split("#[cfg(test)]").next().unwrap_or(code);
262        let mut missing = Vec::new();
263        for item in code.split("pub use ").skip(1) {
264            let item = item.split(';').next().unwrap_or("");
265            let names = item.rsplit("::").next().unwrap_or(item);
266            for name in names
267                .trim_matches(|c: char| c == '{' || c == '}' || c.is_whitespace())
268                .split(',')
269                .map(str::trim)
270                .filter(|n| !n.is_empty())
271            {
272                let listed = docs.contains(&format!("[`{name}`]"))
273                    || docs.contains(&format!("`{name}`"))
274                    || docs.contains(&format!("`{name}!`"));
275                if !listed {
276                    missing.push(name.to_owned());
277                }
278            }
279        }
280        assert!(
281            missing.is_empty(),
282            "not listed in the prelude docs: {missing:?}"
283        );
284    }
285}