pg_wired/lib.rs
1//! Minimal async PostgreSQL wire protocol v3 client.
2//!
3//! `pg-wired` is the lowest-level crate in the resolute workspace. It speaks
4//! the PostgreSQL frontend/backend protocol directly over a [`tokio`] socket,
5//! with no SQL parsing, no type system, and no high-level query API. If you
6//! want a typed, derive-driven query layer, use the [`resolute`] crate instead;
7//! this crate is the foundation it builds on.
8//!
9//! # Protocol features
10//!
11//! - **Startup, authentication.** Cleartext, MD5, and SCRAM-SHA-256 (including
12//! channel binding when the connection is TLS-wrapped).
13//! - **Extended query protocol.** `Parse` / `Bind` / `Describe` / `Execute` /
14//! `Sync` with statement caching at the connection layer.
15//! - **Pipelining.** Multiple round trips fused into a single write via
16//! [`PgPipeline`], with FIFO response matching.
17//! - **Streaming.** Backpressure-aware row streaming for large result sets.
18//! - **`COPY` in / out.** Both CSV and binary formats.
19//! - **`LISTEN` / `NOTIFY`.** Bounded notification channel with a dropped-
20//! notification counter.
21//! - **Cancellation.** Out-of-band cancel via [`CancelToken`] using the
22//! server-issued backend key.
23//! - **TLS.** Optional, gated behind the `tls` feature; uses `rustls`.
24//!
25//! # Where to start
26//!
27//! - [`AsyncConn`] is the main entry point: a single PostgreSQL connection
28//! wrapped around the protocol state machine.
29//! - [`AsyncPool`] is a thin pool over [`AsyncConn`].
30//! - [`PgPipeline`] batches multiple operations into one round trip.
31//! - [`tls::TlsMode`] selects between plaintext and TLS connections.
32//!
33//! # Stability
34//!
35//! The public surface is intended to be stable, but `pg-wired` is primarily
36//! consumed by `resolute` and its sibling crates. Most application code should
37//! prefer the typed [`resolute`] surface.
38//!
39//! [`resolute`]: https://docs.rs/resolute
40//! [`tokio`]: https://docs.rs/tokio
41
42#![deny(missing_docs)]
43
44pub mod async_conn;
45pub mod async_pool;
46pub mod cancel;
47#[cfg(feature = "tls")]
48mod cert_hash;
49pub mod connection;
50pub mod error;
51pub mod pipeline;
52#[doc(hidden)]
53pub mod protocol;
54mod scram;
55pub mod tls;
56
57pub use async_conn::{AsyncConn, PipelineResponse, ResponseCollector};
58pub use async_pool::AsyncPool;
59pub use cancel::CancelToken;
60pub use connection::WireConn;
61pub use error::PgWireError;
62pub use pipeline::PgPipeline;
63pub use protocol::types::{FormatCode, Oid, PgError};
64#[cfg(feature = "tls")]
65pub use tls::TlsConfig;
66pub use tls::TlsMode;