postgres_sync

A purely synchronous PostgreSQL client library that provides the same interface as the postgres crate, but uses standard library networking instead of tokio. This results in a smaller dependency graph and more predictable blocking behavior.

The original postgres crate was synchronous until version 0.15.2. After that, it became a thin wrapper around the async tokio-postgres crate. This project revives the purely synchronous approach for applications where async is not a requirement.

When to use postgres_sync

✅ Use this library when:

• Your application doesn't deal with too many concurent connections
• You want to minimize your dependency tree and avoid tokio
• You prefer predictable, straightforward blocking I/O

❌ Don't use this library when:

• Your application faces the C10k problem
• Your project already depends on tokio
• You require the full, battle-tested API of the official postgres crate

Usage

Replace your postgres dependency in Cargo.toml:

# before
[dependencies]
postgres = { version = "...", features = ["with-serde_json-1"] }

# after
[dependencies]
postgres = { package = "postgres_sync", version = "0.1", features = ["with-serde_json-1"] }

That's it! It's designed as a drop-in replacement.

Feature status

postgres_sync implements a subset of the postgres crate's API. The goal is for any implemented feature to behave identically to the original.

Implemented

• Config::parse() with connection strings of the form "postgresql://user:password@host:port/db"
• Client::connect(), Config::connect() with NoTls
• Client::transaction()
• {Client, Transaction}::query_raw()
• {Client, Transaction}::query_one()
• {Client, Transaction}::query()
• {Client, Transaction}::batch_execute()
• {Client, Transaction}::execute()
• with-serde_json-1 feature flag
• with-chrono-0_4 feature flag

Limitations and divergences

postgres_sync is not a 1:1 clone of the postgres API. It aims for compatibility where implemented, but provides a partial and evolving implementation. This means you may encounter differences in the following ways:

• API surface: Entire types, traits, or modules from the original crate may be missing.
• Incomplete features: An implemented method might not support the full range of parameters as its postgres counterpart. For example, Client::connect() supports connection strings but does not yet handle TLS configuration options.
• Simplified error handling: This crate uses its own error types. They are not type-compatible with the errors from the postgres crate.

Project layout

• postgres_sync - The main library crate
• verify_* - Binary test crates that run the same test suite against a live PostgreSQL instance.
  • verify_orig links against the original postgres crate.
  • verify_sync links against this crate (postgres_sync).
  • The source code is shared via a symlink (verify_sync/src -> verify_orig/src) to guarantee the tests are identical.

License

This project is licensed under the same terms as the postgres crate:

• MIT License
• Apache License 2.0

Choose whichever license works best for your use case.

Acknowledgments

postgres_sync is inspired by and heavily dependent on the excellent rust-postgres collection of crates by Steven Fackler. It specifically uses the postgres-protocol and postgres-types crates for handling low-level details.