Connecting to a TimescaleDB database

This guide provides step-by-step instructions to connect your TimescaleDB 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:

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:

show wal_level;

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

Enabling replication requires a restart of your database.

Configure WAL level

Connect to your TimescaleDB container and edit the PostgreSQL configuration:

# 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

You can also find the location of your postgresql.conf file by running the SQL command show config_file;.

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:

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

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

-- 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:

openssl rand -base64 32

Connect Sequin to your TimescaleDB database

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

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

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:

-- 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;

When using TimescaleDB, there are important considerations for publications:

Using FOR ALL TABLES is the most reliable approach, though it requires more resources
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)
Avoid using FOR TABLE table_name with TimescaleDB hypertables, as this can cause replication to stop when new chunks are created

For either approach, you can further limit which tables are replicated with table filtering in Sequin instead.

Create a replication slot

Next, create a replication slot to capture changes from the publication:

select pg_create_logical_replication_slot('sequin_slot', 'pgoutput');

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”.

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:

Stream to Webhooks

Send database changes to your HTTP endpoints to trigger workflows and keep services in sync

Stream to Redis Streams

Stream changes to Redis Streams for real-time data processing and caching

Stream to Kafka

Publish database changes to Kafka topics for event streaming and processing

Stream to SQS

Send changes to AWS SQS queues to trigger Lambda functions and other AWS services

Get started

Sink setup guides

How-to guides

Concepts

Reference

Database setup guides

Tutorials

Connecting to a TimescaleDB database

Setting up TimescaleDB

Enable logical replication

Configure WAL level

Provision a Postgres user for Sequin

Connect Sequin to your TimescaleDB database

Enter connection details in Sequin

Create a publication

Create a replication slot

Enter the replication slot details in Sequin

Create a sink

Stream to Webhooks

Stream to Redis Streams

Stream to Kafka

Stream to SQS

​Setting up TimescaleDB

​Enable logical replication

Configure WAL level

​Provision a Postgres user for Sequin

​Connect Sequin to your TimescaleDB database

Enter connection details in Sequin

Create a publication

Create a replication slot

Enter the replication slot details in Sequin

​Create a sink

Stream to Webhooks

Stream to Redis Streams

Stream to Kafka

Stream to SQS

Setting up TimescaleDB

Enable logical replication

Provision a Postgres user for Sequin

Connect Sequin to your TimescaleDB database

Create a sink