All sessions with a PostgreSQL database require a connection to be opened with
pg-connectdb. When the default values of the options are sufficient,
you don’t need to specify them. Default values are also useful in creating a
connection dialog (user-interface element).
Guile-PG displays connection objects in one of the following formats:
#<PG-CONN:DB:HOST:PORT:OPTIONS> ; open #<PG-CONN:-> ; closed
db is the database name, or
?; host is the host
name, or socket directory name in the case of Unix-domain connections;
port is the TCP port
where the server is listening, empty in the case of Unix-domain connections;
and options is the same as would be returned by
Everything else appears literally as shown here. It is very strange to have
?; usually that indicates a bug either in Guile-PG or in
#t iff obj is a connection object
Open and return a connection to the database specified
and configured by constr, a possibly empty string
consisting of space-separated
The name can be any of:
The host-name or dotted-decimal IP address of the host
on which the postmaster is running. If no
sub-string is given then consult in order: the
PGHOST, otherwise the name
of the local host.
The TCP or Unix socket on which the backend is
listening. If this is not specified then consult in
order: the environment variable
otherwise the default port (5432).
A string containing the options to the backend server.
The options given here are in addition to the options
given by the environment variable
The options string should be a set of command line
switches as would be passed to the backend. See the
postgres(1) man page for more details.
A string defining the file or device on which error
messages from the backend are to be displayed. If this
is empty (
""), then consult the environment
PGTTY. If the specified tty is a file
then the file will be readable only by the user the
postmaster runs as (usually ‘postgres’).
Similarly, if the specified tty is a device then it
must have permissions allowing the postmaster user to
write to it.
The name of the database. If no
sub-string is given then consult in order: the
PGDATABASE, the environment
USER, otherwise the
The login name of the user to authenticate. If none is
given then consult in order: the environment variable
PGUSER, otherwise the login name of the user
owning the process.
The password. Whether or not this is used depends upon the contents of the pg_hba.conf file. See the pg_hba.conf(5) man page for details.
This must be set to
password if password
authentication is in use, otherwise it must not be
If value contains spaces it must be enclosed in single quotes, and any single quotes appearing in value must be escaped using backslashes. Backslashes appearing in value must similarly be escaped. Note that if the constr is a Guile string literal then all the backslashes will themselves need to be escaped a second time.
Return an alist associating options with their connection defaults. The option name is a keyword. Each associated value is in turn a sub-alist, with the following keys:
Values are strings or
#f, unless noted otherwise.
#\* means the option should
be treated like a password: user dialogs should hide
the value; while
#\D means the option is for
debugging purposes: probably a good idea to entirely avoid
presenting this option in the first place.
(define (user-count host tcp-port) (let* ((conn (pg-connectdb (format #f "host=~A port=~A dbname=template1" host tcp-port))) (result (pg-exec conn "SELECT COUNT(*) FROM pg_user"))) (and result (eq? 'PGRES_TUPLES_OK (pg-result-status result)) (string->number (pg-getvalue result 0 0)))))
pg-finish to close an open connection. Although this is not
strictly necessary (Guile-PG arranges for unreferenced connection
objects to be properly closed when they are garbage collected), failure
to do so before the process exits normally results in a (server side)
logfile entry “unexpected EOF on client connection”.
Close the connection conn with the backend.
PostgreSQL 7.4 and later support the concept of protocol version. See Miscellaneous, for another way to find installation metainfo.
Return the client protocol version for conn.
This (integer) will be 2 prior to PostgreSQL 7.4.
If conn is not a connection object, return
Notices are messages sent from the back- to the front-end, sometimes prefixed
with the word
NOTICE, and always followed by a trailing newline. By
default, they are sent to the current output port.
Set notice output handler of conn to out.
out can be
#f, which means discard notices;
#t, which means send them to the current error port;
an output port to send the notice to; or a procedure that
takes one argument, the notice string. It’s usually a good
idea to call
pg-set-notice-out! soon after establishing
Reset the connection conn with the backend.
Equivalent to closing the connection and re-opening it again
with the same connect options as given to
conn must be a valid
PG_CONN object returned by
Return an integer representation of the server version at conn. This is basically
(+ (* 10000 major) (* 100 minor) micro)
which yields 40725 for PostgreSQL 4.7.25, for example.
#f if conn is closed.
Return a string containing the name of the database to which conn represents a connection.
Return a string containing the user name used to authenticate the connection conn.
Return a string containing the password used to authenticate the connection conn.
Return a string containing the name of the host to which conn represents a connection.
Return a string containing the port number to which conn represents a connection.
Return a string containing the the name of the diagnostic tty for conn.
Return a string containing the options string for conn.
Return an integer which is the the PID of the backend process for conn.
Return a keyword describing the current transaction status,
#:idle (connection idle),
#:active (command in progress),
#:intrans (idle, within transaction block),
#:inerror (idle, within failed transaction),
#:unknown (cannot determine status).
Return the status (a string) of parm for conn,
#f if there is no such parameter.
parm is a symbol, such as
The PostgreSQL back-end supports asynchronous notifications
with the commands
NOTIFY. You can use
pg-notifies to query the pending notifications queue
(see Asynchronous Retrieval).
Return the next as-yet-unhandled notification
from conn, or
#f if there are none available.
The notification is a pair with CAR relname,
a string naming the relation containing data; and
CDR pid, the integer PID
of the backend delivering the notification.
Optional arg tickle non-
#f means to do a
“consume input” operation prior to the query.
The client’s character encoding, represented by a string such as "UNICODE", can be queried and set.
Return the current client encoding for conn as a string.
Set the client encoding for conn to encoding (a symbol or string).
#t if successful,
Set the nonblocking status of conn to mode.
If mode is non-
#f, set it to nonblocking, otherwise
set it to blocking. Return
#t if successful.
#t if conn is in nonblocking mode.