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

Lines changed: 68 additions & 11 deletions
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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy