---
title: Connections
meta:
   description: Connections store the credentials and settings Tinybird uses to ingest data from external services.
---

# Connections

Connections store the credentials and settings Tinybird uses to connect to external services such as Kafka, Amazon S3, and Google Cloud Storage. Data Sources reference connections to stream or batch import data into Tinybird.

Connections are managed by Tinybird and are deployed as part of your project. They handle the integration details for:

- Authentication and secure connections
- Schema detection and mapping
- Incremental updates and change data capture
- Error handling and monitoring
- Scheduling and orchestration

Connections are independent from Data Sources. Deleting a Data Source that uses a connection does not delete the connection, so you can reuse the same connection in other Data Sources.

## Define a connection

You can define connections with `.connection` files, in `.ts` files with the TypeScript SDK, or in `.py` files with the Python SDK. Use `tb_secret()` in datafiles, or `secret()` in the SDKs, to avoid storing credentials in plain text. See [Templating language](/forward/core-concepts/templating-language#secrets) for how secrets are rendered across environments.

{% tabs initial="Tinybird CLI" %}
{% tab label="Tinybird CLI" %}

```tb {% title="connections/events_kafka.connection" %}
TYPE kafka
KAFKA_BOOTSTRAP_SERVERS {{ tb_secret("KAFKA_BOOTSTRAP_SERVERS", "localhost:9092") }}
KAFKA_SECURITY_PROTOCOL SASL_SSL
KAFKA_SASL_MECHANISM PLAIN
KAFKA_KEY {{ tb_secret("KAFKA_KEY") }}
KAFKA_SECRET {{ tb_secret("KAFKA_SECRET") }}
```

{% /tab %}

{% tab label="TypeScript SDK" %}

```ts {% title="tinybird.ts" %}
import { defineKafkaConnection, secret } from "@tinybirdco/sdk";

export const eventsKafka = defineKafkaConnection("events_kafka", {
  bootstrapServers: "kafka.example.com:9092",
  securityProtocol: "SASL_SSL",
  saslMechanism: "PLAIN",
  key: secret("KAFKA_KEY"),
  secret: secret("KAFKA_SECRET"),
});
```

{% /tab %}

{% tab label="Python SDK" %}

```python {% title="tinybird.py" %}
from tinybird_sdk import define_kafka_connection, secret

events_kafka = define_kafka_connection("events_kafka", {
    "bootstrap_servers": "kafka.example.com:9092",
    "security_protocol": "SASL_SSL",
    "sasl_mechanism": "PLAIN",
    "key": secret("KAFKA_KEY"),
    "secret": secret("KAFKA_SECRET"),
})
```

{% /tab %}
{% /tabs %}

See all syntax options in the [Connection files reference](/forward/dev-reference/datafiles/connection-files), [TypeScript SDK reference](/forward/dev-reference/typescript-sdk-resources#connections), and [Python SDK reference](/forward/dev-reference/python-sdk-resources#connections).

## Create a connection

To create a connection, add the `.connection` file to the project, or the connection definition to `.ts` or `.py` files and deploy.

For datafile projects, you can scaffold a new connection with [`tb connection create`](/forward/dev-reference/commands/tb-connection):

```shell
tb connection create <type>
```

Where `<type>` is one of the available connection types:

- `kafka` - Create a [Kafka connection](/forward/ingest-data/connectors/kafka)
- `s3` - Create an [Amazon S3 connection](/forward/ingest-data/connectors/s3)
- `gcs` - Create a [Google Cloud Storage connection](/forward/ingest-data/connectors/gcs)

The CLI will guide you through the configuration process, prompting you for the required credentials and settings. Once created, the connection will be saved as a `.connection` file in your project's `connections/` folder.

To convert existing `.connection` files to SDK definitions, use [`tinybird migrate`](/forward/dev-reference/commands/typescript-sdk-cli#tinybird-migrate) for TypeScript projects or [`tinybird migrate`](/forward/dev-reference/commands/python-sdk-cli#tinybird-migrate) for Python projects.

## Use a connection in a Data Source

After you define a connection, reference it from a Data Source. Use `KAFKA_CONNECTION_NAME`, `S3_CONNECTION_NAME`, or `GCS_CONNECTION_NAME` in `.datasource` files, or pass the connection object in the TypeScript and Python SDKs.

{% tabs initial="Tinybird CLI" %}
{% tab label="Tinybird CLI" %}

```tb {% title="datasources/events.datasource" %}
SCHEMA >
    `timestamp` DateTime `json:$.timestamp`,
    `payload` String `json:$.payload`

ENGINE "MergeTree"
ENGINE_SORTING_KEY "timestamp"

KAFKA_CONNECTION_NAME events_kafka
KAFKA_TOPIC events
KAFKA_GROUP_ID {{ tb_secret("KAFKA_GROUP_ID") }}
```

{% /tab %}

{% tab label="TypeScript SDK" %}

```ts {% title="tinybird.ts" %}
import { defineDatasource, engine, t, secret } from "@tinybirdco/sdk";

export const events = defineDatasource("events", {
  schema: {
    timestamp: t.dateTime(),
    payload: t.string(),
  },
  engine: engine.mergeTree({
    sortingKey: ["timestamp"],
  }),
  kafka: {
    connection: eventsKafka,
    topic: "events",
    groupId: secret("KAFKA_GROUP_ID"),
  },
});
```

{% /tab %}

{% tab label="Python SDK" %}

```python {% title="tinybird.py" %}
from tinybird_sdk import define_datasource, engine, secret, t

events = define_datasource("events", {
    "schema": {
        "timestamp": t.date_time(),
        "payload": t.string(),
    },
    "engine": engine.merge_tree({"sorting_key": ["timestamp"]}),
    "kafka": {
        "connection": events_kafka,
        "topic": "events",
        "group_id": secret("KAFKA_GROUP_ID"),
    },
})
```

{% /tab %}
{% /tabs %}

## Delete a connection

To delete a connection, remove its `.connection` file or SDK definition, make sure no Data Sources reference it, and deploy your changes.

{% tabs initial="Tinybird CLI" %}
{% tab label="Tinybird CLI" %}

```shell
tb deploy --allow-destructive-operations
```

{% /tab %}

{% tab label="TypeScript SDK" %}

```shell
tinybird deploy --allow-destructive-operations
```

{% /tab %}

{% tab label="Python SDK" %}

```shell
tinybird deploy
```

{% /tab %}
{% /tabs %}

The Tinybird CLI and TypeScript SDK CLI require the `--allow-destructive-operations` flag to confirm the removal. The Python SDK CLI doesn't currently support that flag.

{% callout type="warning" %}
Before deleting a connection, make sure no Data Sources use it. If a Data Source references the connection, the deployment fails. Remove the connection reference from all Data Sources first.
{% /callout %}

## Available connection types

Tinybird supports the following connection types:

- [Kafka](/forward/ingest-data/connectors/kafka)
- [Amazon S3](/forward/ingest-data/connectors/s3)
- [Google Cloud Storage](/forward/ingest-data/connectors/gcs)