> ## Documentation Index
> Fetch the complete documentation index at: https://sequinstream.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting to a TimescaleDB database

> Power time-series applications with real-time change capture. Learn how to connect TimescaleDB to Sequin.

This guide provides step-by-step instructions to connect your [TimescaleDB](https://www.timescale.com/) database to Sequin. TimescaleDB is an open-source database built on Postgres that's optimized for time-series data.

## Setting up TimescaleDB

If you don't have a TimescaleDB instance yet, you can set one up using Docker:

```bash theme={null}
docker run -d --name timescaledb -p 5432:5432 \
-e POSTGRES_PASSWORD=postgres \
timescale/timescaledb-ha:pg16
```

## Enable logical replication

To determine if logical replication is already enabled for your TimescaleDB instance, you can run the following SQL command:

```sql theme={null}
show wal_level;
```

This command should return `logical`. If it doesn't, you'll need to enable it by setting `wal_level` to `logical`.

<Warning>Enabling replication requires a restart of your database.</Warning>

<Steps titleSize="h3">
  <Step title="Configure WAL level">
    Connect to your TimescaleDB container and edit the PostgreSQL configuration:

    ```bash theme={null}
    # Connect to the container
    docker exec -it timescaledb bash

    # Edit postgresql.conf
    echo "wal_level = logical" >> /home/postgres/pgdata/data/postgresql.conf

    # Exit the container
    exit

    # Restart the container for changes to take effect
    docker restart timescaledb
    ```
  </Step>
</Steps>

<Tip>
  You can also find the location of your `postgresql.conf` file by running the SQL command `show config_file;`.
</Tip>

## Provision a Postgres user for Sequin

When in development, it's probably fine to supply Sequin with an existing user.

However, when in production, you should create a dedicated user for Sequin. The user needs the following permissions:

1. `connect` permission on the database.
2. `select` permission on all the tables you want to connect to Sequin.
3. `replication` permission to read from replication slots.

Here's how to create a dedicated user with the minimum required permissions:

```sql theme={null}
-- Create user with a secure password
create user sequin_user with password 'REPLACE_WITH_SECURE_PASSWORD';

-- Grant connect permission
grant connect on database your_database to sequin_user;

-- Grant select permission on tables you want to replicate
grant select on table table1, table2, table3 to sequin_user;
-- OR grant select on all tables in a schema
grant select on all tables in schema public to sequin_user;

-- Grant replication permission
alter user sequin_user with replication;
```

To generate a secure password, if you have OpenSSL installed, you can use the following command:

```bash theme={null}
openssl rand -base64 32
```

## Connect Sequin to your TimescaleDB database

After enabling logical replication, you'll now connect to your database in Sequin:

<Steps titleSize="h3">
  <Step title="Enter connection details in Sequin">
    In the Sequin Console, click on the "Connect Database" button and enter the credentials for your TimescaleDB database:

    * Host: Your TimescaleDB host (e.g., `localhost` or your Docker machine IP)
    * Port: 5432 (default Postgres port)
    * Database: Your database name
    * Username: The sequin database user you created earlier
    * Password: The password for your sequin database user
  </Step>

  <Step title="Create a publication">
    Connect to your database using the SQL client of your choice and execute one of the following SQL queries to create a publication:

    ```sql theme={null}
    -- Option 1: Recommended approach - capture all tables
    CREATE PUBLICATION sequin_pub FOR ALL TABLES;

    -- Option 2: If you need to capture specific schemas (includes TimescaleDB internal tables)
    CREATE PUBLICATION sequin_pub FOR TABLES IN SCHEMA public, _timescaledb_internal;
    ```

    <Warning>
      When using TimescaleDB, there are important considerations for publications:

      1. Using `FOR ALL TABLES` is the most reliable approach, though it requires more resources
      2. If you need to publish specific tables, you must include both:
         * The schema containing your base tables (usually `public`)
         * The TimescaleDB internal schema (`_timescaledb_internal`)
      3. Avoid using `FOR TABLE table_name` with TimescaleDB hypertables, as this can cause replication to stop when new chunks are created
    </Warning>

    <Note>
      For either approach, you can further limit which tables are replicated with [table filtering in Sequin](/reference/sinks/overview#source-tables) instead.
    </Note>
  </Step>

  <Step title="Create a replication slot">
    Next, create a replication slot to capture changes from the publication:

    ```sql theme={null}
    select pg_create_logical_replication_slot('sequin_slot', 'pgoutput');
    ```
  </Step>

  <Step title="Enter the replication slot details in Sequin">
    Back in the Sequin Console, enter the name of the replication slot (e.g. `sequin_slot`) and publication (e.g. `sequin_pub`) you just created. Then, name your database and click "Create Database".
  </Step>
</Steps>

## Create a sink

With your TimescaleDB database connected to Sequin, you are ready to create a sink. Follow one of our guides below to get started:

<CardGroup cols={2}>
  <Card title="Stream to Webhooks" icon="webhook" href="/how-to/stream-postgres-to-a-webhook-endpoint">
    Send database changes to your HTTP endpoints to trigger workflows and keep services in sync
  </Card>

  <Card title="Stream to Redis Streams" icon="layer-group" href="/how-to/stream-postgres-to-redis-stream">
    Stream changes to Redis Streams for real-time data processing and caching
  </Card>

  <Card title="Stream to Kafka" icon="code-branch" href="/how-to/stream-postgres-to-kafka">
    Publish database changes to Kafka topics for event streaming and processing
  </Card>

  <Card title="Stream to SQS" icon="aws" href="/how-to/stream-postgres-to-sqs">
    Send changes to AWS SQS queues to trigger Lambda functions and other AWS services
  </Card>
</CardGroup>