# Better DuckDB

> A safe, embedded-first Rust client for DuckDB, with an optional Diesel 2.3 ORM backend, UDF/derive macros, and a Tauri v2 plugin.

- [better-duck](https://better-duck.mintlify.app/index.md): A safe, embedded-first Rust client for DuckDB — with an optional Diesel 2.3 ORM backend, UDF/derive macros, and a Tauri v2 plugin.
- [Introduction](https://better-duck.mintlify.app/guide/introduction.md): A safe, embedded-first Rust client for DuckDB with an optional Diesel ORM backend.
- [Installation](https://better-duck.mintlify.app/guide/installation.md): Add the better-duck crates, pin the exact beta version, and understand bundled-DuckDB build times and toolchain requirements.
- [Quickstart](https://better-duck.mintlify.app/guide/quickstart.md): Open a connection, create a table, insert, and read rows end-to-end.
- [Choosing an API](https://better-duck.mintlify.app/guide/choosing-an-api.md): When to use better-duck-core, the Diesel backend, or the Tauri plugin, plus a feature-flag decision tree.
- [Architecture](https://better-duck.mintlify.app/guide/architecture.md): The better-duck crate family, the FFI safety model that keeps unsafe out of your code, and how DuckDB is compiled and bundled into your binary.
- [Feature Flags](https://better-duck.mintlify.app/guide/feature-flags.md): Every Cargo feature of better-duck-core — grouped, with what each enables, its implications, and recommended presets.
- [DuckDB Essentials](https://better-duck.mintlify.app/guide/duckdb-essentials.md): An orientation to DuckDB through the better-duck driver — the dialect, the type system, extensions, and engine behaviors — with pointers to the focused deep-dive pages.
- [SQL Dialect & Statements](https://better-duck.mintlify.app/guide/sql-dialect.md): DuckDB's PostgreSQL-like dialect through the driver: batch vs single statements, what each statement kind returns, positional and named parameters, transactions, and replacement scans.
- [Type System](https://better-duck.mintlify.app/guide/type-system.md): How DuckDB's full type system maps to driver values: every DuckValue variant and its Rust type, NULL and validity, the lossless TypeInfo descriptor, and which features change the read type.
- [Extensions](https://better-duck.mintlify.app/guide/extensions.md): Two ways DuckDB extensions reach a connection — bundled at build time (json, parquet, icu) with no runtime install, or loaded at runtime (spatial and more) through the extension API.
- [Error Handling](https://better-duck.mintlify.app/guide/error-handling.md): How failures surface in better-duck: the Error and Result types, DuckDB's typed EngineError classification, appender poisoning, async/pool errors, and the panic = abort caveat for UDFs.
- [Benchmarks](https://better-duck.mintlify.app/guide/benchmarks.md): How better-duck-core compares to the community duckdb crate across primitive types, composite types, and common operations — with methodology and the test system.
- [Versioning & Compatibility](https://better-duck.mintlify.app/guide/versioning-and-compatibility.md): The beta release policy, MSRV 1.96, supported platforms, the vendored DuckDB version, and how to pin and upgrade the better-duck crates.
- [Opening Connections](https://better-duck.mintlify.app/core/opening-connections.md): Open in-memory and on-disk DuckDB connections, clone them, close them, and interrupt a running query — the Connection type's lifecycle.
- [Configuration](https://better-duck.mintlify.app/core/configuration.md): Tune DuckDB at open time with the Config builder: access mode, memory and threads, extension autoloading, and the generic with() escape hatch.
- [Sharing a Database](https://better-duck.mintlify.app/core/sharing-a-database.md): Use Database to share one DuckDB database — in-memory or on-disk — across many independent connections.
- [Executing SQL](https://better-duck.mintlify.app/core/executing-sql.md): Run statements with execute_batch, execute, and insert; read affected-row counts; split multi-statement batches; and inspect the catalog without a query.
- [Iterating Results](https://better-duck.mintlify.app/core/iterating-results.md): Drive a DuckResult as a lazy row iterator, read DuckRow values, peek and count rows, replay with rewind, and inspect result and column metadata.
- [Result Sets](https://better-duck.mintlify.app/core/result-sets.md): Materialize a DuckResult into an owned, Send + Sync + Clone ResultSet that holds no FFI handles — and deserialize whole results into Vec<T>.
- [Values Overview](https://better-duck.mintlify.app/core/values-overview.md): The DuckValue enum: every DuckDB column value, the conversion traits around it (FromDuckValue, AppendAble, DuckDialect, DuckLogicalType), and how NULL maps to Option.
- [Scalar Types](https://better-duck.mintlify.app/core/scalar-types.md): Booleans, every integer width (including 128-bit), floats, text, blobs, DECIMAL, UUID, BIT, and BIGNUM — the non-temporal, non-composite DuckValue variants and their Rust types.
- [Temporal Types](https://better-duck.mintlify.app/core/temporal-types.md): Dates, times, timestamps at four precisions, timezone-aware values, intervals, and lossless ±infinity sentinels — with and without the chrono feature.
- [Composite Types](https://better-duck.mintlify.app/core/composite-types.md): LIST, ARRAY, STRUCT, MAP, UNION, and ENUM — the nested DuckValue variants, their metadata-preserving wrappers, and the LogicalType / TypeInfo descriptors.
- [Positional Parameters](https://better-duck.mintlify.app/core/positional-parameters.md): Bind $1 / $2 / ? parameters with execute_with and the AppendAble trait, mix heterogeneous types, bind explicit NULL, and use the params! and insert convenience forms.
- [Named Parameters](https://better-duck.mintlify.app/core/named-parameters.md): Bind $name parameters with execute_with_named — order-independent binding, and how an unknown name is reported.
- [Prepared Statements](https://better-duck.mintlify.app/core/prepared-statements.md): Reuse compiled statements with Statement and CachedStatement, step queries incrementally with pending execution, run multi-statement batches, and read statement metadata.
- [Transactions](https://better-duck.mintlify.app/core/transactions.md): Run transactions with the closure helper, the RAII guard, or raw verbs — plus the transaction! macro, and why there are no savepoints.
- [Appender — Bulk Insert](https://better-duck.mintlify.app/core/appender.md): Load rows fast with DuckDB's Appender: creating one, appending rows, flushing with save/finish, drop behavior, and struct-per-row ergonomics.
- [Appender — Advanced](https://better-duck.mintlify.app/core/appender-advanced.md): Projected columns and default rows, catalog and query appenders, raw and built chunk ingestion, column introspection, and the appender's poisoning semantics.
- [Columnar Overview](https://better-duck.mintlify.app/core/columnar-overview.md): The columnar feature: zero-copy column reads via fetch_chunk, where DataChunkHandle and VectorRef/VectorMut fit, and the strict row-vs-chunk rule.
- [Data Chunks](https://better-duck.mintlify.app/core/data-chunks.md): DataChunkHandle: allocate a columnar batch, read and write its column vectors, set and reset the row count, and respect DuckDB's build-time vector capacity.
- [Vectors](https://better-duck.mintlify.app/core/vectors.md): VectorRef and VectorMut: read a column zero-copy with as_slice, read/write single values, handle validity masks and NULLs, and the FixedWidth marker.
- [Async](https://better-duck.mintlify.app/core/async.md): The Tokio async facade — AsyncConnection and AsyncDatabase — dispatching to spawn_blocking, materializing results, stepping queries incrementally, and cancel-on-drop.
- [Pooling](https://better-duck.mintlify.app/core/pooling.md): An r2d2 connection pool over a shared Database — managers, the Pool type aliases, checkout, and the async AsyncPool wrapper.
- [Arrow Interop](https://better-duck.mintlify.app/core/arrow.md): Export query results via the Arrow C Data Interface with zero added dependencies, and register a caller-owned Arrow stream as a queryable DuckDB view.
- [Polars Interop](https://better-duck.mintlify.app/core/polars.md): Collect DuckDB query results into a Polars DataFrame and materialize a DataFrame back into DuckDB, bridged via the Arrow C Data Interface.
- [Errors](https://better-duck.mintlify.app/core/errors.md): The Error and Result types, every variant, DuckDB's typed EngineError classification, and the conversion-error and owned-value helpers.
- [Extensions](https://better-duck.mintlify.app/core/extensions.md): Load DuckDB extensions at runtime (INSTALL / LOAD / check), bundle json / parquet / icu at build time, and build loadable extensions with the loadable-extension feature.
- [UDF Overview](https://better-duck.mintlify.app/macros/udf-overview.md): Register Rust functions as DuckDB scalar, table, aggregate, and cast functions with the #[duckdb_*] macros — shared semantics, NULL/Result handling, and the panic caveat.
- [Scalar Functions](https://better-duck.mintlify.app/macros/scalar-functions.md): #[duckdb_scalar]: row-wise functions for SELECT / WHERE, with options for naming, volatility, and shared state — plus the VScalar trait behind it.
- [Table Functions](https://better-duck.mintlify.app/macros/table-functions.md): #[duckdb_table_function]: iterator-returning functions for a FROM clause, with column naming, named parameters, projection pushdown, and shared extra info.
- [Aggregate Functions](https://better-duck.mintlify.app/macros/aggregate-functions.md): #[duckdb_aggregate]: fold rows into one value with init / update / combine / finalize, type inference, special_handling, and the VAggregate trait and function sets.
- [Cast Functions](https://better-duck.mintlify.app/macros/cast-functions.md): #[duckdb_cast]: a custom CAST / TRY_CAST between two types, with implicit-cost control and the VCast trait behind it.
- [Entrypoint — Loadable Extensions](https://better-duck.mintlify.app/macros/entrypoint.md): #[duckdb_entrypoint]: generate the C-ABI entrypoint for a .duckdb_extension built with the loadable-extension feature.
- [Derives Overview](https://better-duck.mintlify.app/macros/derives-overview.md): The derive feature's four derive macros and two helper macros for mapping Rust types to DuckDB rows, STRUCTs, and ENUMs — plus the shared rename_all casings.
- [FromRow & ToRow](https://better-duck.mintlify.app/macros/fromrow-torow.md): Read a query row into a struct with #[derive(FromRow)] and column-name mapping; write a struct as an appender row or positional parameters with #[derive(ToRow)].
- [DuckEnum Derive](https://better-duck.mintlify.app/macros/duckenum.md): #[derive(DuckEnum)]: map a Rust unit enum to a DuckDB ENUM by label, with per-variant and whole-enum renaming, plus optional Diesel emission.
- [DuckStruct Derive](https://better-duck.mintlify.app/macros/duckstruct.md): #[derive(DuckStruct)]: map a Rust named-field struct to a DuckDB STRUCT value, with field renaming and optional Diesel emission.
- [Helper Macros](https://better-duck.mintlify.app/macros/helper-macros.md): The always-available transaction! and params! declarative macros, and the UDF body macros duck_bail!, duck_state!, duck_projection!, and duck_extra_info!.
- [Diesel Backend Overview](https://better-duck.mintlify.app/diesel/overview.md): What the better-duck-diesel Diesel 2.3 backend for DuckDB is, how it builds on better-duck-core, its feature flags, and when to reach for the ORM vs the raw core driver.
- [Installation & Setup](https://better-duck.mintlify.app/diesel/installation-and-setup.md): Add the better-duck-diesel crate, open a DuckDbConnection with establish or from_core, reach the underlying core connection, run DDL batches, and understand the backend error type.
- [Schema & Migrations](https://better-duck.mintlify.app/diesel/schema.md): Declare a DuckDB schema with Diesel's table! macro, map DuckDB-specific column types, derive Queryable/Selectable/Insertable/AsChangeset structs, and run diesel migrations against a DuckDbConnection.
- [Select & Load](https://better-duck.mintlify.app/diesel/select.md): Query DuckDB through Diesel: load rows into tuples and structs, select specific columns, filter, order, limit, count, and fetch single rows with first/get_result.
- [Insert](https://better-duck.mintlify.app/diesel/insert.md): Insert rows into DuckDB through Diesel: single-row and batch inserts with value tuples or Insertable structs, affected-row counts, and pointers to RETURNING and ON CONFLICT upserts.
- [Update](https://better-duck.mintlify.app/diesel/update.md): Update DuckDB rows through Diesel: diesel::update with a filtered target, setting single or multiple columns, updating from an AsChangeset struct, and returning changed values.
- [Delete](https://better-duck.mintlify.app/diesel/delete.md): Delete DuckDB rows through Diesel: diesel::delete with a filtered target, deleting all rows, the unscoped-delete gotcha, and returning deleted values.
- [RETURNING](https://better-duck.mintlify.app/diesel/returning.md): Read columns back from INSERT, UPDATE, and DELETE on DuckDB through Diesel's RETURNING clause, using get_result and get_results.
- [Upsert (ON CONFLICT)](https://better-duck.mintlify.app/diesel/upsert.md): Make inserts idempotent or merge on key collisions in DuckDB through Diesel: on_conflict with do_nothing and do_update, and pulling proposed values from the excluded row.
- [Transactions](https://better-duck.mintlify.app/diesel/transactions.md): Run atomic work on DuckDB through Diesel's transaction closure, roll back explicitly, use test transactions for isolation, and understand why DuckDB has no savepoints for nested transactions.
- [DuckDB SQL DSL Overview](https://better-duck.mintlify.app/diesel/dsl-overview.md): The better_duck_diesel::dsl::* prelude: how DuckDB-only operators, scalar functions, and aggregates are exposed as typed Diesel expressions with no raw SQL, how to call them, and the map of the DSL pages.
- [DSL Operators](https://better-duck.mintlify.app/diesel/operators.md): DuckDB-only comparison and text-matching operators as Diesel expression methods: ILIKE, NOT ILIKE, SIMILAR TO, GLOB, POSIX regex (~, !~), prefix (^@), and null-safe IS [NOT] DISTINCT FROM.
- [String Functions](https://better-duck.mintlify.app/diesel/string-functions.md): DuckDB string scalar functions as typed Diesel DSL: case, trim, reverse, repeat, replace, search and position, padding, split/concat, similarity metrics, regex functions, printf-style formatting, hashing, and BLOB/base64/hex encoding.
- [Numeric & Utility Functions](https://better-duck.mintlify.app/diesel/numeric-functions.md): DuckDB numeric, trigonometric, and bitwise scalar functions as typed Diesel DSL, plus conditional null-handling (nullif/ifnull), UUID generators, and utility functions (version, typeof).
- [Date & Time Functions](https://better-duck.mintlify.app/diesel/datetime-functions.md): DuckDB date/time scalar functions as typed Diesel DSL: extract parts (year/month/.../epoch), truncate and format timestamps, build dates/times/timestamps, and compute calendar parts and differences.
- [JSON Functions](https://better-duck.mintlify.app/diesel/json-functions.md): DuckDB JSON scalar functions as typed Diesel DSL — json_valid, json_type, json_extract_string, json_array_length — with the json feature flag that bundles the extension offline.
- [List & Map Functions](https://better-duck.mintlify.app/diesel/list-and-map-functions.md): DuckDB LIST and MAP scalar functions as typed Diesel DSL: array_length/len, list_reverse/sort/distinct/concat, array_to_string, and cardinality/map_keys/map_values.
- [Aggregates](https://better-duck.mintlify.app/diesel/aggregates.md): DuckDB aggregate functions as typed Diesel DSL — general (string_agg, array_agg, arg_max/min, product, any_value, bool_and/or), statistical, approximate quantiles, bitwise, and JSON aggregates — beyond Diesel's built-in count/sum/avg/min/max.
- [Calling Your Own UDFs](https://better-duck.mintlify.app/diesel/calling-udfs.md): Register #[duckdb_*] user-defined functions on the underlying core connection, declare a matching define_sql_function!, and call them as typed Diesel DSL — plus the per-connection registration caveat for pools.
- [Spatial (ST_* Functions)](https://better-duck.mintlify.app/diesel/spatial.md): DuckDB spatial GEOMETRY functions as typed Diesel DSL under feature = spatial: ensure_loaded to install/load the extension, and ST_Point/ST_GeomFromText/ST_AsText/ST_Distance/ST_Area over WKB-encoded geometry.
- [Type Mapping](https://better-duck.mintlify.app/diesel/type-mapping.md): The Rust-to-DuckDB column type mapping for Diesel: standard SQL types, the DuckDB-specific sql_types::Duck* newtypes, QueryableByName round-trips for them, and the values::* binding newtypes for u64/i128/UUID and friends.
- [Pooling](https://better-duck.mintlify.app/diesel/pooling.md): Connection pooling for better-duck-diesel with r2d2 under feature = r2d2: SharedDuckDbConnectionManager for a consistent in-memory database, Diesel's generic ConnectionManager, R2D2Connection health checks, and per-connection setup via on_connect.
- [Data Derives (ORM Emission)](https://better-duck.mintlify.app/diesel/data-derives.md): The derive feature re-exports better-duck-core's DuckEnum/DuckStruct/FromRow/ToRow with Diesel FromSql/ToSql emission on, so your Rust enums and structs bind and load through a DuckDbConnection at the DuckEnum/DuckStruct SQL types via sql_query + QueryableByName.
- [Overview](https://better-duck.mintlify.app/tauri/overview.md): A Tauri v2 plugin that exposes embedded DuckDB (better-duck) to the webview as a local analytics engine, with a fixed command set, pluggable backends, and a two-layer security model.
- [Installation](https://better-duck.mintlify.app/tauri/installation.md): Add the Rust plugin crate with the right backend feature, pin the pre-release version, and install the @better-duck/tauri JS package.
- [Registration](https://better-duck.mintlify.app/tauri/registration.md): Register better-duck-tauri on tauri::Builder — the simple init() path and the fully configured per-backend Builder with migrations, policy, hooks, and checkpoint strategies.
- [Frontend Overview](https://better-duck.mintlify.app/tauri/frontend-overview.md): The @better-duck/tauri Database class: load/close lifecycle, connection strings, the full method map, error handling, and the DuckDB-to-JSON value mapping.
- [Query & Execute](https://better-duck.mintlify.app/tauri/query-and-execute.md): Run read queries with select and write/DDL statements with execute, bind positional parameters, read the affected-row count, and understand how statement policy applies.
- [Schema Introspection](https://better-duck.mintlify.app/tauri/schema-introspection.md): List the tables in the main schema, inspect a table's columns, and read a query's EXPLAIN plan — three read-only commands backed by information_schema.
- [Import & Export](https://better-duck.mintlify.app/tauri/import-export.md): Create tables from Parquet/CSV/JSON files and copy query results back out, with the DataFormat enum, the typed helper methods, and the path-scope constraints that gate file access.
- [Append Rows](https://better-duck.mintlify.app/tauri/append-rows.md): Bulk-insert JSON object rows into a table in a single statement — column inference from the first row, NULL fill for missing keys, identifier validation, and how it compares to execute and import.
- [Streaming & Interrupt](https://better-duck.mintlify.app/tauri/streaming.md): Stream a large query's rows to the webview in chunks over a Tauri Channel, resolve to the total row count, and cancel the in-flight stream from another call with interrupt.
- [Arrow IPC](https://better-duck.mintlify.app/tauri/arrow.md): Return a read query's result as Arrow IPC stream bytes with query_arrow, gated behind the plugin's arrow Cargo feature, and decode it in the webview with apache-arrow.
- [Maintenance](https://better-duck.mintlify.app/tauri/maintenance.md): Operational commands beyond queries: load DuckDB extensions, flush the WAL with checkpoint, and undo the last migration with revert — plus the policy and permissions that gate each.
- [Backends](https://better-duck.mintlify.app/tauri/backends.md): Choose between backend-core and backend-diesel: the DuckBackend trait both implement, how connections and migrations differ, on_connect hook timing, and when to pick each.
- [Checkpointing](https://better-duck.mintlify.app/tauri/checkpointing.md): DuckDB folds WAL writes into the main file on checkpoint. Configure composable strategies on the builder — threshold, after-writes, interval, on-exit, force, and platform defaults — or checkpoint explicitly from the webview.
- [Migrations](https://better-duck.mintlify.app/tauri/migrations.md): Startup schema migrations per connection string: define them for the core or Diesel backend, understand ascending-version ordering, revert, and the crash-safe backup-in-place protocol.
- [Security Overview](https://better-duck.mintlify.app/tauri/security-overview.md): The webview is untrusted and DuckDB SQL can reach the filesystem and network. Understand the threat model, the two independent gates the plugin enforces, and the critical select caveat.
- [Capabilities & Permissions](https://better-duck.mintlify.app/tauri/capabilities-and-permissions.md): Grant the webview access to plugin commands through Tauri capability files: the default and raw-sql sets, every autogenerated allow-/deny- identifier, scoped permission objects, and how the list is generated.
- [Scope & Policy](https://better-duck.mintlify.app/tauri/scope-and-policy.md): The value-level security gate: per-capability scope Entry objects (connection/path, deny-first, traversal-safe) and the mandatory init-time Rust Policy — read-only, allow-lists, the risky-statement filter, and network gating.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.