---
metadata:
  - name: generator
    content: Diplodoc Platform v5.63.0
alternate:
  - en/cookbook/connections
  - ru/cookbook/connections
  - href: en/cookbook/connections.md
    type: text/markdown
    title: Markdown version
csp:
  - script-src:
      - https://mc.yandex.ru
    img-src:
      - https://mc.yandex.ru
    connect-src:
      - https://mc.yandex.ru
      - wss://mc.yandex.ru
    child-src:
      - 'blob:'
      - https://mc.yandex.ru
    frame-src:
      - 'blob:'
      - https://mc.yandex.ru
    frame-ancestors:
      - 'blob:'
      - https://mc.yandex.ru
canonical: en/cookbook/connections.html
vcsPath: en/cookbook/connections.md
---
# Connecting data

## Key principle: network accessibility

Before you create a connection in the DataLens UI, always consider this question: _Can the DataLens server access the database server over the network?_

Network restrictions account for 90% of connection issues:

* **Firewall**: Blocks the port at the database server or network equipment.

* **Security groups**: In cloud environments, security group rules deny incoming traffic from DataLens VMs.

* **Incorrect host or port**: There is a typo in the connection credentials.

### How to troubleshoot issues

Use the `control-api` pod to check accessibility with `curl` or `telnet`:

```shell
# Connect to the `control_api` pod
./init.sh --kubectl exec -it <control-api-pod-name> -- /bin/bash

# Check access to your host and port
curl -v telnet://my-postgres-db.internal:5432
```

Check pod logs for information on the **Connection timeout**. To do this, run the following command:

```shell
 ./init.sh --stern --tail 100 --no-follow pod/<control-api-pod-name>
```

## Creating a basic connection

This is a basic use case. To create a connection, the user needs the `Editor` or `Admin` role.


1. In the DataLens UI, go to **Connections** and click **Create connection**.

1. Select a source type, e.g., **PostgreSQL**.

1. Fill in these fields: host name, port, database name, username, and password.

1. Click **Check connection**. If successful, save the configuration.

Passwords and tokens you enter in the above fields are encrypted using `CONTROL_API_CRYPTO_KEY`, one of the two cryptographic key types used in DataLens. This key is used to encrypt sensitive data (passwords or tokens) in connection fields. It is generated and saved automatically.

## Connecting to a database with TLS encryption

In corporate environments, TLS is often used for secure transfer of data. If a database uses a certificate signed by an internal certificate authority (CA), DataLens will not trust it by default.

To resolve this, add the root CA certificate to the DataLens trust store. You need to do this at the Kubernetes configuration level by updating `values.yaml` to add the CA to the system trust store.

{% note info %}

This is a task for the administrator, not users.

{% endnote %}

Once trust is configured, you can enable **TLS** in the connection settings and specify the relevant properties.

## Configuring and using file connections

To work with files, first enable the `files` feature in `values.yaml`.

Workflow for users:

1. Create a **File**-type connection.

1. Upload a CSV or XLS file.

1. This file is saved to the internal S3 storage (MinIO), and then its contents is pushed to ClickHouse.

1. DataLens automatically creates a dataset over the resulting ClickHouse table.

{% note info %}

The task of the administrator is to make sure all components (S3, ClickHouse, and Valkey) are running correctly with enough available storage.

{% endnote %}

## Connector features

### JSON API

It enables connections to data sources which send JSON over HTTP. The connector is used together with `Chart Editor` to rapidly build charts from software sources.

{% note info %}

To learn more about using API connectors, see [this article](../charts/editor/quickstart/from-api-connector.md).

{% endnote %}

### Trino (formerly PrestoSQL)

Not a database but a federated query engine, Trino enables you to run a single SQL query to data residing in different systems, e.g., join PostgreSQL and S3 data in one query. DataLens connects to Trino, and Trino, to the end sources.

{% note info %}

To learn more about using Trino connectors, see [this article](../operations/connection/create-trino.md).

{% endnote %}

## Use case

A user reports their connection to Greenplum fails with the **Connection timed out** error. What is your first troubleshooting step?

* Restart the `control-api` pod
* Check the user's password
* Check network access from the `control-api` pod to the Greenplum host and port
* Ask the user to check their SQL query

{% cut "Find out the answer" %}

* Restart the `data-api` pod

  Restarting may help if the pod is not responding, but this is not your first step. You need to find out the cause of the issue first.

* Check the user's password

  An incorrect password will cause the **Authentication failed** error, not **Connection timed out**.

* Check network access from the `data-api` pod to the Greenplum host and port

  Correct. **Connection timed out** is a telltale sign of a network issue caused by firewall or security group settings.

* Ask the user to check their SQL query

  Creating a connection does not yet involve running SQL queries. This is a lower-level issue.

{% endcut %}

## Hands-on task: Creating a file-based connection

1. Ensure the `files` feature is enabled in your `values.yaml`:

   ```yaml
   features:
     files:
       enabled: true
   ```

   If not, enable it and apply this configuration: `./init.sh --values <your_file>.yaml`.

1. Create a simple `sales.csv` file on your local computer:

   ```plaintext
   City,Sales
   Moscow,1500
  Paris,1200
   London,1800
   ```

1. In the DataLens UI, create a new **File** connection.

1. Upload `sales.csv` and wait for it to get processed.

1. Upon successful upload, you see a data preview window. Click **Create** in the top right corner.

## Summary

You have reviewed one of the most common administrator tasks: ensuring data connectivity. Now you can create basic and file-based connections and configure TLS properly.