<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!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>31.2. Subscription</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="logical-replication-publication.html" title="31.1. Publication" /><link rel="next" href="logical-replication-conflicts.html" title="31.3. Conflicts" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">31.2. Subscription</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logical-replication-publication.html" title="31.1. Publication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logical-replication.html" title="Chapter 31. Logical Replication">Up</a></td><th width="60%" align="center">Chapter 31. Logical Replication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 11.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logical-replication-conflicts.html" title="31.3. Conflicts">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="LOGICAL-REPLICATION-SUBSCRIPTION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">31.2. Subscription</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="logical-replication-subscription.html#LOGICAL-REPLICATION-SUBSCRIPTION-SLOT">31.2.1. Replication Slot Management</a></span></dt></dl></div><p>
A <em class="firstterm">subscription</em> is the downstream side of logical
replication. The node where a subscription is defined is referred to as
the <em class="firstterm">subscriber</em>. A subscription defines the connection
to another database and set of publications (one or more) to which it wants
to subscribe.
</p><p>
The subscriber database behaves in the same way as any other PostgreSQL
instance and can be used as a publisher for other databases by defining its
own publications.
</p><p>
A subscriber node may have multiple subscriptions if desired. It is
possible to define multiple subscriptions between a single
publisher-subscriber pair, in which case care must be taken to ensure
that the subscribed publication objects don't overlap.
</p><p>
Each subscription will receive changes via one replication slot (see
<a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="26.2.6. Replication Slots">Section 26.2.6</a>). Additional temporary
replication slots may be required for the initial data synchronization
of pre-existing table data.
</p><p>
A logical replication subscription can be a standby for synchronous
replication (see <a class="xref" href="warm-standby.html#SYNCHRONOUS-REPLICATION" title="26.2.8. Synchronous Replication">Section 26.2.8</a>). The standby
name is by default the subscription name. An alternative name can be
specified as <code class="literal">application_name</code> in the connection
information of the subscription.
</p><p>
Subscriptions are dumped by <code class="command">pg_dump</code> if the current user
is a superuser. Otherwise a warning is written and subscriptions are
skipped, because non-superusers cannot read all subscription information
from the <code class="structname">pg_subscription</code> catalog.
</p><p>
The subscription is added using <a class="xref" href="sql-createsubscription.html" title="CREATE SUBSCRIPTION"><span class="refentrytitle">CREATE SUBSCRIPTION</span></a> and
can be stopped/resumed at any time using the
<a class="xref" href="sql-altersubscription.html" title="ALTER SUBSCRIPTION"><span class="refentrytitle">ALTER SUBSCRIPTION</span></a> command and removed using
<a class="xref" href="sql-dropsubscription.html" title="DROP SUBSCRIPTION"><span class="refentrytitle">DROP SUBSCRIPTION</span></a>.
</p><p>
When a subscription is dropped and recreated, the synchronization
information is lost. This means that the data has to be resynchronized
afterwards.
</p><p>
The schema definitions are not replicated, and the published tables must
exist on the subscriber. Only regular tables may be
the target of replication. For example, you can't replicate to a view.
</p><p>
The tables are matched between the publisher and the subscriber using the
fully qualified table name. Replication to differently-named tables on the
subscriber is not supported.
</p><p>
Columns of a table are also matched by name. The order of columns in the
subscriber table does not need to match that of the publisher. The data
types of the columns do not need to match, as long as the text
representation of the data can be converted to the target type. For
example, you can replicate from a column of type <code class="type">integer</code> to a
column of type <code class="type">bigint</code>. The target table can also have
additional columns not provided by the published table. Any such columns
will be filled with the default value as specified in the definition of the
target table.
</p><div class="sect2" id="LOGICAL-REPLICATION-SUBSCRIPTION-SLOT"><div class="titlepage"><div><div><h3 class="title">31.2.1. Replication Slot Management</h3></div></div></div><p>
As mentioned earlier, each (active) subscription receives changes from a
replication slot on the remote (publishing) side. Normally, the remote
replication slot is created automatically when the subscription is created
using <code class="command">CREATE SUBSCRIPTION</code> and it is dropped
automatically when the subscription is dropped using <code class="command">DROP
SUBSCRIPTION</code>. In some situations, however, it can be useful or
necessary to manipulate the subscription and the underlying replication
slot separately. Here are some scenarios:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
When creating a subscription, the replication slot already exists. In
that case, the subscription can be created using
the <code class="literal">create_slot = false</code> option to associate with the
existing slot.
</p></li><li class="listitem"><p>
When creating a subscription, the remote host is not reachable or in an
unclear state. In that case, the subscription can be created using
the <code class="literal">connect = false</code> option. The remote host will then not
be contacted at all. This is what <span class="application">pg_dump</span>
uses. The remote replication slot will then have to be created
manually before the subscription can be activated.
</p></li><li class="listitem"><p>
When dropping a subscription, the replication slot should be kept.
This could be useful when the subscriber database is being moved to a
different host and will be activated from there. In that case,
disassociate the slot from the subscription using <code class="command">ALTER
SUBSCRIPTION</code> before attempting to drop the subscription.
</p></li><li class="listitem"><p>
When dropping a subscription, the remote host is not reachable. In
that case, disassociate the slot from the subscription
using <code class="command">ALTER SUBSCRIPTION</code> before attempting to drop
the subscription. If the remote database instance no longer exists, no
further action is then necessary. If, however, the remote database
instance is just unreachable, the replication slot should then be
dropped manually; otherwise it would continue to reserve WAL and might
eventually cause the disk to fill up. Such cases should be carefully
investigated.
</p></li></ul></div><p>
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logical-replication-publication.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logical-replication.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logical-replication-conflicts.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">31.1. Publication </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 31.3. Conflicts</td></tr></table></div></body></html>
