Skip to content

P
Postgres FD Implementation
Commit e3f36838 authored by Joe Conway's avatar Joe Conway
Browse files
Options

Introduce two new libpq connection functions, PQconnectdbParams and 

PQconnectStartParams. These are analogous to PQconnectdb and PQconnectStart
respectively. They differ from the legacy functions in that they accept
two NULL-terminated arrays, keywords and values, rather than conninfo
strings. This avoids the need to build the conninfo string in cases
where it might be inconvenient to do so. Includes documentation.

Also modify psql to utilize PQconnectdbParams rather than PQsetdbLogin.
This allows the new config parameter application_name to be set, which
in turn is displayed in the pg_stat_activity view and included in CSV
log entries. This will also ensure both new functions get regularly
exercised.

Patch by Guillaume Lelarge with review and minor adjustments by
Joe Conway.
parent 83cb7da7
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 400 additions and 68 deletions
doc/src/sgml/libpq.sgml
View file @ e3f36838
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.295 2010/01/21 14:58:52 rhaas Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.296 2010/01/28 06:28:26 joe Exp $ -->
<chapter id="libpq">
<title><application>libpq</application> - C Library</title>
......@@ -56,7 +56,8 @@
one time. (One reason to do that is to access more than one
database.) Each connection is represented by a
<structname>PGconn</><indexterm><primary>PGconn</></> object, which
is obtained from the function <function>PQconnectdb</> or
is obtained from the function <function>PQconnectdb</>,
<function>PQconnectdbParams</>, or
<function>PQsetdbLogin</>. Note that these functions will always
return a non-null object pointer, unless perhaps there is too
little memory even to allocate the <structname>PGconn</> object.
......@@ -91,35 +92,33 @@
<variablelist>
<varlistentry>
<term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</></></term>
<term><function>PQconnectdbParams</function><indexterm><primary>PQconnectdbParams</></></term>
<listitem>
<para>
Makes a new connection to the database server.
<synopsis>
PGconn *PQconnectdb(const char *conninfo);
PGconn *PQconnectdbParams(const char **keywords, const char **values);
</synopsis>
</para>
<para>
This function opens a new database connection using the parameters taken
from the string <literal>conninfo</literal>. Unlike <function>PQsetdbLogin</> below,
the parameter set can be extended without changing the function signature,
so use of this function (or its nonblocking analogues <function>PQconnectStart</>
and <function>PQconnectPoll</function>) is preferred for new application programming.
from two <symbol>NULL</symbol>-terminated arrays. The first,
<literal>keywords</literal>, is defined as an array of strings, each one
being a key word. The second, <literal>values</literal>, gives the value
for each key word. Unlike <function>PQsetdbLogin</> below, the parameter
set can be extended without changing the function signature, so use of
this function (or its nonblocking analogs <function>PQconnectStartParams</>
and <function>PQconnectPoll</function>) is preferred for new application
programming.
</para>
<para>
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 <literal>keyword = value</literal>.
Spaces around the equal sign are optional.
To write an empty value or a value containing
spaces, surround it with single quotes, e.g.,
<literal>keyword = 'a value'</literal>.
Single quotes and backslashes within the value must be escaped with a
backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
The passed arrays can be empty to use all default parameters, or can
contain one or more parameter settings. They should be matched in length.
Processing will stop with the last non-<symbol>NULL</symbol> element
of the <literal>keywords</literal> array.
</para>
<para>
......@@ -477,6 +476,39 @@
</listitem>
</varlistentry>
<varlistentry>
<term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</></></term>
<listitem>
<para>
Makes a new connection to the database server.
<synopsis>
PGconn *PQconnectdb(const char *conninfo);
</synopsis>
</para>
<para>
This function opens a new database connection using the parameters taken
from the string <literal>conninfo</literal>.
</para>
<para>
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 <literal>keyword = value</literal>.
Spaces around the equal sign are optional. To write an empty value,
or a value containing spaces, surround it with single quotes, e.g.,
<literal>keyword = 'a value'</literal>. Single quotes and backslashes
within the value must be escaped with a backslash, i.e.,
<literal>\'</literal> and <literal>\\</literal>.
</para>
<para>
The currently recognized parameter key words are the same as above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>PQsetdbLogin</function><indexterm><primary>PQsetdbLogin</></></term>
<listitem>
......@@ -532,6 +564,7 @@ PGconn *PQsetdb(char *pghost,
</varlistentry>
<varlistentry>
<term><function>PQconnectStartParams</function><indexterm><primary>PQconnectStartParams</></></term>
<term><function>PQconnectStart</function><indexterm><primary>PQconnectStart</></></term>
<term><function>PQconnectPoll</function><indexterm><primary>PQconnectPoll</></></term>
<listitem>
......@@ -539,6 +572,10 @@ PGconn *PQsetdb(char *pghost,
<indexterm><primary>nonblocking connection</primary></indexterm>
Make a connection to the database server in a nonblocking manner.
<synopsis>
PGconn *PQconnectStartParams(const char **keywords, const char **values);
</synopsis>
<synopsis>
PGconn *PQconnectStart(const char *conninfo);
</synopsis>
......@@ -549,29 +586,37 @@ PGconn *PQsetdb(char *pghost,
</para>
<para>
These two functions are used to open a connection to a database server such
These three functions are used to open a connection to a database server such
that your application's thread of execution is not blocked on remote I/O
whilst doing so.
The point of this approach is that the waits for I/O to complete can occur
in the application's main loop, rather than down inside
<function>PQconnectdb</>, and so the application can manage this
operation in parallel with other activities.
whilst doing so. The point of this approach is that the waits for I/O to
complete can occur in the application's main loop, rather than down inside
<function>PQconnectdbParams</> or <function>PQconnectdb</>, and so the
application can manage this operation in parallel with other activities.
</para>
<para>
The database connection is made using the parameters taken from the string
<literal>conninfo</literal>, passed to <function>PQconnectStart</function>. This string is in
the same format as described above for <function>PQconnectdb</function>.
With <function>PQconnectStartParams</function>, the database connection is made
using the parameters taken from the <literal>keywords</literal> and
<literal>values</literal> arrays, as described above for
<function>PQconnectdbParams</function>.
</para>
<para>
Neither <function>PQconnectStart</function> nor <function>PQconnectPoll</function> will block, so long as a number of
With <function>PQconnectStart</function>, the database connection is made
using the parameters taken from the string <literal>conninfo</literal> as
described above for <function>PQconnectdb</function>.
</para>
<para>
Neither <function>PQconnectStartParams</function> nor <function>PQconnectStart</function>
nor <function>PQconnectPoll</function> will block, so long as a number of
restrictions are met:
<itemizedlist>
<listitem>
<para>
The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
name and reverse name queries are not made. See the documentation of
these parameters under <function>PQconnectdb</function> above for details.
these parameters under <function>PQconnectdbParams</function> above for details.
</para>
</listitem>
......@@ -591,6 +636,11 @@ PGconn *PQsetdb(char *pghost,
</itemizedlist>
</para>
<para>
Note: use of <function>PQconnectStartParams</> is analogous to
<function>PQconnectStart</> shown below.
</para>
<para>
To begin a nonblocking connection request, call <literal>conn = PQconnectStart("<replaceable>connection_info_string</>")</literal>.
If <varname>conn</varname> is null, then <application>libpq</> has been unable to allocate a new <structname>PGconn</>
......@@ -883,7 +933,8 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
parameters previously used. This can be useful for error recovery if a
working connection is lost. They differ from <function>PQreset</function> (above) in that they
act in a nonblocking manner. These functions suffer from the same
restrictions as <function>PQconnectStart</> and <function>PQconnectPoll</>.
restrictions as <function>PQconnectStartParams</>, <function>PQconnectStart</>
and <function>PQconnectPoll</>.
</para>
<para>
......@@ -1096,9 +1147,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
</para>
<para>
See the entry for <function>PQconnectStart</> and <function>PQconnectPoll</> with regards
to other status codes
that might be seen.
See the entry for <function>PQconnectStartParams</>, <function>PQconnectStart</>
and <function>PQconnectPoll</> with regards to other status codes that
might be seen.
</para>
</listitem>
</varlistentry>
......
src/bin/psql/startup.c
View file @ e3f36838
......@@ -3,7 +3,7 @@
*
* Copyright (c) 2000-2010, PostgreSQL Global Development Group
*
* $PostgreSQL: pgsql/src/bin/psql/startup.c,v 1.158 2010/01/02 16:57:59 momjian Exp $
* $PostgreSQL: pgsql/src/bin/psql/startup.c,v 1.159 2010/01/28 06:28:26 joe Exp $
*/
#include "postgres_fe.h"
......@@ -90,6 +90,8 @@ main(int argc, char *argv[])
char *password = NULL;
char *password_prompt = NULL;
bool new_pass;
const char *keywords[] = {"host","port","dbname","user",
"password","application_name",NULL};
set_pglocale_pgservice(argv[0], PG_TEXTDOMAIN("psql"));
......@@ -171,11 +173,20 @@ main(int argc, char *argv[])
/* loop until we have a password if requested by backend */
do
{
new_pass = false;
pset.db = PQsetdbLogin(options.host, options.port, NULL, NULL,
options.action == ACT_LIST_DB && options.dbname == NULL ?
"postgres" : options.dbname,
options.username, password);
const char *values[] = {
options.host,
options.port,
(options.action == ACT_LIST_DB &&
options.dbname == NULL) ? "postgres" : options.dbname,
options.username,
password,
pset.progname,
NULL
};
new_pass = false;
pset.db = PQconnectdbParams(keywords, values);
if (PQstatus(pset.db) == CONNECTION_BAD &&
PQconnectionNeedsPassword(pset.db) &&
......
src/interfaces/libpq/exports.txt
View file @ e3f36838
# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.24 2010/01/21 14:58:53 rhaas Exp $
# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.25 2010/01/28 06:28:26 joe Exp $
# Functions to be exported by libpq DLLs
PQconnectdb 1
PQsetdbLogin 2
......@@ -155,3 +155,5 @@ PQconninfoParse 152
PQinitOpenSSL 153
PQescapeLiteral 154
PQescapeIdentifier 155
PQconnectdbParams 156
PQconnectStartParams 157
src/interfaces/libpq/fe-connect.c
View file @ e3f36838
This diff is collapsed.
src/interfaces/libpq/libpq-fe.h
View file @ e3f36838
......@@ -7,7 +7,7 @@
* Portions Copyright (c) 1996-2010, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* $PostgreSQL: pgsql/src/interfaces/libpq/libpq-fe.h,v 1.149 2010/01/21 14:58:53 rhaas Exp $
* $PostgreSQL: pgsql/src/interfaces/libpq/libpq-fe.h,v 1.150 2010/01/28 06:28:26 joe Exp $
*
*-------------------------------------------------------------------------
*/
......@@ -226,10 +226,12 @@ typedef struct pgresAttDesc
/* make a new client connection to the backend */
/* Asynchronous (non-blocking) */
extern PGconn *PQconnectStart(const char *conninfo);
extern PGconn *PQconnectStartParams(const char **keywords, const char **values);
extern PostgresPollingStatusType PQconnectPoll(PGconn *conn);
/* Synchronous (blocking) */
extern PGconn *PQconnectdb(const char *conninfo);
extern PGconn *PQconnectdbParams(const char **keywords, const char **values);
extern PGconn *PQsetdbLogin(const char *pghost, const char *pgport,
const char *pgoptions, const char *pgtty,
const char *dbName,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment