Connect a database.
Any PostgreSQL 12 or newer with logical replication turned on. You provide a user that may replicate; Waltail creates its own publication and slot.
What you need
- PostgreSQL 12 or newer, on any host.
wal_level = logical. On a managed host this is a parameter or a project setting; on your own server it isALTER SYSTEMplus a restart.- A user with the
REPLICATIONattribute (or a superuser, or the host's replication role). The same user must own the tables you stream — or belong to the role that owns them — because creating a publication for a table requires ownership. - A free replication slot.
max_replication_slotsdefaults to 10. - Network access from Waltail to the database's direct port. A transaction-mode pooler such as PgBouncer cannot carry a replication connection.
The six checks
When you paste a connection string and press Test, the console runs these checks in order. A failed check shows what to change, with SQL you can copy.
| Check | Passes when | If it fails |
|---|---|---|
reachable | Waltail can open a connection to the host within 5 seconds | Open the firewall or security group to Waltail, and make sure the host name resolves publicly |
credentials | The user and password are accepted | Fix the user or password in the connection string |
version | PostgreSQL 12 or newer | Upgrade — logical replication needs 12 or newer |
wal_level | show wal_level returns logical | Run ALTER SYSTEM SET wal_level = 'logical'; and restart, or change the setting in your host's parameter group |
replication_privilege | The user has REPLICATION or is a superuser | Run ALTER ROLE "<user>" REPLICATION; as a superuser, or use the host's equivalent grant |
slot_headroom | At least one replication slot is free (a warning when only one is) | Raise max_replication_slots or drop slots you no longer use |
Which tables can be streamed
Inserts replicate from any table. Updates and deletes need a way to identify the row: a primary key, or REPLICA IDENTITY set to FULL or to an index. The table picker marks tables that do not qualify and says why.
With the default identity, the old field in update and delete messages holds only the key columns. If your consumer needs the whole previous row, set:
ALTER TABLE public.orders REPLICA IDENTITY FULL;What Waltail creates on your database
One publication for the selected tables and one logical replication slot (plugin pgoutput), both named pgcdc_<pipeline-name>. Changing the pipeline's tables alters the publication in place. Deleting the pipeline drops both, so nothing is left behind.
Waltail acknowledges each change as soon as it has stored it, so the WAL kept for the slot stays small even when a destination is slow. The console shows slot lag per pipeline so you can keep an eye on it.