Another review of URI for libpq, v7 submission
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]https://github.com/fdr/postgres/tree/uri, commit e50ef375b7a731ca79bf5d3ca8b0bd69c97a9e71, aka the 'uri' branch. 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
e50ef375b7a731ca79bf5d3ca8b0bd69c97a9e71, aka the 'uri' branch
--
fdr
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 <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support
Daniel Farina <daniel@heroku.com> 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
On Thu, Mar 15, 2012 at 7:36 AM, Alex Shulgin <ash@commandprompt.com> 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
Daniel Farina <daniel@heroku.com> 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
On Thu, Mar 15, 2012 at 11:29:31PM +0200, Alex wrote:
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
Marko Kreen <markokr@gmail.com> writes:
On Thu, Mar 15, 2012 at 11:29:31PM +0200, Alex wrote:
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
Alex <ash@commandprompt.com> writes:
Marko Kreen <markokr@gmail.com> writes:
On Thu, Mar 15, 2012 at 11:29:31PM +0200, Alex wrote:
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
Alex Shulgin <ash@commandprompt.com> 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
Alex <ash@commandprompt.com> writes:
Marko Kreen <markokr@gmail.com> writes:
On Thu, Mar 15, 2012 at 11:29:31PM +0200, Alex wrote:
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
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
Heikki Linnakangas <heikki.linnakangas@enterprisedb.com> 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
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:
libpq-uri-v9+petere.patchtext/x-patch; charset=UTF-8; name=libpq-uri-v9+petere.patchDownload
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
Peter Eisentraut <peter_e@gmx.net> 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.
Alex <ash@commandprompt.com> writes:
Peter Eisentraut <peter_e@gmx.net> 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:
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]
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 <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support
Attachments:
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 <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support
Attachments:
libpq-docs.patchapplication/octet-stream; name=libpq-docs.patchDownload
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">.
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".
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 <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support
Attachments:
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 <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support