> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryardent.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connectors
> Preflight, create, monitor, and update Postgres connectors
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:
```bash theme={null}
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.
```bash theme={null}
ardent connector preflight postgresql 'postgresql://user:***@host:5432/mydb' --schemas public,billing
```
| Option | Description |
| ------------------------ | --------------------------------------------------------------------------------- |
| `--schemas ` | Comma-separated schemas to check, for example `public,billing` |
| `--byoc` | Route preflight through your customer-owned Ardent environment |
| `--environment-id ` | Environment to use for BYOC/private-network preflight |
| `--private-link-id ` | Private connection to use. Required when the environment has active private links |
```text theme={null}
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:
```bash theme={null}
ardent connector preflight postgresql '' --byoc --environment-id env_123 --private-link-id epl_123
```
## ardent connector create
Create a connector after preflight passes:
```bash theme={null}
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.
| Option | Description |
| ------------------------------------- | --------------------------------------------------------------------------------- |
| `-n, --name ` | Friendly connector name |
| `--byoc` | Create the connector in a customer-owned Ardent environment |
| `--environment-id ` | Environment for BYOC/private-network connectors |
| `--private-link-id ` | Private connection to use for connector traffic |
| `--replica-identity-decisions ` | JSON file with table-level replica identity decisions |
| `--accept-replica-identity-defaults` | Non-interactively accept current/default decisions. Undecided tables are excluded |
```text theme={null}
✓ Connector created and ready
ID: conn_abc123
Ready to branch:
ardent branch create
```
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:
```bash theme={null}
ardent connector create postgresql '' --replica-identity-decisions ./replica-identity-decisions.json
```
```json theme={null}
{
"public.audit_events": "exclude",
"public.invoice_line_items": "replica_identity_full",
"public.legacy_orders": "add_pk"
}
```
Decision values are:
| Value | Meaning |
| ----------------------- | ------------------------------------------------------------------------ |
| `exclude` | Do not replicate this table yet |
| `add_pk` | You will add a primary key or valid unique key on source before retrying |
| `replica_identity_full` | Opt 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:
```bash theme={null}
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:
```bash theme={null}
ardent connector switch staging-db
```
```text theme={null}
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.
```bash theme={null}
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:
```bash theme={null}
ardent connector retry-setup prod-db --replica-identity-decisions ./replica-identity-decisions.json
```
You can also accept current/default decisions non-interactively during retry:
```bash theme={null}
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:
```bash theme={null}
ardent connector update prod-db --drop-extensions pgmq,supabase_vault
```
Pass an empty string to clear the list:
```bash theme={null}
ardent connector update prod-db --drop-extensions ''
```
## ardent connector delete
Delete a connector:
```bash theme={null}
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.
```bash theme={null}
ardent connector delete staging-db --force
```
```text theme={null}
✓ Connector deleted
```