Connect with a database client

You can browse and query the data lake from DBeaver or DataGrip using the ClickHouse JDBC driver. The connection goes through the nullplatform API proxy, so the same authentication, authorization, and tenant isolation rules apply.

Connection parameters

Every database client needs the same set of parameters:

Parameter	Value
JDBC URL	jdbc:clickhouse://api.nullplatform.com:443/data/lake/query/customers_lake?ssl=true&compress=0
Host	api.nullplatform.com
Port	443 (HTTPS)
Database	customers_lake
SSL	Required (ssl=true)
Authentication	Driver property: bearer_token = <token>

The token is a short-lived JWT. If you receive a 401 Unauthorized error, the token has expired and you need to obtain a new one. See API keys for how to generate tokens.

DBeaver

1. Open DBeaver and go to Database > New Database Connection.

2. Search for ClickHouse in the driver list and select it. If prompted, let DBeaver download the JDBC driver automatically.

3. In the Main tab, enable manual URL mode and enter the JDBC URL:

   jdbc:clickhouse://api.nullplatform.com:443/data/lake/query/customers_lake?ssl=true&compress=0

   Leave Username and Password empty.

4. Switch to the Driver Properties tab and add:

   Property Name	Value
   bearer_token	<your_nullplatform_access_token>

5. Click Test Connection to verify, then Finish.

note

The compress=0 parameter is required. Without it, the JDBC driver attempts to negotiate compression with the HTTP proxy, which causes connection errors.

DataGrip

warning

DataGrip ships with ClickHouse driver version 0.9.4, which is not compatible with this connection. You need version 0.9.7 or higher. Follow the steps below to install a custom driver before configuring the connection.

Step 1: Download the driver

1. Open the clickhouse-java repository on GitHub.
2. Go to the Releases section and open the latest release (currently v0.9.8).
3. Download the file ending in -all-dependencies.jar.

Step 2: Install the custom driver in DataGrip

1. Open Data Sources by pressing ⌘+; on macOS or going to File > Data Sources.
2. Go to the Drivers tab.
3. Select the ClickHouse driver from the list. If no ClickHouse driver exists, click + to create a new one.
4. If you are editing an existing driver, first remove the outdated driver file from the Driver Files list.
5. In the General tab, go to Driver Files, click +, and choose Custom JARs…. Select the -all-dependencies.jar file you downloaded.
6. In the Class field, set or confirm the value:

   com.clickhouse.jdbc.ClickHouseDriver

7. Click OK to save the driver.

warning

Verify that the Class field is set to com.clickhouse.jdbc.ClickHouseDriver. Selecting an incorrect class will cause the connection to fail without a clear error message.

After saving, restart DataGrip so the new driver takes effect before continuing.

Step 3: Configure the connection

1. Click New Data Source and select the ClickHouse driver you just configured.

2. In the General tab, enable manual URL editing and paste:

   jdbc:clickhouse://api.nullplatform.com:443/data/lake/query/customers_lake?ssl=true&compress=0

3. Leave Username and Password empty.

4. Go to the Advanced tab and open the Properties section. Add the following properties:

   Name	Value
   bearer_token	<your_nullplatform_access_token>
   ignore_unknown_config_key	true

5. Click Test Connection to verify, then OK.

note

ignore_unknown_config_key = true is required because DataGrip validates driver properties strictly and would otherwise reject the bearer_token property. The compress=0 parameter in the URL prevents the driver from attempting compression negotiation with the HTTP proxy, which causes connection errors.

Other JDBC-compatible tools

Any tool that supports a JDBC connection string (BI dashboards, SQL editors) can connect using this URL:

jdbc:clickhouse://api.nullplatform.com:443/data/lake/query/customers_lake?ssl=true&compress=0

Pass authentication as a connection property, not in the URL. Set the bearer_token property to your Nullplatform access token.

Next steps

• Table reference: browse all tables and their column schemas.
• Data lake overview: query syntax, restrictions, access control, and rate limits.