Skip to content

Commit e19e4cf

Browse files
peterepetere
committed
doc: Reorganize pg_resetxlog reference page
The pg_resetxlog reference page didn't have a proper options list, only running text listing the options and some explanations of them. This might have worked when there were only a few options, but the list has grown over the releases, and now it's hard to find an option and its associated explanation. So write out the options list as on other reference pages.
1 parent 28f6df3 commit e19e4cf

File tree

1 file changed

+144
-78
lines changed

1 file changed

+144
-78
lines changed

‎doc/src/sgml/ref/pg_resetxlog.sgml

Lines changed: 144 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,9 @@ PostgreSQL documentation
2222
<refsynopsisdiv>
2323
<cmdsynopsis>
2424
<command>pg_resetxlog</command>
25-
<arg choice="opt"><option>-c</option> <replaceable class="parameter">xid</replaceable>,<replaceable class="parameter">xid</replaceable></arg>
2625
<arg choice="opt"><option>-f</option></arg>
2726
<arg choice="opt"><option>-n</option></arg>
28-
<arg choice="opt"><option>-o</option> <replaceable class="parameter">oid</replaceable></arg>
29-
<arg choice="opt"><option>-x</option> <replaceable class="parameter">xid</replaceable></arg>
30-
<arg choice="opt"><option>-e</option> <replaceable class="parameter">xid_epoch</replaceable></arg>
31-
<arg choice="opt"><option>-m</option> <replaceable class="parameter">mxid</replaceable>,<replaceable class="parameter">mxid</replaceable></arg>
32-
<arg choice="opt"><option>-O</option> <replaceable class="parameter">mxoff</replaceable></arg>
33-
<arg choice="opt"><option>-l</option> <replaceable class="parameter">xlogfile</replaceable></arg>
27+
<arg rep="repeat"><replaceable>option</replaceable></arg>
3428
<arg choice="req"><arg choice="opt"><option>-D</option></arg> <replaceable class="parameter">datadir</replaceable></arg>
3529
</cmdsynopsis>
3630
</refsynopsisdiv>
@@ -76,78 +70,108 @@ PostgreSQL documentation
7670
execute any data-modifying operations in the database before you dump,
7771
as any such action is likely to make the corruption worse.
7872
</para>
73+
</refsect1>
7974

80-
<para>
81-
The <option>-o</>, <option>-x</>, <option>-e</>,
82-
<option>-m</>, <option>-O</>,
83-
<option>-c</>
84-
and <option>-l</>
85-
options allow the next OID, next transaction ID, next transaction ID's
86-
epoch, next and oldest multitransaction ID, next multitransaction offset,
87-
oldest and newest transaction IDs for which the commit time can be retrieved,
88-
and WAL
89-
starting address values to be set manually. These are only needed when
90-
<command>pg_resetxlog</command> is unable to determine appropriate values
91-
by reading <filename>pg_control</>. Safe values can be determined as
92-
follows:
75+
<refsect1>
76+
<title>Options</title>
9377

94-
<itemizedlist>
78+
<variablelist>
79+
<varlistentry>
80+
<term><option>-f</option></term>
9581
<listitem>
9682
<para>
97-
A safe value for the next transaction ID (<option>-x</>)
98-
can be determined by looking for the numerically largest
99-
file name in the directory <filename>pg_clog</> under the data directory,
100-
adding one,
101-
and then multiplying by 1048576. Note that the file names are in
102-
hexadecimal. It is usually easiest to specify the option value in
103-
hexadecimal too. For example, if <filename>0011</> is the largest entry
104-
in <filename>pg_clog</>, <literal>-x 0x1200000</> will work (five
105-
trailing zeroes provide the proper multiplier).
83+
Force <command>pg_resetxlog</command> to proceed even if it cannot determine
84+
valid data for <filename>pg_control</>, as explained above.
10685
</para>
10786
</listitem>
87+
</varlistentry>
10888

89+
<varlistentry>
90+
<term><option>-n</option></term>
10991
<listitem>
11092
<para>
111-
A safe value for the next multitransaction ID (first part of <option>-m</>)
112-
can be determined by looking for the numerically largest
113-
file name in the directory <filename>pg_multixact/offsets</> under the
114-
data directory, adding one, and then multiplying by 65536.
115-
Conversely, a safe value for the oldest multitransaction ID (second part of
116-
<option>-m</>)
117-
can be determined by looking for the numerically smallest
118-
file name in the same directory and multiplying by 65536.
119-
As above, the file names are in hexadecimal, so the easiest way to do
120-
this is to specify the option value in hexadecimal and append four zeroes.
93+
The <option>-n</> (no operation) option instructs
94+
<command>pg_resetxlog</command> to print the values reconstructed from
95+
<filename>pg_control</> and values about to be changed, and then exit
96+
without modifying anything. This is mainly a debugging tool, but can be
97+
useful as a sanity check before allowing <command>pg_resetxlog</command>
98+
to proceed for real.
12199
</para>
122100
</listitem>
101+
</varlistentry>
123102

103+
<varlistentry>
104+
<term><option>-V</option></term>
105+
<term><option>--version</option></term>
106+
<listitem><para>Display version information, then exit.</para></listitem>
107+
</varlistentry>
108+
109+
<varlistentry>
110+
<term><option>-?</option></term>
111+
<term><option>--help</option></term>
112+
<listitem><para>Show help, then exit.</para></listitem>
113+
</varlistentry>
114+
</variablelist>
115+
116+
<para>
117+
The following options are only needed when
118+
<command>pg_resetxlog</command> is unable to determine appropriate values
119+
by reading <filename>pg_control</>. Safe values can be determined as
120+
described below. For values that take numeric arguments, hexadecimal
121+
values can be specified by using the prefix <literal>0x</literal>.
122+
</para>
123+
124+
<variablelist>
125+
<varlistentry>
126+
<term><option>-c</option> <replaceable class="parameter">xid</replaceable>,<replaceable class="parameter">xid</replaceable></term>
124127
<listitem>
125128
<para>
126-
A safe value for the next multitransaction offset (<option>-O</>)
127-
can be determined by looking for the numerically largest
128-
file name in the directory <filename>pg_multixact/members</> under the
129-
data directory, adding one, and then multiplying by 52352. As above,
130-
the file names are in hexadecimal. There is no simple recipe such as
131-
the ones above of appending zeroes.
129+
Manually set the oldest and newest transaction IDs for which the commit
130+
time can be retrieved.
132131
</para>
133-
</listitem>
134132

135-
<listitem>
136133
<para>
137134
A safe value for the oldest transaction ID for which the commit time can
138-
be retrieved (first part of <option>-c</>) can be determined by looking
135+
be retrieved (first part) can be determined by looking
139136
for the numerically smallest file name in the directory
140137
<filename>pg_commit_ts</> under the data directory. Conversely, a safe
141138
value for the newest transaction ID for which the commit time can be
142-
retrieved (second part of <option>-c</>) can be determined by looking for
143-
the numerically greatest file name in the same directory. As above, the
144-
file names are in hexadecimal.
139+
retrieved (second part) can be determined by looking for the numerically
140+
greatest file name in the same directory. The file names are in
141+
hexadecimal.
145142
</para>
146143
</listitem>
144+
</varlistentry>
147145

146+
<varlistentry>
147+
<term><option>-e</option> <replaceable class="parameter">xid_epoch</replaceable></term>
148148
<listitem>
149149
<para>
150-
The WAL starting address (<option>-l</>) should be
150+
Manually set the next transaction ID's epoch.
151+
</para>
152+
153+
<para>
154+
The transaction ID epoch is not actually stored anywhere in the database
155+
except in the field that is set by <command>pg_resetxlog</command>,
156+
so any value will work so far as the database itself is concerned.
157+
You might need to adjust this value to ensure that replication
158+
systems such as <application>Slony-I</> and
159+
<application>Skytools</> work correctly &mdash;
160+
if so, an appropriate value should be obtainable from the state of
161+
the downstream replicated database.
162+
</para>
163+
</listitem>
164+
</varlistentry>
165+
166+
<varlistentry>
167+
<term><option>-l</option> <replaceable class="parameter">xlogfile</replaceable></term>
168+
<listitem>
169+
<para>
170+
Manually set the WAL starting address.
171+
</para>
172+
173+
<para>
174+
The WAL starting address should be
151175
larger than any WAL segment file name currently existing in
152176
the directory <filename>pg_xlog</> under the data directory.
153177
These names are also in hexadecimal and have three parts. The first
@@ -168,46 +192,81 @@ PostgreSQL documentation
168192
</para>
169193
</note>
170194
</listitem>
195+
</varlistentry>
196+
197+
<varlistentry>
198+
<term><option>-m</option> <replaceable class="parameter">mxid</replaceable>,<replaceable class="parameter">mxid</replaceable></term>
199+
<listitem>
200+
<para>
201+
Manually set the next and oldest multitransaction ID.
202+
</para>
203+
204+
<para>
205+
A safe value for the next multitransaction ID (first part) can be
206+
determined by looking for the numerically largest file name in the
207+
directory <filename>pg_multixact/offsets</> under the data directory,
208+
adding one, and then multiplying by 65536 (0x10000). Conversely, a safe
209+
value for the oldest multitransaction ID (second part of
210+
<option>-m</>) can be determined by looking for the numerically smallest
211+
file name in the same directory and multiplying by 65536. The file
212+
names are in hexadecimal, so the easiest way to do this is to specify
213+
the option value in hexadecimal and append four zeroes.
214+
</para>
215+
</listitem>
216+
</varlistentry>
171217

218+
<varlistentry>
219+
<term><option>-o</option> <replaceable class="parameter">oid</replaceable></term>
172220
<listitem>
221+
<para>
222+
Manually set the next OID.
223+
</para>
224+
173225
<para>
174226
There is no comparably easy way to determine a next OID that's beyond
175227
the largest one in the database, but fortunately it is not critical to
176228
get the next-OID setting right.
177229
</para>
178230
</listitem>
231+
</varlistentry>
179232

233+
<varlistentry>
234+
<term><option>-O</option> <replaceable class="parameter">mxoff</replaceable></term>
180235
<listitem>
181236
<para>
182-
The transaction ID epoch is not actually stored anywhere in the database
183-
except in the field that is set by <command>pg_resetxlog</command>,
184-
so any value will work so far as the database itself is concerned.
185-
You might need to adjust this value to ensure that replication
186-
systems such as <application>Slony-I</> and
187-
<application>Skytools</> work correctly &mdash;
188-
if so, an appropriate value should be obtainable from the state of
189-
the downstream replicated database.
237+
Manually set the next multitransaction offset.
190238
</para>
191-
</listitem>
192-
</itemizedlist>
193-
</para>
194239

195-
<para>
196-
The <option>-n</> (no operation) option instructs
197-
<command>pg_resetxlog</command> to print the values reconstructed from
198-
<filename>pg_control</> and values about to be changed, and then exit
199-
without modifying anything. This is mainly a debugging tool, but can be
200-
useful as a sanity check before allowing <command>pg_resetxlog</command>
201-
to proceed for real.
202-
</para>
240+
<para>
241+
A safe value can be determined by looking for the numerically largest
242+
file name in the directory <filename>pg_multixact/members</> under the
243+
data directory, adding one, and then multiplying by 52352 (0xCC80).
244+
The file names are in hexadecimal. There is no simple recipe such as
245+
the ones for other options of appending zeroes.
246+
</para>
247+
</listitem>
248+
</varlistentry>
203249

204-
<para>
205-
The <option>-V</> and <option>--version</> options print
206-
the <application>pg_resetxlog</application> version and exit. The
207-
options <option>-?</> and <option>--help</> show supported arguments,
208-
and exit.
209-
</para>
250+
<varlistentry>
251+
<term><option>-x</option> <replaceable class="parameter">xid</replaceable></term>
252+
<listitem>
253+
<para>
254+
Manually set the next transaction ID.
255+
</para>
210256

257+
<para>
258+
A safe value can be determined by looking for the numerically largest
259+
file name in the directory <filename>pg_clog</> under the data directory,
260+
adding one,
261+
and then multiplying by 1048576 (0x100000). Note that the file names are in
262+
hexadecimal. It is usually easiest to specify the option value in
263+
hexadecimal too. For example, if <filename>0011</> is the largest entry
264+
in <filename>pg_clog</>, <literal>-x 0x1200000</> will work (five
265+
trailing zeroes provide the proper multiplier).
266+
</para>
267+
</listitem>
268+
</varlistentry>
269+
</variablelist>
211270
</refsect1>
212271

213272
<refsect1>
@@ -224,4 +283,11 @@ PostgreSQL documentation
224283
</para>
225284
</refsect1>
226285

286+
<refsect1>
287+
<title>See Also</title>
288+
289+
<simplelist type="inline">
290+
<member><xref linkend="app-pgcontroldata"></member>
291+
</simplelist>
292+
</refsect1>
227293
</refentry>

0 commit comments

Comments
 (0)