Please let me know if I should change anything or if I got it more or less right.
Is attachment fine or is preference inline? On 03/08/2026 15:49, Daniel Gustafsson wrote:
On 3 Aug 2026, at 09:20, Oli Sennhauser <[email protected]> wrote: Yes I can try. One big patch or several small patches (one per chapter)?I think a single patch is fine here.To pgsql-hackers or pgsql-docs?While there are many documentation threads on -hackers, I prefer to keep them on -docs so let's continue here. -- Daniel Gustafsson
-- FromDual - Neutral and vendor independent MariaDB, MySQL and PostgreSQL services. FromDual GmbH Rebenweg 6 CH - 8610 Uster Oli Sennhauser CEO / Senior Consultant Phone: +41 44 500 58 20 Mobile: +41 79 830 09 33 [email protected] https://www.fromdual.com Twitter: fromdual
From 503d963ce05654de14dd82fd53dcc99fdefa2b0c Mon Sep 17 00:00:00 2001 From: shinguz <[email protected]> Date: Thu, 6 Aug 2026 10:06:05 +0200 Subject: [PATCH] some references on variables and functions added --- doc/src/sgml/func/func-admin.sgml | 6 ++-- doc/src/sgml/high-availability.sgml | 43 +++++++++++++++-------------- 2 files changed, 25 insertions(+), 24 deletions(-) diff --git a/doc/src/sgml/func/func-admin.sgml b/doc/src/sgml/func/func-admin.sgml index 0eae1c1f616..a14497e32de 100644 --- a/doc/src/sgml/func/func-admin.sgml +++ b/doc/src/sgml/func/func-admin.sgml @@ -403,7 +403,7 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560 </row> <row> - <entry role="func_table_entry"><para role="func_signature"> + <entry id="pg-backup-start" role="func_table_entry"><para role="func_signature"> <indexterm> <primary>pg_backup_start</primary> </indexterm> @@ -430,7 +430,7 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560 </row> <row> - <entry role="func_table_entry"><para role="func_signature"> + <entry id="pg-backup-stop" role="func_table_entry"><para role="func_signature"> <indexterm> <primary>pg_backup_stop</primary> </indexterm> @@ -491,7 +491,7 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560 </row> <row> - <entry role="func_table_entry"><para role="func_signature"> + <entry id="pg-switch-wal" role="func_table_entry"><para role="func_signature"> <indexterm> <primary>pg_switch_wal</primary> </indexterm> diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index fd338ab1540..91dfe8cd13d 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -1091,7 +1091,7 @@ primary_slot_name = 'node_a_slot' standby servers. This extends that standard level of durability offered by a transaction commit. This level of protection is referred to as 2-safe replication in computer science theory, and group-1-safe - (group-safe and 1-safe) when <varname>synchronous_commit</varname> is set to + (group-safe and 1-safe) when <xref linkend="guc-synchronous-commit"/> is set to <literal>remote_write</literal>. </para> @@ -1124,7 +1124,7 @@ primary_slot_name = 'node_a_slot' replication stream consumer that knows how to send the appropriate feedback messages. Besides the built-in physical and logical replication systems, this includes special programs such - as <command>pg_receivewal</command> and <command>pg_recvlogical</command> + as <xref linkend="app-pgreceivewal"/> and <xref linkend="app-pgrecvlogical"/> as well as some third-party replication systems and custom programs. Check the respective documentation for details on synchronous replication support. @@ -1137,14 +1137,14 @@ primary_slot_name = 'node_a_slot' Once streaming replication has been configured, configuring synchronous replication requires only one additional configuration step: <xref linkend="guc-synchronous-standby-names"/> must be set to - a non-empty value. <varname>synchronous_commit</varname> must also be set to + a non-empty value. <xref linkend="guc-synchronous-commit"/> must also be set to <literal>on</literal>, but since this is the default value, typically no change is required. (See <xref linkend="runtime-config-wal-settings"/> and <xref linkend="runtime-config-replication-primary"/>.) This configuration will cause each commit to wait for confirmation that the standby has written the commit record to durable storage. - <varname>synchronous_commit</varname> can be set by individual + <xref linkend="guc-synchronous-commit"/> can be set by individual users, so it can be configured in the configuration file, for particular users or databases, or dynamically by applications, in order to control the durability guarantee on a per-transaction basis. @@ -1155,11 +1155,11 @@ primary_slot_name = 'node_a_slot' WAL record is then sent to the standby. The standby sends reply messages each time a new batch of WAL data is written to disk, unless <varname>wal_receiver_status_interval</varname> is set to zero on the standby. - In the case that <varname>synchronous_commit</varname> is set to + In the case that <xref linkend="guc-synchronous-commit"/> is set to <literal>remote_apply</literal>, the standby sends reply messages when the commit record is replayed, making the transaction visible. If the standby is chosen as a synchronous standby, according to the setting - of <varname>synchronous_standby_names</varname> on the primary, the reply + of <xref linkend="guc-synchronous-standby-names"/> on the primary, the reply messages from that standby will be considered along with those from other synchronous standbys to decide when to release transactions waiting for confirmation that the commit record has been received. These parameters @@ -1171,7 +1171,7 @@ primary_slot_name = 'node_a_slot' </para> <para> - Setting <varname>synchronous_commit</varname> to <literal>remote_write</literal> will + Setting <xref linkend="guc-synchronous-commit"/> to <literal>remote_write</literal> will cause each commit to wait for confirmation that the standby has received the commit record and written it out to its own operating system, but not for the data to be flushed to disk on the standby. This @@ -1185,7 +1185,7 @@ primary_slot_name = 'node_a_slot' </para> <para> - Setting <varname>synchronous_commit</varname> to <literal>remote_apply</literal> will + Setting <xref linkend="guc-synchronous-commit"/> to <literal>remote_apply</literal> will cause each commit to wait until the current synchronous standbys report that they have replayed the transaction, making it visible to user queries. In simple cases, this allows for load balancing with causal @@ -1211,7 +1211,7 @@ primary_slot_name = 'node_a_slot' transactions will wait until all the standby servers which are considered as synchronous confirm receipt of their data. The number of synchronous standbys that transactions must wait for replies from is specified in - <varname>synchronous_standby_names</varname>. This parameter also specifies + <xref linkend="guc-synchronous-standby-names"/>. This parameter also specifies a list of standby names and the method (<literal>FIRST</literal> and <literal>ANY</literal>) to choose synchronous standbys from the listed ones. </para> @@ -1227,7 +1227,7 @@ primary_slot_name = 'node_a_slot' next-highest-priority standby. </para> <para> - An example of <varname>synchronous_standby_names</varname> for + An example of <xref linkend="guc-synchronous-standby-names"/> for a priority-based multiple synchronous standbys is: <programlisting> synchronous_standby_names = 'FIRST 2 (s1, s2, s3)' @@ -1248,7 +1248,7 @@ synchronous_standby_names = 'FIRST 2 (s1, s2, s3)' synchronous standbys in the list. </para> <para> - An example of <varname>synchronous_standby_names</varname> for + An example of <xref linkend="guc-synchronous-standby-names"/> for a quorum-based multiple synchronous standbys is: <programlisting> synchronous_standby_names = 'ANY 2 (s1, s2, s3)' @@ -1310,9 +1310,9 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)' <title>Planning for High Availability</title> <para> - <varname>synchronous_standby_names</varname> specifies the number and + <xref linkend="guc-synchronous-standby-names"/> specifies the number and names of synchronous standbys that transaction commits made when - <varname>synchronous_commit</varname> is set to <literal>on</literal>, + <xref linkend="guc-synchronous-commit"/> is set to <literal>on</literal>, <literal>remote_apply</literal> or <literal>remote_write</literal> will wait for responses from. Such transaction commits may never be completed if any one of the synchronous standbys should crash. @@ -1321,7 +1321,7 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)' <para> The best solution for high availability is to ensure you keep as many synchronous standbys as requested. This can be achieved by naming multiple - potential synchronous standbys using <varname>synchronous_standby_names</varname>. + potential synchronous standbys using <xref linkend="guc-synchronous-standby-names"/>. </para> <para> @@ -1369,7 +1369,7 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)' If you really cannot keep as many synchronous standbys as requested then you should decrease the number of synchronous standbys that transaction commits must wait for responses from - in <varname>synchronous_standby_names</varname> (or disable it) and + in <xref linkend="guc-synchronous-standby-names"/> (or disable it) and reload the configuration file on the primary server. </para> @@ -1380,9 +1380,9 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)' <para> If you need to re-create a standby server while transactions are - waiting, make sure that the functions <function>pg_backup_start()</function> - and <function>pg_backup_stop()</function> are run in a session with - <varname>synchronous_commit</varname> = <literal>off</literal>, otherwise those + waiting, make sure that the functions <link linkend="pg-backup-start"><function>pg_backup_start()</function></link> + and <link linkend="pg-backup-stop"><function>pg_backup_stop()</function></link> are run in a session with + <xref linkend="guc-synchronous-commit"/> = <literal>off</literal>, otherwise those requests will wait forever for the standby to appear. </para> @@ -1459,10 +1459,10 @@ postgres=# WAIT FOR LSN '0/306EE20'; to <literal>always</literal>, and the standby will call the archive command for every WAL segment it receives, whether it's by restoring from the archive or by streaming replication. The shared archive can - be handled similarly, but the <varname>archive_command</varname> or <varname>archive_library</varname> must + be handled similarly, but the <xref linkend="guc-archive-command"/> or <xref linkend="guc-archive-library"/> must test if the file being archived exists already, and if the existing file has identical contents. This requires more care in the - <varname>archive_command</varname> or <varname>archive_library</varname>, as it must + <xref linkend="guc-archive-command"/> or <xref linkend="guc-archive-library"/>, as it must be careful to not overwrite an existing file with different contents, but return success if the exactly same file is archived twice. And all that must be done free of race conditions, if two servers attempt @@ -2238,7 +2238,8 @@ HINT: You can then restart the server after making the necessary configuration <para> WAL file control commands will not work during recovery, - e.g., <function>pg_backup_start</function>, <function>pg_switch_wal</function> etc. + e.g., <link linkend="pg-backup-start"><function>pg_backup_start()</function></link>, + <link linkend="pg-switch-wal"><function>pg_switch_wal()</function></link> etc. </para> <para> -- 2.47.3
OpenPGP_0xB58CF11D3C9DDEA9.asc
Description: OpenPGP public key
OpenPGP_signature.asc
Description: OpenPGP digital signature
