]> begriffs open source - ai-pg/blob - full-docs/src/sgml/html/app-pgcreatesubscriber.html
WIP: toc builder
[ai-pg] / full-docs / src / sgml / html / app-pgcreatesubscriber.html
1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_createsubscriber</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgcontroldata.html" title="pg_controldata" /><link rel="next" href="app-pg-ctl.html" title="pg_ctl" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_createsubscriber</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgcontroldata.html" title="pg_controldata">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pg-ctl.html" title="pg_ctl">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGCREATESUBSCRIBER"><div class="titlepage"></div><a id="id-1.9.5.7.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_createsubscriber</span></span></h2><p>pg_createsubscriber — convert a physical replica into a new logical replica</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.7.4.1"><code class="command">pg_createsubscriber</code> [<em class="replaceable"><code>option</code></em>...]  { <code class="option">-d</code>  |   <code class="option">--database</code> }<em class="replaceable"><code>dbname</code></em> { <code class="option">-D</code>   |   <code class="option">--pgdata</code> }<em class="replaceable"><code>datadir</code></em> { <code class="option">-P</code>  |   <code class="option">--publisher-server</code> }<em class="replaceable"><code>connstr</code></em> </p></div></div><div class="refsect1" id="id-1.9.5.7.5"><h2>Description</h2><p>
3    <span class="application">pg_createsubscriber</span> creates a new logical
4    replica from a physical standby server.  All tables in the specified
5    database are included in the <a class="link" href="logical-replication.html" title="Chapter 29. Logical Replication">logical
6    replication</a> setup.  A pair of
7    publication and subscription objects are created for each database.  It
8    must be run at the target server.
9   </p><p>
10    After a successful run, the state of the target server is analogous to a
11    fresh logical replication setup.  The main difference between the logical
12    replication setup and <span class="application">pg_createsubscriber</span> is how
13    the data synchronization is done. <span class="application">pg_createsubscriber</span>
14    does not copy the initial table data. It does only the synchronization phase,
15    which ensures each table is brought up to a synchronized state.
16   </p><p>
17    <span class="application">pg_createsubscriber</span> targets large database
18    systems because in logical replication setup, most of the time is spent
19    doing the initial data copy.  Furthermore, a side effect of this long time
20    spent synchronizing data is usually a large amount of changes to be applied
21    (that were produced during the initial data copy), which increases even
22    more the time when the logical replica will be available. For smaller
23    databases, it is recommended to set up logical replication with initial data
24    synchronization.  For details, see the <code class="command">CREATE SUBSCRIPTION</code>
25    <a class="link" href="sql-createsubscription.html#SQL-CREATESUBSCRIPTION-PARAMS-WITH-COPY-DATA">
26    <code class="literal">copy_data</code></a> option.
27
28   </p></div><div class="refsect1" id="id-1.9.5.7.6"><h2>Options</h2><p>
29    <span class="application">pg_createsubscriber</span> accepts the following
30    command-line arguments:
31
32    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--all</code></span></dt><dd><p>
33        Create one subscription per database on the target server. Exceptions
34        are template databases and databases that don't allow connections.
35        To discover the list of all databases, connect to the source server
36        using the database name specified in the <code class="option">--publisher-server</code>
37        connection string, or if not specified, the <code class="literal">postgres</code>
38        database will be used, or if that does not exist, <code class="literal">template1</code>
39        will be used.
40        Automatically generated names for subscriptions, publications, and
41        replication slots are used when this option is specified.
42        This option cannot be used along with <code class="option">--database</code>,
43        <code class="option">--publication</code>, <code class="option">--replication-slot</code>, or
44        <code class="option">--subscription</code>.
45       </p></dd><dt><span class="term"><code class="option">-d <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">--database=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
46        The name of the database in which to create a subscription.  Multiple
47        databases can be selected by writing multiple <code class="option">-d</code>
48        switches. This option cannot be used together with <code class="option">-a</code>.
49        If <code class="option">-d</code> option is not provided, the database name will be
50        obtained from <code class="option">-P</code> option. If the database name is not
51        specified in either the <code class="option">-d</code> option, or the
52        <code class="option">-P</code> option, and <code class="option">-a</code> option is not
53        specified, an error will be reported.
54       </p></dd><dt><span class="term"><code class="option">-D <em class="replaceable"><code>directory</code></em></code><br /></span><span class="term"><code class="option">--pgdata=<em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
55        The target directory that contains a cluster directory from a physical
56        replica.
57       </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--dry-run</code></span></dt><dd><p>
58        Do everything except actually modifying the target directory.
59       </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--subscriber-port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
60        The port number on which the target server is listening for
61        connections.  Defaults to running the target server on port 50432 to
62        avoid unintended client connections.
63       </p></dd><dt><span class="term"><code class="option">-P <em class="replaceable"><code>connstr</code></em></code><br /></span><span class="term"><code class="option">--publisher-server=<em class="replaceable"><code>connstr</code></em></code></span></dt><dd><p>
64        The connection string to the publisher.  For details see <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="32.1.1. Connection Strings">Section 32.1.1</a>.
65       </p></dd><dt><span class="term"><code class="option">-s <em class="replaceable"><code>dir</code></em></code><br /></span><span class="term"><code class="option">--socketdir=<em class="replaceable"><code>dir</code></em></code></span></dt><dd><p>
66        The directory to use for postmaster sockets on target server.  The
67        default is current directory.
68       </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>seconds</code></em></code><br /></span><span class="term"><code class="option">--recovery-timeout=<em class="replaceable"><code>seconds</code></em></code></span></dt><dd><p>
69        The maximum number of seconds to wait for recovery to end.  Setting to
70        0 disables.  The default is 0.
71       </p></dd><dt><span class="term"><code class="option">-T</code><br /></span><span class="term"><code class="option">--enable-two-phase</code></span></dt><dd><p>
72        Enables <a class="link" href="sql-createsubscription.html#SQL-CREATESUBSCRIPTION-PARAMS-WITH-TWO-PHASE"><code class="literal">two_phase</code></a>
73        commit for the subscription. When multiple databases are specified, this
74        option applies uniformly to all subscriptions created on those databases.
75        The default is <code class="literal">false</code>.
76       </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--subscriber-username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
77        The user name to connect as on target server.  Defaults to the current
78        operating system user name.
79       </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
80        Enables verbose mode.  This will cause
81        <span class="application">pg_createsubscriber</span> to output progress
82        messages and detailed information about each step to standard error.
83        Repeating the option causes additional debug-level messages to appear
84        on standard error.
85       </p></dd><dt><span class="term"><code class="option">--clean=<em class="replaceable"><code>objtype</code></em></code></span></dt><dd><p>
86        Drop all objects of the specified type from specified databases on the
87        target server.
88       </p><p>
89        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
90           <code class="literal">publications</code>:
91           The <code class="literal">FOR ALL TABLES</code> publications established for this
92           subscriber are always dropped; specifying this object type causes all
93           other publications replicated from the source server to be dropped as
94           well.
95          </p></li></ul></div><p>
96       </p><p>
97        The objects selected to be dropped are individually logged, including during
98        a <code class="option">--dry-run</code>.  There is no opportunity to affect or stop the
99        dropping of the selected objects, so consider taking a backup of them
100        using <span class="application">pg_dump</span>.
101       </p></dd><dt><span class="term"><code class="option">--config-file=<em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
102        Use the specified main server configuration file for the target data
103        directory.  <span class="application">pg_createsubscriber</span> internally uses
104        the <span class="application">pg_ctl</span> command to start and
105        stop the target server.  It allows you to specify the actual
106        <code class="filename">postgresql.conf</code> configuration file if it is stored
107        outside the data directory.
108       </p></dd><dt><span class="term"><code class="option">--publication=<em class="replaceable"><code>name</code></em></code></span></dt><dd><p>
109        The publication name to set up the logical replication.  Multiple
110        publications can be specified by writing multiple
111        <code class="option">--publication</code> switches.  The number of publication
112        names must match the number of specified databases, otherwise an error
113        is reported.  The order of the multiple publication name switches must
114        match the order of database switches.  If this option is not specified,
115        a generated name is assigned to the publication name. This option cannot
116        be used together with <code class="option">--all</code>.
117       </p></dd><dt><span class="term"><code class="option">--replication-slot=<em class="replaceable"><code>name</code></em></code></span></dt><dd><p>
118        The replication slot name to set up the logical replication.  Multiple
119        replication slots can be specified by writing multiple
120        <code class="option">--replication-slot</code> switches.  The number of
121        replication slot names must match the number of specified databases,
122        otherwise an error is reported.  The order of the multiple replication
123        slot name switches must match the order of database switches.  If this
124        option is not specified, the subscription name is assigned to the
125        replication slot name. This option cannot be used together with
126        <code class="option">--all</code>.
127       </p></dd><dt><span class="term"><code class="option">--subscription=<em class="replaceable"><code>name</code></em></code></span></dt><dd><p>
128        The subscription name to set up the logical replication.  Multiple
129        subscriptions can be specified by writing multiple
130        <code class="option">--subscription</code> switches.  The number of subscription
131        names must match the number of specified databases, otherwise an error
132        is reported.  The order of the multiple subscription name switches must
133        match the order of database switches.  If this option is not specified,
134        a generated name is assigned to the subscription name. This option cannot
135        be used together with <code class="option">--all</code>.
136       </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
137        Print the <span class="application">pg_createsubscriber</span> version and exit.
138       </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
139        Show help about <span class="application">pg_createsubscriber</span> command
140        line arguments, and exit.
141       </p></dd></dl></div><p>
142    </p></div><div class="refsect1" id="id-1.9.5.7.7"><h2>Notes</h2><div class="refsect2" id="id-1.9.5.7.7.2"><h3>Prerequisites</h3><p>
143     There are some prerequisites for
144     <span class="application">pg_createsubscriber</span> to convert the target server
145     into a logical replica.  If these are not met, an error will be reported.
146     The source and target servers must have the same major version as the
147     <span class="application">pg_createsubscriber</span>.  The given target data
148     directory must have the same system identifier as the source data
149     directory.  The given database user for the target data directory must have
150     privileges for creating <a class="link" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION">subscriptions</a> and using <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-ADVANCE"><code class="function">pg_replication_origin_advance()</code></a>.
151    </p><p>
152     The target server must be used as a physical standby.  The target server
153     must have <a class="xref" href="runtime-config-replication.html#GUC-MAX-ACTIVE-REPLICATION-ORIGINS">max_active_replication_origins</a> and <a class="xref" href="runtime-config-replication.html#GUC-MAX-LOGICAL-REPLICATION-WORKERS">max_logical_replication_workers</a> configured to a value
154     greater than or equal to the number of specified databases.  The target
155     server must have <a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a> configured to a
156     value greater than the number of specified databases.  The target server
157     must accept local connections. If you are planning to use the
158     <code class="option">--enable-two-phase</code> switch then you will also need to set
159     the <a class="xref" href="runtime-config-resource.html#GUC-MAX-PREPARED-TRANSACTIONS">max_prepared_transactions</a> appropriately.
160    </p><p>
161     The source server must accept connections from the target server.  The
162     source server must not be in recovery. The source server must have <a class="xref" href="runtime-config-wal.html#GUC-WAL-LEVEL">wal_level</a> as <code class="literal">logical</code>.  The source server
163     must have <a class="xref" href="runtime-config-replication.html#GUC-MAX-REPLICATION-SLOTS">max_replication_slots</a> configured to a value
164     greater than or equal to the number of specified databases plus existing
165     replication slots.  The source server must have <a class="xref" href="runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</a> configured to a value greater than or equal
166     to the number of specified databases and existing WAL sender processes.
167    </p></div><div class="refsect2" id="id-1.9.5.7.7.3"><h3>Warnings</h3><p>
168     If <span class="application">pg_createsubscriber</span> fails after the target
169     server was promoted, then the data directory is likely not in a state that
170     can be recovered.  In such case, creating a new standby server is
171     recommended.
172    </p><p>
173     <span class="application">pg_createsubscriber</span> usually starts the target
174     server with different connection settings during transformation.  Hence,
175     connections to the target server should fail.
176    </p><p>
177     Since DDL commands are not replicated by logical replication, avoid
178     executing DDL commands that change the database schema while running
179     <span class="application">pg_createsubscriber</span>.  If the target server has
180     already been converted to logical replica, the DDL commands might not be
181     replicated, which might cause an error.
182    </p><p>
183     If <span class="application">pg_createsubscriber</span> fails while processing,
184     objects (publications, replication slots) created on the source server are
185     removed.  The removal might fail if the target server cannot connect to
186     the source server.  In such a case, a warning message will inform the
187     objects left.  If the target server is running, it will be stopped.
188    </p><p>
189     If the replication is using <a class="xref" href="runtime-config-replication.html#GUC-PRIMARY-SLOT-NAME">primary_slot_name</a>, it
190     will be removed from the source server after the logical replication
191     setup.
192    </p><p>
193     If the target server is a synchronous replica, transaction commits on the
194     primary might wait for replication while running
195     <span class="application">pg_createsubscriber</span>.
196    </p><p>
197     Unless the <code class="option">--enable-two-phase</code> switch is specified,
198     <span class="application">pg_createsubscriber</span> sets up logical
199     replication with two-phase commit disabled.  This means that any
200     prepared transactions will be replicated at the time
201     of <code class="command">COMMIT PREPARED</code>, without advance preparation.
202     Once setup is complete, you can manually drop and re-create the
203     subscription(s) with
204     the <a class="link" href="sql-createsubscription.html#SQL-CREATESUBSCRIPTION-PARAMS-WITH-TWO-PHASE"><code class="literal">two_phase</code></a>
205     option enabled.
206    </p><p>
207     <span class="application">pg_createsubscriber</span> changes the system
208     identifier using <span class="application">pg_resetwal</span>.  It would avoid
209     situations in which the target server might use WAL files from the source
210     server.  If the target server has a standby, replication will break and a
211     fresh standby should be created.
212    </p><p>
213     Replication failures can occur if required WAL files are missing. To prevent
214     this, the source server must set
215     <a class="xref" href="runtime-config-replication.html#GUC-MAX-SLOT-WAL-KEEP-SIZE">max_slot_wal_keep_size</a> to <code class="literal">-1</code> to
216     ensure that required WAL files are not prematurely removed.
217    </p></div><div class="refsect2" id="id-1.9.5.7.7.4"><h3>How It Works</h3><p>
218     The basic idea is to have a replication start point from the source server
219     and set up a logical replication to start from this point:
220    </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>
221       Start the target server with the specified command-line options.  If the
222       target server is already running,
223       <span class="application">pg_createsubscriber</span> will terminate with an
224       error.
225      </p></li><li class="step"><p>
226       Check if the target server can be converted.  There are also a few
227       checks on the source server.  If any of the prerequisites are not met,
228       <span class="application">pg_createsubscriber</span> will terminate with an
229       error.
230      </p></li><li class="step"><p>
231       Create a publication and replication slot for each specified database on
232       the source server.  Each publication is created using <a class="link" href="sql-createpublication.html#SQL-CREATEPUBLICATION-PARAMS-FOR-ALL-TABLES"><code class="literal">FOR ALL
233       TABLES</code></a>.  If the <code class="option">--publication</code> option
234       is not specified, the publication has the following name pattern:
235       <span class="quote">“<span class="quote"><code class="literal">pg_createsubscriber_%u_%x</code></span>”</span> (parameter:
236       database <em class="parameter"><code>oid</code></em>, random <em class="parameter"><code>int</code></em>).
237       If the <code class="option">--replication-slot</code> option is not specified, the
238       replication slot has the following name pattern:
239       <span class="quote">“<span class="quote"><code class="literal">pg_createsubscriber_%u_%x</code></span>”</span> (parameters:
240       database <em class="parameter"><code>oid</code></em>, random <em class="parameter"><code>int</code></em>).
241       These replication slots will be used by the subscriptions in a future
242       step.  The last replication slot LSN is used as a stopping point in the
243       <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-LSN">recovery_target_lsn</a> parameter and by the
244       subscriptions as a replication start point.  It guarantees that no
245       transaction will be lost.
246      </p></li><li class="step"><p>
247       Write recovery parameters into the target data directory and restart the
248       target server.  It specifies an LSN (<a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-LSN">recovery_target_lsn</a>) of the write-ahead log location up
249       to which recovery will proceed.  It also specifies
250       <code class="literal">promote</code> as the action that the server should take
251       once the recovery target is reached.  Additional <a class="link" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET" title="19.5.6. Recovery Target">recovery parameters</a>
252       are added to avoid unexpected behavior during the recovery process such
253       as end of the recovery as soon as a consistent state is reached (WAL
254       should be applied until the replication start location) and multiple
255       recovery targets that can cause a failure.  This step finishes once the
256       server ends standby mode and is accepting read-write transactions.  If
257       <code class="option">--recovery-timeout</code> option is set,
258       <span class="application">pg_createsubscriber</span> terminates if recovery
259       does not end until the given number of seconds.
260      </p></li><li class="step"><p>
261       Create a subscription for each specified database on the target server.
262       If the <code class="option">--subscription</code> option is not specified, the
263       subscription has the following name pattern:
264       <span class="quote">“<span class="quote"><code class="literal">pg_createsubscriber_%u_%x</code></span>”</span> (parameters:
265       database <em class="parameter"><code>oid</code></em>, random <em class="parameter"><code>int</code></em>).
266       It does not copy existing data from the source server.  It does not
267       create a replication slot.  Instead, it uses the replication slot that
268       was created in a previous step.  The subscription is created but it is
269       not enabled yet.  The reason is the replication progress must be set to
270       the replication start point before starting the replication.
271      </p></li><li class="step"><p>
272       Drop publications on the target server that were replicated because they
273       were created before the replication start location.  It has no use on
274       the subscriber.
275      </p></li><li class="step"><p>
276       Set the replication progress to the replication start point for each
277       subscription.  When the target server starts the recovery process, it
278       catches up to the replication start point.  This is the exact LSN to be
279       used as a initial replication location for each subscription.  The
280       replication origin name is obtained since the subscription was created.
281       The replication origin name and the replication start point are used in
282       <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-ADVANCE"><code class="function">pg_replication_origin_advance()</code></a>
283       to set up the initial replication location.
284      </p></li><li class="step"><p>
285       Enable the subscription for each specified database on the target server.
286       The subscription starts applying transactions from the replication start
287       point.
288      </p></li><li class="step"><p>
289       If the standby server was using <a class="xref" href="runtime-config-replication.html#GUC-PRIMARY-SLOT-NAME">primary_slot_name</a>,
290       it has no use from now on so drop it.
291      </p></li><li class="step"><p>
292       If the standby server contains <a class="link" href="logicaldecoding-explanation.html#LOGICALDECODING-REPLICATION-SLOTS-SYNCHRONIZATION" title="47.2.3. Replication Slot Synchronization">failover
293       replication slots</a>, they cannot be synchronized anymore, so drop
294       them.
295      </p></li><li class="step"><p>
296       Update the system identifier on the target server. The
297       <a class="xref" href="app-pgresetwal.html" title="pg_resetwal"><span class="refentrytitle"><span class="application">pg_resetwal</span></span></a> is run to modify the system identifier.
298       The target server is stopped as a <code class="command">pg_resetwal</code> requirement.
299      </p></li></ol></div></div></div><div class="refsect1" id="id-1.9.5.7.8"><h2>Examples</h2><p>
300    To create a logical replica for databases <code class="literal">hr</code> and
301    <code class="literal">finance</code> from a physical replica at
302    <code class="literal">foo</code>:
303 </p><pre class="screen">
304 <code class="prompt">$</code> <strong class="userinput"><code>pg_createsubscriber -D /usr/local/pgsql/data -P "host=foo" -d hr -d finance</code></strong>
305 </pre><p>
306   </p></div><div class="refsect1" id="id-1.9.5.7.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgcontroldata.html" title="pg_controldata">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pg-ctl.html" title="pg_ctl">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_controldata</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_ctl</span></td></tr></table></div></body></html>