doc: Additional information about timeline ID hexadecimal format

petere · petere · commit 0b51d423e974 · 2023-03-20T08:48:46.000+01:00
Timeline IDs are sometimes presented to the user in hexadecimal format (for example in WAL file names). Add a few bits of information to clarify this. Author: Sébastien Lardière <sebastien@lardiere.net> Discussion: https://www.postgresql.org/message-id/flat/8fef346e-2541-76c3-d768-6536ae052993@lardiere.net
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
@@ -1309,7 +1309,16 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
     a new timeline is created to identify the series of WAL records
     generated after that recovery.  The timeline
     ID number is part of WAL segment file names so a new timeline does
-    not overwrite the WAL data generated by previous timelines.  It is
+    not overwrite the WAL data generated by previous timelines.
+    For example, in the WAL file name
+    <filename>0000000100001234000055CD</filename>, the leading
+    <literal>00000001</literal> is the timeline ID in hexadecimal.  (Note that
+    in other contexts, such as server log messages, timeline IDs are
+    usually printed in decimal.)
+   </para>
+
+   <para>
+    It is
     in fact possible to archive many different timelines.  While that might
     seem like a useless feature, it's often a lifesaver.  Consider the
     situation where you aren't quite sure what point-in-time to recover to,
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
@@ -4113,6 +4113,14 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
         a standby server.  <literal>latest</literal> is the default.
        </para>
 
+       <para>
+        To specify a timeline ID in hexadecimal (for example, if extracted
+        from a WAL file name or history file), prefix it with a
+        <literal>0x</literal>.  For instance, if the WAL file name is
+        <filename>00000011000000A10000004F</filename>, then the timeline ID is
+        <literal>0x11</literal> (or 17 decimal).
+       </para>
+
        <para>
         You usually only need to set this parameter
         in complex re-recovery situations, where you need to return to
