The tdbc::postgres driver provides a database interface that conforms
to Tcl DataBase Connectivity (TDBC) and allows a Tcl script to connect
to a Postgres database.
Connection to a POSTGRES database is established by invoking
tdbc::postgres::connection create, passing it the name to give the
database handle and a set of -option-value pairs. The available
options are enumerated under CONNECTION OPTIONS below.
As an alternative, tdbc::postgres::connection new may be used to create
a database connection with an automatically assigned name. The return value
from tdbc::postgres::connection new is the name that was chosen for the
connection handle.
The side effect of tdbc::postgres::connection create is to create a
new database connection.. See tdbc::connection(n) for the
details of how to use the connection to manipulate a database.
The tdbc::postgres::connection create object command supports the
-encoding, -isolation, -readonly and -timeout
options common to all TDBC drivers. The -timeout option will
only affect connection process, once connected this value will be
ignored and cannot be changed after connecting.
In addition, the following options are recognized (these options must be
set on the initial creation of the connection; they cannot be changed
after connecting) :
Connects to the host specified by given IP address. If both -host and -hostaddr are given, the value
of -host is ignored. Default is to connect using a local Unix domain socket.
These two options are synonymous. They present the given name as the
name of the default database to use in Postgres queries. If not specified,
the default database for the current user is used.
This option determines whether or with what priority an SSL connection will be negotiated with
the server. There are four modes: disable will attempt only an unencrypted SSL connection;
allow will negotiate, trying first a non-SSL connection, then if that fails, trying an SSL
connection; prefer (the default) will negotiate, trying first an SSL connection,
then if that fails, trying a regular non-SSL connection; require will try only an SSL connection.
If PostgreSQL is compiled without SSL support, using option require will cause an error,
and options allow and prefer will be tolerated but the driver will be unable to negotiate
an SSL connection.
This option is deprecated in favor of the -sslmode setting.
The flag value must be a Boolean value. If it is true (or
any equivalent), driver will then refuse to connect if the server does
not accept an SSL connection. The default value is false (or any
equivalent), and acts the same like -sslmodepreffered
It specifies a service name in pg_service.conf file that holds additional connection parameters.
This allows applications to specify only a service name so connection parameters can be
centrally maintained. Refer to PostgreSQL Documentation or PREFIX/share/pg_service.conf.sample file
for details.
tdbc::postgres::connection -user joe -passwd sesame -db joes_database
Connects to the Postgres server on the local host using the default
connection method, presenting user ID 'joe' and password 'sesame'.
Uses 'joes_database' as the default database name.