agora inbox for [email protected]help / color / mirror / Atom feed
Another review of URI for libpq, v7 submission 22+ messages / 9 participants [nested] [flat]
* Another review of URI for libpq, v7 submission @ 2012-03-15 08:49 Daniel Farina <[email protected]> 0 siblings, 2 replies; 22+ messages in thread From: Daniel Farina @ 2012-03-15 08:49 UTC (permalink / raw) To: Alexander Shulgin <[email protected]>; pgsql-hackers I reviewed this and so far have not found any serious problems, although as is par for the course it contains some of the fiddly bits involved in any string manipulations in C. I made a few edits -- none strictly necessary for correctness -- that the original author is free audit and/or include[0]. I did put in some defensive programming choices (instead of if/else if/elseif/else raise an error, even if the latter is allegedly impossible) that I think are a good idea. Loops around pointer increments are very fastidiously checked for NUL-byteness, and those that aren't are carefully guarded by invariants that seem like they should prevent an overrun. The nature of the beast, I suppose, short of giving libpq a "StringData" like struct and a small lexer to make it more clear that a subtle overrun is not creeping in. One thing I found puzzling was that in the latest revision the tests appeared to be broken for me: all "@" signs were translated to "(at)". Is that mangling applied by the archives, or something? The test suite neatly tries to copy pg_regress's general "make installcheck" style, but it likes to use my username as the database rather than the standard "regression" as seen by pg_regress. It is nice that a place to test connection strings and such is there, where there was none before. I am happy with the range and style of accepted URIs, and I think this can stem the bleeding of the fragmentation already taking place at large. [0]: https://github.com/fdr/postgres/tree/uri, commit e50ef375b7a731ca79bf5d3ca8b0bd69c97a9e71, aka the 'uri' branch -- fdr ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-03-15 14:34 Alvaro Herrera <[email protected]> parent: Daniel Farina <[email protected]> 1 sibling, 0 replies; 22+ messages in thread From: Alvaro Herrera @ 2012-03-15 14:34 UTC (permalink / raw) To: Daniel Farina <[email protected]>; +Cc: Alexander Shulgin <[email protected]>; pgsql-hackers Excerpts from Daniel Farina's message of jue mar 15 05:49:50 -0300 2012: > One thing I found puzzling was that in the latest revision the tests > appeared to be broken for me: all "@" signs were translated to "(at)". > Is that mangling applied by the archives, or something? Ugh, ouch. Yeah, that was done by the archives. It seems that when attachments are text/plain Mhonarc applies anti-spamming to them :-( The original message doesn't have that problem. Sorry about that. -- Álvaro Herrera <[email protected]> The PostgreSQL Company - Command Prompt, Inc. PostgreSQL Replication, Consulting, Custom Development, 24x7 support ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-03-15 14:36 Alex Shulgin <[email protected]> parent: Daniel Farina <[email protected]> 1 sibling, 1 reply; 22+ messages in thread From: Alex Shulgin @ 2012-03-15 14:36 UTC (permalink / raw) To: Daniel Farina <[email protected]>; +Cc: pgsql-hackers Daniel Farina <[email protected]> writes: > I reviewed this and so far have not found any serious problems, > although as is par for the course it contains some of the fiddly bits > involved in any string manipulations in C. I made a few edits -- none > strictly necessary for correctness -- that the original author is free > audit and/or include[0]. Thank you for the review, Daniel! Apparently, I was on drugs when I've submitted v7, as it still contains the bug for which to fix I was forced to move parts of the code back into the main parser routine... > I did put in some defensive programming choices (instead of if/else > if/elseif/else raise an error, even if the latter is allegedly > impossible) that I think are a good idea. Yes, this is a good idea, I'll incorporate them in the patch. However, this one doesn't work: https://github.com/fdr/postgres/commit/4fad90fb243d9266b1003cfbcf8397f67269fad3 Neither '@' or '/' are mandatory in the URI anywhere after "scheme://", so we can't just say it "should never happen." Running the regression test with this commit applied highlights the problem. > One thing I found puzzling was that in the latest revision the tests > appeared to be broken for me: all "@" signs were translated to "(at)". > Is that mangling applied by the archives, or something? This is definitely mangling by the lists. I can see this has happened to people before, e.g.: http://archives.postgresql.org/pgsql-hackers/2010-01/msg00938.php But that discussion didn't seem to lead to a solution for the problem. I wonder if there's any evidence as to that mangling the email addresses helps to reduce spam at all? I mean replacing "(at)" back to "@" and "(dot)" to "." is piece of cake for a spam crawler. What I see though, is that most of the message-id URLs are broken by the mangling. Also I don't think everyone should just tolerate that it messes with the attachments. Should we all suddenly use application/octet-stream or application/gzip instead of text/plain? > The test suite neatly tries to copy pg_regress's general "make > installcheck" style, but it likes to use my username as the database > rather than the standard "regression" as seen by pg_regress. It is > nice that a place to test connection strings and such is there, where > there was none before. Oh, I don't see why we can't use "regression" too. While testing this I've also noticed that there was some funny behavior when you left out the final slash after hostname, e.g.: "postgres://localhost/" vs. "postgres://localhost". It turned out in the former case we were setting dbname conninfo parameter to an empty string and in the latter one we didn't set it at all. The difference is that when we do set it, the default dbname is derived from username, but when we don't--$PGDATABASE is used. I've fixed this, so now both URIs work the same way (both do not set dbname.) It also appeared to me that with the current code, a wide range of funny-looking URIs are considered valid, e.g.: postgres://user@ postgres://@host postgres://host:/ and, taking approach to the extreme: postgres://:@: This specifies empty user, password, host and port, and looks really funny. I've added (actually revived) some checks to forbid setting empty URI parts where it doesn't make much sense. Finally, attached is v8. Hopefully I didn't mess things up too much. -- Regards, Alex ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-03-15 21:09 Daniel Farina <[email protected]> parent: Alex Shulgin <[email protected]> 0 siblings, 1 reply; 22+ messages in thread From: Daniel Farina @ 2012-03-15 21:09 UTC (permalink / raw) To: Alex Shulgin <[email protected]>; +Cc: pgsql-hackers On Thu, Mar 15, 2012 at 7:36 AM, Alex Shulgin <[email protected]> wrote: > I wonder if there's any evidence as to that mangling the email addresses > helps to reduce spam at all? I mean replacing "(at)" back to "@" and > "(dot)" to "." is piece of cake for a spam crawler. I suspect we're long past the point in Internet history where such simple obfuscation could possibly matter. > Finally, attached is v8. Hopefully I didn't mess things up too much. I'll give it another look-over. Do you have these in git somewhere? It will help me save time on some of the incremental changes. -- fdr ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-03-15 21:29 Alex <[email protected]> parent: Daniel Farina <[email protected]> 0 siblings, 1 reply; 22+ messages in thread From: Alex @ 2012-03-15 21:29 UTC (permalink / raw) To: Daniel Farina <[email protected]>; +Cc: pgsql-hackers Daniel Farina <[email protected]> writes: > >> Finally, attached is v8. Hopefully I didn't mess things up too much. > > I'll give it another look-over. Do you have these in git somewhere? It > will help me save time on some of the incremental changes. Yes, I've just pushed my dev branch to this fork of mine: https://github.com/a1exsh/postgres/commits/uri ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-03-17 14:51 Marko Kreen <[email protected]> parent: Alex <[email protected]> 0 siblings, 1 reply; 22+ messages in thread From: Marko Kreen @ 2012-03-17 14:51 UTC (permalink / raw) To: Alex <[email protected]>; +Cc: Daniel Farina <[email protected]>; pgsql-hackers On Thu, Mar 15, 2012 at 11:29:31PM +0200, Alex wrote: > https://github.com/a1exsh/postgres/commits/uri The point of the patch is to have one string with all connection options, in standard format, yes? So why does not this work: db = PQconnectdb("postgres://localhost"); ? -- marko ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-03-20 22:18 Alex <[email protected]> parent: Marko Kreen <[email protected]> 0 siblings, 2 replies; 22+ messages in thread From: Alex @ 2012-03-20 22:18 UTC (permalink / raw) To: Marko Kreen <[email protected]>; +Cc: Daniel Farina <[email protected]>; pgsql-hackers Marko Kreen <[email protected]> writes: > On Thu, Mar 15, 2012 at 11:29:31PM +0200, Alex wrote: >> https://github.com/a1exsh/postgres/commits/uri > > The point of the patch is to have one string with all connection options, > in standard format, yes? So why does not this work: > > db = PQconnectdb("postgres://localhost"); > > ? Good catch. I've figured out that we'll need a bit more intrusive change than simply overriding the expand_dbname check in conninfo_array_parse (like the current version does) to support URIs in all PQconnect* variants. I still need to figure out some details, but this is to give people a status update. -- Alex ^ permalink raw reply [nested|flat] 22+ messages in thread
* Trivial libpq refactoring patch (was: Re: Another review of URI for libpq, v7 submission) @ 2012-03-21 16:42 Alex Shulgin <[email protected]> parent: Alex <[email protected]> 1 sibling, 1 reply; 22+ messages in thread From: Alex Shulgin @ 2012-03-21 16:42 UTC (permalink / raw) To: pgsql-hackers Alex <[email protected]> writes: > Marko Kreen <[email protected]> writes: > >> On Thu, Mar 15, 2012 at 11:29:31PM +0200, Alex wrote: >>> https://github.com/a1exsh/postgres/commits/uri >> >> The point of the patch is to have one string with all connection options, >> in standard format, yes? So why does not this work: >> >> db = PQconnectdb("postgres://localhost"); >> >> ? > > Good catch. > > I've figured out that we'll need a bit more intrusive change than simply > overriding the expand_dbname check in conninfo_array_parse (like the > current version does) to support URIs in all PQconnect* variants. > > I still need to figure out some details, but this is to give people a > status update. While working on this fix I've figured out that I need my conninfo_uri_parse to support use_defaults parameter, like conninfo(_array)_parse functions do. The problem is that the block of code which does the defaults handling is duplicated in both of the above functions. What I'd like to do is extract it into a separate function to call. What I wouldn't like is bloating the original URI patch with this unrelated change. So here's a trivial patch to do the refactoring. Also, it uses the newly added conninfo_fill_defaults directly in PQconndefaults, instead of doing the "parse empty conninfo string" trick. If this could be applied, I'd rebase my patch against the updated master branch and submit the new version. As it goes, the patch adds a little duplication when it comes to creating a working copy of PQconninfoOptions array. Attached is the second patch on top of the first one to extract this bit of code into conninfo_init. Not sure if we should go all the way through this, so it's not critical if this one is not applied. -- Regards, Alex *** a/src/interfaces/libpq/fe-connect.c --- b/src/interfaces/libpq/fe-connect.c *************** *** 297,302 **** static PQconninfoOption *conninfo_parse(const char *conninfo, --- 297,304 ---- static PQconninfoOption *conninfo_array_parse(const char *const * keywords, const char *const * values, PQExpBuffer errorMessage, bool use_defaults, int expand_dbname); + static bool conninfo_fill_defaults(PQconninfoOption *options, + PQExpBuffer errorMessage); static char *conninfo_getval(PQconninfoOption *connOptions, const char *keyword); static void defaultNoticeReceiver(void *arg, const PGresult *res); *************** *** 836,842 **** PQconndefaults(void) initPQExpBuffer(&errorBuf); if (PQExpBufferDataBroken(errorBuf)) return NULL; /* out of memory already :-( */ ! connOptions = conninfo_parse("", &errorBuf, true); termPQExpBuffer(&errorBuf); return connOptions; } --- 838,860 ---- initPQExpBuffer(&errorBuf); if (PQExpBufferDataBroken(errorBuf)) return NULL; /* out of memory already :-( */ ! ! /* Make a working copy of PQconninfoOptions */ ! connOptions = malloc(sizeof(PQconninfoOptions)); ! if (connOptions == NULL) ! { ! printfPQExpBuffer(&errorBuf, ! libpq_gettext("out of memory\n")); ! return NULL; ! } ! memcpy(connOptions, PQconninfoOptions, sizeof(PQconninfoOptions)); ! ! if (!conninfo_fill_defaults(connOptions, &errorBuf)) ! { ! PQconninfoFree(connOptions); ! connOptions = NULL; ! } ! termPQExpBuffer(&errorBuf); return connOptions; } *************** *** 4002,4008 **** conninfo_parse(const char *conninfo, PQExpBuffer errorMessage, char *pname; char *pval; char *buf; - char *tmp; char *cp; char *cp2; PQconninfoOption *options; --- 4020,4025 ---- *************** *** 4170,4245 **** conninfo_parse(const char *conninfo, PQExpBuffer errorMessage, free(buf); /* ! * Stop here if caller doesn't want defaults filled in. ! */ ! if (!use_defaults) ! return options; ! ! /* ! * If there's a service spec, use it to obtain any not-explicitly-given ! * parameters. */ ! if (parseServiceInfo(options, errorMessage)) { PQconninfoFree(options); return NULL; } - /* - * Get the fallback resources for parameters not specified in the conninfo - * string nor the service. - */ - for (option = options; option->keyword != NULL; option++) - { - if (option->val != NULL) - continue; /* Value was in conninfo or service */ - - /* - * Try to get the environment variable fallback - */ - if (option->envvar != NULL) - { - if ((tmp = getenv(option->envvar)) != NULL) - { - option->val = strdup(tmp); - if (!option->val) - { - printfPQExpBuffer(errorMessage, - libpq_gettext("out of memory\n")); - PQconninfoFree(options); - return NULL; - } - continue; - } - } - - /* - * No environment variable specified or this one isn't set - try - * compiled in - */ - if (option->compiled != NULL) - { - option->val = strdup(option->compiled); - if (!option->val) - { - printfPQExpBuffer(errorMessage, - libpq_gettext("out of memory\n")); - PQconninfoFree(options); - return NULL; - } - continue; - } - - /* - * Special handling for user - */ - if (strcmp(option->keyword, "user") == 0) - { - option->val = pg_fe_getauthname(errorMessage); - continue; - } - } - return options; } --- 4187,4200 ---- free(buf); /* ! * Fill in defaults if the caller wants that. */ ! if (use_defaults && !conninfo_fill_defaults(options, errorMessage)) { PQconninfoFree(options); return NULL; } return options; } *************** *** 4262,4268 **** conninfo_array_parse(const char *const * keywords, const char *const * values, PQExpBuffer errorMessage, bool use_defaults, int expand_dbname) { - char *tmp; PQconninfoOption *options; PQconninfoOption *str_options = NULL; PQconninfoOption *option; --- 4217,4222 ---- *************** *** 4386,4405 **** conninfo_array_parse(const char *const * keywords, const char *const * values, PQconninfoFree(str_options); /* ! * Stop here if caller doesn't want defaults filled in. */ ! if (!use_defaults) ! return options; /* * If there's a service spec, use it to obtain any not-explicitly-given * parameters. */ if (parseServiceInfo(options, errorMessage)) ! { ! PQconninfoFree(options); ! return NULL; ! } /* * Get the fallback resources for parameters not specified in the conninfo --- 4340,4377 ---- PQconninfoFree(str_options); /* ! * Fill in defaults if the caller wants that. */ ! if (use_defaults && !conninfo_fill_defaults(options, errorMessage)) ! { ! PQconninfoFree(options); ! return NULL; ! } ! ! return options; ! } ! ! /* ! * Fills the connection options array with the default values for unspecified ! * options. ! * ! * Defaults are supplied from a service file, environment variables, etc. ! * ! * Returns TRUE if successful, FALSE otherwise, while filling in errorMessage. ! */ ! static bool ! conninfo_fill_defaults(PQconninfoOption *options, ! PQExpBuffer errorMessage) ! { ! PQconninfoOption *option; ! char *tmp; /* * If there's a service spec, use it to obtain any not-explicitly-given * parameters. */ if (parseServiceInfo(options, errorMessage)) ! return false; /* * Get the fallback resources for parameters not specified in the conninfo *************** *** 4422,4429 **** conninfo_array_parse(const char *const * keywords, const char *const * values, { printfPQExpBuffer(errorMessage, libpq_gettext("out of memory\n")); ! PQconninfoFree(options); ! return NULL; } continue; } --- 4394,4400 ---- { printfPQExpBuffer(errorMessage, libpq_gettext("out of memory\n")); ! return false; } continue; } *************** *** 4440,4447 **** conninfo_array_parse(const char *const * keywords, const char *const * values, { printfPQExpBuffer(errorMessage, libpq_gettext("out of memory\n")); ! PQconninfoFree(options); ! return NULL; } continue; } --- 4411,4417 ---- { printfPQExpBuffer(errorMessage, libpq_gettext("out of memory\n")); ! return false; } continue; } *************** *** 4456,4462 **** conninfo_array_parse(const char *const * keywords, const char *const * values, } } ! return options; } static char * --- 4426,4432 ---- } } ! return true; } static char * *** a/src/interfaces/libpq/fe-connect.c --- b/src/interfaces/libpq/fe-connect.c *************** *** 292,297 **** static PGconn *makeEmptyPGconn(void); --- 292,298 ---- static void fillPGconn(PGconn *conn, PQconninfoOption *connOptions); static void freePGconn(PGconn *conn); static void closePGconn(PGconn *conn); + static PQconninfoOption *conninfo_init(PQExpBuffer errorMessage); static PQconninfoOption *conninfo_parse(const char *conninfo, PQExpBuffer errorMessage, bool use_defaults); static PQconninfoOption *conninfo_array_parse(const char *const * keywords, *************** *** 840,853 **** PQconndefaults(void) return NULL; /* out of memory already :-( */ /* Make a working copy of PQconninfoOptions */ ! connOptions = malloc(sizeof(PQconninfoOptions)); if (connOptions == NULL) - { - printfPQExpBuffer(&errorBuf, - libpq_gettext("out of memory\n")); return NULL; - } - memcpy(connOptions, PQconninfoOptions, sizeof(PQconninfoOptions)); if (!conninfo_fill_defaults(connOptions, &errorBuf)) { --- 841,849 ---- return NULL; /* out of memory already :-( */ /* Make a working copy of PQconninfoOptions */ ! connOptions = conninfo_init(&errorBuf); if (connOptions == NULL) return NULL; if (!conninfo_fill_defaults(connOptions, &errorBuf)) { *************** *** 4005,4010 **** PQconninfoParse(const char *conninfo, char **errmsg) --- 4001,4025 ---- } /* + * Makes a copy of PQconninfoOptions array. + */ + static PQconninfoOption * + conninfo_init(PQExpBuffer errorMessage) + { + PQconninfoOption *options; + + options = malloc(sizeof(PQconninfoOptions)); + if (options == NULL) + { + printfPQExpBuffer(errorMessage, + libpq_gettext("out of memory\n")); + return NULL; + } + memcpy(options, PQconninfoOptions, sizeof(PQconninfoOptions)); + return options; + } + + /* * Conninfo parser routine * * If successful, a malloc'd PQconninfoOption array is returned. *************** *** 4026,4039 **** conninfo_parse(const char *conninfo, PQExpBuffer errorMessage, PQconninfoOption *option; /* Make a working copy of PQconninfoOptions */ ! options = malloc(sizeof(PQconninfoOptions)); if (options == NULL) - { - printfPQExpBuffer(errorMessage, - libpq_gettext("out of memory\n")); return NULL; - } - memcpy(options, PQconninfoOptions, sizeof(PQconninfoOptions)); /* Need a modifiable copy of the input string */ if ((buf = strdup(conninfo)) == NULL) --- 4041,4049 ---- PQconninfoOption *option; /* Make a working copy of PQconninfoOptions */ ! options = conninfo_init(errorMessage); if (options == NULL) return NULL; /* Need a modifiable copy of the input string */ if ((buf = strdup(conninfo)) == NULL) *************** *** 4252,4266 **** conninfo_array_parse(const char *const * keywords, const char *const * values, } /* Make a working copy of PQconninfoOptions */ ! options = malloc(sizeof(PQconninfoOptions)); if (options == NULL) { - printfPQExpBuffer(errorMessage, - libpq_gettext("out of memory\n")); PQconninfoFree(str_options); return NULL; } - memcpy(options, PQconninfoOptions, sizeof(PQconninfoOptions)); i = 0; /* Parse the keywords/values arrays */ --- 4262,4273 ---- } /* Make a working copy of PQconninfoOptions */ ! options = conninfo_init(errorMessage); if (options == NULL) { PQconninfoFree(str_options); return NULL; } i = 0; /* Parse the keywords/values arrays */ ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Trivial libpq refactoring patch (was: Re: Another review of URI for libpq, v7 submission) @ 2012-03-22 16:10 Tom Lane <[email protected]> parent: Alex Shulgin <[email protected]> 0 siblings, 0 replies; 22+ messages in thread From: Tom Lane @ 2012-03-22 16:10 UTC (permalink / raw) To: Alex Shulgin <[email protected]>; +Cc: pgsql-hackers Alex Shulgin <[email protected]> writes: > While working on this fix I've figured out that I need my > conninfo_uri_parse to support use_defaults parameter, like > conninfo(_array)_parse functions do. > The problem is that the block of code which does the defaults handling > is duplicated in both of the above functions. What I'd like to do is > extract it into a separate function to call. What I wouldn't like is > bloating the original URI patch with this unrelated change. Applied with minor adjustments --- notably, I thought conninfo_add_defaults was a better name for the function. regards, tom lane ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-03-22 21:42 Alex <[email protected]> parent: Alex <[email protected]> 1 sibling, 2 replies; 22+ messages in thread From: Alex @ 2012-03-22 21:42 UTC (permalink / raw) To: Marko Kreen <[email protected]>; +Cc: Daniel Farina <[email protected]>; pgsql-hackers Alex <[email protected]> writes: > Marko Kreen <[email protected]> writes: > >> On Thu, Mar 15, 2012 at 11:29:31PM +0200, Alex wrote: >>> https://github.com/a1exsh/postgres/commits/uri >> >> The point of the patch is to have one string with all connection options, >> in standard format, yes? So why does not this work: >> >> db = PQconnectdb("postgres://localhost"); >> >> ? > > Good catch. > > I've figured out that we'll need a bit more intrusive change than simply > overriding the expand_dbname check in conninfo_array_parse (like the > current version does) to support URIs in all PQconnect* variants. Okay, at last here's v9, rebased against current master branch. What's new in this version is parse_connection_string function to be called instead of conninfo_parse. It will check for possible URI in the connection string and dispatch to conninfo_uri_parse if URI was found, otherwise it will fall back to conninfo_parse. In two places in code we don't want to parse the string unless it is deemed a real connection string and not plain dbname. The new function recognized_connection_string is added to check this. Thanks Marko for spotting the problem and thanks Tom for committing the refactoring patch! -- Alex ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-03-27 13:03 Heikki Linnakangas <[email protected]> parent: Alex <[email protected]> 1 sibling, 1 reply; 22+ messages in thread From: Heikki Linnakangas @ 2012-03-27 13:03 UTC (permalink / raw) To: Alex <[email protected]>; +Cc: Marko Kreen <[email protected]>; Daniel Farina <[email protected]>; pgsql-hackers On 22.03.2012 23:42, Alex wrote: > Okay, at last here's v9, rebased against current master branch. Some quick comments on this patch: I see a compiler warning: fe-connect.c: In function ‘conninfo_parse’: fe-connect.c:4113: warning: unused variable ‘option’ Docs are missing. I wonder if you should get an error if you try specify the same option multiple times. At least the behavior needs to be documented. Should %00 be forbidden? The error message is a bit confusing for "postgres://localhost?dbname=%XXfoo": WARNING: ignoring unrecognized URI query parameter: dbname There is in fact nothing wrong with "dbname", it's the %XX in the value that's bogus. Looking at conninfo_uri_decode(), I think it's missing a bounds check, and peeks at two bytes beyond the end of string if the input ends in a '%'. -- Heikki Linnakangas EnterpriseDB http://www.enterprisedb.com ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-03-27 14:13 Alex Shulgin <[email protected]> parent: Heikki Linnakangas <[email protected]> 0 siblings, 0 replies; 22+ messages in thread From: Alex Shulgin @ 2012-03-27 14:13 UTC (permalink / raw) To: Heikki Linnakangas <[email protected]>; +Cc: Marko Kreen <[email protected]>; Daniel Farina <[email protected]>; pgsql-hackers Heikki Linnakangas <[email protected]> writes: > On 22.03.2012 23:42, Alex wrote: >> Okay, at last here's v9, rebased against current master branch. > > Some quick comments on this patch: Heikki, thank you for taking a look at this! > I see a compiler warning: > fe-connect.c: In function ‘conninfo_parse’: > fe-connect.c:4113: warning: unused variable ‘option’ The warning is due to the earlier commit e9ce658b. I believe the above line supposed to go away. > Docs are missing. Yes, my plan is to focus on the documentation and code comments while sorting out any remaining issues with the code. > I wonder if you should get an error if you try specify the same option > multiple times. At least the behavior needs to be documented. Since conninfo strings may contain duplicated keywords and the latter just takes precedence, I think we should just do the same with URIs (which we already do.) I don't see the behavior of conninfo strings documented anywhere, however. > Should %00 be forbidden? Probably yes, good spot. > The error message is a bit confusing for > "postgres://localhost?dbname=%XXfoo": > WARNING: ignoring unrecognized URI query parameter: dbname > There is in fact nothing wrong with "dbname", it's the %XX in the > value that's bogus. Hm, yes, that's a bug. Looks like conninfo_uri_parse_params needs to be adjusted to properly pass the error message generated by conninfo_store_uri_encoded_value. I wonder if examining the errorMessage buffer to tell if it's a hard error (it's going to be empty in the case of ignoreMissing=true) is a good practice. > Looking at conninfo_uri_decode(), I think it's missing a bounds check, > and peeks at two bytes beyond the end of string if the input ends in a > %'. No, in that case what happens on L4919 is this: we dereference q which is pointing at NUL terminator and pass the value to the first get_hexdigit in the "if" condition, the pointer itself is then incremented and does point beyond the end of string, but since get_hexdigit returns FALSE we don't call the second get_hexdigit, so we don't dereference the invalid pointer. There is a comment right before that "if" which says just that. -- Alex ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-03-27 17:22 Peter Eisentraut <[email protected]> parent: Alex <[email protected]> 1 sibling, 1 reply; 22+ messages in thread From: Peter Eisentraut @ 2012-03-27 17:22 UTC (permalink / raw) To: Alex <[email protected]>; +Cc: pgsql-hackers On tor, 2012-03-22 at 23:42 +0200, Alex wrote: > Okay, at last here's v9, rebased against current master branch. Attached is a patch on top of your v9 with two small fixes: - Don't provide a check target in libpq/Makefile if it's not implemented. - Use the configured port number for running the tests (otherwise it runs against my system installation, for example). Attachments: [text/x-patch] libpq-uri-v9+petere.patch (1009B, ../../[email protected]/2-libpq-uri-v9+petere.patch) download | inline diff: diff --git i/src/interfaces/libpq/Makefile w/src/interfaces/libpq/Makefile index f19f272..266e3db 100644 --- i/src/interfaces/libpq/Makefile +++ w/src/interfaces/libpq/Makefile @@ -121,7 +121,7 @@ install: all installdirs install-lib $(INSTALL_DATA) $(srcdir)/pqexpbuffer.h '$(DESTDIR)$(includedir_internal)' $(INSTALL_DATA) $(srcdir)/pg_service.conf.sample '$(DESTDIR)$(datadir)/pg_service.conf.sample' -check installcheck: +installcheck: $(MAKE) -C test $@ installdirs: installdirs-lib diff --git i/src/interfaces/libpq/test/Makefile w/src/interfaces/libpq/test/Makefile index 964bb20..869a2f0 100644 --- i/src/interfaces/libpq/test/Makefile +++ w/src/interfaces/libpq/test/Makefile @@ -5,7 +5,7 @@ include $(top_builddir)/src/Makefile.global all: installcheck installcheck: - BINDIR='$(bindir)' SUBDIR='$(subdir)' $(SHELL) ./regress.sh + BINDIR='$(bindir)' PGPORT='$(DEF_PGPORT)' SUBDIR='$(subdir)' $(SHELL) ./regress.sh clean distclean maintainer-clean: rm -f regress.out regress.diff ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-03-27 19:21 Alex <[email protected]> parent: Peter Eisentraut <[email protected]> 0 siblings, 1 reply; 22+ messages in thread From: Alex @ 2012-03-27 19:21 UTC (permalink / raw) To: Peter Eisentraut <[email protected]>; +Cc: pgsql-hackers Peter Eisentraut <[email protected]> writes: > On tor, 2012-03-22 at 23:42 +0200, Alex wrote: >> Okay, at last here's v9, rebased against current master branch. > > Attached is a patch on top of your v9 with two small fixes: > > - Don't provide a check target in libpq/Makefile if it's not > implemented. > > - Use the configured port number for running the tests (otherwise it > runs against my system installation, for example). Neat, thank you. ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-03-27 22:49 Alex <[email protected]> parent: Alex <[email protected]> 0 siblings, 1 reply; 22+ messages in thread From: Alex @ 2012-03-27 22:49 UTC (permalink / raw) To: Peter Eisentraut <[email protected]>; +Cc: Heikki Linnakangas <[email protected]>; pgsql-hackers Alex <[email protected]> writes: > Peter Eisentraut <[email protected]> writes: >> >> Attached is a patch on top of your v9 with two small fixes: >> >> - Don't provide a check target in libpq/Makefile if it's not >> implemented. >> >> - Use the configured port number for running the tests (otherwise it >> runs against my system installation, for example). > > Neat, thank you. Attached is a gzipped v10, complete with the above fixes and fixes to bugs found by Heikki. Documentation and code comments are also finally updated. Of all the command-line utilities which can accept conninfo string, only psql mentions that, so only its documentation was updated. Other utilities, like pg_dump and pg_restore can also work with either conninfo or URI, however this remains undocumented. -- Alex Attachments: [application/octet-stream] libpq-uri-v10.patch.gz (10.1K, ../../[email protected]/2-libpq-uri-v10.patch.gz) download ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-04-05 16:52 Peter Eisentraut <[email protected]> parent: Alex <[email protected]> 0 siblings, 1 reply; 22+ messages in thread From: Peter Eisentraut @ 2012-04-05 16:52 UTC (permalink / raw) To: Alex <[email protected]>; +Cc: Heikki Linnakangas <[email protected]>; pgsql-hackers On ons, 2012-03-28 at 01:49 +0300, Alex wrote: > Attached is a gzipped v10, complete with the above fixes and fixes to > bugs found by Heikki. Documentation and code comments are also > finally updated. The compiler warning is still there: fe-connect.c: In function ‘conninfo_parse’: fe-connect.c:4122:20: error: unused variable ‘option’ [-Werror=unused-variable] ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-04-05 22:10 Alvaro Herrera <[email protected]> parent: Peter Eisentraut <[email protected]> 0 siblings, 1 reply; 22+ messages in thread From: Alvaro Herrera @ 2012-04-05 22:10 UTC (permalink / raw) To: Peter Eisentraut <[email protected]>; +Cc: Alex <[email protected]>; Heikki Linnakangas <[email protected]>; pgsql-hackers Excerpts from Peter Eisentraut's message of jue abr 05 13:52:13 -0300 2012: > On ons, 2012-03-28 at 01:49 +0300, Alex wrote: > > Attached is a gzipped v10, complete with the above fixes and fixes to > > bugs found by Heikki. Documentation and code comments are also > > finally updated. > > The compiler warning is still there: > > fe-connect.c: In function ‘conninfo_parse’: > fe-connect.c:4122:20: error: unused variable ‘option’ [-Werror=unused-variable] Here's an updated patch, including this fix and others. (Most notable the fact that I got rid of conninfo_store_uri_encoded_value, instead expanding conninfo_storeval a bit). I also fixed the test script to run in VPATH. I intend to commit this shortly, barring objection from Peter who is listed as "committer" in the CF app. I think the only thing I'm not really sure about is the usage of the <synopsis> tag to mark example URIs in the docs. It looks to me that they should mostly be <literal> instead, but I'm not really sure about that either -- I'm suspecting the PDF output would look rather horrible. -- Álvaro Herrera <[email protected]> The PostgreSQL Company - Command Prompt, Inc. PostgreSQL Replication, Consulting, Custom Development, 24x7 support Attachments: [application/x-gzip] libpq-uri-v11.patch.gz (10.6K, ../../[email protected]/2-libpq-uri-v11.patch.gz) download ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-04-06 03:25 Alvaro Herrera <[email protected]> parent: Alvaro Herrera <[email protected]> 0 siblings, 1 reply; 22+ messages in thread From: Alvaro Herrera @ 2012-04-06 03:25 UTC (permalink / raw) To: Peter Eisentraut <[email protected]>; +Cc: Alex <[email protected]>; Heikki Linnakangas <[email protected]>; pgsql-hackers Excerpts from Alvaro Herrera's message of jue abr 05 19:10:25 -0300 2012: > I think the only thing I'm not really sure about is the usage of the > <synopsis> tag to mark example URIs in the docs. It looks to me that > they should mostly be <literal> instead, but I'm not really sure about > that either -- I'm suspecting the PDF output would look rather horrible. Some moments of radical thinking later, I became unhappy with the fact that the conninfo stuff and parameter keywords are all crammed in the PQconnectdbParams description. This feels wrong to me, even more so after we expand it even more to add URIs to the mix. I think it's better to create a separate sect1 (which I've entitled "Connection Strings") which explains the conninfo and URI formats as well as accepted keywords. The new section is referenced from the multiple places that need it, without having to point to PQconnectdbParams. Thoughts? Wording suggestions are welcome. dblink_connect docs should also have a mention of URIs now: alvherre=# select dblink_connect('postgresql://localhost:55432'); dblink_connect ---------------- OK (1 fila) -- Álvaro Herrera <[email protected]> The PostgreSQL Company - Command Prompt, Inc. PostgreSQL Replication, Consulting, Custom Development, 24x7 support Attachments: [application/octet-stream] libpq-docs.patch (49.1K, ../../[email protected]/2-libpq-docs.patch) download | inline diff: diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 0ec501e..568e456 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -119,7 +119,9 @@ PGconn *PQconnectdbParams(const char * const *keywords, <para> When <literal>expand_dbname</literal> is non-zero, the <parameter>dbname</parameter> key word value is allowed to be recognized - as a <parameter>conninfo</parameter> string. See below for details. + as a connection string. More details on that, as well as a list of + currently recognized parameter key words, appears in + <xref linkend="libpq-connstring">. </para> <para> @@ -130,507 +132,6 @@ PGconn *PQconnectdbParams(const char * const *keywords, </para> <para> - The currently recognized parameter key words are: - - <variablelist> - <varlistentry id="libpq-connect-host" xreflabel="host"> - <term><literal>host</literal></term> - <listitem> - <para> - Name of host to connect to.<indexterm><primary>host name</></> - 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 behavior when <literal>host</literal> is not specified - is to connect to a Unix-domain - socket<indexterm><primary>Unix domain socket</></> in - <filename>/tmp</filename> (or whatever socket directory was specified - when <productname>PostgreSQL</> was built). On machines without - Unix-domain sockets, the default is to connect to <literal>localhost</>. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-hostaddr" xreflabel="hostaddr"> - <term><literal>hostaddr</literal></term> - <listitem> - <para> - Numeric IP address of host to connect to. This should be in the - standard IPv4 address format, e.g., <literal>172.28.40.9</>. If - your machine supports IPv6, you can also use those addresses. - TCP/IP communication is - always used when a nonempty string is specified for this parameter. - </para> - - <para> - Using <literal>hostaddr</> instead of <literal>host</> allows the - application to avoid a host name look-up, which might be important - in applications with time constraints. However, a host name is - required for Kerberos, GSSAPI, or SSPI authentication - methods, as well as for <literal>verify-full</> SSL - certificate verification. The following rules are used: - <itemizedlist> - <listitem> - <para> - If <literal>host</> is specified without <literal>hostaddr</>, - a host name lookup occurs. - </para> - </listitem> - <listitem> - <para> - If <literal>hostaddr</> is specified without <literal>host</>, - the value for <literal>hostaddr</> gives the server network address. - The connection attempt will fail if the authentication - method requires a host name. - </para> - </listitem> - <listitem> - <para> - If both <literal>host</> and <literal>hostaddr</> are specified, - the value for <literal>hostaddr</> gives the server network address. - The value for <literal>host</> is ignored unless the - authentication method requires it, in which case it will be - used as the host name. - </para> - </listitem> - </itemizedlist> - Note that authentication is likely to fail if <literal>host</> - is not the name of the server at network address <literal>hostaddr</>. - Also, note that <literal>host</> rather than <literal>hostaddr</> - is used to identify the connection in <filename>~/.pgpass</> (see - <xref linkend="libpq-pgpass">). - </para> - - <para> - Without either a host name or host address, - <application>libpq</application> will connect using a - local Unix-domain socket; or on machines without Unix-domain - sockets, it will attempt to connect to <literal>localhost</>. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-port" xreflabel="port"> - <term><literal>port</literal></term> - <listitem> - <para> - Port number to connect to at the server host, or socket file - name extension for Unix-domain - connections.<indexterm><primary>port</></> - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-dbname" xreflabel="dbname"> - <term><literal>dbname</literal></term> - <listitem> - <para> - The database name. Defaults to be the same as the user name. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-user" xreflabel="user"> - <term><literal>user</literal></term> - <listitem> - <para> - <productname>PostgreSQL</productname> user name to connect as. - Defaults to be the same as the operating system name of the user - running the application. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-password" xreflabel="password"> - <term><literal>password</literal></term> - <listitem> - <para> - Password to be used if the server demands password authentication. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-connect-timeout" xreflabel="connect_timeout"> - <term><literal>connect_timeout</literal></term> - <listitem> - <para> - 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. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-client-encoding" xreflabel="client_encoding"> - <term><literal>client_encoding</literal></term> - <listitem> - <para> - This sets the <varname>client_encoding</varname> - configuration parameter for this connection. In addition to - the values accepted by the corresponding server option, you - can use <literal>auto</literal> to determine the right - encoding from the current locale in the client - (<envar>LC_CTYPE</envar> environment variable on Unix - systems). - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-options" xreflabel="options"> - <term><literal>options</literal></term> - <listitem> - <para> - Adds command-line options to send to the server at run-time. - For example, setting this to <literal>-c geqo=off</> sets the - session's value of the <varname>geqo</> parameter to - <literal>off</>. For a detailed discussion of the available - options, consult <xref linkend="runtime-config">. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-application-name" xreflabel="application_name"> - <term><literal>application_name</literal></term> - <listitem> - <para> - Specifies a value for the <xref linkend="guc-application-name"> - configuration parameter. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-fallback-application-name" xreflabel="fallback_application_name"> - <term><literal>fallback_application_name</literal></term> - <listitem> - <para> - Specifies a fallback value for the <xref - linkend="guc-application-name"> configuration parameter. - This value will be used if no value has been given for - <literal>application_name</> via a connection parameter or the - <envar>PGAPPNAME</envar> environment variable. Specifying - a fallback name is useful in generic utility programs that - wish to set a default application name but allow it to be - overridden by the user. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-keepalives" xreflabel="keepalives"> - <term><literal>keepalives</literal></term> - <listitem> - <para> - Controls whether client-side TCP keepalives are used. The default - value is 1, meaning on, but you can change this to 0, meaning off, - if keepalives are not wanted. This parameter is ignored for - connections made via a Unix-domain socket. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-keepalives-idle" xreflabel="keepalives_idle"> - <term><literal>keepalives_idle</literal></term> - <listitem> - <para> - Controls the number of seconds of inactivity after which TCP should - send a keepalive message to the server. A value of zero uses the - system default. This parameter is ignored for connections made via a - Unix-domain socket, or if keepalives are disabled. It is only supported - on systems where the <symbol>TCP_KEEPIDLE</> or <symbol>TCP_KEEPALIVE</> - socket option is available, and on Windows; on other systems, it has no - effect. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-keepalives-interval" xreflabel="keepalives_interval"> - <term><literal>keepalives_interval</literal></term> - <listitem> - <para> - Controls the number of seconds after which a TCP keepalive message - that is not acknowledged by the server should be retransmitted. A - value of zero uses the system default. This parameter is ignored for - connections made via a Unix-domain socket, or if keepalives are disabled. - It is only supported on systems where the <symbol>TCP_KEEPINTVL</> - socket option is available, and on Windows; on other systems, it has no - effect. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-keepalives-count" xreflabel="keepalives_count"> - <term><literal>keepalives_count</literal></term> - <listitem> - <para> - Controls the number of TCP keepalives that can be lost before the - client's connection to the server is considered dead. A value of - zero uses the system default. This parameter is ignored for - connections made via a Unix-domain socket, or if keepalives are disabled. - It is only supported on systems where the <symbol>TCP_KEEPCNT</> - socket option is available; on other systems, it has no effect. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-tty" xreflabel="tty"> - <term><literal>tty</literal></term> - <listitem> - <para> - Ignored (formerly, this specified where to send server debug output). - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-sslmode" xreflabel="sslmode"> - <term><literal>sslmode</literal></term> - <listitem> - <para> - This option determines whether or with what priority a secure - <acronym>SSL</> TCP/IP connection will be negotiated with the - server. There are six modes: - - <variablelist> - <varlistentry> - <term><literal>disable</literal></term> - <listitem> - <para> - only try a non-<acronym>SSL</> connection - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>allow</literal></term> - <listitem> - <para> - first try a non-<acronym>SSL</> connection; if that - fails, try an <acronym>SSL</> connection - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>prefer</literal> (default)</term> - <listitem> - <para> - first try an <acronym>SSL</> connection; if that fails, - try a non-<acronym>SSL</> connection - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>require</literal></term> - <listitem> - <para> - only try an <acronym>SSL</> connection. If a root CA - file is present, verify the certificate in the same way as - if <literal>verify-ca</literal> was specified - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>verify-ca</literal></term> - <listitem> - <para> - only try an <acronym>SSL</> connection, and verify that - the server certificate is issued by a trusted - certificate authority (<acronym>CA</>) - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>verify-full</literal></term> - <listitem> - <para> - only try an <acronym>SSL</> connection, verify that the - server certificate is issued by a - trusted <acronym>CA</> and that the server host name - matches that in the certificate - </para> - </listitem> - </varlistentry> - </variablelist> - - See <xref linkend="libpq-ssl"> for a detailed description of how - these options work. - </para> - - <para> - <literal>sslmode</> is ignored for Unix domain socket - communication. - If <productname>PostgreSQL</> is compiled without SSL support, - using options <literal>require</>, <literal>verify-ca</>, or - <literal>verify-full</> will cause an error, while - options <literal>allow</> and <literal>prefer</> will be - accepted but <application>libpq</> will not actually attempt - an <acronym>SSL</> - connection.<indexterm><primary>SSL</><secondary - sortas="libpq">with libpq</></indexterm> - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-requiressl" xreflabel="requiressl"> - <term><literal>requiressl</literal></term> - <listitem> - <para> - This option is deprecated in favor of the <literal>sslmode</> - setting. - </para> - - <para> - If set to 1, an <acronym>SSL</acronym> connection to the server - is required (this is equivalent to <literal>sslmode</> - <literal>require</>). <application>libpq</> will then refuse - to connect if the server does not accept an - <acronym>SSL</acronym> connection. If set to 0 (default), - <application>libpq</> will negotiate the connection type with - the server (equivalent to <literal>sslmode</> - <literal>prefer</>). This option is only available if - <productname>PostgreSQL</> is compiled with SSL support. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-sslcompression" xreflabel="sslcompression"> - <term><literal>sslcompression</literal></term> - <listitem> - <para> - If set to 1 (default), data sent over SSL connections will be - compressed (this requires <productname>OpenSSL</> version - 0.9.8 or later). - If set to 0, compression will be disabled (this requires - <productname>OpenSSL</> 1.0.0 or later). - This parameter is ignored if a connection without SSL is made, - or if the version of <productname>OpenSSL</> used does not support - it. - </para> - <para> - Compression uses CPU time, but can improve throughput if - the network is the bottleneck. - Disabling compression can improve response time and throughput - if CPU performance is the limiting factor. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-sslcert" xreflabel="sslcert"> - <term><literal>sslcert</literal></term> - <listitem> - <para> - This parameter specifies the file name of the client SSL - certificate, replacing the default - <filename>~/.postgresql/postgresql.crt</>. - This parameter is ignored if an SSL connection is not made. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-sslkey" xreflabel="sslkey"> - <term><literal>sslkey</literal></term> - <listitem> - <para> - This parameter specifies the location for the secret key used for - the client certificate. It can either specify a file name that will - be used instead of the default - <filename>~/.postgresql/postgresql.key</>, or it can specify a key - obtained from an external <quote>engine</> (engines are - <productname>OpenSSL</> loadable modules). An external engine - specification should consist of a colon-separated engine name and - an engine-specific key identifier. This parameter is ignored if an - SSL connection is not made. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-sslrootcert" xreflabel="sslrootcert"> - <term><literal>sslrootcert</literal></term> - <listitem> - <para> - This parameter specifies the name of a file containing SSL - certificate authority (<acronym>CA</>) certificate(s). - If the file exists, the server's certificate will be verified - to be signed by one of these authorities. The default is - <filename>~/.postgresql/root.crt</>. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-sslcrl" xreflabel="sslcrl"> - <term><literal>sslcrl</literal></term> - <listitem> - <para> - This parameter specifies the file name of the SSL certificate - revocation list (CRL). Certificates listed in this file, if it - exists, will be rejected while attempting to authenticate the - server's certificate. The default is - <filename>~/.postgresql/root.crl</>. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-requirepeer" xreflabel="requirepeer"> - <term><literal>requirepeer</literal></term> - <listitem> - <para> - This parameter specifies the operating-system user name of the - server, for example <literal>requirepeer=postgres</literal>. - When making a Unix-domain socket connection, if this - parameter is set, the client checks at the beginning of the - connection that the server process is running under the specified - user name; if it is not, the connection is aborted with an error. - This parameter can be used to provide server authentication similar - to that available with SSL certificates on TCP/IP connections. - (Note that if the Unix-domain socket is in - <filename>/tmp</filename> or another publicly writable location, - any user could start a server listening there. Use this parameter - to ensure that you are connected to a server run by a trusted user.) - This option is only supported on platforms for which the - <literal>peer</> authentication method is implemented; see - <xref linkend="auth-peer">. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-krbsrvname" xreflabel="krbsrvname"> - <term><literal>krbsrvname</literal></term> - <listitem> - <para> - Kerberos service name to use when authenticating with Kerberos 5 - or GSSAPI. - This must match the service name specified in the server - configuration for Kerberos authentication to succeed. (See also - <xref linkend="kerberos-auth"> and <xref linkend="gssapi-auth">.) - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-gsslib" xreflabel="gsslib"> - <term><literal>gsslib</literal></term> - <listitem> - <para> - GSS library to use for GSSAPI authentication. Only used on Windows. - Set to <literal>gssapi</literal> to force libpq to use the GSSAPI - library for authentication instead of the default SSPI. - </para> - </listitem> - </varlistentry> - - <varlistentry id="libpq-connect-service" xreflabel="service"> - <term><literal>service</literal></term> - <listitem> - <para> - Service name to use for additional parameters. It specifies a service - name in <filename>pg_service.conf</filename> that holds additional connection parameters. - This allows applications to specify only a service name so connection parameters - can be centrally maintained. See <xref linkend="libpq-pgservice">. - </para> - </listitem> - </varlistentry> - </variablelist> - If any parameter is unspecified, then the corresponding environment variable (see <xref linkend="libpq-envars">) is checked. If the environment variable is not set either, @@ -638,20 +139,11 @@ PGconn *PQconnectdbParams(const char * const *keywords, </para> <para> - If <literal>expand_dbname</literal> is non-zero and - <parameter>dbname</parameter> contains an <symbol>=</symbol> sign, it - is taken as a <parameter>conninfo</parameter> string in exactly the same way as - if it had been passed to <function>PQconnectdb</function>(see below). Previously - processed key words will be overridden by key words in the - <parameter>conninfo</parameter> string. - </para> - - <para> - In general key words are processed from the beginning of these arrays in index - order. The effect of this is that when key words are repeated, the last processed - value is retained. Therefore, through careful placement of the - <parameter>dbname</parameter> key word, it is possible to determine what may - be overridden by a <parameter>conninfo</parameter> string, and what may not. + In general key words are processed from the beginning of these arrays in index + order. The effect of this is that when key words are repeated, the last processed + value is retained. Therefore, through careful placement of the + <parameter>dbname</parameter> key word, it is possible to determine what may + be overridden by a <parameter>conninfo</parameter> string, and what may not. </para> </listitem> @@ -675,19 +167,13 @@ PGconn *PQconnectdb(const char *conninfo); <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> + contain one or more parameter settings separated by whitespace, + or it can contain a <acronym>URI</acronym>. + See <xref linkend="libpq-connstring"> for details. + </para> - <para> - The currently recognized parameter key words are the same as above. - </para> - </listitem> + + </listitem> </varlistentry> <varlistentry id="libpq-pqsetdblogin"> @@ -714,10 +200,11 @@ PGconn *PQsetdbLogin(const char *pghost, </para> <para> - If the <parameter>dbName</parameter> contains an <symbol>=</symbol> sign, it + If the <parameter>dbName</parameter> contains + an <symbol>=</symbol> sign or has a valid connection <acronym>URI</acronym> prefix, it is taken as a <parameter>conninfo</parameter> string in exactly the same way as if it had been passed to <function>PQconnectdb</function>, and the remaining - parameters are then applied as above. + parameters are then applied as specified in <xref linkend="libpq-connstring">. </para> </listitem> </varlistentry> @@ -795,7 +282,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); <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>PQconnectdbParams</function> above for details. + these parameters in <xref linkend="libpq-connstring"> for details. </para> </listitem> @@ -6428,6 +5915,607 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) </sect2> </sect1> + <sect1 id="libpq-connstring"> + <title>Connection Strings</title> + + <indexterm zone="libpq-connstring"> + <primary><literal>conninfo</literal></primary> + </indexterm> + + <indexterm zone="libpq-connstring"> + <primary><literal>URI</literal></primary> + </indexterm> + + <para> + Several <application>libpq</> functions parse a user-specified string to obtain + connection parameters. There are two accepted formats for these strings: + plain <literal>keyword = value</literal> strings, and URIs. + </para> + + <para> + In the first format, 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 listed below. + </para> + + <para> + The general form for connection <acronym>URI</acronym> is the + following: +<synopsis> +postgresql://username:password@hostname:port/database?param1=value1&param2=value2&... +</synopsis> + </para> + + <para> + The <acronym>URI</acronym> designator can be + either <literal>postgresql://</literal> or + <literal>postgres://</literal> and each of the <acronym>URI</acronym> parts is + optional. The following examples illustrate valid <acronym>URI</acronym> syntax + uses: +<synopsis> +postgresql:// +postgresql://localhost +postgresql://localhost:5433 +postgresql://localhost/mydb +postgresql://user@localhost +postgresql://user:secret@localhost +postgresql://other@localhost/otherdb +</synopsis> + </para> + + <para> + Additional connection parameters may optionally follow the base <acronym>URI</acronym>. + Any connection parameters not corresponding to key words listed + below are ignored and a warning message about them is sent to + <filename>stderr</filename>. + </para> + + <para> + For improved compatibility with JDBC connection <acronym>URI</acronym> + syntax, instances of parameter <literal>ssl=true</literal> are translated + into <literal>sslmode=require</literal> (see above.) + </para> + + <para> + Percent-encoding may be used to include a symbol with special + meaning in any of the <acronym>URI</acronym> parts. + </para> + + <para> + The host part may be either hostname or an IP address. To specify an + IPv6 host address, enclose it in square brackets: +<synopsis> +postgresql://[::1]/database +</synopsis> + As a special case, a host part which starts with <symbol>/</symbol> is + treated as a local Unix socket directory to look for the connection + socket special file: +<synopsis> +postgresql:///path/to/pgsql/socket/dir +</synopsis> + The whole connection string up to the extra parameters designator + (<symbol>?</symbol>) is treated as the absolute path to the socket + directory (<literal>/path/to/pgsql/socket/dir</literal> in this + example.) To specify a non-default database name in this case use the + following syntax: +<synopsis> +postgresql:///path/to/pgsql/socket/dir?dbname=other +</synopsis> + </para> + + <para> + The currently recognized parameter key words are: + + <variablelist> + <varlistentry id="libpq-connect-host" xreflabel="host"> + <term><literal>host</literal></term> + <listitem> + <para> + Name of host to connect to.<indexterm><primary>host name</></> + 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 behavior when <literal>host</literal> is not specified + is to connect to a Unix-domain + socket<indexterm><primary>Unix domain socket</></> in + <filename>/tmp</filename> (or whatever socket directory was specified + when <productname>PostgreSQL</> was built). On machines without + Unix-domain sockets, the default is to connect to <literal>localhost</>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-hostaddr" xreflabel="hostaddr"> + <term><literal>hostaddr</literal></term> + <listitem> + <para> + Numeric IP address of host to connect to. This should be in the + standard IPv4 address format, e.g., <literal>172.28.40.9</>. If + your machine supports IPv6, you can also use those addresses. + TCP/IP communication is + always used when a nonempty string is specified for this parameter. + </para> + + <para> + Using <literal>hostaddr</> instead of <literal>host</> allows the + application to avoid a host name look-up, which might be important + in applications with time constraints. However, a host name is + required for Kerberos, GSSAPI, or SSPI authentication + methods, as well as for <literal>verify-full</> SSL + certificate verification. The following rules are used: + <itemizedlist> + <listitem> + <para> + If <literal>host</> is specified without <literal>hostaddr</>, + a host name lookup occurs. + </para> + </listitem> + <listitem> + <para> + If <literal>hostaddr</> is specified without <literal>host</>, + the value for <literal>hostaddr</> gives the server network address. + The connection attempt will fail if the authentication + method requires a host name. + </para> + </listitem> + <listitem> + <para> + If both <literal>host</> and <literal>hostaddr</> are specified, + the value for <literal>hostaddr</> gives the server network address. + The value for <literal>host</> is ignored unless the + authentication method requires it, in which case it will be + used as the host name. + </para> + </listitem> + </itemizedlist> + Note that authentication is likely to fail if <literal>host</> + is not the name of the server at network address <literal>hostaddr</>. + Also, note that <literal>host</> rather than <literal>hostaddr</> + is used to identify the connection in <filename>~/.pgpass</> (see + <xref linkend="libpq-pgpass">). + </para> + + <para> + Without either a host name or host address, + <application>libpq</application> will connect using a + local Unix-domain socket; or on machines without Unix-domain + sockets, it will attempt to connect to <literal>localhost</>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-port" xreflabel="port"> + <term><literal>port</literal></term> + <listitem> + <para> + Port number to connect to at the server host, or socket file + name extension for Unix-domain + connections.<indexterm><primary>port</></> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-dbname" xreflabel="dbname"> + <term><literal>dbname</literal></term> + <listitem> + <para> + The database name. Defaults to be the same as the user name. + See <xref linkend="libpq-connstring"> for more details. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-user" xreflabel="user"> + <term><literal>user</literal></term> + <listitem> + <para> + <productname>PostgreSQL</productname> user name to connect as. + Defaults to be the same as the operating system name of the user + running the application. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-password" xreflabel="password"> + <term><literal>password</literal></term> + <listitem> + <para> + Password to be used if the server demands password authentication. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-connect-timeout" xreflabel="connect_timeout"> + <term><literal>connect_timeout</literal></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-client-encoding" xreflabel="client_encoding"> + <term><literal>client_encoding</literal></term> + <listitem> + <para> + This sets the <varname>client_encoding</varname> + configuration parameter for this connection. In addition to + the values accepted by the corresponding server option, you + can use <literal>auto</literal> to determine the right + encoding from the current locale in the client + (<envar>LC_CTYPE</envar> environment variable on Unix + systems). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-options" xreflabel="options"> + <term><literal>options</literal></term> + <listitem> + <para> + Adds command-line options to send to the server at run-time. + For example, setting this to <literal>-c geqo=off</> sets the + session's value of the <varname>geqo</> parameter to + <literal>off</>. For a detailed discussion of the available + options, consult <xref linkend="runtime-config">. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-application-name" xreflabel="application_name"> + <term><literal>application_name</literal></term> + <listitem> + <para> + Specifies a value for the <xref linkend="guc-application-name"> + configuration parameter. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-fallback-application-name" xreflabel="fallback_application_name"> + <term><literal>fallback_application_name</literal></term> + <listitem> + <para> + Specifies a fallback value for the <xref + linkend="guc-application-name"> configuration parameter. + This value will be used if no value has been given for + <literal>application_name</> via a connection parameter or the + <envar>PGAPPNAME</envar> environment variable. Specifying + a fallback name is useful in generic utility programs that + wish to set a default application name but allow it to be + overridden by the user. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-keepalives" xreflabel="keepalives"> + <term><literal>keepalives</literal></term> + <listitem> + <para> + Controls whether client-side TCP keepalives are used. The default + value is 1, meaning on, but you can change this to 0, meaning off, + if keepalives are not wanted. This parameter is ignored for + connections made via a Unix-domain socket. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-keepalives-idle" xreflabel="keepalives_idle"> + <term><literal>keepalives_idle</literal></term> + <listitem> + <para> + Controls the number of seconds of inactivity after which TCP should + send a keepalive message to the server. A value of zero uses the + system default. This parameter is ignored for connections made via a + Unix-domain socket, or if keepalives are disabled. It is only supported + on systems where the <symbol>TCP_KEEPIDLE</> or <symbol>TCP_KEEPALIVE</> + socket option is available, and on Windows; on other systems, it has no + effect. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-keepalives-interval" xreflabel="keepalives_interval"> + <term><literal>keepalives_interval</literal></term> + <listitem> + <para> + Controls the number of seconds after which a TCP keepalive message + that is not acknowledged by the server should be retransmitted. A + value of zero uses the system default. This parameter is ignored for + connections made via a Unix-domain socket, or if keepalives are disabled. + It is only supported on systems where the <symbol>TCP_KEEPINTVL</> + socket option is available, and on Windows; on other systems, it has no + effect. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-keepalives-count" xreflabel="keepalives_count"> + <term><literal>keepalives_count</literal></term> + <listitem> + <para> + Controls the number of TCP keepalives that can be lost before the + client's connection to the server is considered dead. A value of + zero uses the system default. This parameter is ignored for + connections made via a Unix-domain socket, or if keepalives are disabled. + It is only supported on systems where the <symbol>TCP_KEEPCNT</> + socket option is available; on other systems, it has no effect. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-tty" xreflabel="tty"> + <term><literal>tty</literal></term> + <listitem> + <para> + Ignored (formerly, this specified where to send server debug output). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslmode" xreflabel="sslmode"> + <term><literal>sslmode</literal></term> + <listitem> + <para> + This option determines whether or with what priority a secure + <acronym>SSL</> TCP/IP connection will be negotiated with the + server. There are six modes: + + <variablelist> + <varlistentry> + <term><literal>disable</literal></term> + <listitem> + <para> + only try a non-<acronym>SSL</> connection + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>allow</literal></term> + <listitem> + <para> + first try a non-<acronym>SSL</> connection; if that + fails, try an <acronym>SSL</> connection + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>prefer</literal> (default)</term> + <listitem> + <para> + first try an <acronym>SSL</> connection; if that fails, + try a non-<acronym>SSL</> connection + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>require</literal></term> + <listitem> + <para> + only try an <acronym>SSL</> connection. If a root CA + file is present, verify the certificate in the same way as + if <literal>verify-ca</literal> was specified + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>verify-ca</literal></term> + <listitem> + <para> + only try an <acronym>SSL</> connection, and verify that + the server certificate is issued by a trusted + certificate authority (<acronym>CA</>) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>verify-full</literal></term> + <listitem> + <para> + only try an <acronym>SSL</> connection, verify that the + server certificate is issued by a + trusted <acronym>CA</> and that the server host name + matches that in the certificate + </para> + </listitem> + </varlistentry> + </variablelist> + + See <xref linkend="libpq-ssl"> for a detailed description of how + these options work. + </para> + + <para> + <literal>sslmode</> is ignored for Unix domain socket + communication. + If <productname>PostgreSQL</> is compiled without SSL support, + using options <literal>require</>, <literal>verify-ca</>, or + <literal>verify-full</> will cause an error, while + options <literal>allow</> and <literal>prefer</> will be + accepted but <application>libpq</> will not actually attempt + an <acronym>SSL</> + connection.<indexterm><primary>SSL</><secondary + sortas="libpq">with libpq</></indexterm> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-requiressl" xreflabel="requiressl"> + <term><literal>requiressl</literal></term> + <listitem> + <para> + This option is deprecated in favor of the <literal>sslmode</> + setting. + </para> + + <para> + If set to 1, an <acronym>SSL</acronym> connection to the server + is required (this is equivalent to <literal>sslmode</> + <literal>require</>). <application>libpq</> will then refuse + to connect if the server does not accept an + <acronym>SSL</acronym> connection. If set to 0 (default), + <application>libpq</> will negotiate the connection type with + the server (equivalent to <literal>sslmode</> + <literal>prefer</>). This option is only available if + <productname>PostgreSQL</> is compiled with SSL support. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslcompression" xreflabel="sslcompression"> + <term><literal>sslcompression</literal></term> + <listitem> + <para> + If set to 1 (default), data sent over SSL connections will be + compressed (this requires <productname>OpenSSL</> version + 0.9.8 or later). + If set to 0, compression will be disabled (this requires + <productname>OpenSSL</> 1.0.0 or later). + This parameter is ignored if a connection without SSL is made, + or if the version of <productname>OpenSSL</> used does not support + it. + </para> + <para> + Compression uses CPU time, but can improve throughput if + the network is the bottleneck. + Disabling compression can improve response time and throughput + if CPU performance is the limiting factor. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslcert" xreflabel="sslcert"> + <term><literal>sslcert</literal></term> + <listitem> + <para> + This parameter specifies the file name of the client SSL + certificate, replacing the default + <filename>~/.postgresql/postgresql.crt</>. + This parameter is ignored if an SSL connection is not made. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslkey" xreflabel="sslkey"> + <term><literal>sslkey</literal></term> + <listitem> + <para> + This parameter specifies the location for the secret key used for + the client certificate. It can either specify a file name that will + be used instead of the default + <filename>~/.postgresql/postgresql.key</>, or it can specify a key + obtained from an external <quote>engine</> (engines are + <productname>OpenSSL</> loadable modules). An external engine + specification should consist of a colon-separated engine name and + an engine-specific key identifier. This parameter is ignored if an + SSL connection is not made. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslrootcert" xreflabel="sslrootcert"> + <term><literal>sslrootcert</literal></term> + <listitem> + <para> + This parameter specifies the name of a file containing SSL + certificate authority (<acronym>CA</>) certificate(s). + If the file exists, the server's certificate will be verified + to be signed by one of these authorities. The default is + <filename>~/.postgresql/root.crt</>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslcrl" xreflabel="sslcrl"> + <term><literal>sslcrl</literal></term> + <listitem> + <para> + This parameter specifies the file name of the SSL certificate + revocation list (CRL). Certificates listed in this file, if it + exists, will be rejected while attempting to authenticate the + server's certificate. The default is + <filename>~/.postgresql/root.crl</>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-requirepeer" xreflabel="requirepeer"> + <term><literal>requirepeer</literal></term> + <listitem> + <para> + This parameter specifies the operating-system user name of the + server, for example <literal>requirepeer=postgres</literal>. + When making a Unix-domain socket connection, if this + parameter is set, the client checks at the beginning of the + connection that the server process is running under the specified + user name; if it is not, the connection is aborted with an error. + This parameter can be used to provide server authentication similar + to that available with SSL certificates on TCP/IP connections. + (Note that if the Unix-domain socket is in + <filename>/tmp</filename> or another publicly writable location, + any user could start a server listening there. Use this parameter + to ensure that you are connected to a server run by a trusted user.) + This option is only supported on platforms for which the + <literal>peer</> authentication method is implemented; see + <xref linkend="auth-peer">. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-krbsrvname" xreflabel="krbsrvname"> + <term><literal>krbsrvname</literal></term> + <listitem> + <para> + Kerberos service name to use when authenticating with Kerberos 5 + or GSSAPI. + This must match the service name specified in the server + configuration for Kerberos authentication to succeed. (See also + <xref linkend="kerberos-auth"> and <xref linkend="gssapi-auth">.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-gsslib" xreflabel="gsslib"> + <term><literal>gsslib</literal></term> + <listitem> + <para> + GSS library to use for GSSAPI authentication. Only used on Windows. + Set to <literal>gssapi</literal> to force libpq to use the GSSAPI + library for authentication instead of the default SSPI. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-service" xreflabel="service"> + <term><literal>service</literal></term> + <listitem> + <para> + Service name to use for additional parameters. It specifies a service + name in <filename>pg_service.conf</filename> that holds additional connection parameters. + This allows applications to specify only a service name so connection parameters + can be centrally maintained. See <xref linkend="libpq-pgservice">. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </sect1> + <sect1 id="libpq-envars"> <title>Environment Variables</title> @@ -6832,6 +6920,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) </sect1> + <sect1 id="libpq-pgservice"> <title>The Connection Service File</title> diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index b849101..bdcadf3 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -115,7 +115,10 @@ PostgreSQL documentation argument on the command line. </para> <para> - If this parameter contains an <symbol>=</symbol> sign, it is treated as a + If this parameter contains an <symbol>=</symbol> sign or starts + with a valid <acronym>URI</acronym> prefix + (<literal>postgresql://</literal> + or <literal>postgres://</literal>), it is treated as a <parameter>conninfo</parameter> string. See <xref linkend="libpq-connect"> for more information. </para> </listitem> @@ -596,11 +599,13 @@ PostgreSQL documentation <para> An alternative way to specify connection parameters is in a - <parameter>conninfo</parameter> string, which is used instead of a - database name. This mechanism give you very wide control over the + <parameter>conninfo</parameter> string or + a <acronym>URI</acronym>, which is used instead of a database + name. This mechanism give you very wide control over the connection. For example: <programlisting> $ <userinput>psql "service=myservice sslmode=require"</userinput> +$ <userinput>psql postgresql://dbmaster:5433/mydb?sslmode=require</userinput> </programlisting> This way you can also use LDAP for connection parameter lookup as described in <xref linkend="libpq-ldap">. ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-04-06 06:09 Peter Eisentraut <[email protected]> parent: Alvaro Herrera <[email protected]> 0 siblings, 1 reply; 22+ messages in thread From: Peter Eisentraut @ 2012-04-06 06:09 UTC (permalink / raw) To: Alvaro Herrera <[email protected]>; +Cc: Alex <[email protected]>; Heikki Linnakangas <[email protected]>; pgsql-hackers On fre, 2012-04-06 at 00:25 -0300, Alvaro Herrera wrote: > Some moments of radical thinking later, I became unhappy with the fact > that the conninfo stuff and parameter keywords are all crammed in the > PQconnectdbParams description. This feels wrong to me, even more so > after we expand it even more to add URIs to the mix. I think it's > better to create a separate sect1 (which I've entitled "Connection > Strings") which explains the conninfo and URI formats as well as > accepted keywords. The new section is referenced from the multiple > places that need it, without having to point to PQconnectdbParams. Yes, it should be split out. But the libpq chapter already has too many tiny sect1s. I think it should be a sect2 under "Database Connection Control". ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-04-09 19:41 Alvaro Herrera <[email protected]> parent: Peter Eisentraut <[email protected]> 0 siblings, 1 reply; 22+ messages in thread From: Alvaro Herrera @ 2012-04-09 19:41 UTC (permalink / raw) To: Peter Eisentraut <[email protected]>; +Cc: Alex <[email protected]>; Heikki Linnakangas <[email protected]>; pgsql-hackers Excerpts from Peter Eisentraut's message of vie abr 06 03:09:10 -0300 2012: > On fre, 2012-04-06 at 00:25 -0300, Alvaro Herrera wrote: > > Some moments of radical thinking later, I became unhappy with the fact > > that the conninfo stuff and parameter keywords are all crammed in the > > PQconnectdbParams description. This feels wrong to me, even more so > > after we expand it even more to add URIs to the mix. I think it's > > better to create a separate sect1 (which I've entitled "Connection > > Strings") which explains the conninfo and URI formats as well as > > accepted keywords. The new section is referenced from the multiple > > places that need it, without having to point to PQconnectdbParams. > > Yes, it should be split out. But the libpq chapter already has too many > tiny sect1s. I think it should be a sect2 under "Database Connection > Control". Thanks, that seems a good idea. I have tweaked things slightly and it looks pretty decent to me. Wording improvements are welcome. The file in its entirety can be seen here: https://github.com/alvherre/postgres/blob/uri/doc/src/sgml/libpq.sgml The new bits start at line 1224. I also attach the HTML output for easy reading. (I wonder if it's going to be visible in the archives). There are three minor things that need to be changed for this to be committable: 1. it depends on strtok_r which is likely to be a problem in MSVC++ and perhaps older Unix platforms as well. 2. The ssl=true trick being converted into sslmode=require doesn't work if the URI specifies them uri-encoded, which seems bogus. 3. if an unknown keyword is uri-encoded, the error message displays it still uri-encoded. Seems to me it'd be better to uri-decode it before throwing error. Alexander says he's going to work on these and then I'll finally commit it. -- Álvaro Herrera <[email protected]> The PostgreSQL Company - Command Prompt, Inc. PostgreSQL Replication, Consulting, Custom Development, 24x7 support Attachments: [text/html] libpq-connect.html (49.3K, ../../[email protected]/2-libpq-connect.html) download | inline: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >Database Connection Control Functions</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REV="MADE" HREF="mailto:[email protected]"><LINK REL="HOME" TITLE="PostgreSQL 9.2devel Documentation" HREF="index.html"><LINK REL="UP" TITLE="libpq - C Library" HREF="libpq.html"><LINK REL="PREVIOUS" TITLE="libpq - C Library" HREF="libpq.html"><LINK REL="NEXT" TITLE="Connection Status Functions" HREF="libpq-status.html"><LINK REL="STYLESHEET" TYPE="text/css" HREF="stylesheet.css"><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"><META NAME="creation" CONTENT="2012-04-09T19:26:53"></HEAD ><BODY CLASS="SECT1" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="5" ALIGN="center" VALIGN="bottom" ><A HREF="index.html" >PostgreSQL 9.2devel Documentation</A ></TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A TITLE="libpq - C Library" HREF="libpq.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="libpq.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="60%" ALIGN="center" VALIGN="bottom" >Chapter 31. <SPAN CLASS="APPLICATION" >libpq</SPAN > - C Library</TD ><TD WIDTH="20%" ALIGN="right" VALIGN="top" ><A TITLE="Connection Status Functions" HREF="libpq-status.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECT1" ><H1 CLASS="SECT1" ><A NAME="LIBPQ-CONNECT" >31.1. Database Connection Control Functions</A ></H1 ><P > The following functions deal with making a connection to a <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > backend server. An application program can have several backend connections open at one time. (One reason to do that is to access more than one database.) Each connection is represented by a <TT CLASS="STRUCTNAME" >PGconn</TT > object, which is obtained from the function <CODE CLASS="FUNCTION" >PQconnectdb</CODE >, <CODE CLASS="FUNCTION" >PQconnectdbParams</CODE >, or <CODE CLASS="FUNCTION" >PQsetdbLogin</CODE >. Note that these functions will always return a non-null object pointer, unless perhaps there is too little memory even to allocate the <TT CLASS="STRUCTNAME" >PGconn</TT > object. The <CODE CLASS="FUNCTION" >PQstatus</CODE > function should be called to check the return value for a successful connection before queries are sent via the connection object. <DIV CLASS="WARNING" ><P ></P ><TABLE CLASS="WARNING" BORDER="1" WIDTH="100%" ><TR ><TD ALIGN="CENTER" ><B >Warning</B ></TD ></TR ><TR ><TD ALIGN="LEFT" ><P > On Unix, forking a process with open libpq connections can lead to unpredictable results because the parent and child processes share the same sockets and operating system resources. For this reason, such usage is not recommended, though doing an <CODE CLASS="FUNCTION" >exec</CODE > from the child process to load a new executable is safe. </P ></TD ></TR ></TABLE ></DIV > </P><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Note: </B > On Windows, there is a way to improve performance if a single database connection is repeatedly started and shutdown. Internally, libpq calls <CODE CLASS="FUNCTION" >WSAStartup()</CODE > and <CODE CLASS="FUNCTION" >WSACleanup()</CODE > for connection startup and shutdown, respectively. <CODE CLASS="FUNCTION" >WSAStartup()</CODE > increments an internal Windows library reference count which is decremented by <CODE CLASS="FUNCTION" >WSACleanup()</CODE >. When the reference count is just one, calling <CODE CLASS="FUNCTION" >WSACleanup()</CODE > frees all resources and all DLLs are unloaded. This is an expensive operation. To avoid this, an application can manually call <CODE CLASS="FUNCTION" >WSAStartup()</CODE > so resources will not be freed when the last database connection is closed. </P ></BLOCKQUOTE ></DIV ><P> <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><A NAME="LIBPQ-PQCONNECTDBPARAMS" ></A ><CODE CLASS="FUNCTION" >PQconnectdbParams</CODE ></DT ><DD ><P > Makes a new connection to the database server. </P><PRE CLASS="SYNOPSIS" >PGconn *PQconnectdbParams(const char * const *keywords, const char * const *values, int expand_dbname);</PRE ><P> </P ><P > This function opens a new database connection using the parameters taken from two <TT CLASS="SYMBOL" >NULL</TT >-terminated arrays. The first, <TT CLASS="LITERAL" >keywords</TT >, is defined as an array of strings, each one being a key word. The second, <TT CLASS="LITERAL" >values</TT >, gives the value for each key word. Unlike <CODE CLASS="FUNCTION" >PQsetdbLogin</CODE > below, the parameter set can be extended without changing the function signature, so use of this function (or its nonblocking analogs <CODE CLASS="FUNCTION" >PQconnectStartParams</CODE > and <CODE CLASS="FUNCTION" >PQconnectPoll</CODE >) is preferred for new application programming. </P ><P > The currently recognized parameter key words are listed in <A HREF="libpq-connect.html#LIBPQ-PARAMKEYWORDS" >Section 31.1.1</A >. </P ><P > When <TT CLASS="LITERAL" >expand_dbname</TT > is non-zero, the <TT CLASS="PARAMETER" >dbname</TT > key word value is allowed to be recognized as a connection string. More details on the possible formats appear in <A HREF="libpq-connect.html#LIBPQ-CONNSTRING" >Section 31.1.2</A >. </P ><P > 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-<TT CLASS="SYMBOL" >NULL</TT > element of the <TT CLASS="LITERAL" >keywords</TT > array. </P ><P > If any parameter is unspecified, then the corresponding environment variable (see <A HREF="libpq-envars.html" >Section 31.14</A >) is checked. If the environment variable is not set either, then the indicated built-in defaults are used. </P ><P > In general key words are processed from the beginning of these arrays in index order. The effect of this is that when key words are repeated, the last processed value is retained. Therefore, through careful placement of the <TT CLASS="PARAMETER" >dbname</TT > key word, it is possible to determine what may be overridden by a <TT CLASS="PARAMETER" >conninfo</TT > string, and what may not. </P ></DD ><DT ><A NAME="LIBPQ-PQCONNECTDB" ></A ><CODE CLASS="FUNCTION" >PQconnectdb</CODE ></DT ><DD ><P > Makes a new connection to the database server. </P><PRE CLASS="SYNOPSIS" >PGconn *PQconnectdb(const char *conninfo);</PRE ><P> </P ><P > This function opens a new database connection using the parameters taken from the string <TT CLASS="LITERAL" >conninfo</TT >. </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, or it can contain a <ACRONYM CLASS="ACRONYM" >URI</ACRONYM >. See <A HREF="libpq-connect.html#LIBPQ-CONNSTRING" >Section 31.1.2</A > for details. </P ></DD ><DT ><A NAME="LIBPQ-PQSETDBLOGIN" ></A ><CODE CLASS="FUNCTION" >PQsetdbLogin</CODE ></DT ><DD ><P > Makes a new connection to the database server. </P><PRE CLASS="SYNOPSIS" >PGconn *PQsetdbLogin(const char *pghost, const char *pgport, const char *pgoptions, const char *pgtty, const char *dbName, const char *login, const char *pwd);</PRE ><P> </P ><P > This is the predecessor of <CODE CLASS="FUNCTION" >PQconnectdb</CODE > with a fixed set of parameters. It has the same functionality except that the missing parameters will always take on default values. Write <TT CLASS="SYMBOL" >NULL</TT > or an empty string for any one of the fixed parameters that is to be defaulted. </P ><P > If the <TT CLASS="PARAMETER" >dbName</TT > contains an <TT CLASS="SYMBOL" >=</TT > sign or has a valid connection <ACRONYM CLASS="ACRONYM" >URI</ACRONYM > prefix, it is taken as a <TT CLASS="PARAMETER" >conninfo</TT > string in exactly the same way as if it had been passed to <CODE CLASS="FUNCTION" >PQconnectdb</CODE >, and the remaining parameters are then applied as specified in <A HREF="libpq-connect.html#LIBPQ-CONNSTRING" >Section 31.1.2</A >. </P ></DD ><DT ><A NAME="LIBPQ-PQSETDB" ></A ><CODE CLASS="FUNCTION" >PQsetdb</CODE ></DT ><DD ><P > Makes a new connection to the database server. </P><PRE CLASS="SYNOPSIS" >PGconn *PQsetdb(char *pghost, char *pgport, char *pgoptions, char *pgtty, char *dbName);</PRE ><P> </P ><P > This is a macro that calls <CODE CLASS="FUNCTION" >PQsetdbLogin</CODE > with null pointers for the <TT CLASS="PARAMETER" >login</TT > and <TT CLASS="PARAMETER" >pwd</TT > parameters. It is provided for backward compatibility with very old programs. </P ></DD ><DT ><A NAME="LIBPQ-PQCONNECTSTARTPARAMS" ></A ><CODE CLASS="FUNCTION" >PQconnectStartParams</CODE ><BR><CODE CLASS="FUNCTION" >PQconnectStart</CODE ><BR><CODE CLASS="FUNCTION" >PQconnectPoll</CODE ></DT ><DD ><P > Make a connection to the database server in a nonblocking manner. </P><PRE CLASS="SYNOPSIS" >PGconn *PQconnectStartParams(const char * const *keywords, const char * const *values, int expand_dbname); PGconn *PQconnectStart(const char *conninfo); PostgresPollingStatusType PQconnectPoll(PGconn *conn);</PRE ><P> </P ><P > 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 <CODE CLASS="FUNCTION" >PQconnectdbParams</CODE > or <CODE CLASS="FUNCTION" >PQconnectdb</CODE >, and so the application can manage this operation in parallel with other activities. </P ><P > With <CODE CLASS="FUNCTION" >PQconnectStartParams</CODE >, the database connection is made using the parameters taken from the <TT CLASS="LITERAL" >keywords</TT > and <TT CLASS="LITERAL" >values</TT > arrays, and controlled by <TT CLASS="LITERAL" >expand_dbname</TT >, as described above for <CODE CLASS="FUNCTION" >PQconnectdbParams</CODE >. </P ><P > With <CODE CLASS="FUNCTION" >PQconnectStart</CODE >, the database connection is made using the parameters taken from the string <TT CLASS="LITERAL" >conninfo</TT > as described above for <CODE CLASS="FUNCTION" >PQconnectdb</CODE >. </P ><P > Neither <CODE CLASS="FUNCTION" >PQconnectStartParams</CODE > nor <CODE CLASS="FUNCTION" >PQconnectStart</CODE > nor <CODE CLASS="FUNCTION" >PQconnectPoll</CODE > will block, so long as a number of restrictions are met: <P ></P ></P><UL ><LI ><P > The <TT CLASS="LITERAL" >hostaddr</TT > and <TT CLASS="LITERAL" >host</TT > parameters are used appropriately to ensure that name and reverse name queries are not made. See the documentation of these parameters in <A HREF="libpq-connect.html#LIBPQ-PARAMKEYWORDS" >Section 31.1.1</A > for details. </P ></LI ><LI ><P > If you call <CODE CLASS="FUNCTION" >PQtrace</CODE >, ensure that the stream object into which you trace will not block. </P ></LI ><LI ><P > You ensure that the socket is in the appropriate state before calling <CODE CLASS="FUNCTION" >PQconnectPoll</CODE >, as described below. </P ></LI ></UL ><P> </P ><P > Note: use of <CODE CLASS="FUNCTION" >PQconnectStartParams</CODE > is analogous to <CODE CLASS="FUNCTION" >PQconnectStart</CODE > shown below. </P ><P > To begin a nonblocking connection request, call <TT CLASS="LITERAL" >conn = PQconnectStart("<TT CLASS="REPLACEABLE" ><I >connection_info_string</I ></TT >")</TT >. If <TT CLASS="VARNAME" >conn</TT > is null, then <SPAN CLASS="APPLICATION" >libpq</SPAN > has been unable to allocate a new <TT CLASS="STRUCTNAME" >PGconn</TT > structure. Otherwise, a valid <TT CLASS="STRUCTNAME" >PGconn</TT > pointer is returned (though not yet representing a valid connection to the database). On return from <CODE CLASS="FUNCTION" >PQconnectStart</CODE >, call <TT CLASS="LITERAL" >status = PQstatus(conn)</TT >. If <TT CLASS="VARNAME" >status</TT > equals <TT CLASS="SYMBOL" >CONNECTION_BAD</TT >, <CODE CLASS="FUNCTION" >PQconnectStart</CODE > has failed. </P ><P > If <CODE CLASS="FUNCTION" >PQconnectStart</CODE > succeeds, the next stage is to poll <SPAN CLASS="APPLICATION" >libpq</SPAN > so that it can proceed with the connection sequence. Use <CODE CLASS="FUNCTION" >PQsocket(conn)</CODE > to obtain the descriptor of the socket underlying the database connection. Loop thus: If <CODE CLASS="FUNCTION" >PQconnectPoll(conn)</CODE > last returned <TT CLASS="SYMBOL" >PGRES_POLLING_READING</TT >, wait until the socket is ready to read (as indicated by <CODE CLASS="FUNCTION" >select()</CODE >, <CODE CLASS="FUNCTION" >poll()</CODE >, or similar system function). Then call <CODE CLASS="FUNCTION" >PQconnectPoll(conn)</CODE > again. Conversely, if <CODE CLASS="FUNCTION" >PQconnectPoll(conn)</CODE > last returned <TT CLASS="SYMBOL" >PGRES_POLLING_WRITING</TT >, wait until the socket is ready to write, then call <CODE CLASS="FUNCTION" >PQconnectPoll(conn)</CODE > again. If you have yet to call <CODE CLASS="FUNCTION" >PQconnectPoll</CODE >, i.e., just after the call to <CODE CLASS="FUNCTION" >PQconnectStart</CODE >, behave as if it last returned <TT CLASS="SYMBOL" >PGRES_POLLING_WRITING</TT >. Continue this loop until <CODE CLASS="FUNCTION" >PQconnectPoll(conn)</CODE > returns <TT CLASS="SYMBOL" >PGRES_POLLING_FAILED</TT >, indicating the connection procedure has failed, or <TT CLASS="SYMBOL" >PGRES_POLLING_OK</TT >, indicating the connection has been successfully made. </P ><P > At any time during connection, the status of the connection can be checked by calling <CODE CLASS="FUNCTION" >PQstatus</CODE >. If this call returns <TT CLASS="SYMBOL" >CONNECTION_BAD</TT >, then the connection procedure has failed; if the call returns <CODE CLASS="FUNCTION" >CONNECTION_OK</CODE >, then the connection is ready. Both of these states are equally detectable from the return value of <CODE CLASS="FUNCTION" >PQconnectPoll</CODE >, described above. Other states might also occur during (and only during) an asynchronous connection procedure. These indicate the current stage of the connection procedure and might be useful to provide feedback to the user for example. These statuses are: <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><A NAME="LIBPQ-CONNECTION-STARTED" ></A ><TT CLASS="SYMBOL" >CONNECTION_STARTED</TT ></DT ><DD ><P > Waiting for connection to be made. </P ></DD ><DT ><A NAME="LIBPQ-CONNECTION-MADE" ></A ><TT CLASS="SYMBOL" >CONNECTION_MADE</TT ></DT ><DD ><P > Connection OK; waiting to send. </P ></DD ><DT ><A NAME="LIBPQ-CONNECTION-AWAITING-RESPONSE" ></A ><TT CLASS="SYMBOL" >CONNECTION_AWAITING_RESPONSE</TT ></DT ><DD ><P > Waiting for a response from the server. </P ></DD ><DT ><A NAME="LIBPQ-CONNECTION-AUTH-OK" ></A ><TT CLASS="SYMBOL" >CONNECTION_AUTH_OK</TT ></DT ><DD ><P > Received authentication; waiting for backend start-up to finish. </P ></DD ><DT ><A NAME="LIBPQ-CONNECTION-SSL-STARTUP" ></A ><TT CLASS="SYMBOL" >CONNECTION_SSL_STARTUP</TT ></DT ><DD ><P > Negotiating SSL encryption. </P ></DD ><DT ><A NAME="LIBPQ-CONNECTION-SETENV" ></A ><TT CLASS="SYMBOL" >CONNECTION_SETENV</TT ></DT ><DD ><P > Negotiating environment-driven parameter settings. </P ></DD ></DL ></DIV ><P> Note that, although these constants will remain (in order to maintain compatibility), an application should never rely upon these occurring in a particular order, or at all, or on the status always being one of these documented values. An application might do something like this: </P><PRE CLASS="PROGRAMLISTING" >switch(PQstatus(conn)) { case CONNECTION_STARTED: feedback = "Connecting..."; break; case CONNECTION_MADE: feedback = "Connected to server..."; break; . . . default: feedback = "Connecting..."; }</PRE ><P> </P ><P > The <TT CLASS="LITERAL" >connect_timeout</TT > connection parameter is ignored when using <CODE CLASS="FUNCTION" >PQconnectPoll</CODE >; it is the application's responsibility to decide whether an excessive amount of time has elapsed. Otherwise, <CODE CLASS="FUNCTION" >PQconnectStart</CODE > followed by a <CODE CLASS="FUNCTION" >PQconnectPoll</CODE > loop is equivalent to <CODE CLASS="FUNCTION" >PQconnectdb</CODE >. </P ><P > Note that if <CODE CLASS="FUNCTION" >PQconnectStart</CODE > returns a non-null pointer, you must call <CODE CLASS="FUNCTION" >PQfinish</CODE > when you are finished with it, in order to dispose of the structure and any associated memory blocks. This must be done even if the connection attempt fails or is abandoned. </P ></DD ><DT ><A NAME="LIBPQ-PQCONNDEFAULTS" ></A ><CODE CLASS="FUNCTION" >PQconndefaults</CODE ></DT ><DD ><P > Returns the default connection options. </P><PRE CLASS="SYNOPSIS" >PQconninfoOption *PQconndefaults(void); typedef struct { char *keyword; /* The keyword of the option */ char *envvar; /* Fallback environment variable name */ char *compiled; /* Fallback compiled in default value */ char *val; /* Option's current value, or NULL */ char *label; /* Label for field in connect dialog */ char *dispchar; /* Indicates how to display this field in a connect dialog. Values are: "" Display entered value as is "*" Password field - hide value "D" Debug option - don't show by default */ int dispsize; /* Field size in characters for dialog */ } PQconninfoOption;</PRE ><P> </P ><P > Returns a connection options array. This can be used to determine all possible <CODE CLASS="FUNCTION" >PQconnectdb</CODE > options and their current default values. The return value points to an array of <TT CLASS="STRUCTNAME" >PQconninfoOption</TT > structures, which ends with an entry having a null <TT CLASS="STRUCTFIELD" >keyword</TT > pointer. The null pointer is returned if memory could not be allocated. Note that the current default values (<TT CLASS="STRUCTFIELD" >val</TT > fields) will depend on environment variables and other context. Callers must treat the connection options data as read-only. </P ><P > After processing the options array, free it by passing it to <CODE CLASS="FUNCTION" >PQconninfoFree</CODE >. If this is not done, a small amount of memory is leaked for each call to <CODE CLASS="FUNCTION" >PQconndefaults</CODE >. </P ></DD ><DT ><A NAME="LIBPQ-PQCONNINFOPARSE" ></A ><CODE CLASS="FUNCTION" >PQconninfoParse</CODE ></DT ><DD ><P > Returns parsed connection options from the provided connection string. </P><PRE CLASS="SYNOPSIS" >PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);</PRE ><P> </P ><P > Parses a connection string and returns the resulting options as an array; or returns <TT CLASS="SYMBOL" >NULL</TT > if there is a problem with the connection string. This function can be used to extract the <CODE CLASS="FUNCTION" >PQconnectdb</CODE > options in the provided connection string. The return value points to an array of <TT CLASS="STRUCTNAME" >PQconninfoOption</TT > structures, which ends with an entry having a null <TT CLASS="STRUCTFIELD" >keyword</TT > pointer. </P ><P > All legal options will be present in the result array, but the <TT CLASS="LITERAL" >PQconninfoOption</TT > for any option not present in the connection string will have <TT CLASS="LITERAL" >val</TT > set to <TT CLASS="LITERAL" >NULL</TT >; default values are not inserted. </P ><P > If <TT CLASS="LITERAL" >errmsg</TT > is not <TT CLASS="SYMBOL" >NULL</TT >, then <TT CLASS="LITERAL" >*errmsg</TT > is set to <TT CLASS="SYMBOL" >NULL</TT > on success, else to a <CODE CLASS="FUNCTION" >malloc</CODE >'d error string explaining the problem. (It is also possible for <TT CLASS="LITERAL" >*errmsg</TT > to be set to <TT CLASS="SYMBOL" >NULL</TT > and the function to return <TT CLASS="SYMBOL" >NULL</TT >; this indicates an out-of-memory condition.) </P ><P > After processing the options array, free it by passing it to <CODE CLASS="FUNCTION" >PQconninfoFree</CODE >. If this is not done, some memory is leaked for each call to <CODE CLASS="FUNCTION" >PQconninfoParse</CODE >. Conversely, if an error occurs and <TT CLASS="LITERAL" >errmsg</TT > is not <TT CLASS="SYMBOL" >NULL</TT >, be sure to free the error string using <CODE CLASS="FUNCTION" >PQfreemem</CODE >. </P ></DD ><DT ><A NAME="LIBPQ-PQFINISH" ></A ><CODE CLASS="FUNCTION" >PQfinish</CODE ></DT ><DD ><P > Closes the connection to the server. Also frees memory used by the <TT CLASS="STRUCTNAME" >PGconn</TT > object. </P><PRE CLASS="SYNOPSIS" >void PQfinish(PGconn *conn);</PRE ><P> </P ><P > Note that even if the server connection attempt fails (as indicated by <CODE CLASS="FUNCTION" >PQstatus</CODE >), the application should call <CODE CLASS="FUNCTION" >PQfinish</CODE > to free the memory used by the <TT CLASS="STRUCTNAME" >PGconn</TT > object. The <TT CLASS="STRUCTNAME" >PGconn</TT > pointer must not be used again after <CODE CLASS="FUNCTION" >PQfinish</CODE > has been called. </P ></DD ><DT ><A NAME="LIBPQ-PQRESET" ></A ><CODE CLASS="FUNCTION" >PQreset</CODE ></DT ><DD ><P > Resets the communication channel to the server. </P><PRE CLASS="SYNOPSIS" >void PQreset(PGconn *conn);</PRE ><P> </P ><P > This function will close the connection to the server and attempt to reestablish a new connection to the same server, using all the same parameters previously used. This might be useful for error recovery if a working connection is lost. </P ></DD ><DT ><A NAME="LIBPQ-PQRESETSTART" ></A ><CODE CLASS="FUNCTION" >PQresetStart</CODE ><BR><CODE CLASS="FUNCTION" >PQresetPoll</CODE ></DT ><DD ><P > Reset the communication channel to the server, in a nonblocking manner. </P><PRE CLASS="SYNOPSIS" >int PQresetStart(PGconn *conn); PostgresPollingStatusType PQresetPoll(PGconn *conn);</PRE ><P> </P ><P > These functions will close the connection to the server and attempt to reestablish a new connection to the same server, using all the same parameters previously used. This can be useful for error recovery if a working connection is lost. They differ from <CODE CLASS="FUNCTION" >PQreset</CODE > (above) in that they act in a nonblocking manner. These functions suffer from the same restrictions as <CODE CLASS="FUNCTION" >PQconnectStartParams</CODE >, <CODE CLASS="FUNCTION" >PQconnectStart</CODE > and <CODE CLASS="FUNCTION" >PQconnectPoll</CODE >. </P ><P > To initiate a connection reset, call <CODE CLASS="FUNCTION" >PQresetStart</CODE >. If it returns 0, the reset has failed. If it returns 1, poll the reset using <CODE CLASS="FUNCTION" >PQresetPoll</CODE > in exactly the same way as you would create the connection using <CODE CLASS="FUNCTION" >PQconnectPoll</CODE >. </P ></DD ><DT ><A NAME="LIBPQ-PQPINGPARAMS" ></A ><CODE CLASS="FUNCTION" >PQpingParams</CODE ></DT ><DD ><P > <CODE CLASS="FUNCTION" >PQpingParams</CODE > reports the status of the server. It accepts connection parameters identical to those of <CODE CLASS="FUNCTION" >PQconnectdbParams</CODE >, described above. It is not, however, necessary to supply correct user name, password, or database name values to obtain the server status. </P><PRE CLASS="SYNOPSIS" >PGPing PQpingParams(const char * const *keywords, const char * const *values, int expand_dbname);</PRE ><P> The function returns one of the following values: <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><A NAME="LIBPQ-PQPINGPARAMS-PQPING-OK" ></A ><TT CLASS="LITERAL" >PQPING_OK</TT ></DT ><DD ><P > The server is running and appears to be accepting connections. </P ></DD ><DT ><A NAME="LIBPQ-PQPINGPARAMS-PQPING-REJECT" ></A ><TT CLASS="LITERAL" >PQPING_REJECT</TT ></DT ><DD ><P > The server is running but is in a state that disallows connections (startup, shutdown, or crash recovery). </P ></DD ><DT ><A NAME="LIBPQ-PQPINGPARAMS-PQPING-NO-RESPONSE" ></A ><TT CLASS="LITERAL" >PQPING_NO_RESPONSE</TT ></DT ><DD ><P > The server could not be contacted. This might indicate that the server is not running, or that there is something wrong with the given connection parameters (for example, wrong port number), or that there is a network connectivity problem (for example, a firewall blocking the connection request). </P ></DD ><DT ><A NAME="LIBPQ-PQPINGPARAMS-PQPING-NO-ATTEMPT" ></A ><TT CLASS="LITERAL" >PQPING_NO_ATTEMPT</TT ></DT ><DD ><P > No attempt was made to contact the server, because the supplied parameters were obviously incorrect or there was some client-side problem (for example, out of memory). </P ></DD ></DL ></DIV ><P> </P ></DD ><DT ><A NAME="LIBPQ-PQPING" ></A ><CODE CLASS="FUNCTION" >PQping</CODE ></DT ><DD ><P > <CODE CLASS="FUNCTION" >PQping</CODE > reports the status of the server. It accepts connection parameters identical to those of <CODE CLASS="FUNCTION" >PQconnectdb</CODE >, described above. It is not, however, necessary to supply correct user name, password, or database name values to obtain the server status. </P><PRE CLASS="SYNOPSIS" >PGPing PQping(const char *conninfo);</PRE ><P> </P ><P > The return values are the same as for <CODE CLASS="FUNCTION" >PQpingParams</CODE >. </P ></DD ></DL ></DIV ><P> </P ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LIBPQ-PARAMKEYWORDS" >31.1.1. Parameter Key Words</A ></H2 ><P > The currently recognized parameter key words are: <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><A NAME="LIBPQ-CONNECT-HOST" ></A ><TT CLASS="LITERAL" >host</TT ></DT ><DD ><P > Name of host to connect to. 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 behavior when <TT CLASS="LITERAL" >host</TT > is not specified is to connect to a Unix-domain socket in <TT CLASS="FILENAME" >/tmp</TT > (or whatever socket directory was specified when <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > was built). On machines without Unix-domain sockets, the default is to connect to <TT CLASS="LITERAL" >localhost</TT >. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-HOSTADDR" ></A ><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 those addresses. 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 look-up, which might be important in applications with time constraints. However, a host name is required for Kerberos, GSSAPI, or SSPI authentication methods, as well as for <TT CLASS="LITERAL" >verify-full</TT > SSL certificate verification. The following rules are used: <P ></P ></P><UL ><LI ><P > If <TT CLASS="LITERAL" >host</TT > is specified without <TT CLASS="LITERAL" >hostaddr</TT >, a host name lookup occurs. </P ></LI ><LI ><P > If <TT CLASS="LITERAL" >hostaddr</TT > is specified without <TT CLASS="LITERAL" >host</TT >, the value for <TT CLASS="LITERAL" >hostaddr</TT > gives the server network address. The connection attempt will fail if the authentication method requires a host name. </P ></LI ><LI ><P > 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 server network address. The value for <TT CLASS="LITERAL" >host</TT > is ignored unless the authentication method requires it, in which case it will be used as the host name. </P ></LI ></UL ><P> Note that authentication is likely to fail if <TT CLASS="LITERAL" >host</TT > is not the name of the server at network address <TT CLASS="LITERAL" >hostaddr</TT >. Also, note that <TT CLASS="LITERAL" >host</TT > rather than <TT CLASS="LITERAL" >hostaddr</TT > is used to identify the connection in <TT CLASS="FILENAME" >~/.pgpass</TT > (see <A HREF="libpq-pgpass.html" >Section 31.15</A >). </P ><P > Without either a host name or host address, <SPAN CLASS="APPLICATION" >libpq</SPAN > will connect using a local Unix-domain socket; or on machines without Unix-domain sockets, it will attempt to connect to <TT CLASS="LITERAL" >localhost</TT >. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-PORT" ></A ><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. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-DBNAME" ></A ><TT CLASS="LITERAL" >dbname</TT ></DT ><DD ><P > The database name. Defaults to be the same as the user name. In certain, very specific contexts, the value is checked for extended formats; see <A HREF="libpq-connect.html#LIBPQ-CONNSTRING" >Section 31.1.2</A > for more details on those. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-USER" ></A ><TT CLASS="LITERAL" >user</TT ></DT ><DD ><P > <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > user name to connect as. Defaults to be the same as the operating system name of the user running the application. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-PASSWORD" ></A ><TT CLASS="LITERAL" >password</TT ></DT ><DD ><P > Password to be used if the server demands password authentication. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-CONNECT-TIMEOUT" ></A ><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 ><A NAME="LIBPQ-CONNECT-CLIENT-ENCODING" ></A ><TT CLASS="LITERAL" >client_encoding</TT ></DT ><DD ><P > This sets the <TT CLASS="VARNAME" >client_encoding</TT > configuration parameter for this connection. In addition to the values accepted by the corresponding server option, you can use <TT CLASS="LITERAL" >auto</TT > to determine the right encoding from the current locale in the client (<TT CLASS="ENVAR" >LC_CTYPE</TT > environment variable on Unix systems). </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-OPTIONS" ></A ><TT CLASS="LITERAL" >options</TT ></DT ><DD ><P > Adds command-line options to send to the server at run-time. For example, setting this to <TT CLASS="LITERAL" >-c geqo=off</TT > sets the session's value of the <TT CLASS="VARNAME" >geqo</TT > parameter to <TT CLASS="LITERAL" >off</TT >. For a detailed discussion of the available options, consult <A HREF="runtime-config.html" >Chapter 18</A >. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-APPLICATION-NAME" ></A ><TT CLASS="LITERAL" >application_name</TT ></DT ><DD ><P > Specifies a value for the <A HREF="runtime-config-logging.html#GUC-APPLICATION-NAME" >application_name</A > configuration parameter. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-FALLBACK-APPLICATION-NAME" ></A ><TT CLASS="LITERAL" >fallback_application_name</TT ></DT ><DD ><P > Specifies a fallback value for the <A HREF="runtime-config-logging.html#GUC-APPLICATION-NAME" >application_name</A > configuration parameter. This value will be used if no value has been given for <TT CLASS="LITERAL" >application_name</TT > via a connection parameter or the <TT CLASS="ENVAR" >PGAPPNAME</TT > environment variable. Specifying a fallback name is useful in generic utility programs that wish to set a default application name but allow it to be overridden by the user. </P ></DD ><DT ><A NAME="LIBPQ-KEEPALIVES" ></A ><TT CLASS="LITERAL" >keepalives</TT ></DT ><DD ><P > Controls whether client-side TCP keepalives are used. The default value is 1, meaning on, but you can change this to 0, meaning off, if keepalives are not wanted. This parameter is ignored for connections made via a Unix-domain socket. </P ></DD ><DT ><A NAME="LIBPQ-KEEPALIVES-IDLE" ></A ><TT CLASS="LITERAL" >keepalives_idle</TT ></DT ><DD ><P > Controls the number of seconds of inactivity after which TCP should send a keepalive message to the server. A value of zero uses the system default. This parameter is ignored for connections made via a Unix-domain socket, or if keepalives are disabled. It is only supported on systems where the <TT CLASS="SYMBOL" >TCP_KEEPIDLE</TT > or <TT CLASS="SYMBOL" >TCP_KEEPALIVE</TT > socket option is available, and on Windows; on other systems, it has no effect. </P ></DD ><DT ><A NAME="LIBPQ-KEEPALIVES-INTERVAL" ></A ><TT CLASS="LITERAL" >keepalives_interval</TT ></DT ><DD ><P > Controls the number of seconds after which a TCP keepalive message that is not acknowledged by the server should be retransmitted. A value of zero uses the system default. This parameter is ignored for connections made via a Unix-domain socket, or if keepalives are disabled. It is only supported on systems where the <TT CLASS="SYMBOL" >TCP_KEEPINTVL</TT > socket option is available, and on Windows; on other systems, it has no effect. </P ></DD ><DT ><A NAME="LIBPQ-KEEPALIVES-COUNT" ></A ><TT CLASS="LITERAL" >keepalives_count</TT ></DT ><DD ><P > Controls the number of TCP keepalives that can be lost before the client's connection to the server is considered dead. A value of zero uses the system default. This parameter is ignored for connections made via a Unix-domain socket, or if keepalives are disabled. It is only supported on systems where the <TT CLASS="SYMBOL" >TCP_KEEPCNT</TT > socket option is available; on other systems, it has no effect. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-TTY" ></A ><TT CLASS="LITERAL" >tty</TT ></DT ><DD ><P > Ignored (formerly, this specified where to send server debug output). </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-SSLMODE" ></A ><TT CLASS="LITERAL" >sslmode</TT ></DT ><DD ><P > This option determines whether or with what priority a secure <ACRONYM CLASS="ACRONYM" >SSL</ACRONYM > TCP/IP connection will be negotiated with the server. There are six modes: <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="LITERAL" >disable</TT ></DT ><DD ><P > only try a non-<ACRONYM CLASS="ACRONYM" >SSL</ACRONYM > connection </P ></DD ><DT ><TT CLASS="LITERAL" >allow</TT ></DT ><DD ><P > first try a non-<ACRONYM CLASS="ACRONYM" >SSL</ACRONYM > connection; if that fails, try an <ACRONYM CLASS="ACRONYM" >SSL</ACRONYM > connection </P ></DD ><DT ><TT CLASS="LITERAL" >prefer</TT > (default)</DT ><DD ><P > first try an <ACRONYM CLASS="ACRONYM" >SSL</ACRONYM > connection; if that fails, try a non-<ACRONYM CLASS="ACRONYM" >SSL</ACRONYM > connection </P ></DD ><DT ><TT CLASS="LITERAL" >require</TT ></DT ><DD ><P > only try an <ACRONYM CLASS="ACRONYM" >SSL</ACRONYM > connection. If a root CA file is present, verify the certificate in the same way as if <TT CLASS="LITERAL" >verify-ca</TT > was specified </P ></DD ><DT ><TT CLASS="LITERAL" >verify-ca</TT ></DT ><DD ><P > only try an <ACRONYM CLASS="ACRONYM" >SSL</ACRONYM > connection, and verify that the server certificate is issued by a trusted certificate authority (<ACRONYM CLASS="ACRONYM" >CA</ACRONYM >) </P ></DD ><DT ><TT CLASS="LITERAL" >verify-full</TT ></DT ><DD ><P > only try an <ACRONYM CLASS="ACRONYM" >SSL</ACRONYM > connection, verify that the server certificate is issued by a trusted <ACRONYM CLASS="ACRONYM" >CA</ACRONYM > and that the server host name matches that in the certificate </P ></DD ></DL ></DIV ><P> See <A HREF="libpq-ssl.html" >Section 31.18</A > for a detailed description of how these options work. </P ><P > <TT CLASS="LITERAL" >sslmode</TT > is ignored for Unix domain socket communication. If <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > is compiled without SSL support, using options <TT CLASS="LITERAL" >require</TT >, <TT CLASS="LITERAL" >verify-ca</TT >, or <TT CLASS="LITERAL" >verify-full</TT > will cause an error, while options <TT CLASS="LITERAL" >allow</TT > and <TT CLASS="LITERAL" >prefer</TT > will be accepted but <SPAN CLASS="APPLICATION" >libpq</SPAN > will not actually attempt an <ACRONYM CLASS="ACRONYM" >SSL</ACRONYM > connection. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-REQUIRESSL" ></A ><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 ><A NAME="LIBPQ-CONNECT-SSLCOMPRESSION" ></A ><TT CLASS="LITERAL" >sslcompression</TT ></DT ><DD ><P > If set to 1 (default), data sent over SSL connections will be compressed (this requires <SPAN CLASS="PRODUCTNAME" >OpenSSL</SPAN > version 0.9.8 or later). If set to 0, compression will be disabled (this requires <SPAN CLASS="PRODUCTNAME" >OpenSSL</SPAN > 1.0.0 or later). This parameter is ignored if a connection without SSL is made, or if the version of <SPAN CLASS="PRODUCTNAME" >OpenSSL</SPAN > used does not support it. </P ><P > Compression uses CPU time, but can improve throughput if the network is the bottleneck. Disabling compression can improve response time and throughput if CPU performance is the limiting factor. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-SSLCERT" ></A ><TT CLASS="LITERAL" >sslcert</TT ></DT ><DD ><P > This parameter specifies the file name of the client SSL certificate, replacing the default <TT CLASS="FILENAME" >~/.postgresql/postgresql.crt</TT >. This parameter is ignored if an SSL connection is not made. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-SSLKEY" ></A ><TT CLASS="LITERAL" >sslkey</TT ></DT ><DD ><P > This parameter specifies the location for the secret key used for the client certificate. It can either specify a file name that will be used instead of the default <TT CLASS="FILENAME" >~/.postgresql/postgresql.key</TT >, or it can specify a key obtained from an external <SPAN CLASS="QUOTE" >"engine"</SPAN > (engines are <SPAN CLASS="PRODUCTNAME" >OpenSSL</SPAN > loadable modules). An external engine specification should consist of a colon-separated engine name and an engine-specific key identifier. This parameter is ignored if an SSL connection is not made. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-SSLROOTCERT" ></A ><TT CLASS="LITERAL" >sslrootcert</TT ></DT ><DD ><P > This parameter specifies the name of a file containing SSL certificate authority (<ACRONYM CLASS="ACRONYM" >CA</ACRONYM >) certificate(s). If the file exists, the server's certificate will be verified to be signed by one of these authorities. The default is <TT CLASS="FILENAME" >~/.postgresql/root.crt</TT >. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-SSLCRL" ></A ><TT CLASS="LITERAL" >sslcrl</TT ></DT ><DD ><P > This parameter specifies the file name of the SSL certificate revocation list (CRL). Certificates listed in this file, if it exists, will be rejected while attempting to authenticate the server's certificate. The default is <TT CLASS="FILENAME" >~/.postgresql/root.crl</TT >. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-REQUIREPEER" ></A ><TT CLASS="LITERAL" >requirepeer</TT ></DT ><DD ><P > This parameter specifies the operating-system user name of the server, for example <TT CLASS="LITERAL" >requirepeer=postgres</TT >. When making a Unix-domain socket connection, if this parameter is set, the client checks at the beginning of the connection that the server process is running under the specified user name; if it is not, the connection is aborted with an error. This parameter can be used to provide server authentication similar to that available with SSL certificates on TCP/IP connections. (Note that if the Unix-domain socket is in <TT CLASS="FILENAME" >/tmp</TT > or another publicly writable location, any user could start a server listening there. Use this parameter to ensure that you are connected to a server run by a trusted user.) This option is only supported on platforms for which the <TT CLASS="LITERAL" >peer</TT > authentication method is implemented; see <A HREF="auth-methods.html#AUTH-PEER" >Section 19.3.7</A >. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-KRBSRVNAME" ></A ><TT CLASS="LITERAL" >krbsrvname</TT ></DT ><DD ><P > Kerberos service name to use when authenticating with Kerberos 5 or GSSAPI. This must match the service name specified in the server configuration for Kerberos authentication to succeed. (See also <A HREF="auth-methods.html#KERBEROS-AUTH" >Section 19.3.5</A > and <A HREF="auth-methods.html#GSSAPI-AUTH" >Section 19.3.3</A >.) </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-GSSLIB" ></A ><TT CLASS="LITERAL" >gsslib</TT ></DT ><DD ><P > GSS library to use for GSSAPI authentication. Only used on Windows. Set to <TT CLASS="LITERAL" >gssapi</TT > to force libpq to use the GSSAPI library for authentication instead of the default SSPI. </P ></DD ><DT ><A NAME="LIBPQ-CONNECT-SERVICE" ></A ><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 <A HREF="libpq-pgservice.html" >Section 31.16</A >. </P ></DD ></DL ></DIV ><P> </P ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LIBPQ-CONNSTRING" >31.1.2. Connection Strings</A ></H2 ><P > Several <SPAN CLASS="APPLICATION" >libpq</SPAN > functions parse a user-specified string to obtain connection parameters. There are two accepted formats for these strings: plain <TT CLASS="LITERAL" >keyword = value</TT > strings, and URIs. </P ><P > In the first format, each parameter setting is in the form <TT CLASS="LITERAL" >keyword = value</TT >. Spaces around the equal sign are optional. 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 >. </P ><P > The currently recognized parameter key words are listed in <A HREF="libpq-connect.html#LIBPQ-PARAMKEYWORDS" >Section 31.1.1</A >. </P ><P > The general form for connection <ACRONYM CLASS="ACRONYM" >URI</ACRONYM > is the following: </P><PRE CLASS="SYNOPSIS" >postgresql://username:password@hostname:port/database?param1=value1&param2=value2&... postgresql:///path/to/pgsql/socket/dir?param1=value1 </PRE ><P> </P ><P > The <ACRONYM CLASS="ACRONYM" >URI</ACRONYM > designator can be either <TT CLASS="LITERAL" >postgresql://</TT > or <TT CLASS="LITERAL" >postgres://</TT > and each of the <ACRONYM CLASS="ACRONYM" >URI</ACRONYM > parts is optional. The following examples illustrate valid <ACRONYM CLASS="ACRONYM" >URI</ACRONYM > syntax uses: </P><PRE CLASS="SYNOPSIS" > postgresql:// postgresql://localhost postgresql://localhost:5433 postgresql://localhost/mydb postgresql://user@localhost postgresql://user:secret@localhost postgresql://other@localhost/otherdb </PRE ><P> </P ><P > Additional connection parameters may optionally follow the base <ACRONYM CLASS="ACRONYM" >URI</ACRONYM >. Any connection parameters not corresponding to key words listed below are ignored and a warning message about them is sent to <TT CLASS="FILENAME" >stderr</TT >. </P ><P > For improved compatibility with JDBC connection <ACRONYM CLASS="ACRONYM" >URI</ACRONYM > syntax, instances of parameter <TT CLASS="LITERAL" >ssl=true</TT > are translated into <TT CLASS="LITERAL" >sslmode=require</TT > (see above.) </P ><P > Percent-encoding may be used to include a symbol with special meaning in any of the <ACRONYM CLASS="ACRONYM" >URI</ACRONYM > parts. </P ><P > The host part may be either hostname or an IP address. To specify an IPv6 host address, enclose it in square brackets: </P><PRE CLASS="SYNOPSIS" > postgresql://[::1]/database </PRE ><P> As a special case, a host part which starts with <TT CLASS="SYMBOL" >/</TT > is treated as a local Unix socket directory to look for the connection socket special file: </P><PRE CLASS="SYNOPSIS" > postgresql:///path/to/pgsql/socket/dir </PRE ><P> The whole connection string up to the extra parameters designator (<TT CLASS="SYMBOL" >?</TT >) is treated as the absolute path to the socket directory (<TT CLASS="LITERAL" >/path/to/pgsql/socket/dir</TT > in this example.) To specify a non-default database name in this case use the following syntax: </P><PRE CLASS="SYNOPSIS" > postgresql:///path/to/pgsql/socket/dir?dbname=other </PRE ><P> </P ></DIV ></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="libpq.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="libpq-status.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><SPAN CLASS="APPLICATION" >libpq</SPAN > - C Library</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="libpq.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Connection Status Functions</TD ></TR ></TABLE ></DIV ></BODY ></HTML > ^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Another review of URI for libpq, v7 submission @ 2012-04-11 07:46 Alvaro Herrera <[email protected]> parent: Alvaro Herrera <[email protected]> 0 siblings, 0 replies; 22+ messages in thread From: Alvaro Herrera @ 2012-04-11 07:46 UTC (permalink / raw) To: Peter Eisentraut <[email protected]>; +Cc: Alex <[email protected]>; Heikki Linnakangas <[email protected]>; pgsql-hackers Excerpts from Alvaro Herrera's message of lun abr 09 16:41:50 -0300 2012: > There are three minor things that need to be changed for this to be > committable: Committed this patch after some more editorialization; in particular the test was rewritten so that instead of trying to connect, it uses PQconninfoParse to figure out how the URI is parsed, which makes a lot more sense. Also some other changes to the accepted URI, in particular so that username, pwd, and port are possible to be specified when using unix-domain sockets. Now that it is a done deal I'm sure people will start complaining how bad the documentation change was; please keep the flames up. -- Álvaro Herrera <[email protected]> The PostgreSQL Company - Command Prompt, Inc. PostgreSQL Replication, Consulting, Custom Development, 24x7 support ^ permalink raw reply [nested|flat] 22+ messages in thread
* [PATCH 5/9] document store_change somewhat more @ 2026-03-12 15:10 Álvaro Herrera <[email protected]> 0 siblings, 0 replies; 22+ messages in thread From: Álvaro Herrera @ 2026-03-12 15:10 UTC (permalink / raw) --- .../replication/pgoutput_repack/pgoutput_repack.c | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/backend/replication/pgoutput_repack/pgoutput_repack.c b/src/backend/replication/pgoutput_repack/pgoutput_repack.c index 90f3a8975b9..79fc611b9ff 100644 --- a/src/backend/replication/pgoutput_repack/pgoutput_repack.c +++ b/src/backend/replication/pgoutput_repack/pgoutput_repack.c @@ -158,7 +158,14 @@ plugin_change(LogicalDecodingContext *ctx, ReorderBufferTXN *txn, } } -/* Store concurrent data change. */ +/* + * For each change affecting the table being repacked, we store enough + * information about each tuple in it, so that it can be replayed in the + * new copy of the table. + * + * XXX for DELETE and the UPDATE OLD tuples, we could store just the + * replication identity instead of the full tuple. + */ static void store_change(LogicalDecodingContext *ctx, Relation relation, ConcurrentChangeKind kind, HeapTuple tuple) -- 2.47.3 --pnppmxqkefjd4hu2 Content-Type: text/plain; charset=utf-8 Content-Disposition: attachment; filename*0="0006-use-int-instead-of-uint32-for-the-result-of-list_len.noc"; filename*1="fbot.txt" ^ permalink raw reply [nested|flat] 22+ messages in thread
end of thread, other threads:[~2026-03-12 15:10 UTC | newest] Thread overview: 22+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2012-03-15 08:49 Another review of URI for libpq, v7 submission Daniel Farina <[email protected]> 2012-03-15 14:34 ` Alvaro Herrera <[email protected]> 2012-03-15 14:36 ` Alex Shulgin <[email protected]> 2012-03-15 21:09 ` Daniel Farina <[email protected]> 2012-03-15 21:29 ` Alex <[email protected]> 2012-03-17 14:51 ` Marko Kreen <[email protected]> 2012-03-20 22:18 ` Alex <[email protected]> 2012-03-21 16:42 ` Trivial libpq refactoring patch (was: Re: Another review of URI for libpq, v7 submission) Alex Shulgin <[email protected]> 2012-03-22 16:10 ` Re: Trivial libpq refactoring patch (was: Re: Another review of URI for libpq, v7 submission) Tom Lane <[email protected]> 2012-03-22 21:42 ` Alex <[email protected]> 2012-03-27 13:03 ` Heikki Linnakangas <[email protected]> 2012-03-27 14:13 ` Alex Shulgin <[email protected]> 2012-03-27 17:22 ` Peter Eisentraut <[email protected]> 2012-03-27 19:21 ` Alex <[email protected]> 2012-03-27 22:49 ` Alex <[email protected]> 2012-04-05 16:52 ` Peter Eisentraut <[email protected]> 2012-04-05 22:10 ` Alvaro Herrera <[email protected]> 2012-04-06 03:25 ` Alvaro Herrera <[email protected]> 2012-04-06 06:09 ` Peter Eisentraut <[email protected]> 2012-04-09 19:41 ` Alvaro Herrera <[email protected]> 2012-04-11 07:46 ` Alvaro Herrera <[email protected]> 2026-03-12 15:10 [PATCH 5/9] document store_change somewhat more Álvaro Herrera <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox