From 46a3d2ba70decd1931e13c190bfa49217e57718d Mon Sep 17 00:00:00 2001
From: Stefan Kreutz <mail@skreutz.com>
Date: Thu, 30 Apr 2026 10:10:46 +0200
Subject: Rewrite in async Rust

---
 README.md | 89 ++++++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 51 insertions(+), 38 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index e41fe7e..b7a7872 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,6 @@
 # temp-postgres
 
 The `temp-postgres` utility runs the [PostgreSQL](https://www.postgresql.org/) server off a temporary data directory.
-See the [original blog post](https://www.skreutz.com/posts/temporary-postgresql-server/) for an introduction.
 
 The project's source code is hosted on <https://git.skreutz.com/temp-postgres.git/>.
 
@@ -13,7 +12,7 @@ Create and serve a temporary database:
 temp-postgres
 ```
 
-Wrap the `psql` command to connect to the temporary database once the server is ready:
+Wrap the `psql` command for an interactive terminal:
 
 ```sh
 temp-postgres -- psql
@@ -43,67 +42,81 @@ run-wrapper = 'temp-postgres'
 Set up a symlink to enable static client configuration:
 
 ```sh
-temp-postgres --symlink ./db
-psql --host "$(realpath ./db)"
+temp-postgres --symlink db
+psql --host "$(realpath db)"
 ```
 
-Specify a database name, and PostgreSQL user name:
+See the built-in help for details:
 
 ```sh
-temp-postgres --dbname myproject --username alex
+temp-postgres --help
 ```
 
-
-See the manual page for details.
-
 ## Dependencies
 
-The `temp-postgres` utility depends on `sh(1)` and `postgres(1)`.
+The `temp-postgres` utility has a run-time dependency on [PostgreSQL](https://www.postgresql.org/).
+
+## Installation
 
-On OpenBSD you can install the dependencies using `pkg_add(1)`:
+You can install `temp-postgres` using Cargo:
 
 ```sh
-doas pkg_add postgresql-server postgresql-client
-```
+# From crates.io
+cargo install temp-postgres-command
 
-On FreeBSD you can install the dependencies using `pkg-install(8)`:
+# From the hosted Git repository
+cargo --config net.git-fetch-with-cli=true install --git https://git.skreutz.com/temp-postgres.git/
 
-```sh
-sudo pkg install postgresql16-server postgresql16-client
+# From your local source copy
+cargo install --path .
 ```
 
-On Void Linux you can install the dependencies using `xbps-install(1)`:
+Alternatively you can run or install `temp-postgres` using the experimental Nix flake:
 
 ```sh
-sudo xbps-install -S dash postgresql postgresql-client
-```
+# Default package
+nix run git+https://git.skreutz.com/temp-postgres.git -- --help
 
-On Arch Linux you can install the dependencies using `pacman(8)`:
+# Fixed PostgreSQL major version
+nix run git+https://git.skreutz.com/temp-postgres.git#temp-postgres_18 -- --help
 
-```sh
-sudo pacman -Syu postgresql
+# Unwrapped package (to be used with your own PostgreSQL installation)
+nix run git+https://git.skreutz.com/temp-postgres.git#temp-postgres-unwrapped -- --help
 ```
 
-## Installation
+**NOTE**: Try using Nix' `--refresh` flag, or adding `?ref=main&shallow=0` to the URL if you experience caching issues.
 
-```sh
-./configure
-make
-sudo make install
-```
+See the [NixOS example](./examples/nixos) for how to install `temp-postgres` on NixOS using Nix flakes.
 
-Alternatively you can run or install the experimental Nix flake:
+## Limitations
 
-```sh
-nix run git+https://git.skreutz.com/temp-postgres.git -- --help
-```
+For now, `temp-postgres` supports only UNIX-like systems.
 
-You can optionally select the PostgreSQL version provided by Nixpkgs:
+`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`.
 
-```sh
-nix run git+https://git.skreutz.com/temp-postgres.git#temp-postgres_18 -- --help
-```
+## Maintenance
 
-Try using Nix' `--refresh` flag, or adding `?ref=main&shallow=0` to the URL if you experience caching issues.
+`temp-postgres` is semi-actively maintained.
+I intend to fix bugs, and keep it working.
 
-See the [NixOS example](./examples/nixos) for how to install `temp-postgres` on NixOS using Nix flakes.
+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.
-- 
cgit v1.3