pgwire/lib.rs
1//! # pgwire
2//!
3//! `pgwire` provides the PostgreSQL wire protocol as a library for
4//! implementing PostgreSQL-compatible servers and clients.
5//! [`rust-postgres`](https://crates.io/crates/postgres) will be sufficient
6//! for most Postgres client use-cases, so this library focuses on
7//! server development.
8//!
9//! ## About Postgres Wire Protocol
10//!
11//! Postgres Wire Protocol is a relatively general-purpose Layer-7
12//! protocol. There are 3 parts of the protocol:
13//!
14//! - Startup: client-server handshake and authentication.
15//! - Simple Query: The legacy query protocol of postgresql. Query are provided
16//! as string, and server is allowed to stream data in response.
17//! - Extended Query: A new sub-protocol for query which has ability to cache
18//! the query on server-side and reuse it with new parameters. The response part
19//! is identical to Simple Query.
20//!
21//! Also note that Postgres Wire Protocol has no semantics about SQL, so
22//! literally you can use any query language, data formats or even natural
23//! language to interact with the backend.
24//!
25//! The response are always encoded as data row format. And there is a field
26//! description as header of the data to describe its name, type and format.
27//!
28//! ## Components
29//!
30//! There are two main components in postgresql wire protocol: **startup** and
31//! **query**. In **query**, there are two subprotocols: the legacy text-based
32//! **simple query** and binary **extended query**.
33//!
34//! ## Layered API
35//!
36//! pgwire provides three layers of abstractions that allows you to compose your
37//! application from any level of abstraction. They are:
38//!
39//! - Protocol layer: Just use message definitions and codecs in `messages`
40//! module.
41//! - Message handler layer: Implement `on_` prefixed methods in traits:
42//! - `StartupHandler`
43//! - `SimpleQueryHandler`
44//! - `ExtendedQueryHandler`
45//! - High-level API layer
46//! - `AuthSource` and various authentication mechanisms
47//! - `do_` prefixed methods in handler traits
48//! - `QueryParser`/`PortalStore` for extended query support
49//!
50//! ## Features
51//!
52//! - `server-api-aws-lc-rs` is enabled by default, it includes all three layers
53//! of our API and uses `aws-lc-rs` as crypto backend.
54//! - `server-api-ring` is almost same to `server-api-aws-lc-rs` except for it's
55//! using `ring` as crypto backend.
56//! - `scram` for the SASL/SCRAM authenticator.
57//! - Turn off default features if you just use our Protocol layer.
58//!
59//! ## Examples
60//!
61//! [Examples](https://github.com/sunng87/pgwire) are provided to demo API
62//! usages.
63//!
64
65#[macro_use]
66extern crate derive_new;
67
68/// handler layer and high-level API layer.
69#[cfg(any(feature = "server-api", feature = "client-api"))]
70pub mod api;
71/// error types.
72pub mod error;
73/// the protocol layer.
74pub mod messages;
75/// server entry-point for tokio based application.
76#[cfg(any(feature = "server-api", feature = "client-api"))]
77pub mod tokio;
78/// types and encoding related helper
79#[cfg(any(feature = "server-api", feature = "client-api"))]
80pub mod types;