`postgres_secrets` - Load Postgres credentials securely
-------------------------------------------------------

`postgres_secrets` allows you to load credentials from a file in standard ways that
are compatible with the Postgres tooling ecosystem.

Currently, only the [`pgpass`](https://www.postgresql.org/docs/current/libpq-pgpass.html)
format is supported. Support for [`connection service files`](https://www.postgresql.org/docs/current/libpq-pgservice.html)
may be implemented in the future.

# Use cases

- **Command line tools.** `postgres_secrets` uses the same [pgpass format](https://www.postgresql.org/docs/current/libpq-pgpass.html)
    as `psql`. This gives command-line users a seamless experience between `psql` and tools
    written with `postgres_secrets`.
- **In container environments.** `postgres_secrets` makes it easy to pass credentials
    to a container using tools like Docker secrets.

# Key features

## Simple, ergonomic API

- The API uses well-known Rust design patterns, and integrates with the `postgres` crate
- This is all it takes to connect to a database:

```rust
let pgpass = postgres_secrets::PgPass::load()?; // Looks for the pgpass file in it's default location
let creds = pgpass.query()
    .hostname("example.com")?
    .find()?
    .unwrap();
let config: postgres::Config = creds.into();
let db = config.connect(tls)?;
```

## Rock solid and well tested

- The test suite includes [property tests](https://www.postgresql.org/docs/current/libpq-pgpass.html),
    meaning the library has been tested against many randomly-generated pathological inputs.
- While it's possible the library has bugs, you are unlikely to encounter them in normal usage.

## Small, easily auditable codebase

- For those concerned about supply-chain attacks, `postgres_secrets` can be audited in an afternoon.
- All of it's dependencies are canonical, well-known crates.
- The license is public domain, making it easy to fork or vendor.

# Caveats

- This does not behave precisely the same as the parser in `libpq`.
    While unlikely, this could lead to bugs or confusing behavior
    in some circumstances.
- `libpq` is more permissive than this implementation. `libpq` will
    tolerate invalid escape sequences and extra columns. Because
    this behavior could cause bugs and confusing behavior, this
    implementation returns errors in these circumstances.
- `libpq` has special behavior when `localhost` is supplied as the
    hostname. This library does not support this.
- `libpq` performs a permissions check on the pgpass file, and will
    not open a file which is too permissive. This library does not
    perform this check.

# Documentation

[The documentation](https://docs.rs/postgres_secrets) is hosted on `docs.rs`.