158 lines
6.0 KiB
Plaintext
158 lines
6.0 KiB
Plaintext
|
'\"
|
||
|
|
.\" tdbc_postgres.n --
|
||
|
|
.\"
|
||
|
|
.\" Copyright (c) 2009 by Slawomir Cygan
|
||
|
|
.\"
|
||
|
|
.\" See the file "license.terms" for information on usage and redistribution of
|
||
|
|
.\" this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||
|
|
.TH "tdbc::postgres" n 8.6 Tcl "Tcl Database Connectivity"
|
||
|
|
.\" .so man.macros
|
||
|
|
.if t .wh -1.3i ^B
|
||
|
|
.nr ^l \n(.l
|
||
|
|
.ad b
|
||
|
|
.\" # BS - start boxed text
|
||
|
|
.\" # ^y = starting y location
|
||
|
|
.\" # ^b = 1
|
||
|
|
.de BS
|
||
|
|
.br
|
||
|
|
.mk ^y
|
||
|
|
.nr ^b 1u
|
||
|
|
.if n .nf
|
||
|
|
.if n .ti 0
|
||
|
|
.if n \l'\\n(.lu\(ul'
|
||
|
|
.if n .fi
|
||
|
|
..
|
||
|
|
.\" # BE - end boxed text (draw box now)
|
||
|
|
.de BE
|
||
|
|
.nf
|
||
|
|
.ti 0
|
||
|
|
.mk ^t
|
||
|
|
.ie n \l'\\n(^lu\(ul'
|
||
|
|
.el \{\
|
||
|
|
.\" Draw four-sided box normally, but don't draw top of
|
||
|
|
.\" box if the box started on an earlier page.
|
||
|
|
.ie !\\n(^b-1 \{\
|
||
|
|
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
|
||
|
|
.\}
|
||
|
|
.el \}\
|
||
|
|
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
|
||
|
|
.\}
|
||
|
|
.\}
|
||
|
|
.fi
|
||
|
|
.br
|
||
|
|
.nr ^b 0
|
||
|
|
..
|
||
|
|
.\" # CS - begin code excerpt
|
||
|
|
.de CS
|
||
|
|
.RS
|
||
|
|
.nf
|
||
|
|
.ta .25i .5i .75i 1i
|
||
|
|
..
|
||
|
|
.\" # CE - end code excerpt
|
||
|
|
.de CE
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
..
|
||
|
|
.BS
|
||
|
|
.SH "NAME"
|
||
|
|
tdbc::postgres \- TDBC-POSTGRES bridge
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
package require \fBtdbc::postgres 1.0\fR
|
||
|
|
.sp
|
||
|
|
\fBtdbc::postgres::connection create\fR \fIdb\fR ?\fI-option value...\fR?
|
||
|
|
.br
|
||
|
|
\fBtdbc::postgres::connection new\fR ?\fI-option value...\fR?
|
||
|
|
.BE
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
.PP
|
||
|
|
The \fBtdbc::postgres\fR driver provides a database interface that conforms
|
||
|
|
to Tcl DataBase Connectivity (TDBC) and allows a Tcl script to connect
|
||
|
|
to a Postgres database.
|
||
|
|
.PP
|
||
|
|
Connection to a POSTGRES database is established by invoking
|
||
|
|
\fBtdbc::postgres::connection create\fR, passing it the name to give the
|
||
|
|
database handle and a set of \fI-option-value\fR pairs. The available
|
||
|
|
options are enumerated under CONNECTION OPTIONS below.
|
||
|
|
As an alternative, \fBtdbc::postgres::connection new\fR may be used to create
|
||
|
|
a database connection with an automatically assigned name. The return value
|
||
|
|
from \fBtdbc::postgres::connection new\fR is the name that was chosen for the
|
||
|
|
connection handle.
|
||
|
|
.PP
|
||
|
|
The side effect of \fBtdbc::postgres::connection create\fR is to create a
|
||
|
|
new database connection.. See \fBtdbc::connection(n)\fR for the
|
||
|
|
details of how to use the connection to manipulate a database.
|
||
|
|
.SH "CONNECTION OPTIONS"
|
||
|
|
.PP
|
||
|
|
The \fBtdbc::postgres::connection create\fR object command supports the
|
||
|
|
\fB-encoding\fR, \fB-isolation\fR, \fB-readonly\fR and \fB-timeout\fR
|
||
|
|
options common to all TDBC drivers. The \fB-timeout\fR option will
|
||
|
|
only affect connection process, once connected this value will be
|
||
|
|
ignored and cannot be changed after connecting.
|
||
|
|
.PP
|
||
|
|
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) :
|
||
|
|
.IP "\fB-host\fR \fIhostname\fR"
|
||
|
|
Connects to the host specified by \fIhostname\fR. Default is to connect using a local Unix domain socket.
|
||
|
|
.IP "\fB-hostaddr\fR \fIaddress\fR"
|
||
|
|
Connects to the host specified by given IP \fIaddress\fR. If both \fB-host\fR and \fB-hostaddr\fR are given, the value
|
||
|
|
of \fB-host\fR is ignored. Default is to connect using a local Unix domain socket.
|
||
|
|
.IP "\fB-port\fR \fInumber\fR"
|
||
|
|
Connects to a Postgres server listening on the port specified by \fInumber\fR.
|
||
|
|
It is used only when \fIhost\fR or \fIhostaddr\fR is specified.
|
||
|
|
.IP "\fB-user\fR \fIname\fR"
|
||
|
|
Presents \fIname\fR as the user name to the Postgres server. Default is the
|
||
|
|
current user ID.
|
||
|
|
.IP "\fB-passwd\fR \fIpassword\fR"
|
||
|
|
.IP "\fB-password\fR \fIpassword\fR"
|
||
|
|
These two options are synonymous. They present the given \fIpassword\fR as
|
||
|
|
the user's password to the Postgres server. Default is not to present a password.
|
||
|
|
.IP "\fB-database\fR \fIname\fR"
|
||
|
|
.IP "\fB-db\fR \fIname\fR"
|
||
|
|
These two options are synonymous. They present the given \fIname\fR as the
|
||
|
|
name of the default database to use in Postgres queries. If not specified,
|
||
|
|
the default database for the current user is used.
|
||
|
|
.IP "\fB-options\fR \fIopts\fR"
|
||
|
|
This sets \fIopts\fR as additional command line options send to the server.
|
||
|
|
.IP "\fB-tty\fR \fIfile\fR"
|
||
|
|
This option is ignored on never servers. Formerly this specified where to send debug
|
||
|
|
output. This option is left for compatibility with older servers.
|
||
|
|
.IP "\fB-sslmode\fR \fImode\fR"
|
||
|
|
This option determines whether or with what priority an SSL connection will be negotiated with
|
||
|
|
the server. There are four \fImodes\fR: \fBdisable\fR will attempt only an unencrypted SSL connection;
|
||
|
|
\fBallow\fR will negotiate, trying first a non-SSL connection, then if that fails, trying an SSL
|
||
|
|
connection; \fBprefer\fR (the default) will negotiate, trying first an SSL connection,
|
||
|
|
then if that fails, trying a regular non-SSL connection; \fBrequire\fR will try only an SSL connection.
|
||
|
|
If PostgreSQL is compiled without SSL support, using option \fBrequire\fR will cause an error,
|
||
|
|
and options \fBallow\fR and \fBprefer\fR will be tolerated but the driver will be unable to negotiate
|
||
|
|
an SSL connection.
|
||
|
|
.IP \fB-requiressl\fR \fIflag\fR
|
||
|
|
This option is deprecated in favor of the \fB-sslmode\fR setting.
|
||
|
|
The \fIflag\fR value must be a Boolean value. If it is \fBtrue\fR (or
|
||
|
|
any equivalent), driver will then refuse to connect if the server does
|
||
|
|
not accept an SSL connection. The default value is \fBfalse\fR (or any
|
||
|
|
equivalent), and acts the same like \fB-sslmode\fR \fBpreffered\fR
|
||
|
|
.IP \fB-service\fR \fIname\fR
|
||
|
|
It specifies a service \fIname\fR 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.
|
||
|
|
.SH EXAMPLES
|
||
|
|
.PP
|
||
|
|
.CS
|
||
|
|
tdbc::postgres::connection -user joe -passwd sesame -db joes_database
|
||
|
|
.CE
|
||
|
|
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.
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
tdbc(n), tdbc::connection(n), tdbc::resultset(n), tdbc::statement(n)
|
||
|
|
.SH "KEYWORDS"
|
||
|
|
TDBC, SQL, Postgres, database, connectivity, connection
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
Copyright (c) 2009 by Slawomir Cygan
|
||
|
|
.\" Local Variables:
|
||
|
|
.\" mode: nroff
|
||
|
|
.\" End:
|
||
|
|
.\"
|