prax-duckdb 0.11.1

DuckDB database driver for Prax ORM - optimized for analytical workloads
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

// QueryError is intentionally large; see prax-query/src/lib.rs.
#![allow(clippy::result_large_err)]

//! DuckDB database driver for Prax ORM.
//!
//! This crate provides DuckDB support for the Prax ORM, optimized for analytical
//! workloads (OLAP). DuckDB is an in-process analytical database similar to SQLite
//! but designed for fast analytical queries.
//!
//! # Features
//!
//! - **In-process analytics**: No server required, runs embedded
//! - **Columnar storage**: Optimized for analytical queries
//! - **Parquet support**: Native reading/writing of Parquet files
//! - **JSON support**: Query JSON data directly
//! - **SQL compatibility**: Full SQL support with extensions
//! - **Async support**: Async operations via Tokio task spawning
//!
//! # When to Use DuckDB
//!
//! DuckDB excels at:
//! - Analytical queries (aggregations, joins, window functions)
//! - Data transformation and ETL
//! - Querying Parquet, CSV, and JSON files
//! - Embedded analytics in applications
//!
//! For OLTP workloads (many small transactions), consider PostgreSQL or SQLite instead.
//!
//! # Example
//!
//! ```rust,ignore
//! use prax_duckdb::{DuckDbPool, DuckDbConfig};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // In-memory database
//!     let config = DuckDbConfig::in_memory();
//!     let pool = DuckDbPool::new(config).await?;
//!
//!     // Or file-based
//!     let config = DuckDbConfig::from_path("./analytics.duckdb")?;
//!     let pool = DuckDbPool::new(config).await?;
//!
//!     // Query Parquet files directly
//!     let results = pool.get().await?
//!         .query("SELECT * FROM 'data/*.parquet' WHERE year = 2024", &[])
//!         .await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! # Analytical Features
//!
//! ```rust,ignore
//! // Window functions
//! let sql = r#"
//!     SELECT
//!         date,
//!         revenue,
//!         SUM(revenue) OVER (
//!             PARTITION BY region
//!             ORDER BY date
//!             ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
//!         ) as cumulative_revenue
//!     FROM sales
//! "#;
//!
//! // COPY to Parquet
//! engine.raw_sql_execute(
//!     "COPY (SELECT * FROM analytics) TO 'output.parquet' (FORMAT PARQUET)",
//!     &[]
//! ).await?;
//! ```

pub(crate) mod capabilities;
pub mod config;
pub mod connection;
pub mod engine;
pub mod error;
pub mod pool;
pub mod row;
pub mod row_ref;
pub mod types;

pub use config::{AccessMode, DuckDbConfig, DuckDbConfigBuilder};
pub use connection::DuckDbConnection;
pub use engine::{DuckDbEngine, DuckDbQueryResult};
pub use error::{DuckDbError, DuckDbResult};
pub use pool::{DuckDbPool, DuckDbPoolBuilder, PoolConfig};
pub use row::FromDuckDbRow;

/// Prelude for convenient imports.
pub mod prelude {
    pub use crate::config::{AccessMode, DuckDbConfig, DuckDbConfigBuilder};
    pub use crate::connection::DuckDbConnection;
    pub use crate::engine::{DuckDbEngine, DuckDbQueryResult};
    pub use crate::error::{DuckDbError, DuckDbResult};
    pub use crate::pool::{DuckDbPool, DuckDbPoolBuilder};
    pub use crate::row::FromDuckDbRow;
}