Skip to content

Commit ee1bfd1

Browse files
robertmhaasrobertmhaas
committed
Add new pg_walsummary tool.
This can dump the contents of the WAL summary files found in pg_wal/summaries. Normally, this shouldn't really be something anyone needs to do, but it may be needed for debugging problems with incremental backup, or could possibly be useful to external tools. Discussion: http://postgr.es/m/CA+Tgmobvqqj-DW9F7uUzT-cQqs6wcVb-Xhs=w=hzJnXSE-kRGw@mail.gmail.com
1 parent d9ef650 commit ee1bfd1

File tree

13 files changed

+600
-0
lines changed

13 files changed

+600
-0
lines changed

‎doc/src/sgml/ref/allfiles.sgml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,6 +219,7 @@ Complete list of usable sgml source files in this directory.
219219
<!ENTITY pgtesttiming SYSTEM "pgtesttiming.sgml">
220220
<!ENTITY pgupgrade SYSTEM "pgupgrade.sgml">
221221
<!ENTITY pgwaldump SYSTEM "pg_waldump.sgml">
222+
<!ENTITY pgwalsummary SYSTEM "pg_walsummary.sgml">
222223
<!ENTITY postgres SYSTEM "postgres-ref.sgml">
223224
<!ENTITY psqlRef SYSTEM "psql-ref.sgml">
224225
<!ENTITY reindexdb SYSTEM "reindexdb.sgml">

‎doc/src/sgml/ref/pg_walsummary.sgml‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
<!--
2+
doc/src/sgml/ref/pg_walsummary.sgml
3+
PostgreSQL documentation
4+
-->
5+
6+
<refentry id="app-pgwalsummary">
7+
<indexterm zone="app-pgwalsummary">
8+
<primary>pg_walsummary</primary>
9+
</indexterm>
10+
11+
<refmeta>
12+
<refentrytitle><application>pg_walsummary</application></refentrytitle>
13+
<manvolnum>1</manvolnum>
14+
<refmiscinfo>Application</refmiscinfo>
15+
</refmeta>
16+
17+
<refnamediv>
18+
<refname>pg_walsummary</refname>
19+
<refpurpose>print contents of WAL summary files</refpurpose>
20+
</refnamediv>
21+
22+
<refsynopsisdiv>
23+
<cmdsynopsis>
24+
<command>pg_walsummary</command>
25+
<arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
26+
<arg rep="repeat"><replaceable>file</replaceable></arg>
27+
</cmdsynopsis>
28+
</refsynopsisdiv>
29+
30+
<refsect1>
31+
<title>Description</title>
32+
<para>
33+
<application>pg_walsummary</application> is used to print the contents of
34+
WAL summary files. These binary files are found with the
35+
<literal>pg_wal/summaries</literal> subdirectory of the data directory,
36+
and can be converted to text using this tool. This is not ordinarily
37+
necessary, since WAL summary files primarily exist to support
38+
<link linkend="backup-incremental-backup">incremental backup</link>,
39+
but it may be useful for debugging purposes.
40+
</para>
41+
42+
<para>
43+
A WAL summary file is indexed by tablespace OID, relation OID, and relation
44+
fork. For each relation fork, it stores the list of blocks that were
45+
modified by WAL within the range summarized in the file. It can also
46+
store a "limit block," which is 0 if the relation fork was created or
47+
truncated within the relevant WAL range, and otherwise the shortest length
48+
to which the relation fork was truncated. If the relation fork was not
49+
created, deleted, or truncated within the relevant WAL range, the limit
50+
block is undefined or infinite and will not be printed by this tool.
51+
</para>
52+
</refsect1>
53+
54+
<refsect1>
55+
<title>Options</title>
56+
57+
<para>
58+
<variablelist>
59+
<varlistentry>
60+
<term><option>-i</option></term>
61+
<term><option>--indivudual</option></term>
62+
<listitem>
63+
<para>
64+
By default, <literal>pg_walsummary</literal> prints one line of output
65+
for each range of one or more consecutive modified blocks. This can
66+
make the output a lot briefer, since a relation where all blocks from
67+
0 through 999 were modified will produce only one line of output rather
68+
than 1000 separate lines. This option requests a separate line of
69+
output for every modified block.
70+
</para>
71+
</listitem>
72+
</varlistentry>
73+
74+
<varlistentry>
75+
<term><option>-q</option></term>
76+
<term><option>--quiet</option></term>
77+
<listitem>
78+
<para>
79+
Do not print any output, except for errors. This can be useful
80+
when you want to know whether a WAL summary file can be successfully
81+
parsed but don't care about the contents.
82+
</para>
83+
</listitem>
84+
</varlistentry>
85+
86+
<varlistentry>
87+
<term><option>-?</option></term>
88+
<term><option>--help</option></term>
89+
<listitem>
90+
<para>
91+
Shows help about <application>pg_walsummary</application> command line
92+
arguments, and exits.
93+
</para>
94+
</listitem>
95+
</varlistentry>
96+
97+
</variablelist>
98+
</para>
99+
100+
</refsect1>
101+
102+
<refsect1>
103+
<title>Environment</title>
104+
105+
<para>
106+
The environment variable <envar>PG_COLOR</envar> specifies whether to use
107+
color in diagnostic messages. Possible values are
108+
<literal>always</literal>, <literal>auto</literal> and
109+
<literal>never</literal>.
110+
</para>
111+
</refsect1>
112+
113+
<refsect1>
114+
<title>See Also</title>
115+
116+
<simplelist type="inline">
117+
<member><xref linkend="app-pgbasebackup"/></member>
118+
<member><xref linkend="app-pgcombinebackup"/></member>
119+
</simplelist>
120+
</refsect1>
121+
122+
</refentry>

‎doc/src/sgml/reference.sgml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -289,6 +289,7 @@
289289
&pgtesttiming;
290290
&pgupgrade;
291291
&pgwaldump;
292+
&pgwalsummary;
292293
&postgres;
293294

294295
</reference>

‎src/bin/Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ SUBDIRS = \
3131
pg_upgrade \
3232
pg_verifybackup \
3333
pg_waldump \
34+
pg_walsummary \
3435
pgbench \
3536
psql \
3637
scripts

‎src/bin/meson.build‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ subdir('pg_test_timing')
1717
subdir('pg_upgrade')
1818
subdir('pg_verifybackup')
1919
subdir('pg_waldump')
20+
subdir('pg_walsummary')
2021
subdir('pgbench')
2122
subdir('pgevent')
2223
subdir('psql')

‎src/bin/pg_walsummary/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pg_walsummary

‎src/bin/pg_walsummary/Makefile‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
#-------------------------------------------------------------------------
2+
#
3+
# Makefile for src/bin/pg_walsummary
4+
#
5+
# Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group
6+
# Portions Copyright (c) 1994, Regents of the University of California
7+
#
8+
# src/bin/pg_walsummary/Makefile
9+
#
10+
#-------------------------------------------------------------------------
11+
12+
PGFILEDESC = "pg_walsummary - print contents of WAL summary files"
13+
PGAPPICON=win32
14+
15+
subdir = src/bin/pg_walsummary
16+
top_builddir = ../../..
17+
include $(top_builddir)/src/Makefile.global
18+
19+
override CPPFLAGS := -I$(libpq_srcdir) $(CPPFLAGS)
20+
LDFLAGS_INTERNAL += -L$(top_builddir)/src/fe_utils -lpgfeutils
21+
22+
OBJS = \
23+
$(WIN32RES) \
24+
pg_walsummary.o
25+
26+
all: pg_walsummary
27+
28+
pg_walsummary: $(OBJS) | submake-libpgport submake-libpgfeutils
29+
$(CC) $(CFLAGS) $^ $(LDFLAGS) $(LDFLAGS_EX) $(LIBS) -o $@$(X)
30+
31+
32+
install: all installdirs
33+
$(INSTALL_PROGRAM) pg_walsummary$(X) '$(DESTDIR)$(bindir)/pg_walsummary$(X)'
34+
35+
installdirs:
36+
$(MKDIR_P) '$(DESTDIR)$(bindir)'
37+
38+
uninstall:
39+
rm -f '$(DESTDIR)$(bindir)/pg_walsummary$(X)'
40+
41+
clean distclean maintainer-clean:
42+
rm -f pg_walsummary$(X) $(OBJS)
43+
44+
check:
45+
$(prove_check)
46+
47+
installcheck:
48+
$(prove_installcheck)

‎src/bin/pg_walsummary/meson.build‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Copyright (c) 2022-2023, PostgreSQL Global Development Group
2+
3+
pg_walsummary_sources = files(
4+
'pg_walsummary.c',
5+
)
6+
7+
if host_system == 'windows'
8+
pg_walsummary_sources += rc_bin_gen.process(win32ver_rc, extra_args: [
9+
'--NAME', 'pg_walsummary',
10+
'--FILEDESC', 'pg_walsummary - print contents of WAL summary files',])
11+
endif
12+
13+
pg_walsummary = executable('pg_walsummary',
14+
pg_walsummary_sources,
15+
dependencies: [frontend_code],
16+
kwargs: default_bin_args,
17+
)
18+
bin_targets += pg_walsummary
19+
20+
tests += {
21+
'name': 'pg_walsummary',
22+
'sd': meson.current_source_dir(),
23+
'bd': meson.current_build_dir(),
24+
'tap': {
25+
'tests': [
26+
't/001_basic.pl',
27+
't/002_blocks.pl',
28+
],
29+
}
30+
}

‎src/bin/pg_walsummary/nls.mk‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# src/bin/pg_combinebackup/nls.mk
2+
CATALOG_NAME = pg_walsummary
3+
GETTEXT_FILES = $(FRONTEND_COMMON_GETTEXT_FILES) \
4+
pg_walsummary.c
5+
GETTEXT_TRIGGERS = $(FRONTEND_COMMON_GETTEXT_TRIGGERS)
6+
GETTEXT_FLAGS = $(FRONTEND_COMMON_GETTEXT_FLAGS)

0 commit comments

Comments
 (0)