61.2.3 Synchronous Interface Functions

Function: pq-connectdb conninfo

Establish a (synchronous) database connection. conninfo A string of blank separated options. Options are of the form “option = value”. If value contains blanks, it must be single quoted. Blanks around the equal sign are optional. Multiple option assignments are blank separated.

(pq-connectdb "dbname=kantdb port=5432")
     ⇒ #<PGconn kantdb:5432 freundt/freundt>

The printed representation of a database connection object has four fields. The first field is the hostname where the database server is running (in this case localhost), the second field is the port number, the third field is the database user name, and the fourth field is the name of the database.

Database connection objects which have been disconnected and will generate an immediate error if they are used look like:

  #<PGconn BAD>

Bad connections can be reestablished with pq-reset, or deleted entirely with pq-finish.

A database connection object that has been deleted looks like:

(let ((P1 (pq-connectdb "")))
  (pq-finish P1)
  P1)
     ⇒ #<PGconn DEAD>

Note that database connection objects are the most heavy weight objects in SXEmacs Lisp at this writing, usually representing as much as several megabytes of virtual memory on the machine the database server is running on. It is wisest to explicitly delete them when you are finished with them, rather than letting garbage collection do it. An example idiom is:

(let ((P (pq-connectiondb "")))
  (unwind-protect
      (progn
	(...)) ; access database here
    (pq-finish P)))

The following options are available in the options string:

authtype

Authentication type. Same as PGAUTHTYPE. This is no longer used.

user

Database user name. Same as PGUSER.

password

Database password.

dbname

Database name. Same as PGDATABASE

host

Symbolic hostname. Same as PGHOST.

hostaddr

Host address as four octets (eg. like 192.168.1.1).

port

TCP port to connect to. Same as PGPORT.

tty

Debugging TTY. Same as PGTTY. This value is suppressed in the SXEmacs Lisp API.

options

Extra backend database options. Same as PGOPTIONS.

A database connection object is returned regardless of whether a connection was established or not.

Function: pq-reset conn

Reestablish database connection. conn A database connection object.

This function reestablishes a database connection using the original connection parameters. This is useful if something has happened to the TCP link and it has become broken.

Function: pq-exec conn query

Make a synchronous database query. conn A database connection object. query A string containing an SQL query. A PGresult object is returned, which in turn may be queried by its many accessor functions to retrieve state out of it. If the query string contains multiple SQL commands, only results from the final command are returned.

(setq R (pq-exec P "SELECT * FROM sxemacs_codenames;
DELETE FROM sxemacs_codenames WHERE id=8;"))
     ⇒ #<PGresult PGRES_COMMAND_OK[1] - DELETE 1>

Function: pq-notifies conn

Return the latest async notification that has not yet been handled. conn A database connection object. If there has been a notification, then a list of two elements will be returned. The first element contains the relation name being notified, the second element contains the backend process ID number. nil is returned if there aren’t any notifications to process.

Function: PQsetenv conn

Synchronous transfer of environment variables to a backend conn A database connection object.

Environment variable transfer is done as a normal part of database connection.

Compatibility note: This function was present but not documented in versions of libpq prior to 7.0.