|
| 1 | +--- |
| 2 | +title: Setting up logical replication as a publisher in PostgreSQL |
| 3 | +description: Learn how to set up and use logical replication as a publisher in PostgreSQL |
| 4 | +tags: postgresql logical replication publisher publication database |
| 5 | +dates: |
| 6 | + validation: 2025-08-25 |
| 7 | + posted: 2025-02-20 |
| 8 | +--- |
| 9 | +import Requirements from '@macros/iam/requirements.mdx' |
| 10 | + |
| 11 | +The logical replication of databases as a publisher is available with [PostgreSQL 17](/managed-databases-for-postgresql-and-mysql/reference-content/pg-version-updates#postgresql-17), which is supported in Scaleway's Managed Databases for PostgreSQL. |
| 12 | + |
| 13 | +The feature allows you to replicate data from a managed PostgreSQL to another Database Instance (a Managed PostgreSQL in another region, for example). |
| 14 | + |
| 15 | +Replication slots can be created with the `failover` flag, which ensures that replication slots survive failovers. When a secondary node is promoted to primary, the replication slot is automatically available on the new main node. |
| 16 | + |
| 17 | +<Requirements /> |
| 18 | + |
| 19 | +- A Scaleway account logged into the [console](https://console.scaleway.com) |
| 20 | +- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization |
| 21 | +- A [Database Instance](/managed-databases-for-postgresql-and-mysql/how-to/create-a-database/) running PostgreSQL 17 |
| 22 | + |
| 23 | +## Configuring advanced settings and user rights |
| 24 | + |
| 25 | +As the service uses physical replication internally, some advanced settings and parameters must be enabled to allow the logical replication to work properly with our system, for standalone and High Availability clusters. |
| 26 | + |
| 27 | +Follow the steps in the [How to configure advanced settings](/managed-databases-for-postgresql-and-mysql/how-to/configure-advanced-settings) documentation page to configure the following settings: |
| 28 | + |
| 29 | +To enable logical replication, you must: |
| 30 | + |
| 31 | +- Enable the `rdb.enable_logical_replication` setting. This automatically changes the `wal_level` settings to `logical`. |
| 32 | +- Set `hot_standby_feedback` to `ON` |
| 33 | +- Set `sync_replication_slots` to `ON`- [replication slots](https://www.postgresql.org/docs/17/logicaldecoding-explanation.html#LOGICALDECODING-REPLICATION-SLOTS) is an important part of the logical replication. Each subscription receives changes via one replication slot created on the "publishing" node. You have one replication slot available per logical database. |
| 34 | + |
| 35 | +<Message type="important"> |
| 36 | + As the service uses physical replication to provide High Availability, the `hot_standby_feedback` and `sync_replication_slots` parameters must be enabled to allow the logical replication to remain active after the promotion of a secondary node, without disturbing the HA setup. It is essential to ensure these settings are enabled as even a Database Instance in standalone mode can be replaced with temporary replicas. |
| 37 | +</Message> |
| 38 | + |
| 39 | +To use replication, users must also have the corresponding rights. |
| 40 | + |
| 41 | +Follow the steps in the [How to manage users](/managed-databases-for-postgresql-and-mysql/how-to/manage-users) documentation page to attribute user rights. |
| 42 | + |
| 43 | +To create publications and replication slots, the `replication_user` must: |
| 44 | + |
| 45 | +- Either be an member of admin user role (`_rdb_admin`) |
| 46 | +- Or be granted the following rights from a role member of the`_rdb_admin` role: |
| 47 | + - `ALTER replication_user with REPLICATION` |
| 48 | + - `GRANT CREATE ON DATABASE my_database TO my_replication_user;` |
| 49 | + |
| 50 | +## Setting up logical replication |
| 51 | + |
| 52 | +We use an example scenario to show how logical replication can be set up. |
| 53 | + |
| 54 | +1. Create the table and publication on the publisher database. |
| 55 | + ```sql |
| 56 | + CREATE TABLE mytable (id INTEGER PRIMARY KEY, val TEXT); |
| 57 | + CREATE PUBLICATION pub FOR TABLE mytable; |
| 58 | + ``` |
| 59 | +2. Insert a sample row into the table. This ensures that there is data to test the replication with. |
| 60 | + ```sql |
| 61 | + INSERT INTO mytable VALUES (1, 'foo'); |
| 62 | + ``` |
| 63 | +3. Create the same table structure on the subscriber database. Leave the table empty, as data will be copied into it upon subscription. |
| 64 | + ```sql |
| 65 | + CREATE TABLE mytable (id INTEGER PRIMARY KEY, val TEXT); |
| 66 | + ``` |
| 67 | +4. Create a subscription. Two methods are available: |
| 68 | + - **Direct subscription with failover** - use this method if your environment supports the failover option in `CREATE SUBSCRIPTION` |
| 69 | + - **Creating a replication slot manually on the publisher** - |
| 70 | + |
| 71 | + <Tabs> |
| 72 | + <TabsTab label="Set up direct subscription"> |
| 73 | + ```sql |
| 74 | + CREATE SUBSCRIPTION sub CONNECTION 'host=myhost port=myport user=myuser dbname=mydb password=mypassword' PUBLICATION pub WITH (failover); |
| 75 | + ``` |
| 76 | + </TabsTab> |
| 77 | + <TabsTab label="Create replication slot manually"> |
| 78 | + Some environments do not allow `CREATE SUBSCRIPTION` to auto-create slots due to permissions or configuration. In this case, you can create a slot with failover manually. |
| 79 | + 1. Create a replication slot on the publisher database. |
| 80 | + ```sql |
| 81 | + SELECT pg_create_logical_replication_slot('sub', 'pgoutput', false, false, true); |
| 82 | + ``` |
| 83 | + <Message type="note"> |
| 84 | + The last `true` in the command above enables the `failover` flag. |
| 85 | + </Message> |
| 86 | + 2. Create the subscription without creating a slot. |
| 87 | + ```sql |
| 88 | + CREATE SUBSCRIPTION sub CONNECTION 'host=myhost port=myport user=myuser dbname=mydb password=mypassword' PUBLICATION pub WITH (enabled=true, create_slot=false, slot_name='sub'); |
| 89 | + ``` |
| 90 | + <Message type="note"> |
| 91 | + Refer to the official [PostgreSQL documentation](https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-REPLICATION) for more information about `pg_create_logical_replication_slot()`. |
| 92 | + </Message> |
| 93 | + </TabsTab> |
| 94 | + </Tabs> |
| 95 | + |
| 96 | +5. Query the publisher table in the subscriber to test the replication. |
| 97 | + ```sql |
| 98 | + SELECT * FROM mytable; |
| 99 | + ``` |
| 100 | + |
| 101 | +<Message type="note"> |
| 102 | + Refer to the official [PostgreSQL documentation](https://www.postgresql.org/docs/current/logical-replication.html) for more information about logical replication. |
| 103 | +</Message> |
| 104 | + |
| 105 | +## Limitations |
| 106 | + |
| 107 | +- 100 replication slots are available for each Database Instance. |
| 108 | +- 25 out of the 100 slots are reserved for Scaleway's internal systems. |
| 109 | +- During the synchronization phase, 2 or more slots might be needed for a subscription. |
| 110 | + <Message type="important"> |
| 111 | + - If you need more than 50 replication slots, [create a support ticket](https://console.scaleway.com/support). |
| 112 | + - Exceeding this limit may cause the Instance's internal replication to fail. High Availability and cluster operations may also become degraded or not functional. In extreme cases, service availability may be affected. |
| 113 | + </Message> |
| 114 | + |
| 115 | + <Message type="tip"> |
| 116 | + Run the following command to get a list of your replication slots: |
| 117 | + ```sql |
| 118 | + SELECT * FROM pg_replication_slots where slot_type = 'logical'; |
| 119 | + ``` |
| 120 | + And the following command to check publications: |
| 121 | + ```sql |
| 122 | + SELECT * from pg_publication; |
| 123 | + ``` |
| 124 | + </Message> |
| 125 | + |
| 126 | +- If a logical replication is not active (not consumed by a subscription or other tool), PostgreSQL WAL files will accumulate in the primary node, filling up storage. In the worst case scenario, your database can be set to read only mode (check disk full section) or unavailable. |
| 127 | + <Message type="tip"> |
| 128 | + - We recommend you delete any replication slots that are no longer used. |
| 129 | + - If a logical replication is inactive for 24h, it will be automatically removed. |
| 130 | + </Message> |
0 commit comments