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.
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.
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.
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:
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>
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
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
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
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
95 </p></li></ul></div><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>.
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.
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
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.
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.
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.
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
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>.
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
204 the <a class="link" href="sql-createsubscription.html#SQL-CREATESUBSCRIPTION-PARAMS-WITH-TWO-PHASE"><code class="literal">two_phase</code></a>
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.
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
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
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
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
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
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>
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>