# temp-postgres

The `temp-postgres` utility runs the [PostgreSQL](https://www.postgresql.org/) server off a temporary data directory.

The project's source code is hosted on <https://git.skreutz.com/temp-postgres.git/>.

## Usage

Create and serve a temporary database:

```sh
temp-postgres
```

Wrap the `psql` command for an interactive terminal:

```sh
temp-postgres -- psql
```

Run [SQLx integration tests](https://docs.rs/sqlx/latest/sqlx/attr.test.html) against a temporary database:

```sh
temp-postgres -- cargo test
```

**NOTE**: You may need to set `SQLX_OFFLINE=true` for the build process invoked by `cargo test`.

Or configure `temp-postgres` as a wrapper for [cargo-nextest](https://nexte.st/):

```toml
experimental = ["wrapper-scripts"]

[scripts.wrapper.temp-postgres]
command = 'temp-postgres'

[[profile.default.scripts]]
platform = { host = 'cfg(unix)' }
run-wrapper = 'temp-postgres'
```

Set up a symlink to enable static client configuration:

```sh
temp-postgres --symlink db
psql --host "$(realpath db)"
```

See the built-in help for details:

```sh
temp-postgres --help
```

## Dependencies

The `temp-postgres` utility has a run-time dependency on [PostgreSQL](https://www.postgresql.org/).

## Installation

You can install `temp-postgres` using Cargo:

```sh
# From crates.io
cargo install temp-postgres-command

# From the hosted Git repository
cargo --config net.git-fetch-with-cli=true install --git https://git.skreutz.com/temp-postgres.git/

# From your local source copy
cargo install --path .
```

Alternatively you can run or install `temp-postgres` using the experimental Nix flake:

```sh
# Default package
nix run git+https://git.skreutz.com/temp-postgres.git -- --help

# Fixed PostgreSQL major version
nix run git+https://git.skreutz.com/temp-postgres.git#temp-postgres_18 -- --help

# Unwrapped package (to be used with your own PostgreSQL installation)
nix run git+https://git.skreutz.com/temp-postgres.git#temp-postgres-unwrapped -- --help
```

**NOTE**: Try using Nix' `--refresh` flag, or adding `?ref=main&shallow=0` to the URL if you experience caching issues.

See the [NixOS example](./examples/nixos) for how to install `temp-postgres` on NixOS using Nix flakes.

## Limitations

For now, `temp-postgres` supports only UNIX-like systems.

`temp-postgres` may fail to clean up resources.
While `temp-postgres` performs a graceful shutdown on `SIGINT`, it terminates immediately when the graceful shutdown times out, and on `SIGTERM`.

## Maintenance

`temp-postgres` is semi-actively maintained.
I intend to fix bugs, and keep it working.

Releases adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html), see the [changelog](CHANGELOG.md).

The minimum supported Rust version (MSRV) is the latest stable release.

The Nix flake is experimental.

## Contribution

Contributions are welcome!
Please [contact](https://www.skreutz.com/contact/) me via email.

## License

This work is distributed under the terms of both, the [MIT License](LICENSE-MIT) and the [Apache License, Version 2.0](LICENSE-APACHE-2.0).

## History

The `temp-postgres` utility started as a POSIX shell script, first published in a [blog post](https://www.skreutz.com/posts/temporary-postgresql-server/) on 15 October 2020.
Six years later, in 2026, I rewrote the shell script in async Rust, partially because I wanted to improve error and signal handling, partially because why not ☺.
I chose *async* Rust because signal handling is fundamentally asynchronous.