Next: Procedures for Retrieving Data, Previous: Quick Start, Up: The (database postgres*) Modules [Contents][Index]
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 pg-get-options.
Everything else appears literally as shown here. It is very strange to have
db be ?; usually that indicates a bug either in Guile-PG or in
PostgreSQL.
Return #t iff obj is a connection object
returned by pg-connectdb.
Open and return a connection to the database specified
and configured by constr, a possibly empty string
consisting of space-separated name=value pairs.
The name can be any of:
hostThe host-name or dotted-decimal IP address of the host
on which the postmaster is running. If no host=
sub-string is given then consult in order: the
environment variable PGHOST, otherwise the name
of the local host.
portThe TCP or Unix socket on which the backend is
listening. If this is not specified then consult in
order: the environment variable PGPORT,
otherwise the default port (5432).
optionsA string containing the options to the backend server.
The options given here are in addition to the options
given by the environment variable PGOPTIONS.
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.
ttyA 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
variable 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.
dbnameThe name of the database. If no dbname=
sub-string is given then consult in order: the
environment variable PGDATABASE, the environment
variable USER, otherwise the user value.
userThe 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.
passwordThe 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.
authtypeThis must be set to password if password
authentication is in use, otherwise it must not be
specified.
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:
#:envvar
#:compiled
#:val
#:label
#:dispchar (character: #\* or #\D;
or #f)
#:dispsize (integer)
Values are strings or #f, unless noted otherwise.
A dispchar of #\* 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)))))
Use 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 Procedures, 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 #f.
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
the connection.
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 pg-connectdb.
conn must be a valid PG_CONN object returned by
pg-connectdb.
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. However, for PostgreSQL 10 and later, the number represents
(+ (* 10000 major) minor)
although the documentation recommends considering it to be
(+ (* 100 effective-major) minor)
for the purposes of feature comparison.
Return #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,
one of: #: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,
or #f if there is no such parameter.
parm is a symbol, such as client_encoding.
The PostgreSQL back-end supports asynchronous notifications
with the commands LISTEN and 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).
Return #t if successful, #f otherwise.
Next: Procedures for Retrieving Data, Previous: Quick Start, Up: The (database postgres*) Modules [Contents][Index]