chopin_pg/lib.rs
1//! # chopin-pg
2//!
3//! A zero-copy, high-performance PostgreSQL driver designed for the
4//! Chopin thread-per-core, Shared-Nothing architecture.
5//!
6//! ## Features
7//! - **Thread-per-core**: Each worker owns its own PG connections.
8//! - **Non-blocking I/O**: Socket is set to non-blocking after connect; all
9//! reads/writes go through poll-based primitives with configurable timeouts.
10//! - **Zero-copy**: Row data is sliced directly from the read buffer.
11//! - **SCRAM-SHA-256**: Full authentication support.
12//! - **Extended Query Protocol**: Parse/Bind/Execute with implicit caching.
13//! - **Transaction support**: Safe closure-based API with auto-rollback.
14//! - **COPY protocol**: Both COPY IN (writer) and COPY OUT (reader).
15//! - **LISTEN/NOTIFY**: Notification buffering during query processing.
16//! - **Rich types**: UUID, Date, Time, Timestamp, Interval, Numeric, INET, Arrays.
17//! - **Binary INET/CIDR**: Proper binary encoding/decoding for network types.
18//! - **Type-safe queries**: `ToSql`/`FromSql` traits for ergonomic parameter passing.
19//! - **Connection pool**: Worker-local pool with RAII `ConnectionGuard`, FIFO idle
20//! queue, `try_get()` / `get()` with timeout, and automatic return on drop.
21//! - **Error classification**: Transient vs permanent errors for retry logic.
22//!
23//! ## Quick Start
24//! ```ignore
25//! use chopin_pg::{PgConfig, PgConnection};
26//!
27//! let config = PgConfig::new("localhost", 5432, "user", "pass", "mydb");
28//! let mut conn = PgConnection::connect(&config)?;
29//!
30//! // Simple query
31//! let rows = conn.query("SELECT $1::int4 + $2::int4", &[&1i32, &2i32])?;
32//! let sum: i32 = rows[0].get_typed(0)?;
33//!
34//! // Transaction with closure
35//! conn.transaction(|tx| {
36//! tx.execute("INSERT INTO users (name) VALUES ($1)", &[&"Alice"])?;
37//! Ok(())
38//! })?;
39//! ```
40//!
41//! ## Pool Usage
42//! ```ignore
43//! use chopin_pg::{PgConfig, PgPool, PgPoolConfig};
44//!
45//! let config = PgConfig::new("localhost", 5432, "user", "pass", "mydb");
46//! let pool_cfg = PgPoolConfig::new().max_size(25).checkout_timeout(Duration::from_secs(3));
47//! let mut pool = PgPool::connect_with_config(config, pool_cfg)?;
48//!
49//! // Get a connection — returned to pool when guard drops
50//! let mut guard = pool.get()?;
51//! let rows = guard.query("SELECT 1", &[])?;
52//! // guard drops → connection returned to idle queue
53//! ```
54
55pub mod auth;
56pub mod codec;
57pub mod connection;
58pub mod error;
59pub mod pool;
60pub mod protocol;
61pub mod row;
62pub mod statement;
63#[cfg(feature = "tls")]
64pub mod tls;
65pub mod types;
66
67pub use connection::{CopyReader, CopyWriter, Notification, PgConfig, PgConnection, Transaction};
68pub use error::{ErrorClass, PgError, PgResult};
69pub use pool::{ConnectionGuard, PgPool, PgPoolConfig, PoolStats};
70pub use row::Row;
71pub use statement::Statement;
72#[cfg(feature = "tls")]
73pub use tls::SslMode;
74pub use types::{FromSql, PgValue, ToParam, ToSql, TypeRegistry, encode_inet_binary};