Manage Reverse ETL Connections using Rudder CLI

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.

Key features

Declarative sync configuration

• Set 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.
• Delete a connection entry to disconnect the pair without deleting the source or destination.

Local validation

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.

Git integration and CI/CD support

• Import Reverse ETL connections from your workspace, then manage them in Git.
• Run validate in CI so a pull request that violates connection rules fails before apply.

Who can use this feature?

CLI-based Reverse ETL connections are useful when you need to:

• Keep the SQL model, the destination, and the sync configuration between them in one repository.
• Review schedule and mapping changes in a pull request before they reach a workspace.

Enable Reverse ETL connection support

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.

export RUDDERSTACK_CLI_EXPERIMENTAL=true
export RUDDERSTACK_X_RETL_CONNECTION_SUPPORT=true

{
  "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.

Supported sources and destinations

• Sources — SQL models on any supported warehouse. Table sources are available behind an additional experimental flag. See Supported sources.
• Destinations — HTTP Webhook in Rudder CLI v0.27.0. v0.28.0 or later adds more destination types, including Amplitude, Braze, HubSpot, and Iterable. See Supported destinations for the full list.

Limits

• Audience sources: Rudder CLI doesn’t manage connections from Audiences.
• Customer.io: Customer.io syncs Reverse ETL data through its own flow, which connection specs can’t express. validate rejects a connection to it.
• One Reverse ETL source per destination: In a project, a destination can receive from only one Reverse ETL source, and can’t receive from both Event Stream and Reverse ETL sources.
• Connections outside the project: 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.
• Sync operations: Rudder CLI declares the connection but doesn’t start, stop, or report on syncs. Use the dashboard to start and stop syncs.
• Single-connection import: You can import Reverse ETL connections only with rudder-cli import workspace.

Apply and replace behavior

What apply does with a change depends on the field you changed:

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.

Change an immutable field

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 it

To 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.

Replacement

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.

Get started

• Follow the End-to-End Walkthrough: Reverse ETL Connections with Rudder CLI to sync a SQL model to a destination
• See the Reverse ETL Connection YAML Reference for fields, mapping flows, and validation rules
• Define endpoints first: SQL models and destinations
• Automate with GitHub Actions for Rudder CLI