I already use ClickHouse as an ETL destination. Can reverse ETL read from that connection?

No. The destination and the reverse ETL source are separate connections, even when they point at the same cluster. Add the source under the **Reverse ETL** filter of the source catalog with a user that has the privileges listed on this page.

Do I have to create the planner database myself?

No. Renta runs CREATE DATABASE IF NOT EXISTS when you save the connection and at the start of every run. The user still needs the CREATE DATABASE privilege: ClickHouse checks the privilege before it checks whether the database exists, so a database you created by hand does not remove the requirement.

Why does saving the connection fail with a message about the planner database?

The user cannot create the planner database, and Renta does not store a connection that would fail on its first run. Grant CREATE DATABASE ON *.* to the user, or enter a database name the user is allowed to create in the **Planner database** field, and save again.

Why is my model missing from the pipeline's Data model list?

A pipeline lists only models with the **Reverse ETL only** or **AI agents & Reverse ETL** scope. Open the model, change the scope on the **Query** tab, and save.

Why did the unique key check fail?

The column contains NULL or repeats a value. Renta reports nulls first, so a column with both problems says nothing about the duplicates until the nulls are gone. Wrap the column in assumeNotNull , filter the rows out, or pick a different column.

Can a model query end with a FORMAT clause?

No. Renta embeds the model in a subquery and selects the output format itself, so a trailing FORMAT clause is rejected. The same applies to INTO OUTFILE and to every write statement.

Which ClickHouse deployments can Renta read from?

Any deployment whose HTTP interface accepts connections from the Renta IP addresses: a self-managed server, ClickHouse Cloud, or a managed service. For Yandex Managed Service for ClickHouse over **https**, Renta trusts the Yandex root certificate without extra setup.

ClickHouse reverse ETL source

Renta reads a data model from your ClickHouse database and syncs its rows to a business tool through a reverse ETL pipeline. A model is a SELECT statement in the ClickHouse dialect or a table. Each run keeps its working tables in a planner database on the same cluster.

This page describes how to connect ClickHouse as a reverse ETL source, create a data model on it, and start a pipeline. The destination settings of the pipeline are described on the page of each destination.

Before you begin

Before you add the connection, check the following.

Network access.
The ClickHouse HTTP interface accepts connections from the Renta IP addresses. The default ports are 8443 for HTTPS and 8123 for HTTP.
A dedicated ClickHouse user.
Renta signs in with a database user that can create its planner database and read the databases your models query. The privileges are listed in the next section.
A separate connection.
A ClickHouse ETL destination in your workspace does not work as a reverse ETL source. The reverse ETL source is a separate connection with its own user.

Grant the required privileges

Renta keeps the working tables of every run in a database of its own. This database is called the planner database, and it is named renta_planner unless you rename it in the connection settings.

Privilege	Scope	What Renta uses it for
CREATE DATABASE	.	Creating the planner database when you save the connection and at the start of every run.
CREATE TABLE, DROP TABLE, INSERT, SELECT, ALTER, OPTIMIZE	The planner database	Writing the plan and rejection tables of a run and dropping the tables of older runs.
SELECT	Every database your models read	Running the preview, checking the unique key, and reading the model on every run.

To create the user and grant the privileges, run the following statements from an account with access management rights. Replace analytics with the database your models read from, and repeat the last statement for every other database they use.

CREATE USER renta IDENTIFIED WITH sha256_password BY 'your-strong-password';

GRANT CREATE DATABASE ON *.* TO renta;
GRANT CREATE TABLE, DROP TABLE, INSERT, SELECT, ALTER, OPTIMIZE ON renta_planner.* TO renta;
GRANT SELECT ON analytics.* TO renta;

Renta checks the CREATE DATABASE privilege when you save the connection, not on the first run. Without it, Renta does not store the connection and shows the privileges it expects.

Connect ClickHouse for reverse ETL

You need the hostname of the HTTP interface, the port, and the user you created in the previous section.

Open the source catalogStep 1

In the left sidebar, click Connections > Sources, and then click Add source. Under Source type, select Reverse ETL, and then click the ClickHouse tile.

Source catalog filtered by Reverse ETL with the ClickHouse tile highlighted

Enter the connection detailsStep 2

Fill in the form.

Source name.
The name of the connection in Renta.
Server hostname.
The hostname with the protocol, for example https://ch.example.com or http://10.0.0.5. Renta treats a hostname without a protocol as plain HTTP.
Database name.
The default database for unqualified table names in your queries. The table picker of the model wizard lists the tables of this database.
Port.
The port of the HTTP interface.
User and Password.
The credentials of the user you created.
Planner database.
The database for the working tables of each run. Leave the field empty to use renta_planner. A custom name can contain letters, digits, and underscores, and cannot start with a digit.

ClickHouse connection form with the server hostname and database name filled in

Save the connectionStep 3

Click Save. Renta opens a session, runs a test query, and creates the planner database if it does not exist. If any check fails, Renta does not store the connection and names the missing privilege in the error.

Bottom of the connection form with the empty Planner database field and the Save button

Verify the connectionStep 4

The connection appears in Connections > Sources with the Active status. You can now use it in data models and reverse ETL pipelines.

Sources list with the new ClickHouse connection in the Active state

Create a data model

A data model is the query a pipeline reads, together with its metadata: the column list, the unique key that identifies a row between runs, and the descriptions that AI agents use. One model can feed several pipelines.

Models live in Tools > Data models. The list shows the warehouse each model reads from, its scope, and its row count.

Data models list with the New model button and the scope counters

To create a model, click New model. The wizard walks you through the data source, the scope, the schema, and the metadata. A fifth step, measures, appears only when the scope includes AI agents.

Define the query

On the Data source step, select the connection and choose what to read from it.

Data source step with the ClickHouse connection selected, the SQL query option, and a query in the editor

Source.
The ClickHouse connection the model reads from. You cannot change it after the model is created.
Query type.
Select SQL query to write a statement yourself, or Table or view to sync an existing object as is.

If you select Table or view, the panel on the right lists the tables and views of the connection's database. Select one, and Renta syncs it column for column.

If you select SQL query, write a single SELECT statement in the ClickHouse dialect. Click Format to reformat it. Renta validates the statement before it sends the query to the server.

Rule	What Renta rejects
Single statement	Anything after the first statement. Remove the extra statements separated by semicolons.
Read-only	INSERT, ALTER, DELETE, CREATE, DROP, TRUNCATE, RENAME, and commands such as KILL, SYSTEM, or OPTIMIZE, including inside a CTE.
SELECT at the root	A statement whose root is not SELECT, UNION, or a subquery.
No output clauses	A trailing FORMAT clause and INTO OUTFILE. Renta wraps the model in a subquery, where neither is allowed.

Preview the query

Click Run preview. Renta runs the query and shows the first rows, the total row count, the run time, and the amount of data the server read.

Query preview with the returned rows and the row count, run time, and processed bytes above the table

A preview returns at most 100 rows, waits up to 60 seconds, and reads at most 10 GiB. A query that exceeds the read limit reports the limit instead of running. Add a WHERE clause to the query before you continue.

Set the scope

On the Scope step, choose who can use the model.

Scope step with the Reverse ETL only option selected

Scope	Who can use the model	Unique key
AI agents & Reverse ETL	AI agents and reverse ETL pipelines	Required
AI agents only	AI agents	Optional
Reverse ETL only	Reverse ETL pipelines	Required

A pipeline lists only models with the Reverse ETL only or AI agents & Reverse ETL scope. A model with the AI agents only scope does not appear in the Data model list.

Select the unique key

On the Schema step, Renta lists the columns the query returns with their type, a sample value, and a nullability flag. Hold the pointer over a type badge to see the original ClickHouse type.

Schema step with the customer_id column selected as the unique key

ClickHouse type	Type in Renta
Int8 to Int32, UInt8 to UInt32	int
Int64 and wider, UInt64 and wider	int64
Float32, Float64	float
Decimal of any precision	decimal
String, FixedString, UUID, Enum, IPv4, IPv6	text
Date, Date32	date
DateTime, DateTime64	datetime
Bool	bool
Array(T)	An array of the matching type
Map, Tuple, Nested, JSON, Variant, Dynamic	json

The Nullable and LowCardinality wrappers do not change the type. They only set the nullability flag.

In the Unique column, select the column that identifies a row between runs. The key is a single column, and its name can contain only letters, digits, and underscores. When you click Next step, Renta verifies the column on the server.

Check	Message
The column contains NULL	The count of nulls against the total row count. A unique key must not contain NULL.
The column repeats values	The number of duplicates and the number of distinct values.

Renta checks nulls first. A column that is both nullable and duplicated reports its nulls and says nothing about the duplicates until you fix the nulls. The check runs under the same read limit and timeout as the preview.

Add metadata

On the Metadata step, describe the model for your teammates and for AI agents.

Metadata step with the model name, the description, the Auto-generate with AI button, and the tool definition preview

Model name.
The name that pipelines and agent tools use to refer to the model. Use lowercase letters and underscores.
Description.
What the model represents and when to use it. Markdown is supported.
Column descriptions.
Optional, one per column. Click Auto-generate with AI to fill them in from the query and a sample of ten rows.

Auto-generate with AI sends the sample rows to the AI provider. Do not use it on a model that returns data you are not allowed to share.

The right pane shows the tool definition an agent receives, and the token counter shows how much of an agent's context the model takes.

Create the model

Click Create model. The model appears in the list with its source, scope, and row count.

Data models list filtered to the new model with the ClickHouse source and the Reverse ETL scope badge

To change the model later, open it and use the Query, Schema & key, Metadata, and Measures tabs.

Start a reverse ETL pipeline

You need a saved model with the Reverse ETL only or the AI agents & Reverse ETL scope.

Select ClickHouse as the sourceStep 1

In the left sidebar, click New pipeline. Switch the tab from ETL to Reverse ETL, select ClickHouse, and then click Next step.

Source step of the pipeline wizard with the Reverse ETL tab and the ClickHouse card selected

Select the connectionStep 2

Select the ClickHouse connection that holds your model, and then click Next step. The wizard continues with the destination, where the Data model list shows the models this connection exposes to reverse ETL.

Select your ClickHouse connection step with the connection card and the Next step button

The settings that follow belong to the destination. Each destination page describes its own field mapping and sync options.

What a run leaves in your cluster

A reverse ETL run reads the model and writes its working tables to the planner database on the same cluster.

Each run creates a plan table with the rows to send and a rejections table with the rows the destination refused. Both are MergeTree tables named after the pipeline and the run. Renta keeps the tables of the current run and the previous one, and drops anything older. After the first sync, the planner database holds two such tables. From the second sync on, it holds four.

Cleanup is best effort. If the user cannot drop tables, the run still succeeds, the old tables stay, and the planner database grows on every run. Keep the DROP TABLE privilege on the planner database, or clean it yourself.

A run reads the whole model on every sync. If the column names or types of the model change, the next run syncs everything again, because the previous plan can no longer be compared with the new one.

Limitations

The following limits apply to ClickHouse models and runs.

Single-column key.
The unique key is one column. Concatenate the columns in the query if a row is identified by several of them.
Statement budget.
Renta gives every statement of a run up to ten minutes. If the model takes longer to read, the run fails. Narrow the query with a filter or read from a materialized view.

What's next

Continue with the destination side of the pipeline or review the network requirements.

Reverse ETL destinations

Field mapping and sync options for each destination.

Renta IP addresses

Addresses to allow on the ClickHouse HTTP interface.

Google BigQuery reverse ETL

The same workflow for a BigQuery data model.

Frequently asked questions

Ready to get started?

Build your data pipeline today or get a personalized demo. Start free!

Need help?

Get expert support to ensure your project succeeds. We're here to help!

Feature requests?

Help shape our product! Share your ideas for new features and integrations.