Skip to main content

​
Logical Replication Slots

Postgres logical replication slots are used to keep track of replication progress (recorded as a LSN). Every time a new version of Sync Streams or Sync Rules is deployed, PowerSync creates a new replication slot. Once the new version is fully processed, PowerSync switches to use the new slot and deletes the old one. The Service logs these steps and, during a snapshot, how much WAL budget remains. See Postgres Replication Slots and WAL Budget in the Log Reference. The replication slots can be viewed using this query:
Example output: In some cases, a replication slot may remain without being used. In this case, the slot prevents Postgres from deleting older WAL entries. For example, this happens when a PowerSync instance has been deprovisioned. Keeping unused slots alive prevents WAL cleanup, which can lead to excessive disk usage. If a slot is no longer needed, it should be dropped. Inactive slots can be dropped using:
Postgres prevents active slots from being dropped. If an active slot is somehow dropped while a PowerSync instance is disconnected, PowerSync will automatically recreate the slot when it reconnects and restart replication.

​
Recovering from an Invalidated Slot

A replication slot becomes invalidated when its wal_status is lost. This happens when the WAL data needed by the slot has been removed, typically because the replication lag exceeded max_slot_wal_keep_size. When this occurs, you will see an error such as:
Replication slot powersync_1_xxxx was invalidated (reason: wal_removed). Increase max_slot_wal_keep_size on the source database and delete the existing slot to recover.
To recover:
  1. Increase max_slot_wal_keep_size on the source Postgres database to prevent re-occurrence. See Managing and Monitoring Replication Lag for sizing guidance.
  2. Drop the invalidated slot:
Replace powersync_1_xxxx with the actual slot name from the error message.
  1. Restart the PowerSync Service. It will create a new replication slot and begin replication from scratch.
If the slot was invalidated during the initial snapshot (before it completed), the PowerSync Service will not automatically retry. You must drop the invalidated slot manually before the service can recover.
If the invalidation reason is idle_timeout (Postgres 18+), the slot was invalidated due to inactivity. In this case, increase idle_replication_slot_timeout on the source database instead.

​
Maximum Replication Slots

Postgres is configured with a maximum number of replication slots per server. Each PowerSync instance uses one replication slot for replication and an additional one while deploying a new Sync Streams or Sync Rules version. The maximum number of PowerSync instances you can connect to one Postgres server is equal to the maximum number of replication slots, minus one. If other clients are also using replication slots, this number is reduced further. To configure the maximum number of slots, set max_replication_slots (though not all hosting providers expose this setting). Check the current value using:
If this number is exceeded, you’ll see an error such as “all replication slots are in use”.

​
Oversized Replication Messages

Postgres replication currently has a 50 MiB receive buffer limit. A message that cannot fit can stall replication, with postgres sent too big message in the Replicator logs. The limit applies to every table in the publication, even those not referenced by Sync Streams. Publish only required tables and keep source rows within the separate 15 MiB row/document limit.
With REPLICA IDENTITY FULL, a message can include both previous and new row values, which doubles the size of a single row.

​
Recovery

This involves removal of oversized rows from replication and a potential reprocessing:
1

Identify Source

Review writes across all published tables for oversized rows. The time of the error’s first occurrence can help identify the source table.
2

Correct the Source

If the affected table is part of the PowerSync publication but not used by any Sync Streams, then remove the table from the publication and redeploy the service, and skip to step 4.Otherwise, reduce the size of the oversized row or delete it from the source database and move on to step 3.
3

Start a New Snapshot

Start full reprocessing for each affected instance. This creates a new replication slot and snapshots the current source data. Deleting a row alone does not erase its earlier WAL entries.
In the PowerSync Dashboard, open Settings, then select Defragment in the Compact operation history section.
4

Verify Recovery

If you reprocessed, confirm in your logs that the new replication stream is active. Check that replication lag decreases and clients receive new source updates.