audb_runtime/
lib.rs

1//! AuDB Runtime Library
2//!
3//! Minimal runtime support for code generated by `audb-codegen`.
4//!
5//! This crate provides the essential types and traits needed by generated code
6//! to execute queries against a database. The runtime is intentionally minimal,
7//! with most work (parsing, validation, optimization) happening at compile time.
8//!
9//! ## Core Components
10//!
11//! - **`Database`** - Connection wrapper with async query execution methods
12//! - **`QueryError`** - Comprehensive error types for runtime failures
13//! - **`QueryResult`, `Row`, `Value`** - Type system for query results
14//! - **`QueryExecutor`** - Trait for type-safe async query execution
15//! - **`FromRow`** - Trait for deserializing rows into Rust types
16//!
17//! ## Design Philosophy
18//!
19//! The runtime follows a compile-time-first approach:
20//! - Queries are parsed and validated at build time
21//! - Type checking happens during compilation
22//! - Optimization is done by the code generator
23//! - Runtime only handles execution and result deserialization
24//!
25//! This results in:
26//! - **Zero runtime parsing overhead**
27//! - **Compile-time type safety**
28//! - **Minimal binary size contribution** (~1MB)
29//! - **Excellent performance** (no query interpretation)
30//!
31//! ## Example Usage
32//!
33//! ```no_run
34//! use audb_runtime::{Database, QueryError};
35//!
36//! async fn example() -> Result<(), QueryError> {
37//!     // Open database connection
38//!     let db = Database::open("./data").await?;
39//!
40//!     // Execute queries (typically via generated code)
41//!     let result = db.execute_hyperql("SELECT * FROM users").await?;
42//!
43//!     // Clean shutdown
44//!     db.close().await?;
45//!     Ok(())
46//! }
47//! ```
48//!
49//! ## Integration with Generated Code
50//!
51//! The runtime is designed to work seamlessly with code generated by `audb-codegen`.
52//! Generated query functions use the `Database` methods and `FromRow` trait to
53//! provide type-safe, compile-time-checked query execution.
54//!
55//! ## Module Organization
56//!
57//! - `database` - Database connection and query execution
58//! - `error` - Error types and utilities
59//! - `types` - Result types (QueryResult, Row, Value)
60//! - `executor` - Traits for type-safe execution and deserialization
61
62mod database;
63mod error;
64mod executor;
65mod types;
66
67pub use database::Database;
68pub use error::{QueryError, Result};
69pub use executor::{FromRow, FromValue, QueryExecutor};
70pub use types::{QueryResult, Row, Value};