Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 42cd381

Browse files
author
Liudmila Mantrova
committed
DOC: pg_pageprep docs
1 parent 8da5d8d commit 42cd381

File tree

3 files changed

+385
-0
lines changed

3 files changed

+385
-0
lines changed

‎doc/src/sgml/contrib.sgml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
137137
&pgcrypto;
138138
&pgfreespacemap;
139139
&pgpathman;
140+
&pg-pageprep;
140141
&pgprewarm;
141142
&pgquerystate;
142143
&pgrowlocks;

‎doc/src/sgml/filelist.sgml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,7 @@
144144
<!ENTITY pgcrypto SYSTEM "pgcrypto.sgml">
145145
<!ENTITY pgfreespacemap SYSTEM "pgfreespacemap.sgml">
146146
<!ENTITY pgpathman SYSTEM "pgpathman.sgml">
147+
<!ENTITY pg-pageprep SYSTEM "pg_pageprep.sgml">
147148
<!ENTITY pgprewarm SYSTEM "pgprewarm.sgml">
148149
<!ENTITY pgquerystate SYSTEM "pgquerystate.sgml">
149150
<!ENTITY pgrepack SYSTEM "pgrepack.sgml">

‎doc/src/sgml/pg_pageprep.sgml

Lines changed: 383 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,383 @@
1+
<sect1 id="pg-pageprep">
2+
<title>pg_pageprep</title>
3+
<para>
4+
The <filename>pg_pageprep</filename> extension prepares heap pages
5+
with 32-bit transaction IDs for migration to
6+
<productname>&project;</productname> versions that use 64-bit page format,
7+
which enables you to upgrade your database cluster without a dump/restore.
8+
You must run <filename>pg_pageprep</filename> before <xref linkend="pgupgrade">
9+
to ensure each page has enough free space to be converted to the 64-bit format.
10+
</para>
11+
12+
<para>
13+
The <filename>pg_pageprep</filename> extension must be enabled
14+
in both source and target clusters.
15+
</para>
16+
17+
<sect2 id="pg-pageprep-installation">
18+
<title>Installation and Configuration</title>
19+
<para>
20+
The <filename>pg_pageprep</filename> extension is included into
21+
&project;. Once you have &project; installed, enable
22+
<filename>pg_pageprep</filename>, as follows:
23+
</para>
24+
<orderedlist>
25+
<listitem>
26+
<para>
27+
Add the <literal>pg_pageprep</literal> value to the
28+
<varname>shared_preload_libraries</varname> variable
29+
in the <filename>postgresql.conf</filename> file:
30+
</para>
31+
<programlisting>
32+
shared_preload_libraries = 'pg_pageprep'
33+
</programlisting>
34+
</listitem>
35+
<listitem>
36+
<para>
37+
Restart <productname>&project;</productname> for the
38+
changes to take effect.
39+
</para>
40+
</listitem>
41+
<listitem>
42+
<para>
43+
Execute the <xref linkend="sql-createextension"> command on
44+
each database in the cluster you are going to upgrade:
45+
<programlisting>
46+
CREATE EXTENSION pg_pageprep;
47+
</programlisting>
48+
</para>
49+
</listitem>
50+
<listitem>
51+
<para>
52+
Customize the <filename>pg_pageprep</filename>
53+
setup if required by changing configuration variables described in
54+
<xref linkend="pg-pageprep-guc-variables">. In particular,
55+
make sure that the <xref linkend="guc-pageprep-database">
56+
variable is set to an existing database for
57+
<filename>pg_pageprep</filename> to connect to your cluster.
58+
</para>
59+
</listitem>
60+
</orderedlist>
61+
62+
</sect2>
63+
64+
<sect2 id="pg-pageprep-usage">
65+
<title>Usage</title>
66+
<para>
67+
To support 64-bit transaction IDs, <productname>Postgres Pro Enterprise</productname> page format
68+
requires extra 20 bytes per page as compared to pages with 32-bit transaction IDs.
69+
The <filename>pg_pageprep</filename> extension prepares enough
70+
space in each page for the new format, without stopping the database server.
71+
</para>
72+
73+
<para>
74+
The typical workflow is as follows:
75+
</para>
76+
77+
<procedure>
78+
<step>
79+
<para>
80+
Create <filename>pg_pageprep</filename> extension for each
81+
database you are going to migrate, as explained in
82+
<xref linkend="pg-pageprep-installation">.
83+
</para>
84+
</step>
85+
86+
<step>
87+
<para>
88+
For each database to be migrated, run:
89+
<programlisting>
90+
SELECT start_bgworker();
91+
</programlisting>
92+
This process sets the fill factor for each relation in the database
93+
to 90%, unless the fill factor is already smaller.
94+
</para>
95+
96+
<tip>
97+
<para>
98+
If the <xref linkend="guc-pageprep-enable-workers"> parameter is
99+
set to <literal>on</literal> and the cluster uses 32-bit transaction IDs,
100+
<filename>pg_pageprep</filename> workers are launched automatically
101+
at the cluster restart, so you can simply restart the cluster.
102+
</para>
103+
</tip>
104+
105+
<para>
106+
If required, you can stop the background worker by running the
107+
<function>stop_bgworker()</function> function, which
108+
also affects the current database only:
109+
<programlisting>
110+
SELECT stop_bgworker();
111+
</programlisting>
112+
</para>
113+
114+
</step>
115+
116+
<step>
117+
<para>
118+
Wait for <filename>pg_pageprep</filename> to process all
119+
relations in all databases. To get the current status of
120+
<filename>pg_pageprep</filename> workers for all databases, use the
121+
<function>get_workers_list()</function> function:
122+
<programlisting>
123+
SELECT * FROM get_workers_list();
124+
125+
database | status
126+
----------+--------
127+
postgres | active
128+
(1 row)
129+
</programlisting>
130+
</para>
131+
132+
<para>
133+
You can check the progress for each database in the
134+
<structname>pg_pageprep_todo</structname> view, which
135+
displays the list of relations that still need to be processed:
136+
<programlisting>
137+
SELECT * FROM pg_pageprep_todo;
138+
</programlisting>
139+
</para>
140+
</step>
141+
142+
<step>
143+
<para>
144+
When all relations are processed, run <xref linkend="pgupgrade">
145+
to complete the migration.
146+
</para>
147+
</step>
148+
149+
<step>
150+
<para>
151+
In the upgraded cluster, restore the fill factor of
152+
all relations to the original values:
153+
<programlisting>
154+
SELECT restore_fillfactors();
155+
</programlisting>
156+
Once this operation completes, the database cluster is ready to use.
157+
</para>
158+
</step>
159+
160+
<step>
161+
<para>
162+
Optionally, drop the <filename>pg_pageprep</filename> extension in the
163+
target cluster as it is no longer required:
164+
<programlisting>
165+
DROP EXTENSION pg_pageprep;
166+
</programlisting>
167+
</para>
168+
</step>
169+
170+
</procedure>
171+
172+
<sect3>
173+
<title>Handling Page Conversion for Multiple Databases</title>
174+
<para>
175+
If you have a lot of databases, you may prepare all databases
176+
for upgrade at once by running the Python script
177+
<filename><replaceable>install-dir</replaceable>/contrib/pg_pageprep/manager.py</filename>.
178+
The syntax is as follows:
179+
<programlisting>
180+
python manager.py -d <replaceable>database</replaceable> -U <replaceable>username</replaceable> <replaceable>command</replaceable>
181+
</programlisting>
182+
where:
183+
184+
<itemizedlist>
185+
<listitem>
186+
<para>
187+
<replaceable>database</replaceable> is the database used to connect
188+
to the cluster and get the list of all databases to be migrated.
189+
</para>
190+
</listitem>
191+
<listitem>
192+
<para>
193+
<replaceable>username</replaceable> defines the user on behalf of which to
194+
run the script.
195+
</para>
196+
</listitem>
197+
<listitem>
198+
<para>
199+
<replaceable>command</replaceable> must be substituted
200+
by one of the following commands:
201+
</para>
202+
</listitem>
203+
</itemizedlist>
204+
</para>
205+
206+
<variablelist>
207+
<varlistentry>
208+
<term>
209+
<literal>install</literal>
210+
</term>
211+
<listitem>
212+
<para>
213+
Creates <filename>pg_pageprep</filename> extension on
214+
each database in the cluster. The <filename>pg_pageprep</filename>
215+
background workers will start automatically after the next cluster
216+
restart if the <xref linkend="guc-pageprep-enable-workers"> variable
217+
is set to <literal>on</literal>.
218+
</para>
219+
</listitem>
220+
</varlistentry>
221+
<varlistentry>
222+
<term>
223+
<literal>start</literal>
224+
</term>
225+
<listitem>
226+
<para>
227+
Starts background workers that set the fill factor of each relation to 90%,
228+
unless the fill factor is already smaller.
229+
</para>
230+
</listitem>
231+
</varlistentry>
232+
<varlistentry>
233+
<term>
234+
<literal>stop</literal>
235+
</term>
236+
<listitem>
237+
<para>
238+
Stops all <filename>pg_pageprep</filename> background workers.
239+
</para>
240+
</listitem>
241+
</varlistentry>
242+
<varlistentry>
243+
<term>
244+
<literal>status</literal>
245+
</term>
246+
<listitem>
247+
<para>
248+
Shows information about the current activity of background workers
249+
and the list of relations to be processed.
250+
</para>
251+
</listitem>
252+
</varlistentry>
253+
<varlistentry>
254+
<term>
255+
<literal>restore</literal>
256+
</term>
257+
<listitem>
258+
<para>
259+
Stops all <filename>pg_pageprep</filename> background workers, if any,
260+
and restores the original fill factor for all relations.
261+
Run this command on the target cluster after <filename>pg_upgrade</filename>.
262+
</para>
263+
</listitem>
264+
</varlistentry>
265+
</variablelist>
266+
</sect3>
267+
268+
</sect2>
269+
270+
<sect2 id="pg-pageprep-guc-variables">
271+
<title>Configuration Variables</title>
272+
273+
<variablelist>
274+
<varlistentry id="guc-pageprep-database" xreflabel="pg_pageprep.database">
275+
<term><varname>pg_pageprep.database</varname> (<type>text</type>)
276+
<indexterm>
277+
<primary><varname>pg_pageprep.database</> pg-pageprep parameter</primary>
278+
</indexterm>
279+
</term>
280+
<listitem>
281+
<para>
282+
The name of the database used by <filename>pg_pageprep</filename>
283+
to connect to the cluster and get the list of all databases to be migrated.
284+
</para>
285+
<para>
286+
Default: <literal>postgres</literal>
287+
</para>
288+
</listitem>
289+
</varlistentry>
290+
291+
<varlistentry id="guc-pageprep-enable-workers" xreflabel="pg_pageprep.enable_workers">
292+
<term><varname>pg_pageprep.enable_workers</varname> (<type>text</type>)
293+
<indexterm>
294+
<primary><varname>pg_pageprep.enable_workers</> pg-pageprep parameter</primary>
295+
</indexterm>
296+
</term>
297+
<listitem>
298+
<para>
299+
Defines whether to launch <filename>pg_pageprep</filename> background
300+
workers automatically at the cluster restart.
301+
</para>
302+
<para>
303+
Default: <literal>on</literal>
304+
</para>
305+
</listitem>
306+
</varlistentry>
307+
308+
<varlistentry>
309+
<term><varname>pg_pageprep.per_attempt_delay</varname> (<type>text</type>)
310+
<indexterm>
311+
<primary><varname>pg_pageprep.per_attempt_delay</> pg-pageprep parameter</primary>
312+
</indexterm>
313+
</term>
314+
<listitem>
315+
<para>
316+
Time interval between attempts to scan the next relation if the previous attempt
317+
was unsuccessful. For example, if all relations are already prepared for migration.
318+
</para>
319+
<para>
320+
Default: <literal>60s</literal>
321+
</para>
322+
</listitem>
323+
</varlistentry>
324+
325+
<varlistentry>
326+
<term><varname>pg_pageprep.per_page_delay</varname> (<type>text</type>)
327+
<indexterm>
328+
<primary><varname>pg_pageprep.per_page_delay</> pg-pageprep parameter</primary>
329+
</indexterm>
330+
</term>
331+
<listitem>
332+
<para>
333+
Time interval between consequent page scans, in milliseconds.
334+
</para>
335+
<para>
336+
Default: <literal>100ms</literal>
337+
</para>
338+
</listitem>
339+
</varlistentry>
340+
341+
<varlistentry>
342+
<term><varname>pg_pageprep.per_relation_delay</varname> (<type>text</type>)
343+
<indexterm>
344+
<primary><varname>pg_pageprep.per_relation_delay</> pg-pageprep parameter</primary>
345+
</indexterm>
346+
</term>
347+
<listitem>
348+
<para>
349+
Time interval between consequent relation scans, in milliseconds.
350+
</para>
351+
<para>
352+
Default: <literal>1000ms</literal>
353+
</para>
354+
</listitem>
355+
</varlistentry>
356+
357+
<varlistentry>
358+
<term><varname>pg_pageprep.role</varname> (<type>text</type>)
359+
<indexterm>
360+
<primary><varname>pg_pageprep.role</> pg-pageprep parameter</primary>
361+
</indexterm>
362+
</term>
363+
<listitem>
364+
<para>
365+
The user name on behalf of which to prepare pages for upgrade.
366+
</para>
367+
<para>
368+
Default: <literal>postgres</literal>
369+
</para>
370+
</listitem>
371+
</varlistentry>
372+
373+
</variablelist>
374+
375+
</sect2>
376+
377+
<sect2>
378+
<title>Authors</title>
379+
<para>
380+
Postgres Professional, Moscow, Russia
381+
</para>
382+
</sect2>
383+
</sect1>

0 commit comments

Comments
 (0)