File: pgtcl-pgconnect.html

package info (click to toggle)
pgtcl 1%3A1.9%2Bgit20120911-3
links: PTS
area: main
in suites: jessie, jessie-kfreebsd
size: 2,240 kB
ctags: 315
sloc: ansic: 4,475; tcl: 634; sh: 149; makefile: 36; sql: 11
file content (899 lines) | stat: -rw-r--r-- 15,222 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>pg_connect</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL Tcl Interface Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="pgtcl Command Reference"
HREF="libpgtcl-ref.html"><LINK
REL="PREVIOUS"
TITLE="pgtcl Command Reference"
HREF="libpgtcl-ref.html"><LINK
REL="NEXT"
TITLE="pg_dbinfo"
HREF="pgtcl-pgconninfo.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
NAME="creation"
CONTENT="2005-11-27T13:24:31"></HEAD
><BODY
CLASS="REFENTRY"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
>PostgreSQL Tcl Interface Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpgtcl-ref.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpgtcl-ref.html#LIBPGTCL-REF"
>Fast Backward</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="pgtcl-pgconninfo.html"
>Fast Forward</A
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="pgtcl-pgconninfo.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="PGTCL-PGCONNECT"
></A
>pg_connect</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN283"
></A
><H2
>Name</H2
>pg_connect&nbsp;--&nbsp;open a connection to the server<A
NAME="IX-PGTCL-PGCONNECT-2"
></A
></DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN288"
></A
><H2
>Synopsis</H2
><PRE
CLASS="SYNOPSIS"
>pg_connect -conninfo <VAR
CLASS="PARAMETER"
>connectOptions</VAR
> ?<SPAN
CLASS="OPTIONAL"
>-connhandle <VAR
CLASS="PARAMETER"
>connectionHandleName</VAR
></SPAN
>?
pg_connect <VAR
CLASS="PARAMETER"
>dbName</VAR
> ?<SPAN
CLASS="OPTIONAL"
>-host <VAR
CLASS="PARAMETER"
>hostName</VAR
></SPAN
>? ?<SPAN
CLASS="OPTIONAL"
>-port <VAR
CLASS="PARAMETER"
>portNumber</VAR
></SPAN
>? ?<SPAN
CLASS="OPTIONAL"
>-tty <VAR
CLASS="PARAMETER"
>tty</VAR
></SPAN
>? ?<SPAN
CLASS="OPTIONAL"
>-options <VAR
CLASS="PARAMETER"
>serverOptions</VAR
></SPAN
>? ?<SPAN
CLASS="OPTIONAL"
>-connhandle <VAR
CLASS="PARAMETER"
>connectionHandleName</VAR
></SPAN
>?
pg_connect -connlist <VAR
CLASS="PARAMETER"
>connectNameValueList</VAR
> ?<SPAN
CLASS="OPTIONAL"
>-connhandle <VAR
CLASS="PARAMETER"
>connectionHandleName</VAR
></SPAN
>?</PRE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN307"
></A
><H2
>Description</H2
><P
>   <CODE
CLASS="FUNCTION"
>pg_connect</CODE
> opens a connection to the
   <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> server.
  </P
><P
>   Three syntaxes are available.  In the older one, each possible option
   has a separate option switch in the <TT
CLASS="COMMAND"
>pg_connect</TT
>
   command.  In the newer form, a single option string is supplied
   that can contain multiple option values. The third form takes
   the parameters as a name value Tcl list.
   <CODE
CLASS="FUNCTION"
>pg_conndefaults</CODE
> can be used to retrieve
   information about the available options in the newer syntax.
  </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN315"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><P
><B
>New style</B
></P
><DL
><DT
><VAR
CLASS="PARAMETER"
>connectOptions</VAR
></DT
><DD
><P
>       <CODE
CLASS="FUNCTION"
>pg_connect</CODE
> opens a new database connection using the 
       parameters taken from the <TT
CLASS="LITERAL"
>connectOptions</TT
> string.  Unlike 
       the old-style usage of <CODE
CLASS="FUNCTION"
>pg_connect</CODE
>,
       with the new-style usage the parameter set can be extended without 
       requiring changes to either <TT
CLASS="FILENAME"
>libpgtcl</TT
> or the underlying
      <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> library,
       so use of the new style (or its nonexistent
       nonblocking analogues <CODE
CLASS="FUNCTION"
>pg_connect_start</CODE
>
       and <CODE
CLASS="FUNCTION"
>pg_connect_poll</CODE
>) is preferred for new 
       application programming.
       </P
><P
>       The passed string
       can be empty to use all default parameters, or it can contain one or more
       parameter settings separated by whitespace.
       Each parameter setting is in the form <TT
CLASS="LITERAL"
>keyword = value</TT
>.
       (To write an empty value or a value containing
       spaces, surround it with single quotes, e.g.,
       <TT
CLASS="LITERAL"
>keyword = 'a value'</TT
>.
       Single quotes and backslashes within the value must be escaped with a
       backslash, i.e., <TT
CLASS="LITERAL"
>\'</TT
> and <TT
CLASS="LITERAL"
>\\</TT
>.)
       Spaces around the equal sign are optional.
       </P
><P
>       The currently recognized parameter key words are:

       <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>host</TT
></DT
><DD
><P
>	  Name of host to connect to.<A
NAME="AEN343"
></A
>
	  If this begins with a slash, it specifies Unix-domain
	  communication rather than TCP/IP communication; the value is the
	  name of the directory in which the socket file is stored.  The
	  default is to connect to a Unix-domain socket in
	  <TT
CLASS="FILENAME"
>/tmp</TT
>.<A
NAME="AEN346"
></A
>
	 </P
></DD
><DT
><TT
CLASS="LITERAL"
>hostaddr</TT
></DT
><DD
><P
>	  Numeric IP address of host to connect to.  This should be in the
	  standard IPv4 address format, e.g., <TT
CLASS="LITERAL"
>172.28.40.9</TT
>.  If
	  your machine supports IPv6, you can also use IPv6 address
	  format, e.g., <TT
CLASS="LITERAL"
>fe80::203:93ff:fedb:49bc</TT
>.
	  TCP/IP communication is
	  always used when a nonempty string is specified for this parameter.
	 </P
><P
>	  Using <TT
CLASS="LITERAL"
>hostaddr</TT
> instead of <TT
CLASS="LITERAL"
>host</TT
> allows the
	  application to avoid a host name lookup, which may be important in
	  applications with time constraints. However, Kerberos authentication
	  requires the host name. The following therefore applies: If
	  <TT
CLASS="LITERAL"
>host</TT
> is specified without <TT
CLASS="LITERAL"
>hostaddr</TT
>, a host name
	  lookup occurs. If <TT
CLASS="LITERAL"
>hostaddr</TT
> is specified without
	  <TT
CLASS="LITERAL"
>host</TT
>, the value for <TT
CLASS="LITERAL"
>hostaddr</TT
> gives the remote
	  address. When Kerberos is used, a reverse name query occurs to obtain
	  the host name for Kerberos. If both
	  <TT
CLASS="LITERAL"
>host</TT
> and <TT
CLASS="LITERAL"
>hostaddr</TT
> are specified, the value for
	  <TT
CLASS="LITERAL"
>hostaddr</TT
> gives the remote address; the value for
	  <TT
CLASS="LITERAL"
>host</TT
> is ignored, unless Kerberos is used, in which case that
	  value is used for Kerberos authentication. (Note that authentication is
	  likely to fail if <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> is passed a host name
	  that is not the name of the machine at <TT
CLASS="LITERAL"
>hostaddr</TT
>.)  Also,
	  <TT
CLASS="LITERAL"
>host</TT
> rather than <TT
CLASS="LITERAL"
>hostaddr</TT
> is used to identify
	  the connection in <TT
CLASS="FILENAME"
>$HOME/.pgpass</TT
>.
	 </P
><P
>	  Without either a host name or host address,
	  <SPAN
CLASS="APPLICATION"
>Pgtcl</SPAN
> will connect using a
	  local Unix domain socket.
	 </P
></DD
><DT
><TT
CLASS="LITERAL"
>port</TT
></DT
><DD
><P
>	  Port number to connect to at the server host, or socket file
	  name extension for Unix-domain
	  connections.<A
NAME="AEN379"
></A
>
	 </P
></DD
><DT
><TT
CLASS="LITERAL"
>dbname</TT
></DT
><DD
><P
>	  The database name.  Defaults to be the same as the user name.
	 </P
></DD
><DT
><TT
CLASS="LITERAL"
>user</TT
></DT
><DD
><P
>	  <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> user name to connect as.
	 </P
></DD
><DT
><TT
CLASS="LITERAL"
>password</TT
></DT
><DD
><P
>	  Password to be used if the server demands password authentication.
	 </P
></DD
><DT
><TT
CLASS="LITERAL"
>connect_timeout</TT
></DT
><DD
><P
>	  Maximum wait for connection, in seconds (write as a decimal integer
	  string). Zero or not specified means wait indefinitely.  It is not
	  recommended to use a timeout of less than 2 seconds.
	 </P
></DD
><DT
><TT
CLASS="LITERAL"
>options</TT
></DT
><DD
><P
>	   Command-line options to be sent to the server.
	  </P
></DD
><DT
><TT
CLASS="LITERAL"
>tty</TT
></DT
><DD
><P
>	  Ignored (formerly, this specified where to send server debug output).
	 </P
></DD
><DT
><TT
CLASS="LITERAL"
>sslmode</TT
></DT
><DD
><P
>	   This option determines whether or with what priority an
	   <ACRONYM
CLASS="ACRONYM"
>SSL</ACRONYM
> connection will be negotiated with the
	   server. There are four modes: <TT
CLASS="LITERAL"
>disable</TT
> will attempt
	   only an unencrypted <ACRONYM
CLASS="ACRONYM"
>SSL</ACRONYM
> connection;
	   <TT
CLASS="LITERAL"
>allow</TT
> will negotiate, trying first a
	   non-<ACRONYM
CLASS="ACRONYM"
>SSL</ACRONYM
> connection, then if that fails, trying an
	   <ACRONYM
CLASS="ACRONYM"
>SSL</ACRONYM
> connection; <TT
CLASS="LITERAL"
>prefer</TT
> (the default)
	   will negotiate, trying first an <ACRONYM
CLASS="ACRONYM"
>SSL</ACRONYM
> connection,
	   then if that fails, trying a regular non-<ACRONYM
CLASS="ACRONYM"
>SSL</ACRONYM
>
	   connection; <TT
CLASS="LITERAL"
>require</TT
> will try only an
	   <ACRONYM
CLASS="ACRONYM"
>SSL</ACRONYM
> connection.
	  </P
><P
>	   If <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> is compiled without SSL support,
	   using option <TT
CLASS="LITERAL"
>require</TT
> will cause an error, and
	   options <TT
CLASS="LITERAL"
>allow</TT
> and <TT
CLASS="LITERAL"
>prefer</TT
> will be
	   tolerated but <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> will be unable to negotiate
	   an <ACRONYM
CLASS="ACRONYM"
>SSL</ACRONYM
>
	   connection.<A
NAME="AEN435"
></A
>
	  </P
></DD
><DT
><TT
CLASS="LITERAL"
>requiressl</TT
></DT
><DD
><P
>	   This option is deprecated in favor of the <TT
CLASS="LITERAL"
>sslmode</TT
>
	   setting.
	  </P
><P
>	   If set to 1, an <ACRONYM
CLASS="ACRONYM"
>SSL</ACRONYM
> connection to the server
	   is required (this is equivalent to <TT
CLASS="LITERAL"
>sslmode</TT
>
	   <TT
CLASS="LITERAL"
>require</TT
>).  <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> will then refuse
	   to connect if the server does not accept an
	   <ACRONYM
CLASS="ACRONYM"
>SSL</ACRONYM
> connection.  If set to 0 (default),
	   <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> will negotiate the connection type with
	   the server (equivalent to <TT
CLASS="LITERAL"
>sslmode</TT
>
	   <TT
CLASS="LITERAL"
>prefer</TT
>).  This option is only available if
	   <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> is compiled with SSL support.
	  </P
></DD
><DT
><TT
CLASS="LITERAL"
>service</TT
></DT
><DD
><P
>	  Service name to use for additional parameters.  It specifies a service
	  name in <TT
CLASS="FILENAME"
>pg_service.conf</TT
> that holds additional connection parameters.
	  This allows applications to specify only a service name so connection parameters 
	  can be centrally maintained.  See 
	  <TT
CLASS="FILENAME"
><VAR
CLASS="REPLACEABLE"
>PREFIX</VAR
>/share/pg_service.conf.sample</TT
> for
	  information on how to set up the file.
	 </P
></DD
><DT
><VAR
CLASS="OPTION"
>-connhandle <VAR
CLASS="PARAMETER"
>connectionHandleName</VAR
></VAR
></DT
><DD
><P
>         Name to use for the connection handle, instead of pgtcl generating the
name automatically. Without the option, the name is auto-generated, prefixed with pgsql, and with a numeric id at the end. This gives the programmer control over the name of the connection handle.
	 </P
></DD
></DL
></DIV
><P>

       If  any  parameter is unspecified, then the corresponding
       environment variable (see <TT
CLASS="LITERAL"
>libpq</TT
> documentation in the <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> manual)
       is checked. If the  environment  variable is not set either,
       then built-in defaults are used.
       </P
></DD
></DL
></DIV
><P
></P
><DIV
CLASS="VARIABLELIST"
><P
><B
>Old style</B
></P
><DL
><DT
><VAR
CLASS="PARAMETER"
>dbName</VAR
></DT
><DD
><P
>      The name of the database to connect to.
     </P
></DD
><DT
><VAR
CLASS="OPTION"
>-host <VAR
CLASS="PARAMETER"
>hostName</VAR
></VAR
></DT
><DD
><P
>      The host name of the database server to connect to.
     </P
></DD
><DT
><VAR
CLASS="OPTION"
>-port <VAR
CLASS="PARAMETER"
>portNumber</VAR
></VAR
></DT
><DD
><P
>      The TCP port number of the database server to connect to.
     </P
></DD
><DT
><VAR
CLASS="OPTION"
>-tty <VAR
CLASS="PARAMETER"
>tty</VAR
></VAR
></DT
><DD
><P
>      A file or <ACRONYM
CLASS="ACRONYM"
>TTY</ACRONYM
> for optional debug output from
      the server.
     </P
></DD
><DT
><VAR
CLASS="OPTION"
>-options <VAR
CLASS="PARAMETER"
>serverOptions</VAR
></VAR
></DT
><DD
><P
>      Additional configuration options to pass to the server.
     </P
></DD
><DT
><VAR
CLASS="OPTION"
>-connhandle <VAR
CLASS="PARAMETER"
>connectionHandleName</VAR
></VAR
></DT
><DD
><P
>         Name to use for the connection handle, instead of pgtcl generating the
name automatically. Without the option, the name is auto-generated, prefixed with pgsql, and with a numeric id at the end. This gives the programmer control over the name of the connection handle.
	 </P
></DD
></DL
></DIV
><P
></P
><DIV
CLASS="VARIABLELIST"
><P
><B
>Third style (most recent one added)</B
></P
><DL
><DT
><VAR
CLASS="PARAMETER"
>-connlist connectNameValuelist</VAR
></DT
><DD
><P
>       <CODE
CLASS="FUNCTION"
>pg_connect</CODE
> opens a new database connection using the 
       parameters taken from the <TT
CLASS="LITERAL"
>connectNameValuelist</TT
> list. The parameters are exactly the same for the New Style, but they are stored as a Tcl list, instead of a string. The list is a name value pair, for example: <TT
CLASS="COMMAND"
>[list host localhost port 5400 dbname template1]</TT
>.

</P><PRE
CLASS="PROGRAMLISTING"
>array set conninfo {
    host    192.168.123.180
    port    5801
    dbname  template1
    user    postgres
}
set conn [pg::connect -connlist [array get ::conninfo]]</PRE
><P></P><PRE
CLASS="PROGRAMLISTING"
>&#13;
	 </PRE
><P></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN520"
></A
><H2
>Return Value</H2
><P
>   If successful, a handle for a database connection is returned.
   Handles start with the prefix <TT
CLASS="LITERAL"
>pgsql</TT
>.
  </P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpgtcl-ref.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="pgtcl-pgconninfo.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><SPAN
CLASS="APPLICATION"
>pgtcl</SPAN
> Command Reference</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="libpgtcl-ref.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>pg_dbinfo</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>