10000 Introduce two new libpq connection functions, PQconnectdbParams and · postgres/postgres@e3f3683 · GitHub
[go: up one dir, main page]
Skip to content

Commit e3f3683

Browse files
jconwayjconway
committed
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.
1 parent 83cb7da commit e3f3683

File tree

5 files changed

+400
-68
lines changed

5 files changed

+400
-68
lines changed

‎doc/src/sgml/libpq.sgml

Lines changed: 84 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.295 2010/01/21 14:58:52 rhaas Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.296 2010/01/28 06:28:26 joe Exp $ -->
22

33
<chapter id="libpq">
44
<title><application>libpq</application> - C Library</title>
@@ -56,7 +56,8 @@
5656
one time. (One reason to do that is to access more than one
5757
database.) Each connection is represented by a
5858
<structname>PGconn</><indexterm><primary>PGconn</></> object, which
59-
is obtained from the function <function>PQconnectdb</> or
59+
is obtained from the function <function>PQconnectdb</>,
60+
<function>PQconnectdbParams</>, or
6061
<function>PQsetdbLogin</>. Note that these functions will always
6162
return a non-null object pointer, unless perhaps there is too
6263
little memory even to allocate the <structname>PGconn</> object.
@@ -91,35 +92,33 @@
9192

9293
<variablelist>
9394
<varlistentry>
94-
<term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</></></term>
95+
<term><function>PQconnectdbParams</function><indexterm><primary>PQconnectdbParams</></></term>
9596
<listitem>
9697
<para>
9798
Makes a new connection to the database server.
9899

99100
<synopsis>
100-
PGconn *PQconnectdb(const char *conninfo);
101+
PGconn *PQconnectdbParams(const char **keywords, const char **values);
101102
</synopsis>
102103
</para>
103104

104105
<para>
105106
This function opens a new database connection using the parameters taken
106-
from the string <literal>conninfo</literal>. Unlike <function>PQsetdbLogin</> below,
107-
the parameter set can be extended without changing the function signature,
108-
so use of this function (or its nonblocking analogues <function>PQconnectStart</>
109-
and <function>PQconnectPoll</function>) is preferred for new application programming.
107+
from two <symbol>NULL</symbol>-terminated arrays. The first,
108+
<literal>keywords</literal>, is defined as an array of strings, each one
109+
being a key word. The second, <literal>values</literal>, gives the value
110+
for each key word. Unlike <function>PQsetdbLogin</> below, the parameter
111+
set can be extended without changing the function signature, so use of
112+
this function (or its nonblocking analogs <function>PQconnectStartParams</>
113+
and <function>PQconnectPoll</function>) is preferred for new application
114+
programming.
110115
</para>
111116

112117
<para>
113-
The passed string
114-
can be empty to use all default parameters, or it can contain one or more
115-
parameter settings separated by whitespace.
116-
Each parameter setting is in the form <literal>keyword = value</literal>.
117-
Spaces around the equal sign are optional.
118-
To write an empty value or a value containing
119-
spaces, surround it with single quotes, e.g.,
120-
<literal>keyword = 'a value'</literal>.
121-
Single quotes and backslashes within the value must be escaped with a
122-
backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
118+
The passed arrays can be empty to use all default parameters, or can
119+
contain one or more parameter settings. They shou EDBE ld be matched in length.
120+
Processing will stop with the last non-<symbol>NULL</symbol> element
121+
of the <literal>keywords</literal> array.
123122
</para>
124123

125124
<para>
@@ -477,6 +476,39 @@
477476
</listitem>
478477
</varlistentry>
479478

479+
<varlistentry>
480+
<term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</></></term>
481+
<listitem>
482+
<para>
483+
Makes a new connection to the database server.
484+
485+
<synopsis>
486+
PGconn *PQconnectdb(const char *conninfo);
487+
</synopsis>
488+
</para>
489+
490+
<para>
491+
This function opens a new database connection using the parameters taken
492+
from the string <literal>conninfo</literal>.
493+
</para>
494+
495+
<para>
496+
The passed string can be empty to use all default parameters, or it can
497+
contain one or more parameter settings separated by whitespace.
498+
Each parameter setting is in the form <literal>keyword = value</literal>.
499+
Spaces around the equal sign are optional. To write an empty value,
500+
or a value containing spaces, surround it with single quotes, e.g.,
501+
<literal>keyword = 'a value'</literal>. Single quotes and backslashes
502+
within the value must be escaped with a backslash, i.e.,
503+
<literal>\'</literal> and <literal>\\</literal>.
504+
</para>
505+
506+
<para>
507+
The currently recognized parameter key words are the same as above.
508+
</para>
509+
</listitem>
510+
</varlistentry>
511+
480512
<varlistentry>
481513
<term><function>PQsetdbLogin</function><indexterm><primary>PQsetdbLogin</></></term>
482514
<listitem>
@@ -532,13 +564,18 @@ PGconn *PQsetdb(char *pghost,
532564
</varlistentry>
533565

534566
<varlistentry>
567+
<term><function>PQconnectStartParams</function><indexterm><primary>PQconnectStartParams</></></term>
535568
<term><function>PQconnectStart</function><indexterm><primary>PQconnectStart</></></term>
536569
<term><function>PQconnectPoll</function><indexterm><primary>PQconnectPoll</></></term>
537570
<listitem>
538571
<para>
539572
<indexterm><primary>nonblocking connection</primary></indexterm>
540573
Make a connection to the database server in a nonblocking manner.
541574

575+
<synopsis>
576+
PGconn *PQconnectStartParams(const char **keywords, const char **values);
577+
</synopsis>
578+
542579
<synopsis>
543580
PGconn *PQconnectStart(const char *conninfo);
544581
</synopsis>
@@ -549,29 +586,37 @@ PGconn *PQsetdb(char *pghost,
549586
</para>
550587

551588
<para>
552-
These two functions are used to open a connection to a database server such
589+
These three functions are used to open a connection to a database server such
553590
that your application's thread of execution is not blocked on remote I/O
554-
whilst doing so.
555-
The point of this approach is that the waits for I/O to complete can occur
556-
in the application's main loop, rather than down inside
557-
<function>PQconnectdb</>, and so the application can manage this
558-
operation in parallel with other activities.
591+
whilst doing so. The point of this approach is that the waits for I/O to
592+
complete can occur in the application's main loop, rather than down inside
593+
<function>PQconnectdbParams</> or <function>PQconnectdb</>, and so the
594+
application can manage this operation in parallel with other activities.
559595
</para>
560596

561597
<para>
562-
The database connection is made using the parameters taken from the string
563-
<literal>conninfo</literal>, passed to <function>PQconnectStart</function>. This string is in
564-
the same format as described above for <function>PQconnectdb</function>.
598+
With <function>PQconnectStartParams</function>, the database connection is made
599+
using the parameters taken from the <literal>keywords</literal> and
600+
<literal>values</literal> arrays, as described above for
601+
<function>PQconnectdbParams</function>.
565602
</para>
603+
566604
<para>
567-
Neither <function>PQconnectStart</function> nor <function>PQconnectPoll</function> will block, so long as a number of
605+
With <function>PQconnectStart</function>, the database connection is made
606+
using the parameters taken from the string <literal>conninfo</literal> as
607+
described above for <function>PQconnectdb</function>.
608+
</para>
609+
610+
<para>
611+
Neither <function>PQconnectStartParams</function> nor <function>PQconnectStart</function>
612+
nor <function>PQconnectPoll</function> will block, so long as a number of
568613
restrictions are met:
569614
<itemizedlist>
570615
<listitem>
571616
<para>
572617
The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
573618
name and reverse name queries are not made. See the documentation of
574-
these parameters under <function>PQconnectdb</function> above for details.
619+
these parameters under <function>PQconnectdbParams</function> above for details.
575620
</para>
576621
</listitem>
577622

@@ -591,6 +636,11 @@ PGconn *PQsetdb(char *pghost,
591636
</itemizedlist>
592637
</para>
593638

639+
<para>
640+
Note: use of <function>PQconnectStartParams</> is analogous to
641+
<function>PQconnectStart</> shown below.
642+
</para>
643+
594644
<para>
595645
To begin a nonblocking connection request, call <literal>conn = PQconnectStart("<replaceable>connection_info_string</>")</literal>.
596646
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);
883933
parameters previously used. This can be useful for error recovery if a
884934
working connection is lost. They differ from <function>PQreset</function> (above) in that they
885935
act in a nonblocking manner. These functions suffer from the same
886-
restrictions as <function>PQconnectStart</> and <function>PQconnectPoll</>.
936+
restrictions as <function>PQconnectStartParams</>, <function>PQconnectStart</>
937+
and <function>PQconnectPoll</>.
887938
</para>
888939

889940
<para>
@@ -1096,9 +1147,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
10961147
</para>
10971148

10981149
<para>
1099-
See the entry for <function>PQconnectStart</> and <function>PQconnectPoll</> with regards
1100-
to other status codes
1101-
that might be seen.
1150+
See the entry for <function>PQconnectStartParams</>, <function>PQconnectStart</>
1151+
and <function>PQconnectPoll</> with regards to other status codes that
1152+
might be seen.
11021153
</para>
11031154
</listitem>
11041155
</varlistentry>

‎src/bin/psql/startup.c

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
*
44
* Copyright (c) 2000-2010, PostgreSQL Global Development Group
55
*
6-
* $PostgreSQL: pgsql/src/bin/psql/startup.c,v 1.158 2010/01/02 16:57:59 momjian Exp $
6+
* $PostgreSQL: pgsql/src/bin/psql/startup.c,v 1.159 2010/01/28 06:28:26 joe Exp $
77
*/
88
#include "postgres_fe.h"
99

@@ -90,6 +90,8 @@ main(int argc, char *argv[])
9090
char *password = NULL;
9191
char *password_prompt = NULL;
9292
bool new_pass;
93+
const char *keywords[] = {"host","port","dbname","user",
94+
"password","application_name",NULL};
9395

9496
set_pglocale_pgservice(argv[0], PG_TEXTDOMAIN("psql"));
9597

@@ -171,11 +173,20 @@ main(int argc, char *argv[])
171173
/* loop until we have a password if requested by backend */
172174
do
173175
{
174-
new_pass = false;
175-
pset.db = PQsetdbLogin(options.host, options.port, NULL, NULL,
176-
options.action == ACT_LIST_DB && options.dbname == NULL ?
177-
"postgres" : options.dbname,
178-
options.username, password);
176+
const char *values[] = {
177+
options.host,
178+
options.port,
179+
(options.action == ACT_LIST_DB &&
180+
options.dbname == NULL) ? "postgres" : options.dbname,
181+
options.username,
182+
password,
183+
pset.progname,
184+
NULL
185+
};
186+
187+
new_pass = false;
188+
189+
pset.db = PQconnectdbParams(keywords, values);
179190

180191
if (PQstatus(pset.db) == CONNECTION_BAD &&
181192
PQconnectionNeedsPassword(pset.db) &&

‎src/interfaces/libpq/exports.txt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.24 2010/01/21 14:58:53 rhaas Exp $
1+
# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.25 2010/01/28 06:28:26 joe Exp $
22
# Functions to be exported by libpq DLLs
33
PQconnectdb 1
44
PQsetdbLogin 2
@@ -155,3 +155,5 @@ PQconninfoParse 152
155155
PQinitOpenSSL 153
156156
PQescapeLiteral 154
157157
PQescapeIdentifier 155
158+
PQconnectdbParams 156
159+
PQconnectStartParams 157

0 commit comments

Comments
 (0)
0