Add hostorder and failover_timeout parameters to libpq; also provide backward compatibility with PGPROEE 9.6

Author: zilder

doc/src/sgml/libpq.sgml

@@ -844,7 +844,7 @@ postgresql://localhost/mydb
 postgresql://user@localhost
 postgresql://user:secret@localhost
 postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp
-postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp
+postgresql://host1:123,host2:456/somedb?hostorder=random&target_session_attrs=any&application_name=myapp
 </programlisting>
     Components of the hierarchical part of the <acronym>URI</acronym> can also
     be given as parameters.  For example:
@@ -909,14 +909,15 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
      <title>Specifying Multiple Hosts</title>
 
      <para>
-       It is possible to specify multiple hosts to connect to, so that they are
-       tried in the given order. In the Keyword/Value format, the <literal>host</>,
-       <literal>hostaddr</>, and <literal>port</> options accept a comma-separated
-       list of values. The same number of elements must be given in each option, such
-       that e.g. the first <literal>hostaddr</> corresponds to the first host name,
-       the second <literal>hostaddr</> corresponds to the second host name, and so
-       forth. As an exception, if only one <literal>port</literal> is specified, it
-       applies to all the hosts.
+       It is possible to specify multiple hosts to connect to. In the Keyword/Value
+       format, the <literal>host</>, <literal>hostaddr</>, and <literal>port</>
+       options accept a comma-separated list of values. The same number of
+       elements must be given in each option, such that e.g. the first
+       <literal>hostaddr</> corresponds to the first host name, the second
+       <literal>hostaddr</> corresponds to the second host name, and so
+       forth. As an exception, if only one <literal>port</literal> is specified,
+       it applies to all the hosts. The order in which hosts are tried may be
+       specified by <xref linkend="libpq-connect-hostorder"> parameter.
      </para>
 
      <para>
@@ -967,8 +968,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
         Unix-domain sockets, the default is to connect to <literal>localhost</>.
        </para>
        <para>
-        A comma-separated list of host names is also accepted, in which case
-        each host name in the list is tried in order. See
+        A comma-separated list of host names is also accepted. See
         <xref linkend="libpq-multiple-hosts"> for details.
        </para>
       </listitem>
@@ -1038,6 +1038,30 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
        </listitem>
       </varlistentry>
 
+      <varlistentry id="libpq-connect-hostorder" xreflabel="hostorder">
+       <term><literal>hostorder</literal></term>
+       <listitem>
+       <para>
+        Specifies the order in which hosts from the list of hosts
+        specified by the <xref linkend="libpq-connect-host"> parameter are
+        tried.
+       </para>
+       <para>
+        If the value of this argument is <literal>sequential</literal> (the
+        default) connections to the hosts will be attempted in the order in
+        which they are given.
+       </para>
+       <para>
+        If the value is <literal>random</literal>, the host to connect to
+        will be randomly picked from the list. It allows load balacing between
+        several cluster nodes. However, PostgreSQL doesn't currently support
+        multimaster clusters. So, without the use of third-party products,
+        only read-only connections can take advantage from load-balancing.
+        See <xref linkend="libpq-connect-target-session-attrs">
+       </para>
+       </listitem>
+      </varlistentry>
+
       <varlistentry id="libpq-connect-port" xreflabel="port">
        <term><literal>port</literal></term>
        <listitem>
@@ -1114,6 +1138,29 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       </listitem>
      </varlistentry>
 
+     <varlistentry id="libpq-connect-falover-timeout" xreflabel="failover_timeout">
+      <term><literal>failover_timeout</literal></term>
+      <listitem>
+      <para>
+       Maximum time to cyclically retry all the hosts in the connection string.
+       (as decimal integer number of seconds). If not specified, then
+       hosts are tried just once.
+      </para>
+      <para>
+       If we have replicating cluster, and master node fails, it might
+       take some time to promote one of the standby nodes to the new master.
+       So clients which detect failure to connect to the master might
+       abandon attempts to reestablish a connection before the new master
+       becomes available.
+      </para>
+      <para>
+       Setting this parameter to a value that takes into account the amount of
+       time needed for failover to complete will ensure attempts to connect
+       to hosts continue to be made until the new master becomes available.
+      </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="libpq-connect-client-encoding" xreflabel="client_encoding">
       <term><literal>client_encoding</literal></term>
       <listitem>
@@ -1498,13 +1545,14 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
 
      <varlistentry id="libpq-connect-target-session-attrs" xreflabel="target_session_attrs">
       <term><literal>target_session_attrs</literal></term>
+      <term><literal>target_server_type (synonym)</literal></term>
       <listitem>
        <para>
-        If this parameter is set to <literal>read-write</literal>, only a
-        connection in which read-write transactions are accepted by default
-        is considered acceptable.  The query
-        <literal>SHOW transaction_read_only</literal> will be sent upon any
-        successful connection; if it returns <literal>on</>, the connection
+        If this parameter is set to <literal>read-write</literal> (or its
+        equivalent <literal>master</literal>, only a connection in which
+        read-write transactions are accepted by default is considered acceptable.
+        The query <literal>SHOW transaction_read_only</literal> will be sent upon
+        any successful connection; if it returns <literal>on</>, the connection
         will be closed.  If multiple hosts were specified in the connection
         string, any remaining servers will be tried just as if the connection
         attempt had failed.  The default value of this parameter,

src/interfaces/libpq/Makefile

@@ -35,8 +35,8 @@ OBJS=	fe-auth.o fe-auth-scram.o fe-connect.o fe-exec.o fe-misc.o fe-print.o fe-l
 	fe-protocol2.o fe-protocol3.o pqexpbuffer.o fe-secure.o \
 	libpq-events.o
 # libpgport C files we always use
-OBJS += chklocale.o inet_net_ntop.o noblock.o pgstrcasecmp.o pqsignal.o \
-	thread.o
+OBJS += chklocale.o inet_net_ntop.o noblock.o pgsleep.o pgstrcasecmp.o \
+	pqsignal.o thread.o
 # libpgport C files that are needed if identified by configure
 OBJS += $(filter crypt.o getaddrinfo.o getpeereid.o inet_aton.o open.o system.o snprintf.o strerror.o strlcpy.o win32error.o win32setlocale.o, $(LIBOBJS))
 
@@ -148,6 +148,9 @@ install: all installdirs install-lib
 installcheck:
 	$(MAKE) -C test $@
 
+check:
+	$(prove_check)
+
 installdirs: installdirs-lib
 	$(MKDIR_P) '$(DESTDIR)$(includedir)' '$(DESTDIR)$(includedir_internal)' '$(DESTDIR)$(datadir)'
 

src/interfaces/libpq/fe-auth.c

@@ -45,6 +45,9 @@
 #include "fe-auth.h"
 
 
+#define CURRENT_HOST(conn) \
+	((conn)->connhost[(conn)->connaddr[(conn)->whichaddr].hostidx])
+
 #ifdef ENABLE_GSS
 /*
  * GSSAPI authentication system.
@@ -538,7 +541,7 @@ pg_SASL_init(PGconn *conn, int payloadlen)
 			char	   *password;
 
 			conn->password_needed = true;
-			password = conn->connhost[conn->whichhost].password;
+			password = CURRENT_HOST(conn).password;
 			if (password == NULL)
 				password = conn->pgpass;
 			if (password == NULL || password[0] == '\0')
@@ -949,7 +952,7 @@ pg_fe_sendauth(AuthRequest areq, int payloadlen, PGconn *conn)
 				char	   *password;
 
 				conn->password_needed = true;
-				password = conn->connhost[conn->whichhost].password;
+				password = CURRENT_HOST(conn).password;
 				if (password == NULL)
 					password = conn->pgpass;
 				if (password == NULL || password[0] == '\0')