tokio-postgres-rustls

tokio-postgres-rustls is a focused integration crate that lets tokio-postgres (the standard async PostgreSQL client for Rust/Tokio) establish TLS-encrypted connections using the pure-Rust rustls TLS stack instead of requiring OpenSSL or another native TLS library. It implements tokio-postgres’s MakeTlsConnect/TlsConnect traits on top of tokio-rustls, so a rustls ClientConfig can be handed directly to tokio_postgres::connect() via the crate’s MakeRustlsConnect type.

The crate ships with no default features, requiring consumers to explicitly opt into a rustls crypto provider (ring or aws-lc-rs) matching whatever they use elsewhere in their dependency tree, plus optional convenience constructors for common root certificate stores via the webpki-roots or native-certs (backed by rustls-native-certs) features. This keeps the crate lean and avoids silently pulling in a crypto backend the consuming application isn’t already using.

What You Get

• A MakeRustlsConnect type implementing tokio-postgres’s TLS connector traits, ready to pass directly to tokio_postgres::connect()
• No-default-features design that requires an explicit ring or aws-lc-rs crypto provider choice, avoiding silent crypto backend duplication
• Optional webpki-roots and native-certs features for convenience root-store constructors without hand-wiring certificate loading
• PostgreSQL channel binding support (via sha2/x509-cert) for SCRAM authentication that’s bound to the TLS channel, hardening against certain MITM attack classes
• An integration test suite (tests/integration.rs) run against a real PostgreSQL instance via bollard (Docker) in CI

Common Use Cases

• Connecting an async Rust backend service to a managed PostgreSQL instance (RDS, Cloud SQL, etc.) requiring TLS, without an OpenSSL system dependency
• Building fully statically-linked Rust binaries (e.g. for minimal container images) that need TLS-encrypted database connections
• Standardizing a codebase’s TLS stack on rustls across HTTP and database connections instead of mixing OpenSSL and rustls
• Enabling PostgreSQL channel-binding-aware SCRAM authentication for stronger protection against TLS-terminating proxies

Under The Hood

Architecture The entire integration lives in a single src/lib.rs (416 lines) implementing tokio-postgres’s MakeTlsConnect and TlsConnect traits by wrapping tokio_rustls::TlsConnector, translating between tokio-postgres’s connection lifecycle hooks and rustls’s async TLS handshake, including computing the tls-server-end-point channel binding data (via sha2 hashing of the peer certificate, parsed with x509-cert) that PostgreSQL’s SCRAM-SHA-256-PLUS mechanism requires. Tech Stack Rust 2024 edition. Built on rustls 0.23 and tokio-rustls 0.26 (both with default-features = false, requiring explicit crypto provider selection), tokio-postgres 0.7’s runtime feature, and sha2/x509-cert for channel-binding certificate hashing. Dev-dependencies include bollard (Docker API client) to spin up a real PostgreSQL container for integration testing. Code Quality A 162-line integration test suite exercises real TLS-encrypted connections against a live PostgreSQL instance provisioned via Docker/bollard, rather than mocking the TLS handshake — a stronger correctness signal for TLS integration code, where subtle handshake or certificate-verification bugs are easy to introduce and hard to catch with unit tests alone. The crate’s narrow, single-purpose scope (416 lines total) keeps the surface area small enough that this test coverage is proportionally thorough. API Design The crate’s job is to make one thing simple: turning a rustls::ClientConfig into something tokio_postgres::connect() accepts, via MakeRustlsConnect::new(config). The explicit, no-default-features approach to crypto providers and root stores adds a small upfront decision (which provider/root-store feature to enable) but avoids the common pitfall of two crates in the same dependency tree silently pulling in conflicting rustls crypto backends.