From d10c626de47d8b048b663471c7785603a2ec8641 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 11 May 2017 11:49:59 -0400 Subject: 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 --- doc/src/sgml/func.sgml | 80 ++++++++++++++++++------------------- doc/src/sgml/high-availability.sgml | 16 ++++---- doc/src/sgml/logicaldecoding.sgml | 62 ++++++++++++++-------------- doc/src/sgml/monitoring.sgml | 16 ++++---- doc/src/sgml/test-decoding.sgml | 2 +- 5 files changed, 88 insertions(+), 88 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 629865701fb..4b9a54c0c9e 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -17908,17 +17908,17 @@ SELECT collation for ('foo' COLLATE "de_DE"); - checkpoint_location + checkpoint_lsn pg_lsn - prior_location + prior_lsn pg_lsn - redo_location + redo_lsn pg_lsn @@ -18146,7 +18146,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); - min_recovery_end_location + min_recovery_end_lsn pg_lsn @@ -18156,12 +18156,12 @@ SELECT collation for ('foo' COLLATE "de_DE"); - backup_start_location + backup_start_lsn pg_lsn - backup_end_location + backup_end_lsn pg_lsn @@ -18404,13 +18404,13 @@ SELECT set_config('log_statement_stats', 'off', false); pg_create_restore_point - pg_current_wal_flush_location + pg_current_wal_flush_lsn - pg_current_wal_insert_location + pg_current_wal_insert_lsn - pg_current_wal_location + pg_current_wal_lsn pg_start_backup @@ -18434,7 +18434,7 @@ SELECT set_config('log_statement_stats', 'off', false); pg_walfile_name_offset - pg_wal_location_diff + pg_wal_lsn_diff @@ -18442,7 +18442,7 @@ SELECT set_config('log_statement_stats', 'off', false); linkend="functions-admin-backup-table"> assist in making on-line backups. These functions cannot be executed during recovery (except pg_is_in_backup, pg_backup_start_time - and pg_wal_location_diff). + and pg_wal_lsn_diff). @@ -18463,21 +18463,21 @@ SELECT set_config('log_statement_stats', 'off', false); - pg_current_wal_flush_location() + pg_current_wal_flush_lsn() pg_lsn Get current transaction log flush location - pg_current_wal_insert_location() + pg_current_wal_insert_lsn() pg_lsn Get current transaction log insert location - pg_current_wal_location() + pg_current_wal_lsn() pg_lsn Get current transaction log write location @@ -18526,21 +18526,21 @@ SELECT set_config('log_statement_stats', 'off', false); - pg_walfile_name(location pg_lsn) + pg_walfile_name(lsn pg_lsn) text - Convert transaction log location string to file name + Convert transaction log location to file name - pg_walfile_name_offset(location pg_lsn) + pg_walfile_name_offset(lsn pg_lsn) text, integer - Convert transaction log location string to file name and decimal byte offset within file + Convert transaction log location to file name and decimal byte offset within file - pg_wal_location_diff(location pg_lsn, location pg_lsn) + pg_wal_lsn_diff(lsn pg_lsn, lsn pg_lsn) numeric Calculate the difference between two transaction log locations @@ -18623,17 +18623,17 @@ postgres=# select pg_start_backup('label_goes_here'); - pg_current_wal_location displays the current transaction log write + pg_current_wal_lsn displays the current transaction log write location in the same format used by the above functions. Similarly, - pg_current_wal_insert_location displays the current transaction log - insertion point and pg_current_wal_flush_location displays the - current transaction log flush point. The insertion point is the logical + pg_current_wal_insert_lsn displays the current transaction log + insertion location and pg_current_wal_flush_lsn displays the + current transaction log flush location. The insertion location is the logical end of the transaction log at any instant, while the write location is the end of what has actually been written out from the server's internal buffers and flush location is the location guaranteed to be written to durable storage. The write location is the end of what can be examined from outside the server, and is usually what you want if you are interested in archiving partially-complete transaction log - files. The insertion and flush points are made available primarily for server + files. The insertion and flush locations are made available primarily for server debugging purposes. These are both read-only operations and do not require superuser permissions. @@ -18658,7 +18658,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); - pg_wal_location_diff calculates the difference in bytes + pg_wal_lsn_diff calculates the difference in bytes between two transaction log locations. It can be used with pg_stat_replication or some functions shown in to get the replication lag. @@ -18678,10 +18678,10 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); pg_is_in_recovery - pg_last_wal_receive_location + pg_last_wal_receive_lsn - pg_last_wal_replay_location + pg_last_wal_replay_lsn pg_last_xact_replay_timestamp @@ -18713,7 +18713,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); - pg_last_wal_receive_location() + pg_last_wal_receive_lsn() pg_lsn 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()); - pg_last_wal_replay_location() + pg_last_wal_replay_lsn() pg_lsn Get last transaction log location replayed during recovery. @@ -18950,7 +18950,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); pg_create_physical_replication_slot(slot_name name , immediately_reserve boolean, temporary boolean) - (slot_name name, wal_position pg_lsn) + (slot_name name, lsn pg_lsn) Creates a new physical replication slot named @@ -18995,7 +18995,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); pg_create_logical_replication_slot(slot_name name, plugin name , temporary boolean) - (slot_name name, wal_position pg_lsn) + (slot_name name, lsn pg_lsn) Creates a new logical (decoding) replication slot named @@ -19018,7 +19018,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); pg_logical_slot_get_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[]) - (location pg_lsn, xid xid, data text) + (lsn pg_lsn, xid xid, data text) Returns changes in the slot slot_name, starting @@ -19043,7 +19043,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); pg_logical_slot_peek_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[]) - (location text, xid xid, data text) + (lsn pg_lsn, xid xid, data text) Behaves just like @@ -19061,7 +19061,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); pg_logical_slot_get_binary_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[]) - (location pg_lsn, xid xid, data bytea) + (lsn pg_lsn, xid xid, data bytea) Behaves just like @@ -19078,7 +19078,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); pg_logical_slot_peek_binary_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[]) - (location pg_lsn, xid xid, data bytea) + (lsn pg_lsn, xid xid, data bytea) Behaves just like @@ -19197,7 +19197,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); pg_lsn - Return the replay position for the replication origin configured in + Return the replay location for the replication origin configured in the current session. The parameter flush determines whether the corresponding local transaction will be guaranteed to have been flushed to disk or not. @@ -19244,15 +19244,15 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); pg_replication_origin_advance - pg_replication_origin_advance(node_name text, pos pg_lsn) + pg_replication_origin_advance(node_name text, lsn pg_lsn) void Set replication progress for the given node to the given - position. This primarily is useful for setting up the initial position - or a new position after configuration changes and similar. Be aware + location. This primarily is useful for setting up the initial location + or a new location after configuration changes and similar. Be aware that careless use of this function can lead to inconsistently replicated data. @@ -19269,7 +19269,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); pg_lsn - Return the replay position for the given replication origin. The + Return the replay location for the given replication origin. The parameter flush determines whether the corresponding local transaction will be guaranteed to have been flushed to disk or not. diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index 22ac10f4284..913f9ae41f5 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -850,9 +850,9 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' of WAL records generated in the primary, but not yet applied in the standby. You can calculate this lag by comparing the current WAL write location on the primary with the last WAL location received by the - standby. They can be retrieved using - pg_current_wal_location on the primary and the - pg_last_wal_receive_location on the standby, + standby. These locations can be retrieved using + pg_current_wal_lsn on the primary and + pg_last_wal_receive_lsn on the standby, respectively (see and for details). 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' You can retrieve a list of WAL sender processes via the pg_stat_replication view. Large differences between - pg_current_wal_location and sent_location field + pg_current_wal_lsn and the view's sent_lsn field might indicate that the master server is under heavy load, while - differences between sent_location and - pg_last_wal_receive_location on the standby might indicate + differences between sent_lsn and + pg_last_wal_receive_lsn on the standby might indicate network delay, or that the standby is under heavy load. @@ -927,8 +927,8 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' You can create a replication slot like this: postgres=# SELECT * FROM pg_create_physical_replication_slot('node_a_slot'); - slot_name | wal_position --------------+--------------- + slot_name | lsn +-------------+----- node_a_slot | postgres=# SELECT * FROM pg_replication_slots; diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml index bb22f9ae22d..c2950613fa5 100644 --- a/doc/src/sgml/logicaldecoding.sgml +++ b/doc/src/sgml/logicaldecoding.sgml @@ -56,8 +56,8 @@ postgres=# -- Create a slot named 'regression_slot' using the output plugin 'test_decoding' postgres=# SELECT * FROM pg_create_logical_replication_slot('regression_slot', 'test_decoding'); - slot_name | wal_position ------------------+--------------- + slot_name | lsn +-----------------+----------- regression_slot | 0/16B1970 (1 row) @@ -69,8 +69,8 @@ postgres=# SELECT slot_name, plugin, slot_type, database, active, restart_lsn, c postgres=# -- There are no changes to see yet postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL); - location | xid | data -----------+-----+------ + lsn | xid | data +-----+-----+------ (0 rows) postgres=# CREATE TABLE data(id serial primary key, data text); @@ -78,17 +78,17 @@ CREATE TABLE postgres=# -- DDL isn't replicated, so all you'll see is the transaction postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL); - location | xid | data ------------+-----+------------ - 0/16D5D48 | 688 | BEGIN 688 - 0/16E0380 | 688 | COMMIT 688 + lsn | xid | data +-----------+-------+-------------- + 0/BA2DA58 | 10297 | BEGIN 10297 + 0/BA5A5A0 | 10297 | COMMIT 10297 (2 rows) postgres=# -- Once changes are read, they're consumed and not emitted postgres=# -- in a subsequent call: postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL); - location | xid | data -----------+-----+------ + lsn | xid | data +-----+-----+------ (0 rows) postgres=# BEGIN; @@ -97,41 +97,41 @@ postgres=# INSERT INTO data(data) VALUES('2'); postgres=# COMMIT; postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL); - location | xid | data ------------+-----+----------------------------------------------- - 0/16E0478 | 689 | BEGIN 689 - 0/16E0478 | 689 | table public.data: INSERT: id[integer]:1 data[text]:'1' - 0/16E0580 | 689 | table public.data: INSERT: id[integer]:2 data[text]:'2' - 0/16E0650 | 689 | COMMIT 689 + lsn | xid | data +-----------+-------+--------------------------------------------------------- + 0/BA5A688 | 10298 | BEGIN 10298 + 0/BA5A6F0 | 10298 | table public.data: INSERT: id[integer]:1 data[text]:'1' + 0/BA5A7F8 | 10298 | table public.data: INSERT: id[integer]:2 data[text]:'2' + 0/BA5A8A8 | 10298 | COMMIT 10298 (4 rows) postgres=# INSERT INTO data(data) VALUES('3'); postgres=# -- You can also peek ahead in the change stream without consuming changes postgres=# SELECT * FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL); - location | xid | data ------------+-----+----------------------------------------------- - 0/16E09C0 | 690 | BEGIN 690 - 0/16E09C0 | 690 | table public.data: INSERT: id[integer]:3 data[text]:'3' - 0/16E0B90 | 690 | COMMIT 690 + lsn | xid | data +-----------+-------+--------------------------------------------------------- + 0/BA5A8E0 | 10299 | BEGIN 10299 + 0/BA5A8E0 | 10299 | table public.data: INSERT: id[integer]:3 data[text]:'3' + 0/BA5A990 | 10299 | COMMIT 10299 (3 rows) postgres=# -- The next call to pg_logical_slot_peek_changes() returns the same changes again postgres=# SELECT * FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL); - location | xid | data ------------+-----+----------------------------------------------- - 0/16E09C0 | 690 | BEGIN 690 - 0/16E09C0 | 690 | table public.data: INSERT: id[integer]:3 data[text]:'3' - 0/16E0B90 | 690 | COMMIT 690 + lsn | xid | data +-----------+-------+--------------------------------------------------------- + 0/BA5A8E0 | 10299 | BEGIN 10299 + 0/BA5A8E0 | 10299 | table public.data: INSERT: id[integer]:3 data[text]:'3' + 0/BA5A990 | 10299 | COMMIT 10299 (3 rows) postgres=# -- options can be passed to output plugin, to influence the formatting postgres=# SELECT * FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL, 'include-timestamp', 'on'); - location | xid | data ------------+-----+----------------------------------------------- - 0/16E09C0 | 690 | BEGIN 690 - 0/16E09C0 | 690 | table public.data: INSERT: id[integer]:3 data[text]:'3' - 0/16E0B90 | 690 | COMMIT 690 (at 2014-02-27 16:41:51.863092+01) + lsn | xid | data +-----------+-------+--------------------------------------------------------- + 0/BA5A8E0 | 10299 | BEGIN 10299 + 0/BA5A8E0 | 10299 | table public.data: INSERT: id[integer]:3 data[text]:'3' + 0/BA5A990 | 10299 | COMMIT 10299 (at 2017-05-10 12:07:21.272494-04) (3 rows) postgres=# -- Remember to destroy a slot you no longer need to stop it consuming diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 80d12b26d77..d5e656f2db8 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -1699,26 +1699,26 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i - sent_location + sent_lsn pg_lsn - Last transaction log position sent on this connection + Last transaction log location sent on this connection - write_location + write_lsn pg_lsn - Last transaction log position written to disk by this standby + Last transaction log location written to disk by this standby server - flush_location + flush_lsn pg_lsn - Last transaction log position flushed to disk by this standby + Last transaction log location flushed to disk by this standby server - replay_location + replay_lsn pg_lsn - Last transaction log position replayed into the database on this + Last transaction log location replayed into the database on this standby server diff --git a/doc/src/sgml/test-decoding.sgml b/doc/src/sgml/test-decoding.sgml index 23cdfe35f8a..4f4fd41e320 100644 --- a/doc/src/sgml/test-decoding.sgml +++ b/doc/src/sgml/test-decoding.sgml @@ -25,7 +25,7 @@ postgres=# SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'include-xids', '0'); - location | xid | data + lsn | xid | data -----------+-----+-------------------------------------------------- 0/16D30F8 | 691 | BEGIN 0/16D32A0 | 691 | table public.data: INSERT: id[int4]:2 data[text]:'arg' -- cgit v1.2.3