From 1f0a41e95505c12af17c416651d70f18ea7c6a07 Mon Sep 17 00:00:00 2001 From: Pierre Neidhardt Date: Wed, 10 Jun 2020 11:29:04 +0200 Subject: [PATCH] doc: Explain how to use psql with peer authentication. * doc/guix.texi (Database Services): Add example of shell commands to use psql as system user. Also add troubleshooting tip when service fails to start because of incompatible cluster. --- doc/guix.texi | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/guix.texi b/doc/guix.texi index b2030e68cf..c23ed8d715 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -17260,6 +17260,24 @@ The PostgreSQL daemon loads its runtime configuration from @var{config-file}, creates a database cluster with @var{locale} as the default locale, stored in @var{data-directory}. It then listens on @var{port}. +If the services fails to start, it may be due to an incompatible +cluster already present in @var{data-directory}. Adjust it (or, if you +don't need the cluster anymore, delete @var{data-directory}), then +restart the service. + +Peer authentication is used by default and the @code{postgres} user +account has no shell, which prevents the direct execution of @code{psql} +commands as this user. To use @code{psql}, you can temporarily log in +as @code{postgres} using a shell, create a PostgreSQL superuser with the +same name as one of the system users and then create the associated +database. + +@example +sudo -u postgres -s /bin/sh +createuser --interactive +createdb $MY_USER_LOGIN # Replace appropriately. +@end example + @cindex postgresql extension-packages Additional extensions are loaded from packages listed in @var{extension-packages}. Extensions are available at runtime. For instance,