Skip to main content
A connector links Ardent to one Postgres source server. Once a connector is ready, every branch you create comes from that source. For production databases, start with preflight. It checks the source and prints the SQL to fix missing grants without creating a connector or storing credentials.
Currently supported connector type: postgresql.

​
ardent connector preflight

Validate a Postgres source before creating a connector: 
ardent connector preflight postgresql 'postgresql://user:***@host:5432/mydb'
Preflight answers one question: “Can Ardent safely create a working connector for this database?” It checks:
  • connection and authentication
  • whether the URL points at a writer, not a read replica
  • logical replication settings
  • replication slot and WAL sender capacity
  • wal2json plugin availability
  • table-read permissions and Ardent metadata-schema permissions
  • whether this server is already connected to Ardent
If anything is missing, Ardent tells you exactly what to fix. When missing grants can be fixed with SQL, preflight prints a grant script you can copy, review, run, and then re-run preflight. 
ardent connector preflight postgresql 'postgresql://user:***@host:5432/mydb'   --schemas public,billing
OptionDescription
--schemas <list>Comma-separated schemas to check, for example public,billing
--byocRoute preflight through your customer-owned Ardent environment
--environment-id <id>Environment to use for BYOC/private-network preflight
--private-link-id <id>Private connection to use. Required when the environment has active private links
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.
For BYOC/private-network sources, route the check through the same environment and private connection you will use for connector creation: 
ardent connector preflight postgresql '<url>'   --byoc   --environment-id env_123   --private-link-id epl_123

​
ardent connector create

Create a connector after preflight passes: 
ardent connector create postgresql 'postgresql://user:***@host:5432/mydb' --name prod-db
Shell quoting: Wrap the connection URL in single quotes. Real connection strings often contain ?, &, #, !, $, parentheses, or spaces inside passwords. Single quotes keep your shell from interpreting those characters.
OptionDescription
-n, --name <name>Friendly connector name
--byocCreate the connector in a customer-owned Ardent environment
--environment-id <id>Environment for BYOC/private-network connectors
--private-link-id <id>Private connection to use for connector traffic
--replica-identity-decisions <path>JSON file with table-level replica identity decisions
--accept-replica-identity-defaultsNon-interactively accept current/default decisions. Undecided tables are excluded
✓ Connector created and ready
  ID: conn_abc123
  Ready to branch:
  ardent branch create <name>
Initial setup can take minutes to hours depending on source size, write rate, and network throughput. After setup, branch creation is fast and independent of source database size.

​
Replica identity decisions

Some tables cannot safely replicate UPDATE or DELETE events unless Postgres can identify the affected row. If Ardent finds tables without a primary key, valid unique NOT NULL index, or REPLICA IDENTITY FULL, the CLI asks what to do. For non-interactive flows, pass a complete decision file: 
ardent connector create postgresql '<url>'   --replica-identity-decisions ./replica-identity-decisions.json

{
  "public.audit_events": "exclude",
  "public.invoice_line_items": "replica_identity_full",
  "public.legacy_orders": "add_pk"
}
Decision values are:
ValueMeaning
excludeDo not replicate this table yet
add_pkYou will add a primary key or valid unique key on source before retrying
replica_identity_fullOpt into REPLICA IDENTITY FULL for this table
REPLICA IDENTITY FULL increases WAL volume for UPDATE and DELETE on that table. Use it deliberately; Ardent never changes replica identity on your source automatically.

​
ardent connector list

List all connectors in the current project: 
ardent connector list
The active connector is highlighted and prefixed with *. ● means the connector is ready to branch from; ○ means it is not. Warnings appear under the connector name.
Connectors:
* ● prod-db
postgresql
○ staging-db
postgresql

​
ardent connector switch

Switch the active connector without changing projects: 
ardent connector switch staging-db

Switched from 'prod-db' to 'staging-db'

​
ardent connector retry-setup

Recover setup for a connector that is still pending, failed source checks, or became unhealthy. The command preserves the existing connector row, credentials, and recovery handles; do not delete and recreate a connector just to retry setup. 
ardent connector retry-setup prod-db
When source checks are stale, failed, or unhealthy, the CLI first re-checks the source database, then starts engine setup. When setup is already healthy, the backend can short-circuit and the CLI prints that no work was needed. If setup is already in progress, retry-setup is still safe to run. Ardent reuses the active server-side setup operation instead of starting a duplicate. In connector status output, validating means source validation or setup is already in progress. If the connector is already validating and a replica-identity decision is still required, the CLI exits with code 1 and prints that decisions cannot be changed while setup is already in progress; wait for the current setup attempt to finish, then retry if the connector still shows setup pending. If the original setup needed replica identity decisions, pass the same JSON file when retrying: 
ardent connector retry-setup prod-db   --replica-identity-decisions ./replica-identity-decisions.json
You can also accept current/default decisions non-interactively during retry: 
ardent connector retry-setup prod-db --accept-replica-identity-defaults

​
ardent connector update

Update connector configuration. For example, omit selected source extensions from future 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

Delete a connector: 
ardent connector delete staging-db
By default, Ardent waits for in-progress replication work to finish so changes are not abandoned. Use --force only when you intentionally want to skip that wait. 
ardent connector delete staging-db --force

✓ Connector deleted