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

---
 temp-postgres.1 | 47 +++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 6 deletions(-)

(limited to 'temp-postgres.1')

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 ,
-- 
cgit v1.3