Next: Retrieving Data, Previous: Quick Start, Up: Top
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.
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:
host
- The 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 variablePGHOST
, otherwise the name of the local host.port
- The 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).options
- A 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.tty
- 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 variablePGTTY
. If the specified tty is a file then the file will be readable only by the user the postmaster runs as (usuallypostgres
). Similarly, if the specified tty is a device then it must have permissions allowing the postmaster user to write to it.dbname
- The name of the database. If no
dbname=
sub-string is given then consult in order: the environment variablePGDATABASE
, the environment variableUSER
, otherwise theuser
value.user
- 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.password
- 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.
authtype
- This 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. Adispchar
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”.
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
#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 callpg-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 validPG_CONN
object returned bypg-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. 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 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 asclient_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.
Set the client encoding for conn to encoding. Return
#t
if successful, #f otherwise.