pg_connect

pg_connect
Prev	4.1. Database Connection Control Commands	Next

pg_connect — Open a connection to the server

Synopsis

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

Description

pg_connect opens a connection to the PostgreSQL server.

There are three ways to specify connection options: using a connection string (connectOptions), using a connection list (connectList), and an obsolete method with a database name followed by separate option and value pairs.

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

Arguments

Using a connection string

-conninfo connectOptions

connectOptions is 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. Spaces are optional around the equal signs. An example is:

pg_connect -conninfo "host=myserver dbname=productiondb user=me password=mysecret"

You can also use a URI form for the connectOptions string. The usual URI-escaping needs to be used (RFC 3986) for each component. (For example, if the password contains a ':' it must be written as '%3A'.) Refer to the notes below for more information. An example is:

pg_connect -conninfo "postgresql://me:mysecret@myserver/productiondb"

Using a connection list

-connlist connectList

connectList is a Tcl list with keyword and value pairs. The keywords are the same as those specified in the connection string form above. The advantage of this form is that it does not require escaping or quoting of individual values, other than requiring a well-formed Tcl list argument. An example is:

pg_connect -connlist {host myserver dbname productiondb user me password mysecret}

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.

Notes

Specifying an unknown or invalid option in a connection string or connection list will result in an error.

The older style is deprecated and should not be used. It does not support specifying username or password. Assuming the database requires authentication, using this form requires passing authentication credentials in some other way (such as through environment variables).

The connection list form, and support for URI connection strings, were added in pgtclng-2.1.0 and in pgintcl-3.5.0.

Refer to the PostgreSQL documentation, "libpq - C Library", "Database Connection Control Functions", "Connection URIs" for details on URI connection strings. With libpq-based implementations of the Pgtcl interface, such as Pgtcl-ng, libpq parses the URI and handles the full specification. It requires PostgreSQL-9.2.0 or higher. The general form for a URI connection string is:

postgresql://user:password@host:port/dbname?option=value...

Pgintcl, a pure-Tcl implementation of the pgtcl interface, does not use libpq, and has these limitations in pg_connect:

The older form, with separate dbname command argument, is not supported.
The URI form postgresql://... is supported, but option parameters (following ? in the URI) are ignored and not supported.
The list of valid connection options is much smaller than that provided by libpq. Assume only host, hostaddr, port, dbname, user, and password are valid (or use pg_conndefaults to see the list).

This command uses or emulates the PostgreSQL libpq functions PQconnectdb for the connection string style, PQconnectdbParams for the connection list style, and PQsetdb for the older style.