Skip to main content
Contact us for help configuring ClickHouse native ExperimentationAccess to ClickHouse native Experimentation requires both Data Export and Experimentation. If you do not have access or need help getting started, contact your LaunchDarkly representative or start a Support ticket.
This topic explains how to set up the ClickHouse native Experimentation integration. ClickHouse native Experimentation lets you run experiments in LaunchDarkly using data directly from your ClickHouse service. LaunchDarkly experiments read and analyze metric events stored in ClickHouse, without requiring you to send event data through LaunchDarkly SDKs. Setting up the integration requires the following steps:
  1. Configure the LaunchDarkly integration
  2. Run the grant script in ClickHouse
  3. Test the connection and save the integration
  4. Verify the connection

​
Prerequisites

Before setting up ClickHouse native Experimentation, ensure that you have:
  • The ClickHouse Data Export integration set up in LaunchDarkly for the project and environment you use. Only environments with a ClickHouse Data Export destination are available when you create this integration.
  • A LaunchDarkly role of Owner or Admin, or a custom role that allows the following actions:
  • Access to the ClickHouse SQL console as a user who can create users and grant privileges.
  • Metric event data in ClickHouse that you want to use for Experimentation.
  • If your ClickHouse service restricts inbound connections by IP address, an IP access list that includes the following LaunchDarkly IP addresses:
    • 52.21.152.96/32
    • 52.200.35.24/32
    • 52.200.50.23/32
    • 54.144.218.89/32
    • 54.221.221.197/32
    • 34.236.6.43/32
Keep the IP address that ClickHouse Data Export requires in the same IP access list. For a full list of LaunchDarkly public IP addresses, read Public IP list.

​
About the ClickHouse databases

ClickHouse native Experimentation uses the following databases in your ClickHouse service:
  • Data Export database: The database that your ClickHouse Data Export destination writes to. LaunchDarkly reads the experiment data that Data Export sends there.
  • Metrics database: The database that holds the tables your metric data sources query. If you do not enter a metrics database, LaunchDarkly uses the Data Export database.
  • Results database: The database where LaunchDarkly writes experiment results. LaunchDarkly creates it the first time it connects, if it does not already exist.
LaunchDarkly connects to these databases as a ClickHouse experimentation user that is separate from the Data Export user. The grant script that LaunchDarkly generates creates this user and grants it access to all three databases.

​
ClickHouse naming conventions

When you select a project and environment, LaunchDarkly pre-fills default names for the ClickHouse experimentation user and the results database. You can keep these defaults or customize them:
  • User: ld_experimentation_user_<PROJKEY>__<ENVKEY>, where <PROJKEY> is your project key and <ENVKEY> is your environment key, in uppercase.
  • Results database: ld_experimentation_<projkey>__<envkey>, in lowercase.
In both names, LaunchDarkly replaces each character that is not a letter or a number with an underscore. LaunchDarkly shortens a long results database name in a way that keeps it unique to the environment. Use a different results database for each environment. This keeps each environment’s experiment results separate.

​
Step 1: Configure the LaunchDarkly integration

Configure the ClickHouse native Experimentation integration in LaunchDarkly. This integration is a second LaunchDarkly integration that looks similar to the ClickHouse Data Export integration, but requires a separate setup process. To set up the integration:
  1. Navigate to the Integrations page.
  2. Search for and select ClickHouse Native Experimentation.
  3. Click Add integration. The configuration page appears.
  4. Enter an integration Name.
  5. Choose the LaunchDarkly project and environment in Select project and environment. Only environments with a ClickHouse Data Export destination are available. You cannot change this after you save the integration. If the Data Export setup for the environment is not finished, LaunchDarkly displays a warning. Finish the Data Export setup before you continue.
  6. Review the “Data export destination.” LaunchDarkly selects the ClickHouse Data Export destination for the environment you chose.
  7. Review the “ClickHouse host” and “Native TLS port.” LaunchDarkly fills both from the Data Export destination. You cannot edit them.
  8. Review the Username. LaunchDarkly pre-fills a default name. To learn more, read ClickHouse naming conventions.
  9. Enter a Password for the ClickHouse experimentation user. Use only alphanumeric characters, dashes (-), and underscores (_). LaunchDarkly includes this password in the grant script.
  10. Review the Results database. LaunchDarkly pre-fills a default name.
  11. (Optional) Enter the Metrics database that holds your metric event tables, if they are not in the Data Export database. When this field is empty, LaunchDarkly reads metric events from the Data Export database.
  12. Copy the SQL from the “Grant script” field. LaunchDarkly generates this script from the values you entered.
Leave the configuration page open. You return to it after you run the grant script.

​
Step 2: Run the grant script in ClickHouse

Run the grant script before you save the integration. When you save, LaunchDarkly tests the connection as the ClickHouse experimentation user. The user and its privileges must already exist for this test to pass. To run the grant script:
  1. Open the SQL console for your ClickHouse service as a user who can create users and grant privileges.
  2. Paste the grant script you copied in Step 1.
  3. Run the script.
The grant script makes the following changes:
  • It creates the ClickHouse experimentation user with the password you entered. If the user already exists, the script updates its password.
  • It grants the user privileges to create the results database, as well as to create tables in, write to, and read from that database.
  • It grants the user read access to the Data Export database.
  • It grants the user read access to the metrics database, if you entered one that is different from the Data Export database.
You can run the script more than once. Each run produces the same result. The grant script gives the ClickHouse experimentation user read access only to the Data Export database and the metrics database. If a metric data source reads tables from another database, grant the experimentation user SELECT on that database as well. The grant script does not restrict the experimentation user to specific hosts. If your ClickHouse service restricts inbound connections by IP address, add the LaunchDarkly IP addresses listed in the Prerequisites to its IP access list.

​
Step 3: Test the connection and save the integration

Next, return to LaunchDarkly to save the integration:
  1. Return to the ClickHouse native Experimentation configuration page.
  2. After reading the Integration Terms and Conditions, check the I have read and agree to the Integration Terms and Conditions checkbox.
  3. Click Test connection and save. LaunchDarkly connects to ClickHouse as the experimentation user. If the connection succeeds, LaunchDarkly saves the integration and opens the integration’s page.
If the connection test fails, LaunchDarkly displays an error that starts with “ClickHouse connection test failed” and does not save the integration. To resolve the most common errors:
  • If the error says “authentication failed,” check the Username and Password. If you changed either value after you ran the grant script, copy the updated script and run it again.
  • If the error says “database not found,” check that the Data Export database and the metrics database you entered both exist in ClickHouse.
  • If the error says “TLS handshake failed,” confirm that your ClickHouse service accepts native Transport Layer Security (TLS) connections on the port that the Data Export destination uses.
  • If the error says “could not reach host,” check your ClickHouse IP access list. It must include the LaunchDarkly IP addresses listed in the Prerequisites.

​
Step 4: Verify the connection

Finally, verify the connection. On the integration’s page, check “Connection status” in the details panel. The status is one of the following:
  • Connected: LaunchDarkly can connect to ClickHouse and has the privileges it needs.
  • Pending: LaunchDarkly has not finished setting up the results database yet.
  • Degraded: LaunchDarkly connected to ClickHouse earlier, but its most recent attempt failed.
  • Disconnected: LaunchDarkly could not connect to ClickHouse.
  • Not connected: LaunchDarkly has no connection information for the integration yet.
If the status is “Degraded” or “Disconnected,” confirm that the ClickHouse experimentation user still has the privileges from the grant script, and that your IP access list still includes the LaunchDarkly IP addresses. The details panel also shows “Results last updated” with the date and time LaunchDarkly last wrote experiment results to ClickHouse.

​
Edit an existing integration

After you save the integration, the connection fields are read-only. You can change the integration Name and Status. LaunchDarkly saves each change as you make it. You can also update the maintainer and review connection health from the details panel. You cannot change the project, environment, host, port, username, password, results database, or metrics database. To change any of these values, delete the integration and create a new one. To delete the integration, click Delete integration, type DELETE to confirm, and click Delete.

​
Next steps

Read the following topics to understand how to create an experiment using ClickHouse native metrics and how to analyze the experiment results: The results page for a warehouse native experiment displays the date and time the results were last updated from ClickHouse. Experiment data reaches ClickHouse through the hourly Data Export job. Because of this, the first results can take up to three hours to appear after an experiment starts receiving traffic. After that, LaunchDarkly refreshes results every 15 minutes.