Self-hosted Postgres

Ardent works with self-managed Postgres 13 or newer. This page prepares your server; the connect-and-branch walkthrough is the Quickstart. Setup is a loop: run preflight, apply the SQL it prints, run preflight again until it passes.

ardent connector preflight postgresql 'postgresql://user:[YOUR-PASSWORD]@host:5432/mydb' --schemas public

Preflight is fast and non-destructive — it stores no credentials and creates nothing. It prints a pass/fail checklist and a Grant script with the exact SQL for your database and schemas.

Using Claude Code or Cursor? It can do the checks for you

With the ardent-cli skill installed, a short ask is enough — the skill fetches this page and runs the checks:

Check whether my self-hosted Postgres database is ready to connect to Ardent.
My connection string: [paste here]

Without the skill, paste the full directions:

Check whether my self-hosted Postgres database is ready to connect to Ardent.
My connection string: [paste here]

Use Ardent preflight first:
ardent connector preflight postgresql '<connection-string>' --schemas public

Then verify these source requirements and tell me exactly what to fix:
1. The host is reachable from Ardent over TLS on the Postgres port.
2. pg_hba.conf allows both normal and replication connections from Ardent's outbound IP.
3. wal_level is logical, max_wal_senders >= 10, max_replication_slots >= 10 (or higher if already higher, since these are minimums Ardent expects), and at least one replication slot is free.
4. wal2json is available. If you create a temporary slot to test it, immediately drop it; if the drop fails, stop and run SELECT pg_drop_replication_slot('ardent_probe'); before doing anything else.
5. The connection is to a writable primary, not a read replica: SELECT pg_is_in_recovery(); must return false.
6. The Ardent role has the grants from the preflight Grant script.
7. Tables selected for replication have a primary key, valid unique NOT NULL index, or REPLICA IDENTITY FULL.

After preflight passes, run:
ardent connector create postgresql '<connection-string>'

Allow inbound from Ardent

Ardent connects from a static outbound IP for your environment. If your network restricts inbound traffic, allow that IP on the Postgres port, usually 5432. Ask your Ardent contact for the current outbound IP if you don’t have it.Make sure ssl = on and pg_hba.conf accepts both regular SQL sessions and logical replication sessions from Ardent. Postgres treats them as different connection types, so both lines matter:

# regular connections: discovery, grants, and bookkeeping
hostssl all          ardent_replication  <outbound_ip>/32  scram-sha-256

# replication connections: logical WAL streaming
hostssl replication  ardent_replication  <outbound_ip>/32  scram-sha-256

After editing pg_hba.conf, reload Postgres — a reload is enough, no restart needed:

SELECT pg_reload_conf();

Or from the shell: pg_ctl reload -D <datadir> (or sudo systemctl reload postgresql on systemd installs).Hostnames must resolve to an IPv4 address. IPv6-only hosts are not supported today.

Enable logical replication

Check the current values first:

SHOW wal_level;
SHOW max_wal_senders;
SHOW max_replication_slots;

Ardent needs wal_level = logical, at least one free replication slot, and enough WAL sender capacity for Ardent plus anything else already replicating from your database. If your existing values are higher than Ardent’s minimums, keep the higher values.ALTER SYSTEM SET only accepts a literal value, not an expression — so ALTER SYSTEM SET max_wal_senders = 10 on a server that already has 20 (say, for existing standbys) would lower it on the next restart and could start refusing those standbys. This block raises each setting only when it’s below Ardent’s minimum:

DO $$
DECLARE
  v_wal_level  text := current_setting('wal_level');
  v_senders    int  := current_setting('max_wal_senders')::int;
  v_slots      int  := current_setting('max_replication_slots')::int;
BEGIN
  IF v_wal_level <> 'logical' THEN
    EXECUTE 'ALTER SYSTEM SET wal_level = ''logical''';
  END IF;
  IF v_senders < 10 THEN
    EXECUTE format('ALTER SYSTEM SET max_wal_senders = %s', 10);
  END IF;
  IF v_slots < 10 THEN
    EXECUTE format('ALTER SYSTEM SET max_replication_slots = %s', 10);
  END IF;
END
$$;

Prefer doing it by hand? Run the SHOW queries above and only change the settings whose values are below 10.

These changes need a Postgres restart. Plan a maintenance window before continuing.

Be careful with max_slot_wal_keep_size. A finite value protects your disk, but if a logical slot falls behind past that limit, Postgres can invalidate the slot — which forces a connector rebuild, not a graceful catch-up. For high-write databases, leave enough headroom and monitor retained WAL.

Long idle transactions hold back WAL cleanup. Consider idle_in_transaction_session_timeout on roles that might leave transactions open, for example ALTER ROLE app_user SET idle_in_transaction_session_timeout = '5min';.

Install the wal2json output plugin

Ardent reads changes through the wal2json logical-decoding plugin. Install the package matching your Postgres major version:

Debian and Ubuntu: postgresql-<major>-wal2json
RHEL family: wal2json_<major>

Restart Postgres if the plugin wasn’t already loaded.To test it manually, create and immediately drop a temporary slot:

SELECT pg_create_logical_replication_slot('ardent_probe', 'wal2json');
SELECT pg_drop_replication_slot('ardent_probe');

If your session is interrupted after the create statement, run the drop manually before continuing — an unconsumed logical slot retains WAL indefinitely and can fill the disk. Verify cleanup:

SELECT slot_name
FROM pg_replication_slots
WHERE slot_name = 'ardent_probe';

No rows should come back.

Create the Ardent role

Today, vanilla self-hosted Postgres requires the Ardent role to create event triggers, which is restricted to SUPERUSER. That’s a broad permission — a Postgres superuser can read and modify anything on the cluster. Use a dedicated role, restrict network access to Ardent’s outbound IP, rotate the password deliberately, and prefer a dedicated source cluster or database if your security model requires stricter isolation.

CREATE ROLE ardent_replication WITH LOGIN PASSWORD '<strong-password>';
ALTER ROLE ardent_replication WITH REPLICATION SUPERUSER;

The grants below are still worth running. They don’t limit a superuser — they document the intended read footprint and make the setup ready for the future narrower Ardent role.For each database you want to replicate:

GRANT CONNECT ON DATABASE "<db>" TO ardent_replication;
GRANT CREATE  ON DATABASE "<db>" TO ardent_replication;

GRANT CREATE ON DATABASE lets Ardent create its own pgstream bookkeeping schema and publication. It does not grant write access to your application schemas.For each schema you want replicated, run inside the matching database:

GRANT USAGE ON SCHEMA "<schema>" TO ardent_replication;
GRANT SELECT ON ALL TABLES    IN SCHEMA "<schema>" TO ardent_replication;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA "<schema>" TO ardent_replication;

ALTER DEFAULT PRIVILEGES IN SCHEMA "<schema>"
  GRANT SELECT ON TABLES TO ardent_replication;
ALTER DEFAULT PRIVILEGES IN SCHEMA "<schema>"
  GRANT SELECT ON SEQUENCES TO ardent_replication;

The ALTER DEFAULT PRIVILEGES lines keep future tables and sequences visible to replication. They only apply to objects created by the role that ran the ALTER — if your application creates tables as another role, repeat them with FOR ROLE:

ALTER DEFAULT PRIVILEGES FOR ROLE "app_writer" IN SCHEMA "<schema>"
  GRANT SELECT ON TABLES TO ardent_replication;
ALTER DEFAULT PRIVILEGES FOR ROLE "app_writer" IN SCHEMA "<schema>"
  GRANT SELECT ON SEQUENCES TO ardent_replication;

Find table-owner roles in a schema with:

SELECT DISTINCT tableowner
FROM pg_tables
WHERE schemaname = '<schema>';

You usually don’t need to assemble this by hand — preflight prints the generated grant script for your schemas.

Run preflight until it passes

ardent connector preflight postgresql 'postgresql://ardent_replication:[YOUR-PASSWORD]@your-host:5432/mydb' --schemas public

Common failures:

is writer fails — the URL points at a read replica. Use the writable primary.
wal level fails — enable logical replication and restart Postgres.
wal2json unverified or failed — install the plugin, or ask Ardent to confirm provider support.
can read tables fails — run the generated grant script.
duplicate source fails — this database is already connected. Run ardent connector list.

When preflight passes, continue with the Quickstart: create the connector and your first branch. One heads-up for that step: tables without a primary key or valid unique index need a replica identity decision. The CLI walks you through it, and Ardent never runs DDL on your source.