Skip to content

Commit ee28cac

Browse files
tglsfdctglsfdc
committed
Extend the abilities of libpq's target_session_attrs parameter.
In addition to the existing options of "any" and "read-write", we now support "read-only", "primary", "standby", and "prefer-standby". "read-write" retains its previous meaning of "transactions are read-write by default", and "read-only" inverts that. The other three modes test specifically for hot-standby status, which is not quite the same thing. (Setting default_transaction_read_only on a primary server renders it read-only to this logic, but not a standby.) Furthermore, if talking to a v14 or later server, no extra network round trip is needed to detect the session's status; the GUC_REPORT variables delivered by the server are enough. When talking to an older server, a SHOW or SELECT query is issued to detect session read-only-ness or server hot-standby state, as needed. Haribabu Kommi, Greg Nancarrow, Vignesh C, Tom Lane; reviewed at various times by Laurenz Albe, Takayuki Tsunakawa, Peter Smith. Discussion: https://postgr.es/m/CAF3+xM+8-ztOkaV9gHiJ3wfgENTq97QcjXQt+rbFQ6F7oNzt9A@mail.gmail.com
1 parent 57e6db7 commit ee28cac

File tree

6 files changed

+456
-114
lines changed

6 files changed

+456
-114
lines changed

‎doc/src/sgml/libpq.sgml

+68-11
Original file line numberDiff line numberDiff line change
@@ -1877,18 +1877,75 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
18771877
<term><literal>target_session_attrs</literal></term>
18781878
<listitem>
18791879
<para>
1880-
If this parameter is set to <literal>read-write</literal>, only a
1881-
connection in which read-write transactions are accepted by default
1882-
is considered acceptable. The query
1883-
<literal>SHOW transaction_read_only</literal> will be sent upon any
1884-
successful connection; if it returns <literal>on</literal>, the connection
1885-
will be closed. If multiple hosts were specified in the connection
1886-
string, any remaining servers will be tried just as if the connection
1887-
attempt had failed. The default value of this parameter,
1888-
<literal>any</literal>, regards all connections as acceptable.
1889-
</para>
1880+
This option determines whether the session must have certain
1881+
properties to be acceptable. It's typically used in combination
1882+
with multiple host names to select the first acceptable alternative
1883+
among several hosts. There are six modes:
1884+
1885+
<variablelist>
1886+
<varlistentry>
1887+
<term><literal>any</literal> (default)</term>
1888+
<listitem>
1889+
<para>
1890+
any successful connection is acceptable
1891+
</para>
1892+
</listitem>
1893+
</varlistentry>
1894+
1895+
<varlistentry>
1896+
<term><literal>read-write</literal></term>
1897+
<listitem>
1898+
<para>
1899+
session must accept read-write transactions by default (that
1900+
is, the server must not be in hot standby mode and
1901+
the <varname>default_transaction_read_only</varname> parameter
1902+
must be <literal>off</literal>)
1903+
</para>
1904+
</listitem>
1905+
</varlistentry>
1906+
1907+
<varlistentry>
1908+
<term><literal>read-only</literal></term>
1909+
<listitem>
1910+
<para>
1911+
session must not accept read-write transactions by default (the
1912+
converse)
1913+
</para>
1914+
</listitem>
1915+
</varlistentry>
1916+
1917+
<varlistentry>
1918+
<term><literal>primary</literal></term>
1919+
<listitem>
1920+
<para>
1921+
server must not be in hot standby mode
1922+
</para>
1923+
</listitem>
1924+
</varlistentry>
1925+
1926+
<varlistentry>
1927+
<term><literal>standby</literal></term>
1928+
<listitem>
1929+
<para>
1930+
server must be in hot standby mode
1931+
</para>
1932+
</listitem>
1933+
</varlistentry>
1934+
1935+
<varlistentry>
1936+
<term><literal>prefer-standby</literal></term>
1937+
<listitem>
1938+
<para>
1939+
first try to find a standby server, but if none of the listed
1940+
hosts is a standby server, try again in <literal>all</literal>
1941+
mode
1942+
</para>
1943+
</listitem>
1944+
</varlistentry>
1945+
</variablelist>
1946+
</para>
18901947
</listitem>
1891-
</varlistentry>
1948+
</varlistentry>
18921949
</variablelist>
18931950
</para>
18941951
</sect2>

0 commit comments

Comments
 (0)