Connectors - Ardent

A connector links Ardent to one Postgres server. Once it’s ready, every branch you create comes from that source.

Currently supported connector type: postgresql.

ardent connector preflight

Check a database before connecting it. Preflight creates nothing and stores no credentials:

ardent connector preflight postgresql 'postgresql://user:***@host:5432/mydb'

It answers one question: can Ardent safely branch this database? It checks:

Connection — the host is reachable and the credentials work
Permissions — the role can read the tables you want to replicate
Replication settings — wal_level, free replication slots, WAL senders, and the wal2json plugin

When something is missing, it tells you the exact fix — and prints a ready-to-run SQL grant script when grants are the problem.

Example output

Running preflight against db.example.com:5432…

Connection checks:
  ✓ tcp reachable
  ✓ auth
  ✓ postgres metadata
  ✓ is writer
  ✓ wal level (actual: logical)
  ✓ replication slots (2/10 used)
  ✓ wal senders (max: 10)
  ✓ wal2json
  ✗ can read tables
      Missing SELECT on public.orders
      → Run the grant script below, then re-run preflight.

Detected source provider: vanilla

--- Grant script ---
-- psql artifact generated by Ardent
-- ...

✗ Preflight checks did NOT pass. Fix the failures above before creating.

Option	Description
`--schemas <list>`	Only check these schemas, e.g. `public,billing`
`--byoc`	Run the check through your customer-owned Ardent environment
`--environment-id <id>`	Which environment to use (needs `--byoc`)
`--private-link-id <id>`	Which private connection to use (needs `--byoc`)
`--allow-high-rtt-placement`	Allow a far-away placement despite higher latency (needs `--byoc`)

Preflight exits 0 when everything passes and 2 when it doesn’t, so you can use it in scripts.

ardent connector create

When preflight passes, connect the database:

ardent connector create postgresql 'postgresql://user:***@host:5432/mydb' --name prod-db

Wrap the URL in single quotes. Passwords often contain characters your shell would otherwise interpret.

Option	Description
`-n, --name <name>`	Connector name. Leave it off and Ardent derives one from your project and database
`--byoc [environment-id]`	Create in a customer-owned Ardent environment
`--environment-id <id>`	Which environment (needs `--byoc`)
`--private-link-id <id>`	Which private connection. Auto-picked when the environment has exactly one
`--allow-high-rtt-placement`	Allow a far-away placement despite higher latency (needs `--byoc`)
`--replica-identity-decisions <path>`	JSON file of table decisions — see below
`--accept-replica-identity-defaults`	Accept the default decision for every table, without prompting
`--write-replica-plan <path>`	Write the recommended decisions to a file and stop, so you can review before setup

The last three are different ways to answer replica identity decisions — use at most one. With none, the CLI walks you through the choices interactively.

Example output

✓ Connector created and ready
  ID: conn_abc123
  Ready to branch:
  ardent branch create <name>

First-time setup copies your data, so it can take minutes to hours depending on database size, write rate, and network speed. After that, branches are created in seconds regardless of size.

Replica identity decisions

Some tables have no primary key or valid unique index, so Postgres can’t tell which row an UPDATE or DELETE touched. When Ardent finds tables like this, the CLI asks what to do with each one. In scripts (no terminal), it exits with code 1 instead of guessing — pass one of the three flags above. You can also answer ahead of time: --replica-identity-decisions takes a JSON file mapping each table to a choice. Most databases have keys on every table and never hit this.

What each choice means, and the decisions file format

A valid unique index means unique, NOT NULL on every column, non-partial, and non-deferrable. Tables without a primary key or an index like that need a decision:

{
  "public.audit_events": "exclude",
  "public.invoice_line_items": "replica_identity_full",
  "public.legacy_orders": "add_pk"
}

Value	Meaning
`exclude`	Don’t replicate this table yet
`add_pk`	You’ll add a primary key or unique key on the source, then retry
`replica_identity_full`	Use `REPLICA IDENTITY FULL` for this table

The file must cover every listed table. With --accept-replica-identity-defaults, undecided tables are excluded.

REPLICA IDENTITY FULL makes UPDATE and DELETE write more to your database’s WAL. Choose it deliberately. Ardent never changes replica identity on your source — when a change is needed, it prints the SQL for you to run.

ardent connector list

ardent connector list

Your active connector is green and marked *. Status icons:

Icon	Meaning
`●` green	Ready to branch
`●` yellow	Working, but degraded — some source objects are left out of branches
`◐` cyan	Setup still in progress
`○` red	Broken — failed or unreachable

Warnings appear under the connector, with a ⚠ count next to the name. A [delete locked] marker means deletion is locked (see below). In CI, add --fail-on-warnings to exit with code 2 when any connector has warnings.

ardent connector status

Show one connector’s health and setup progress:

ardent connector status prod-db

Example output

Connector: prod-db
Service:   postgresql
Status:    Ready

validating means source checks or setup are running right now.

ardent connector switch

Change the active connector without changing projects:

ardent connector switch staging-db

ardent connector retry-setup

Finish or repair setup without deleting the connector. Your credentials and configuration are kept.

ardent connector retry-setup prod-db

What happens depends on the connector’s state:

Checks are stale or failed — the CLI re-checks the source first, then runs setup.
Already healthy — nothing to do; the CLI says so and exits.
Setup already running — safe to run anyway; it joins the running setup instead of starting another. If that setup still needs replica identity decisions, the CLI exits with code 1 — decisions can’t change mid-setup. Wait for it to finish, then retry.

If the original setup needed replica identity decisions, pass the same file or flag again:

ardent connector retry-setup prod-db --replica-identity-decisions ./decisions.json
ardent connector retry-setup prod-db --accept-replica-identity-defaults

ardent connector update

Change connector configuration. One setting today: which source extensions to leave out of new branches.

ardent connector update prod-db --drop-extensions pgmq,supabase_vault

Pass an empty string to clear the list:

ardent connector update prod-db --drop-extensions ''

ardent connector delete

ardent connector delete staging-db

By default, Ardent waits for in-progress replication to finish so no changes are lost. --force skips the wait and abandons those changes. Two things can stop a delete:

Deletion is locked — someone ran connector lock on it. Unlock first.
A branch has un-replicated changes — wait, or re-run with --force.

Locks and quarantines

You’ll rarely need these two, but you should know they exist.

ardent connector lock / unlock — protect a connector from deletion

ardent connector lock prod-db --reason "production source"
ardent connector unlock prod-db

While locked, connector delete refuses and tells you to unlock first. Locked connectors show [delete locked] in connector list.

ardent connector quarantine — inspect and release paused replication

If part of a connector’s replication keeps crashing, Ardent pauses (quarantines) it to protect your source. Quarantines don’t show in connector status — list them directly:

ardent connector quarantine list prod-db

Each entry shows what was paused, why, when, and the exact release command:

ardent connector quarantine release prod-db <quarantine-id>

Fix the underlying cause before releasing, or it will likely quarantine again.

​ardent connector preflight

​ardent connector create

​Replica identity decisions

​ardent connector list

​ardent connector status

​ardent connector switch

​ardent connector retry-setup

​ardent connector update

​ardent connector delete

​Locks and quarantines

ardent connector preflight

ardent connector create

Replica identity decisions

ardent connector list

ardent connector status

ardent connector switch

ardent connector retry-setup

ardent connector update

ardent connector delete

Locks and quarantines