pg_connect

Name

pg_connect -- open a connection to the server

Synopsis

pg_connect -conninfo connectOptions
pg_connect dbName ?-host hostName? ?-port portNumber? ?-tty tty? ?-options serverOptions?

Description

pg_connect opens a connection to the PostgreSQL server.

Two syntaxes are available. In the older one, each possible option has a separate option switch in the pg_connect command. This syntax is deprecated and should not be used. In the newer form, a single option string is supplied that can contain multiple option values. pg_conndefaults can be used to retrieve information about the available options in the newer syntax.

Connections opened with pg_connect should be closed with pg_disconnect once they are no longer needed.

Arguments

New style

-conninfo connectOptions

A string of connection options, each written in the form keyword = value. A list of valid options can be found in the description of the libpq function PQconnectdb. Some of the more common keywords are: host, port, dbname, user, and password. The keyword value must be placed in single quotes if it is empty or contains spaces. Within the single quotes, a single quote or backslash must be escaped by preceding it with a backslash.

Old style

dbName

The name of the database to connect to.

-host hostName

The host name of the database server to connect to.

-port portNumber

The TCP port number of the database server to connect to.

-tty tty

A file or TTY for optional debug output from the server.

-options serverOptions

Additional configuration options to pass to the server.

Return Value

If successful, a handle for a database connection is returned. Handles start with the prefix pgsql.

A Tcl error will be thrown if a connection could not be made. The Tcl error message indicates the reason.