Skip to content

Commit f347f21

Browse files
vbwagnervbwagner
committed
Applied multihost patch
1 parent 8965c10 commit f347f21

File tree

9 files changed

+1483
-124
lines changed

9 files changed

+1483
-124
lines changed

‎doc/src/sgml/libpq.sgml

Lines changed: 96 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -792,7 +792,7 @@ host=localhost port=5432 dbname=mydb connect_timeout=10
792792
<para>
793793
The general form for a connection <acronym>URI</acronym> is:
794794
<synopsis>
795-
postgresql://[user[:password]@][netloc][:port][/dbname][?param1=value1&amp;...]
795+
postgresql://[user[:password]@][netloc][:port][,netloc[:port]...][/dbname][?param1=value1&amp;...]
796796
</synopsis>
797797
</para>
798798

@@ -809,6 +809,7 @@ postgresql://localhost/mydb
809809
postgresql://user@localhost
810810
postgresql://user:secret@localhost
811811
postgresql://other@localhost/otherdb?connect_timeout=10&amp;application_name=myapp
812+
postgresql://node1,node2:5433,node3:4432,node4/mydb?hostorder=random&amp;target_server_type=any
812813
</programlisting>
813814
Components of the hierarchical part of the <acronym>URI</acronym> can also
814815
be given as parameters. For example:
@@ -831,7 +832,9 @@ postgresql:///mydb?host=localhost&amp;port=5433
831832
<para>
832833
For improved compatibility with JDBC connection <acronym>URI</acronym>s,
833834
instances of parameter <literal>ssl=true</literal> are translated into
834-
<literal>sslmode=require</literal>.
835+
<literal>sslmode=require</literal> and
836+
<literal>loadBalanceHosts=true</literal> into
837+
<literal>hostorder=random</literal>.
835838
</para>
836839

837840
<para>
@@ -841,6 +844,10 @@ postgresql:///mydb?host=localhost&amp;port=5433
841844
postgresql://[2001:db8::1234]/database
842845
</synopsis>
843846
</para>
847+
<para>
848+
There can be several host specifications, optionally accompanied
849+
with port, separated by comma.
850+
</para>
844851

845852
<para>
846853
The host component is interpreted as described for the parameter <xref
@@ -881,6 +888,21 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
881888
when <productname>&productname;</> was built). On machines without
882889
Unix-domain sockets, the default is to connect to <literal>localhost</>.
883890
</para>
891+
<para>
892+
There can be more than one <literal>host</literal> parameter in
893+
the connection string. In this case these hosts would be considered
894+
alternate entries into same database and if connection to first one
895+
fails, the second would be attemped, and so on. This can be used
896+
for high availability clusters or for load balancing. See the
897+
<xref linkend="libpq-connect-hostorder"> parameter. This feature
898+
works for TCP/IP host names only.
899+
</para>
900+
<para>
901+
The network host name can be accompanied by a port number, separated by
902+
colon. This port number is used only when connected to
903+
this host. If there is no port number, the port specified in the
904+
<xref linkend="libpq-connect-port"> parameter would be used instead.
905+
</para>
884906
</listitem>
885907
</varlistentry>
886908

@@ -933,7 +955,6 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
933955
is used to identify the connection in <filename>~/.pgpass</> (see
934956
<xref linkend="libpq-pgpass">).
935957
</para>
936-
937958
<para>
938959
Without either a host name or host address,
939960
<application>libpq</application> will connect using a
@@ -943,6 +964,43 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
943964
</listitem>
944965
</varlistentry>
945966

967+
<varlistentry id="libpq-connect-hostorder" xreflabel="hostorder">
968+
<term><literal>hostorder</literal></term>
969+
<listitem>
970+
<para>
971+
Specifies how to choose the host from the list of alternate hosts,
972+
specified in the <xref linkend="libpq-connect-host"> parameter.
973+
</para>
974+
<para>
975+
If the value of this argument is <literal>sequential</literal> (the
976+
default) connections to the hosts will be attempted in the order in
977+
which they are specified.
978+
</para>
979+
<para>
980+
If the value is <literal>random</literal>, the host to connect to
981+
will be randomly picked from the list. It allows load balacing between
982+
several cluster nodes. However, PostgreSQL doesn't currently support
983+
multimaster clusters. So, without the use of third-party products,
984+
only read-only connections can take advantage from
985+
load-balancing. See <xref linkend="libpq-connect-target-server-type">
986+
</para>
987+
</listitem>
988+
</varlistentry>
989+
990+
<varlistentry id="libpq-connect-target-server-type" xreflabel="target_server_type">
991+
<term><literal>target_server_type</literal></term>
992+
<listitem>
993+
<para>
994+
If this parameter is <literal>master</literal>, upon
995+
successful connection the host is checked to determine whether
996+
it is in a recovery state. If it is, it then tries next host
997+
in the connection string. If this parameter is
998+
<literaL>any</literal>, connection to standby nodes are
999+
considered successful.
1000+
</para>
1001+
</listitem>
1002+
</varlistentry>
1003+
9461004
<varlistentry id="libpq-connect-port" xreflabel="port">
9471005
<term><literal>port</literal></term>
9481006
<listitem>
@@ -985,7 +1043,6 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
9851043
</para>
9861044
</listitem>
9871045
</varlistentry>
988-
9891046
<varlistentry id="libpq-connect-connect-timeout" xreflabel="connect_timeout">
9901047
<term><literal>connect_timeout</literal></term>
9911048
<listitem>
@@ -996,7 +1053,28 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
9961053
</para>
9971054
</listitem>
9981055
</varlistentry>
999-
1056+
<varlistentry id="libpq-connect-falover-timeout" xreflabel="failover_timeout">
1057+
<term><literal>failover_timeout</literal></term>
1058+
<listitem>
1059+
<para>
1060+
Maximum time to cyclically retry all the hosts in the connection string.
1061+
(as decimal integer number of seconds). If not specified, then
1062+
hosts are tried just once.
1063+
</para>
1064+
<para>
1065+
If we have replicating cluster, and master node fails, it might
1066+
take some time to promote one of the standby nodes to the new master.
1067+
So clients which detect failure to connect to the master might
1068+
abandon attempts to reestablish a connection before the new master
1069+
becomes available.
1070+
</para>
1071+
<para>
1072+
Setting this parameter to a value that takes into account the amount of
1073+
time needed for failover to complete will ensure attempts to connect
1074+
to hosts continue to be made until the new master becomes available.
1075+
</para>
1076+
</listitem>
1077+
</varlistentry>
10001078
<varlistentry id="libpq-connect-client-encoding" xreflabel="client_encoding">
10011079
<term><literal>client_encoding</literal></term>
10021080
<listitem>
@@ -7228,6 +7306,19 @@ user=admin
72287306
An example file is provided at
72297307
<filename>share/pg_service.conf.sample</filename>.
72307308
</para>
7309+
<para>
7310+
If more than one <literal>host</literal> option is present in the same
7311+
section of the service file, it is interpeted as alternate servers for
7312+
failover or load-balancing. See <xref linkend="libpq-connect-host">
7313+
option in the connection string.
7314+
</para>
7315+
<para>
7316+
For all other options, the first value takes precedence over later ones.
7317+
</para>
7318+
<para>
7319+
Options specified in the connection string, along with the service option,
7320+
have precedence over values from the service file.
7321+
</para>
72317322
</sect1>
72327323

72337324

‎src/interfaces/libpq/Makefile

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ OBJS= fe-auth.o fe-auth-scram.o fe-connect.o fe-exec.o fe-misc.o fe-print.o fe-l
3636
libpq-events.o
3737
# libpgport C files we always use
3838
OBJS += chklocale.o inet_net_ntop.o noblock.o pg_strong_random.o \
39-
pgstrcasecmp.o pqsignal.o thread.o
39+
pgstrcasecmp.o pqsignal.o thread.o pgsleep.o
4040
# libpgport C files that are needed if identified by configure
4141
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))
4242
# backend/libpq
@@ -134,6 +134,9 @@ install: all installdirs install-lib
134134
installcheck:
135135
$(MAKE) -C test $@
136136

137+
check:
138+
$(prove_check)
139+
137140
installdirs: installdirs-lib
138141
$(MKDIR_P) '$(DESTDIR)$(includedir)' '$(DESTDIR)$(includedir_internal)' '$(DESTDIR)$(datadir)'
139142

@@ -147,6 +150,7 @@ uninstall: uninstall-lib
147150
clean distclean: clean-lib
148151
$(MAKE) -C test $@
149152
rm -f $(OBJS) pthread.h libpq.rc
153+
rm -rf tmp_check
150154
# Might be left over from a Win32 client-only build
151155
rm -f pg_config_paths.h
152156
rm -f inet_net_ntop.c noblock.c pgstrcasecmp.c pqsignal.c thread.c

0 commit comments

Comments
 (0)