prax_postgres/lib.rs
1// QueryError is intentionally large; see prax-query/src/lib.rs.
2#![allow(clippy::result_large_err)]
3
4//! # prax-postgres
5//!
6//! PostgreSQL driver for the Prax ORM with connection pooling and prepared statement caching.
7//!
8//! This crate provides:
9//! - Connection pool management using `deadpool-postgres`
10//! - Prepared statement caching for improved performance
11//! - Type-safe parameter binding
12//! - Row deserialization into Prax models
13//! - [`PgListener`]: `LISTEN` / `NOTIFY` on a dedicated, auto-reconnecting
14//! connection, with `PgConnection::notify` / `PgTransaction::notify` for
15//! sending (any role can `NOTIFY` any channel, so treat payloads as
16//! untrusted)
17//! - Pool recycling policy ([`PgRecycling`]: `Fast` (default), `Verified`,
18//! `Clean`), bounded by `PoolConfig::recycle_timeout`, plus jittered
19//! `max_lifetime` retirement. `Fast` keeps session state (`SET ROLE`,
20//! `search_path`, tenant GUCs) across checkouts; use `Clean` when that
21//! matters
22//! - Row locking (`FOR UPDATE` / `FOR SHARE`, `SKIP LOCKED`, `NOWAIT`,
23//! `OF`) through [`PgEngine`] and `prax_query`'s `.lock(RowLock)`; `OF`
24//! table names must be plain identifiers
25//! - Typed array binding for `FilterValue::Array` (use `= ANY($1)`) and raw
26//! `bytea` for `FilterValue::Bytes`
27//!
28//! ## Example
29//!
30//! ```rust,ignore
31//! use prax_postgres::PgPool;
32//!
33//! #[tokio::main]
34//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
35//! // Create a connection pool
36//! let pool = PgPool::builder()
37//! .url("postgresql://user:pass@localhost/db")
38//! .max_connections(10)
39//! .build()
40//! .await?;
41//!
42//! // Get a connection
43//! let conn = pool.get().await?;
44//!
45//! Ok(())
46//! }
47//! ```
48
49pub(crate) mod capabilities;
50pub mod config;
51pub mod connection;
52pub(crate) mod connector;
53pub mod deserialize;
54pub mod engine;
55pub mod error;
56pub mod listener;
57pub(crate) mod notify;
58pub mod pool;
59pub mod row;
60pub mod row_ref;
61pub mod statement;
62#[cfg(feature = "tls")]
63pub mod tls;
64pub mod types;
65
66pub use config::{PgConfig, PgConfigBuilder};
67pub use connection::PgConnection;
68pub use engine::PgEngine;
69pub use error::{PgError, PgResult};
70pub use listener::{
71 PgListener, PgListenerBuilder, PgListenerEvent, PgListenerOptions, PgNotification,
72};
73pub use pool::{PgPool, PgPoolBuilder, PgRecycling, PoolConfig, PoolStatus};
74pub use row::PgRow;
75pub use statement::PreparedStatementCache;
76
77/// Prelude for convenient imports.
78pub mod prelude {
79 pub use crate::config::{PgConfig, PgConfigBuilder};
80 pub use crate::connection::PgConnection;
81 pub use crate::engine::PgEngine;
82 pub use crate::error::{PgError, PgResult};
83 pub use crate::pool::{PgPool, PgPoolBuilder};
84 pub use crate::row::PgRow;
85}