From e9bd990587227b29dc6e41e3d43a5cf2ec9dcd5b Mon Sep 17 00:00:00 2001
From: Stefan Kreutz <mail@skreutz.com>
Date: Thu, 16 Apr 2026 01:07:28 +0200
Subject: Add wrapped command option

---
 CHANGELOG.md     |  5 +++--
 README.md        | 25 +++++++++++++++++++++----
 temp-postgres.1  | 47 +++++++++++++++++++++++++++++++++++++++++------
 temp-postgres.sh | 31 +++++++++++++++++++++----------
 4 files changed, 86 insertions(+), 22 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2cb3874..e06782a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,10 +11,11 @@ The format is based on [Keep A Changelog][] and this project adheres to [Semanti
 
 ### Added
 
+* Added option to execute a given command when PostgreSQL server is ready
+* Added minimal `--help` option
+* Added changelog
 * Added experimental Nix flake
 * Added direnv configuration
-* Added changelog
-* Added minimal `--help` option
 
 ### Changed
 
diff --git a/README.md b/README.md
index 3663571..1d65c60 100644
--- a/README.md
+++ b/README.md
@@ -10,13 +10,30 @@ This project's original source code is hosted [here][home].
 
 ## Usage
 
-Create a temporary database "test" with superuser "alex":
+Create and serve a temporary database:
 
-    $ temp-postgres --dbname test --username alex
+    $ temp-postgres
 
-Connect to the "test" database:
+Wrap the `psql` command to connect to the temporary database once the server is ready:
 
-    $ psql --host localhost --dbname test --username alex
+    $ temp-postgres -- psql
+
+Run [SQLx integration tests](https://docs.rs/sqlx/latest/sqlx/attr.test.html) against a temporary database:
+
+    $ temp-postgres -- 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'
+```
 
 See the manual page for details.
 
diff --git a/temp-postgres.1 b/temp-postgres.1
index 1adb8ed..324a2f1 100644
--- a/temp-postgres.1
+++ b/temp-postgres.1
@@ -20,6 +20,8 @@
 .Sh SYNOPSIS
 .Nm temp-postgres
 .Op options
+.Op Fl -
+.Op Ar command
 .Sh DESCRIPTION
 The
 .Nm
@@ -30,23 +32,56 @@ The options are as follows:
 .It Fl h , -help
 Print help.
 .It Fl d , -dbname Ar dbname
-The PostgreSQL database name.
+Database name.
 Defaults to the name of the effective user.
 .It Fl u , -username Ar username
-The PostgreSQL user name.
+PostgreSQL user name.
 Defaults to the name of the effective user.
 .El
+.Pp
+.Nm
+can optionally execute a given
+.Ar command
+once the PostgreSQL server is ready.
+If so,
+.Nm
+will pass the following environment variables to the
+.Ar command :
+.Bl -tag -width Ds
+.It Ev PGHOST
+Absolute path to the directory in which the UNIX domain socket file is stored.
+.It Ev PGDATABASE
+Database name.
+.It Ev PGUSER
+PostgreSQL user name.
+.It Ev DATABASE_URI
+Connection URI.
+.It Ev DATABASE_URL
+Connection URI.
+.El
+.Pp
+See also the
+.Lk https://www.postgresql.org/docs/current/libpq-envars.html "environment variables used by libpg" ,
+and the
+.Lk https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS "connection URI scheme understood by libpg" .
 .Sh EXIT STATUS
 .Ex -std temp-postgres
 .Sh EXAMPLES
-Create a temporary database "test" with superuser "alex":
+Create and serve a temporary database:
 .Bd -literal -offset indent
-$ temp-postgres --dbname test --username alex
+$ temp-postgres
 .Ed
 .Pp
-Connect to the "test" database:
+Specify a database name, and PostgreSQL user name:
+.Bd -literal -offset indent
+$ temp-postgres --dbname myproject --username alex
+.Ed
+.Pp
+Wrap the
+.Xr psql 1
+command to connect to the temporary database once the server is ready:
 .Bd -literal -offset indent
-$ psql --host=localhost test alex
+$ temp-postgres -- psql
 .Ed
 .Sh SEE ALSO
 .Xr postgres 1 ,
diff --git a/temp-postgres.sh b/temp-postgres.sh
index 6064b66..8504257 100755
--- a/temp-postgres.sh
+++ b/temp-postgres.sh
@@ -20,8 +20,7 @@ set -o nounset
 trap 'quit' INT
 quit() {
   code="${1:-0}"
-  trap '' INT TERM
-  kill -TERM 0
+  [ -z "$postgres_pid" ] || kill -TERM "$postgres_pid"
   wait
   rm -rf "${tmpdir-}" || {
     ( >&2 printf "temp-postgres: failed to remove temporary directory: %s\\n" "${tmpdir}" )
@@ -36,7 +35,7 @@ username="$( id -un )"
 while [ $# -gt 0 ] ; do
   case "$1" in
     -h|--help)
-      echo "Usage: temp-postgres [-h|--help] [-d|--dbname <dbname>] [-u|--username <username>]"
+      echo "Usage: temp-postgres [-h|--help] [-d|--dbname <dbname>] [-u|--username <username>] [--] [<command>]"
       exit
       ;;
     -d|--dbname)
@@ -60,10 +59,6 @@ while [ $# -gt 0 ] ; do
       ;;
   esac
 done
-if [ $# -gt 0 ] ; then
-  ( >&2 echo "too many arguments" )
-  exit 2
-fi
 
 # Create a temporary directory
 tmpdir="$( mktemp -d )" || {
@@ -79,6 +74,7 @@ initdb --pgdata="${tmpdir}" --username="${username}" || {
 
 # Serve the directory
 ( postgres -k "${tmpdir}" -D "${tmpdir}" </dev/null ) &
+postgres_pid=$!
 
 # Test the connection
 sleep 1
@@ -96,8 +92,23 @@ createdb --host="${tmpdir}" --username="${username}" --no-password "${dbname}" |
 printf '
 Connect with the following command:
 
-\tpsql --host=localhost "%s" "%s"
+\tpsql --host "%s" --dbname "%s" --username "%s"
+
+' "$tmpdir" "$dbname" "$username"
 
-' "${dbname}" "${username}"
+if [ $# -eq 0 ] ; then
+  wait
+else
+  export PGHOST="$tmpdir"
+  export PGDATABASE="$dbname"
+  export PGUSER="$username"
+  export DATABASE_URI="postgresql:${dbname}?host=${tmpdir}&user=${username}"
+  export DATABASE_URL="$DATABASE_URI"
 
-wait
+  "$@" || {
+    code=$?
+    ( >&2 echo "temp-postgres: command exited ${code}" )
+    quit "$code"
+  }
+  quit
+fi
-- 
cgit v1.3