From e3f36838e5b2666a15286b137bb11f35a7245848 Mon Sep 17 00:00:00 2001 From: Joe Conway Date: Thu, 28 Jan 2010 06:28:26 +0000 Subject: 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. --- doc/src/sgml/libpq.sgml | 117 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 84 insertions(+), 33 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 1d13e8b0b4e..a698ab1958d 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,4 +1,4 @@ - + <application>libpq</application> - C Library @@ -56,7 +56,8 @@ one time. (One reason to do that is to access more than one database.) Each connection is represented by a PGconnPGconn object, which - is obtained from the function PQconnectdb or + is obtained from the function PQconnectdb, + PQconnectdbParams, or PQsetdbLogin. Note that these functions will always return a non-null object pointer, unless perhaps there is too little memory even to allocate the PGconn object. @@ -91,35 +92,33 @@ - PQconnectdbPQconnectdb + PQconnectdbParamsPQconnectdbParams Makes a new connection to the database server. - PGconn *PQconnectdb(const char *conninfo); + PGconn *PQconnectdbParams(const char **keywords, const char **values); This function opens a new database connection using the parameters taken - from the string conninfo. Unlike PQsetdbLogin below, - the parameter set can be extended without changing the function signature, - so use of this function (or its nonblocking analogues PQconnectStart - and PQconnectPoll) is preferred for new application programming. + from two NULL-terminated arrays. The first, + keywords, is defined as an array of strings, each one + being a key word. The second, values, gives the value + for each key word. Unlike PQsetdbLogin below, the parameter + set can be extended without changing the function signature, so use of + this function (or its nonblocking analogs PQconnectStartParams + and PQconnectPoll) is preferred for new application + programming. - 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 keyword = value. - Spaces around the equal sign are optional. - To write an empty value or a value containing - spaces, surround it with single quotes, e.g., - keyword = 'a value'. - Single quotes and backslashes within the value must be escaped with a - backslash, i.e., \' and \\. + 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-NULL element + of the keywords array. @@ -477,6 +476,39 @@ + + PQconnectdbPQconnectdb + + + Makes a new connection to the database server. + + + PGconn *PQconnectdb(const char *conninfo); + + + + + This function opens a new database connection using the parameters taken + from the string conninfo. + + + + 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 keyword = value. + Spaces around the equal sign are optional. To write an empty value, + or a value containing spaces, surround it with single quotes, e.g., + keyword = 'a value'. Single quotes and backslashes + within the value must be escaped with a backslash, i.e., + \' and \\. + + + + The currently recognized parameter key words are the same as above. + + + + PQsetdbLoginPQsetdbLogin @@ -532,6 +564,7 @@ PGconn *PQsetdb(char *pghost, + PQconnectStartParamsPQconnectStartParams PQconnectStartPQconnectStart PQconnectPollPQconnectPoll @@ -539,6 +572,10 @@ PGconn *PQsetdb(char *pghost, nonblocking connection Make a connection to the database server in a nonblocking manner. + + PGconn *PQconnectStartParams(const char **keywords, const char **values); + + PGconn *PQconnectStart(const char *conninfo); @@ -549,29 +586,37 @@ PGconn *PQsetdb(char *pghost, - 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 - 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 + PQconnectdbParams or PQconnectdb, and so the + application can manage this operation in parallel with other activities. - The database connection is made using the parameters taken from the string - conninfo, passed to PQconnectStart. This string is in - the same format as described above for PQconnectdb. + With PQconnectStartParams, the database connection is made + using the parameters taken from the keywords and + values arrays, as described above for + PQconnectdbParams. + - Neither PQconnectStart nor PQconnectPoll will block, so long as a number of + With PQconnectStart, the database connection is made + using the parameters taken from the string conninfo as + described above for PQconnectdb. + + + + Neither PQconnectStartParams nor PQconnectStart + nor PQconnectPoll will block, so long as a number of restrictions are met: The hostaddr and host parameters are used appropriately to ensure that name and reverse name queries are not made. See the documentation of - these parameters under PQconnectdb above for details. + these parameters under PQconnectdbParams above for details. @@ -591,6 +636,11 @@ PGconn *PQsetdb(char *pghost, + + Note: use of PQconnectStartParams is analogous to + PQconnectStart shown below. + + To begin a nonblocking connection request, call conn = PQconnectStart("connection_info_string"). If conn is null, then libpq has been unable to allocate a new 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 PQreset (above) in that they act in a nonblocking manner. These functions suffer from the same - restrictions as PQconnectStart and PQconnectPoll. + restrictions as PQconnectStartParams, PQconnectStart + and PQconnectPoll. @@ -1096,9 +1147,9 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); - See the entry for PQconnectStart and PQconnectPoll with regards - to other status codes - that might be seen. + See the entry for PQconnectStartParams, PQconnectStart + and PQconnectPoll with regards to other status codes that + might be seen. -- cgit v1.2.3