Skip to content

Commit d10c626

Browse files
tglsfdctglsfdc
committed
Rename WAL-related functions and views to use "lsn" not "location".
Per discussion, "location" is a rather vague term that could refer to multiple concepts. "LSN" is an unambiguous term for WAL locations and should be preferred. Some function names, view column names, and function output argument names used "lsn" already, but others used "location", as well as yet other terms such as "wal_position". Since we've already renamed a lot of things in this area from "xlog" to "wal" for v10, we may as well incur a bit more compatibility pain and make these names all consistent. David Rowley, minor additional docs hacking by me Discussion: https://postgr.es/m/CAKJS1f8O0njDKe8ePFQ-LK5-EjwThsDws6ohJ-+c6nWK+oUxtg@mail.gmail.com
1 parent b66adb7 commit d10c626

31 files changed

+185
-185
lines changed

‎contrib/bloom/t/001_wal.pl

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ sub test_index_replay
1616
# Wait for standby to catch up
1717
my $applname = $node_standby->name;
1818
my $caughtup_query =
19-
"SELECT pg_current_wal_location() <= write_location FROM pg_stat_replication WHERE application_name = '$applname';";
19+
"SELECT pg_current_wal_lsn() <= write_lsn FROM pg_stat_replication WHERE application_name = '$applname';";
2020
$node_master->poll_query_until('postgres', $caughtup_query)
2121
or die "Timed out while waiting for standby 1 to catch up";
2222

‎contrib/test_decoding/expected/ddl.out

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ SELECT 'init' FROM pg_create_logical_replication_slot('regression_slot', 'test_d
5858
SELECT slot_name, plugin, slot_type, active,
5959
NOT catalog_xmin IS NULL AS catalog_xmin_set,
6060
xmin IS NULl AS data_xmin_not_set,
61-
pg_wal_location_diff(restart_lsn, '0/01000000') > 0 AS some_wal
61+
pg_wal_lsn_diff(restart_lsn, '0/01000000') > 0 AS some_wal
6262
FROM pg_replication_slots;
6363
slot_name | plugin | slot_type | active | catalog_xmin_set | data_xmin_not_set | some_wal
6464
-----------------+---------------+-----------+--------+------------------+-------------------+----------

‎contrib/test_decoding/sql/ddl.sql

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ SELECT 'init' FROM pg_create_logical_replication_slot('regression_slot', 'test_d
2929
SELECT slot_name, plugin, slot_type, active,
3030
NOT catalog_xmin IS NULL AS catalog_xmin_set,
3131
xmin IS NULl AS data_xmin_not_set,
32-
pg_wal_location_diff(restart_lsn, '0/01000000') > 0 AS some_wal
32+
pg_wal_lsn_diff(restart_lsn, '0/01000000') > 0 AS some_wal
3333
FROM pg_replication_slots;
3434

3535
/*

‎doc/src/sgml/func.sgml

Lines changed: 40 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -17908,17 +17908,17 @@ SELECT collation for ('foo' COLLATE "de_DE");
1790817908
<tbody>
1790917909

1791017910
<row>
17911-
<entry><literal>checkpoint_location</literal></entry>
17911+
<entry><literal>checkpoint_lsn</literal></entry>
1791217912
<entry><type>pg_lsn</type></entry>
1791317913
</row>
1791417914

1791517915
<row>
17916-
<entry><literal>prior_location</literal></entry>
17916+
<entry><literal>prior_lsn</literal></entry>
1791717917
<entry><type>pg_lsn</type></entry>
1791817918
</row>
1791917919

1792017920
<row>
17921-
<entry><literal>redo_location</literal></entry>
17921+
<entry><literal>redo_lsn</literal></entry>
1792217922
<entry><type>pg_lsn</type></entry>
1792317923
</row>
1792417924

@@ -18146,7 +18146,7 @@ SELECT collation for ('foo' COLLATE "de_DE");
1814618146
<tbody>
1814718147

1814818148
<row>
18149-
<entry><literal>min_recovery_end_location</literal></entry>
18149+
<entry><literal>min_recovery_end_lsn</literal></entry>
1815018150
<entry><type>pg_lsn</type></entry>
1815118151
</row>
1815218152

@@ -18156,12 +18156,12 @@ SELECT collation for ('foo' COLLATE "de_DE");
1815618156
</row>
1815718157

1815818158
<row>
18159-
<entry><literal>backup_start_location</literal></entry>
18159+
<entry><literal>backup_start_lsn</literal></entry>
1816018160
<entry><type>pg_lsn</type></entry>
1816118161
</row>
1816218162

1816318163
<row>
18164-
<entry><literal>backup_end_location</literal></entry>
18164+
<entry><literal>backup_end_lsn</literal></entry>
1816518165
<entry><type>pg_lsn</type></entry>
1816618166
</row>
1816718167

@@ -18404,13 +18404,13 @@ SELECT set_config('log_statement_stats', 'off', false);
1840418404
<primary>pg_create_restore_point</primary>
1840518405
</indexterm>
1840618406
<indexterm>
18407-
<primary>pg_current_wal_flush_location</primary>
18407+
<primary>pg_current_wal_flush_lsn</primary>
1840818408
</indexterm>
1840918409
<indexterm>
18410-
<primary>pg_current_wal_insert_location</primary>
18410+
<primary>pg_current_wal_insert_lsn</primary>
1841118411
</indexterm>
1841218412
<indexterm>
18413-
<primary>pg_current_wal_location</primary>
18413+
<primary>pg_current_wal_lsn</primary>
1841418414
</indexterm>
1841518415
<indexterm>
1841618416
<primary>pg_start_backup</primary>
@@ -18434,15 +18434,15 @@ SELECT set_config('log_statement_stats', 'off', false);
1843418434
<primary>pg_walfile_name_offset</primary>
1843518435
</indexterm>
1843618436
<indexterm>
18437-
<primary>pg_wal_location_diff</primary>
18437+
<primary>pg_wal_lsn_diff</primary>
1843818438
</indexterm>
1843918439

1844018440
<para>
1844118441
The functions shown in <xref
1844218442
linkend="functions-admin-backup-table"> assist in making on-line backups.
1844318443
These functions cannot be executed during recovery (except
1844418444
<function>pg_is_in_backup</function>, <function>pg_backup_start_time</function>
18445-
and <function>pg_wal_location_diff</function>).
18445+
and <function>pg_wal_lsn_diff</function>).
1844618446
</para>
1844718447

1844818448
<table id="functions-admin-backup-table">
@@ -18463,21 +18463,21 @@ SELECT set_config('log_statement_stats', 'off', false);
1846318463
</row>
1846418464
<row>
1846518465
<entry>
18466-
<literal><function>pg_current_wal_flush_location()</function></literal>
18466+
<literal><function>pg_current_wal_flush_lsn()</function></literal>
1846718467
</entry>
1846818468
<entry><type>pg_lsn</type></entry>
1846918469
<entry>Get current transaction log flush location</entry>
1847018470
</row>
1847118471
<row>
1847218472
<entry>
18473-
<literal><function>pg_current_wal_insert_location()</function></literal>
18473+
<literal><function>pg_current_wal_insert_lsn()</function></literal>
1847418474
</entry>
1847518475
<entry><type>pg_lsn</type></entry>
1847618476
<entry>Get current transaction log insert location</entry>
1847718477
</row>
1847818478
<row>
1847918479
<entry>
18480-
<literal><function>pg_current_wal_location()</function></literal>
18480+
<literal><function>pg_current_wal_lsn()</function></literal>
1848118481
</entry>
1848218482
<entry><type>pg_lsn</type></entry>
1848318483
<entry>Get current transaction log write location</entry>
@@ -18526,21 +18526,21 @@ SELECT set_config('log_statement_stats', 'off', false);
1852618526
</row>
1852718527
<row>
1852818528
<entry>
18529-
<literal><function>pg_walfile_name(<parameter>location</> <type>pg_lsn</>)</function></literal>
18529+
<literal><function>pg_walfile_name(<parameter>lsn</> <type>pg_lsn</>)</function></literal>
1853018530
</entry>
1853118531
<entry><type>text</type></entry>
18532-
<entry>Convert transaction log location string to file name</entry>
18532+
<entry>Convert transaction log location to file name</entry>
1853318533
</row>
1853418534
<row>
1853518535
<entry>
18536-
<literal><function>pg_walfile_name_offset(<parameter>location</> <type>pg_lsn</>)</function></literal>
18536+
<literal><function>pg_walfile_name_offset(<parameter>lsn</> <type>pg_lsn</>)</function></literal>
1853718537
</entry>
1853818538
<entry><type>text</>, <type>integer</></entry>
18539-
<entry>Convert transaction log location string to file name and decimal byte offset within file</entry>
18539+
<entry>Convert transaction log location to file name and decimal byte offset within file</entry>
1854018540
</row>
1854118541
<row>
1854218542
<entry>
18543-
<literal><function>pg_wal_location_diff(<parameter>location</> <type>pg_lsn</>, <parameter>location</> <type>pg_lsn</>)</function></literal>
18543+
<literal><function>pg_wal_lsn_diff(<parameter>lsn</> <type>pg_lsn</>, <parameter>lsn</> <type>pg_lsn</>)</function></literal>
1854418544
</entry>
1854518545
<entry><type>numeric</></entry>
1854618546
<entry>Calculate the difference between two transaction log locations</entry>
@@ -18623,17 +18623,17 @@ postgres=# select pg_start_backup('label_goes_here');
1862318623
</para>
1862418624

1862518625
<para>
18626-
<function>pg_current_wal_location</> displays the current transaction log write
18626+
<function>pg_current_wal_lsn</> displays the current transaction log write
1862718627
location in the same format used by the above functions. Similarly,
18628-
<function>pg_current_wal_insert_location</> displays the current transaction log
18629-
insertion point and <function>pg_current_wal_flush_location</> displays the
18630-
current transaction log flush point. The insertion point is the <quote>logical</>
18628+
<function>pg_current_wal_insert_lsn</> displays the current transaction log
18629+
insertion location and <function>pg_current_wal_flush_lsn</> displays the
18630+
current transaction log flush location. The insertion location is the <quote>logical</>
1863118631
end of the transaction log at any instant, while the write location is the end of
1863218632
what has actually been written out from the server's internal buffers and flush
1863318633
location is the location guaranteed to be written to durable storage. The write
1863418634
location is the end of what can be examined from outside the server, and is usually
1863518635
what you want if you are interested in archiving partially-complete transaction log
18636-
files. The insertion and flush points are made available primarily for server
18636+
files. The insertion and flush locations are made available primarily for server
1863718637
debugging purposes. These are both read-only operations and do not
1863818638
require superuser permissions.
1863918639
</para>
@@ -18658,7 +18658,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1865818658
</para>
1865918659

1866018660
<para>
18661-
<function>pg_wal_location_diff</> calculates the difference in bytes
18661+
<function>pg_wal_lsn_diff</> calculates the difference in bytes
1866218662
between two transaction log locations. It can be used with
1866318663
<structname>pg_stat_replication</structname> or some functions shown in
1866418664
<xref linkend="functions-admin-backup-table"> to get the replication lag.
@@ -18678,10 +18678,10 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1867818678
<primary>pg_is_in_recovery</primary>
1867918679
</indexterm>
1868018680
<indexterm>
18681-
<primary>pg_last_wal_receive_location</primary>
18681+
<primary>pg_last_wal_receive_lsn</primary>
1868218682
</indexterm>
1868318683
<indexterm>
18684-
<primary>pg_last_wal_replay_location</primary>
18684+
<primary>pg_last_wal_replay_lsn</primary>
1868518685
</indexterm>
1868618686
<indexterm>
1868718687
<primary>pg_last_xact_replay_timestamp</primary>
@@ -18713,7 +18713,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1871318713
</row>
1871418714
<row>
1871518715
<entry>
18716-
<literal><function>pg_last_wal_receive_location()</function></literal>
18716+
<literal><function>pg_last_wal_receive_lsn()</function></literal>
1871718717
</entry>
1871818718
<entry><type>pg_lsn</type></entry>
1871918719
<entry>Get last transaction log location received and synced to disk by
@@ -18727,7 +18727,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1872718727
</row>
1872818728
<row>
1872918729
<entry>
18730-
<literal><function>pg_last_wal_replay_location()</function></literal>
18730+
<literal><function>pg_last_wal_replay_lsn()</function></literal>
1873118731
</entry>
1873218732
<entry><type>pg_lsn</type></entry>
1873318733
<entry>Get last transaction log location replayed during recovery.
@@ -18950,7 +18950,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1895018950
<literal><function>pg_create_physical_replication_slot(<parameter>slot_name</parameter> <type>name</type> <optional>, <parameter>immediately_reserve</> <type>boolean</>, <parameter>temporary</> <type>boolean</></optional>)</function></literal>
1895118951
</entry>
1895218952
<entry>
18953-
(<parameter>slot_name</parameter> <type>name</type>, <parameter>wal_position</parameter> <type>pg_lsn</type>)
18953+
(<parameter>slot_name</parameter> <type>name</type>, <parameter>lsn</parameter> <type>pg_lsn</type>)
1895418954
</entry>
1895518955
<entry>
1895618956
Creates a new physical replication slot named
@@ -18995,7 +18995,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1899518995
<literal><function>pg_create_logical_replication_slot(<parameter>slot_name</parameter> <type>name</type>, <parameter>plugin</parameter> <type>name</type> <optional>, <parameter>temporary</> <type>boolean</></optional>)</function></literal>
1899618996
</entry>
1899718997
<entry>
18998-
(<parameter>slot_name</parameter> <type>name</type>, <parameter>wal_position</parameter> <type>pg_lsn</type>)
18998+
(<parameter>slot_name</parameter> <type>name</type>, <parameter>lsn</parameter> <type>pg_lsn</type>)
1899918999
</entry>
1900019000
<entry>
1900119001
Creates a new logical (decoding) replication slot named
@@ -19018,7 +19018,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1901819018
<literal><function>pg_logical_slot_get_changes(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal>
1901919019
</entry>
1902019020
<entry>
19021-
(<parameter>location</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>text</type>)
19021+
(<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>text</type>)
1902219022
</entry>
1902319023
<entry>
1902419024
Returns changes in the slot <parameter>slot_name</parameter>, starting
@@ -19043,7 +19043,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1904319043
<literal><function>pg_logical_slot_peek_changes(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal>
1904419044
</entry>
1904519045
<entry>
19046-
(<parameter>location</parameter> <type>text</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>text</type>)
19046+
(<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>text</type>)
1904719047
</entry>
1904819048
<entry>
1904919049
Behaves just like
@@ -19061,7 +19061,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1906119061
<literal><function>pg_logical_slot_get_binary_changes(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal>
1906219062
</entry>
1906319063
<entry>
19064-
(<parameter>location</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>bytea</type>)
19064+
(<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>bytea</type>)
1906519065
</entry>
1906619066
<entry>
1906719067
Behaves just like
@@ -19078,7 +19078,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1907819078
<literal><function>pg_logical_slot_peek_binary_changes(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal>
1907919079
</entry>
1908019080
<entry>
19081-
(<parameter>location</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>bytea</type>)
19081+
(<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>bytea</type>)
1908219082
</entry>
1908319083
<entry>
1908419084
Behaves just like
@@ -19197,7 +19197,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1919719197
<type>pg_lsn</type>
1919819198
</entry>
1919919199
<entry>
19200-
Return the replay position for the replication origin configured in
19200+
Return the replay location for the replication origin configured in
1920119201
the current session. The parameter <parameter>flush</parameter>
1920219202
determines whether the corresponding local transaction will be
1920319203
guaranteed to have been flushed to disk or not.
@@ -19244,15 +19244,15 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1924419244
<indexterm>
1924519245
<primary>pg_replication_origin_advance</primary>
1924619246
</indexterm>
19247-
<literal>pg_replication_origin_advance<function>(<parameter>node_name</parameter> <type>text</type>, <parameter>pos</parameter> <type>pg_lsn</type>)</function></literal>
19247+
<literal>pg_replication_origin_advance<function>(<parameter>node_name</parameter> <type>text</type>, <parameter>lsn</parameter> <type>pg_lsn</type>)</function></literal>
1924819248
</entry>
1924919249
<entry>
1925019250
<type>void</>
1925119251
</entry>
1925219252
<entry>
1925319253
Set replication progress for the given node to the given
19254-
position. This primarily is useful for setting up the initial position
19255-
or a new position after configuration changes and similar. Be aware
19254+
location. This primarily is useful for setting up the initial location
19255+
or a new location after configuration changes and similar. Be aware
1925619256
that careless use of this function can lead to inconsistently
1925719257
replicated data.
1925819258
</entry>
@@ -19269,7 +19269,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
1926919269
<type>pg_lsn</type>
1927019270
</entry>
1927119271
<entry>
19272-
Return the replay position for the given replication origin. The
19272+
Return the replay location for the given replication origin. The
1927319273
parameter <parameter>flush</parameter> determines whether the
1927419274
corresponding local transaction will be guaranteed to have been
1927519275
flushed to disk or not.

‎doc/src/sgml/high-availability.sgml

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -850,9 +850,9 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
850850
of WAL records generated in the primary, but not yet applied in the
851851
standby. You can calculate this lag by comparing the current WAL write
852852
location on the primary with the last WAL location received by the
853-
standby. They can be retrieved using
854-
<function>pg_current_wal_location</> on the primary and the
855-
<function>pg_last_wal_receive_location</> on the standby,
853+
standby. These locations can be retrieved using
854+
<function>pg_current_wal_lsn</> on the primary and
855+
<function>pg_last_wal_receive_lsn</> on the standby,
856856
respectively (see <xref linkend="functions-admin-backup-table"> and
857857
<xref linkend="functions-recovery-info-table"> for details).
858858
The last WAL receive location in the standby is also displayed in the
@@ -863,10 +863,10 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
863863
You can retrieve a list of WAL sender processes via the
864864
<link linkend="monitoring-stats-views-table">
865865
<literal>pg_stat_replication</></link> view. Large differences between
866-
<function>pg_current_wal_location</> and <literal>sent_location</> field
866+
<function>pg_current_wal_lsn</> and the view's <literal>sent_lsn</> field
867867
might indicate that the master server is under heavy load, while
868-
differences between <literal>sent_location</> and
869-
<function>pg_last_wal_receive_location</> on the standby might indicate
868+
differences between <literal>sent_lsn</> and
869+
<function>pg_last_wal_receive_lsn</> on the standby might indicate
870870
network delay, or that the standby is under heavy load.
871871
</para>
872872
</sect3>
@@ -927,8 +927,8 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
927927
You can create a replication slot like this:
928928
<programlisting>
929929
postgres=# SELECT * FROM pg_create_physical_replication_slot('node_a_slot');
930-
slot_name | wal_position
931-
-------------+---------------
930+
slot_name | lsn
931+
-------------+-----
932932
node_a_slot |
933933

934934
postgres=# SELECT * FROM pg_replication_slots;

0 commit comments

Comments
 (0)