A Reverse ETL connection is the link between a Reverse ETL source and a destination. It also holds the sync configuration for that pair: the sync mode, the schedule, the identifiers, and the column mappings. Rudder CLI already manages SQL models and destinations as YAML. Connection specs declare those links in the same project so rudder-cli apply creates the source, destination, and connection in the right order — without a dashboard step to wire them together.
Use kind: retl-connections. Each entry in spec.connections references resources in the same project (#retl-source-sql-model:… and #destination:…) and carries its sync configuration in a config block. Rudder CLI uses those references to create endpoints before the connection, and to delete the connection before the endpoints.
To connect an Event Stream source instead, see Manage Connections using Rudder CLI.
To set up a connection step by step, follow the Reverse ETL connections walkthrough.
Reverse ETL connection support is experimental and requires Rudder CLI v0.27.0 or later.
v0.27.0 connects to HTTP Webhook only. The other supported destinations need v0.28.0 or later.
Enable the experimental flags before you validate or apply connection resources.
enabled to control whether that pair syncs. If you omit enabled, it defaults to true. Both endpoints must also be enabled for the connection to sync.rudder-cli validate checks Reverse ETL connection specs — including that both endpoints exist in the project, the destination accepts Reverse ETL sources, the mappings fit the mapping flow, and the schedule syncs no more often than every five minutes.
See Reverse ETL Connection YAML Reference for the full rule list.
validate in CI so a pull request that violates connection rules fails before apply.CLI-based Reverse ETL connections are useful when you need to:
Reverse ETL connections need two settings. The first turns on experimental features as a whole — without it, Rudder CLI ignores every experimental flag. The second turns on Reverse ETL connections.
| Setting | Environment variable | Config key |
|---|---|---|
| Experimental features | RUDDERSTACK_CLI_EXPERIMENTAL |
experimental |
| Reverse ETL connections | RUDDERSTACK_X_RETL_CONNECTION_SUPPORT |
flags.retlConnectionSupport |
export RUDDERSTACK_CLI_EXPERIMENTAL=true
export RUDDERSTACK_X_RETL_CONNECTION_SUPPORT=trueAdd these keys to ~/.rudder/config.json, next to the ones already in the file:
{
"experimental": true,
"flags": {
"retlConnectionSupport": true
}
}Every command that loads a project containing a retl-connections spec needs both settings, including validate and apply in CI. import workspace needs them too, or it doesn’t import Reverse ETL connections. Without them, Rudder CLI doesn’t recognize the kind, and the spec fails validation with a 'kind' must be one of [...] error that lists the kinds it does recognize.
validate rejects a connection to it.validate sees only the connections in your project. The one-Reverse-ETL-source-per-destination and no-mixed-source rules are enforced by the dashboard and Rudder CLI, not by the API, so a conflict with a connection that exists only in the workspace isn’t caught at apply either — it lands in the workspace as a misconfiguration.rudder-cli import workspace.What apply does with a change depends on the field you changed:
| Change | What apply does |
|---|---|
enabled, schedule, identifiers, mappings, constants, sync_settings |
Updates the connection in place. Adding or changing a mapping triggers a full sync. |
sync_behaviour, cursor_column, object, event |
Fails. These fields are immutable after the connection is created. |
source or destination |
Replaces the connection (delete + create). The backend treats each source–destination pair as unique. |
RudderStack keeps sync state per connection ID, so every connection that apply creates starts with a full sync, whatever its sync_behaviour. That includes a connection it replaces, or one you delete and recreate.
Changing an immutable field fails the apply with an error that names the field. validate and apply --dry-run don’t detect this change, so the error appears only when you apply:
syncing resources: connection "users-to-webhook": connection update: cursor_column is immutable ("" -> "updated_at"); delete and recreate the connection to apply itTo apply the change, remove the connection entry from the spec and run apply. Then, add the entry back with the new value and run apply again. The recreated connection has a new ID.
Rudder CLI builds and checks the new connection before it deletes the existing one. A replacement that fails those checks leaves the live connection untouched.
A replaced connection has a new ID.
If the delete succeeds and the create then fails, the error says that the previous connection was deleted:
recreating rETL connection "users-to-webhook" after an endpoint change (the previous connection was deleted): ...Fix the cause and run apply again to create the connection. The error doesn’t include the ID of the deleted connection. Rudder CLI logs it as connectionId in the replacing rETL connection after an endpoint change warning in ~/.rudder/cli.log.