Databases
Reference for connecting databases to Sequin
Supported databases
Sequin works with any PostgreSQL database version 14 or higher that supports Logical Replication.
Sequin soft-supports PostgresSQL 12 and 13 with some limitations.
You can find guides for connecting to local and hosted databases in the connect postgres guide.
Database connection details
Sequin requires the following details to connect to your database:
- Host: The hostname of your database
- Port: The port number of your database
- Database: The name of your database
- Username: The username of a database user with the necessary permissions
- Password: The password for the database user
You can also enable or disable SSL mode for your database connection.
Tunneling to your database
Use the Sequin CLI to create a secure tunnel between Sequin Cloud and a database running on your local machine.
If your database is hosted by a cloud provider and requires a VPN to connect, Sequin can create a secure tunnel through a bastion host. Please contact support to enable this.
Database user permissions
We recommend creating a dedicated database user for Sequin. Grant that user 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).
You can create a user with those permissions with the following commands:
Please create a strong password for Sequin’s database user. You can generate a secure password using the following command:
Enabling logical replication
Sequin requires logical replication to be enabled on your database. You can check if it’s enabled:
If the value isn’t logical
, you’ll need to enable it. The process for enabling logical replication varies by provider. You can find more information in the following guides:
- Standard PostgreSQL: Modify
postgresql.conf
to setwal_level = logical
- AWS RDS: Create a parameter group with
rds.logical_replication = 1
- Google Cloud SQL: Enable through the console or API
- Azure: Configure through server parameters
- Neon: Enable through project settings
- Supabase: Enabled by default
Enabling logical replication often requires a database restart.
Publications
Publications identify which tables to track for changes.
Create the publication before creating the replication slot. If you don’t, the publication and slot combination may be invalid, and Sequin will fail to connect to your database.
Creating a publication
The simplest publication includes all tables:
To specify a subset of tables, use the following command:
Or all tables in a schema:
Working with partitioned tables
When using partitioned tables, you must ensure publish_via_partition_root
is set to true
to ensure Sequin captures changes correctly. This means changes to partition tables are associated with the root table:
You can check this setting by running, for example:
Modifying Publications
To add or remove tables from a publication, use the ALTER PUBLICATION
statement:
Deleting a Publication
You can delete a publication using the DROP PUBLICATION
statement:
Replication slots
Replication slots ensure that PostgreSQL retains WAL (Write-Ahead Log) data needed by Sequin.
Creating a Replication Slot
Deleting a Replication Slot
Best practices
Create the publication before creating the replication slot. If you don’t, the publication and slot combination may be invalid, and Sequin will fail to connect to your database.
Monitor slot lag Excessive lag in a replication slot can cause WAL buildup and disk space issues. Monitor lag with:
Clean up unused slots: Delete slots that are no longer in use to prevent WAL retention:
Replica identity
Sequin uses REPLICA IDENTITY
for two purposes:
- To determine the old values of an updated row. These values are used to create the
changes
field for change messages. - To load unchanged TOAST columns for updates of both change and row sink consumers.
Changes
With REPLICA IDENTITY
set to FULL
, Sequin receives new and old values for all columns during updates. For columns that have changed values, Sequin includes the old values in the changes
field.
TOAST columns
PostgreSQL uses TOAST (The Oversized-Attribute Storage Technique) to store large column values. Here’s how Sequin handles TOAST columns:
- TOAST columns are always included for INSERT operations
- For UPDATE operations:
- Changed TOAST columns are included in rows and changes
- Unchanged TOAST columns will appear as
"unchanged_toast"
unlessREPLICA IDENTITY
is set toFULL
- If
REPLICA IDENTITY
isFULL
, all TOAST columns are included regardless of changes
- For DELETE operations:
- TOAST columns are included only if
REPLICA IDENTITY
is set toFULL
- TOAST columns are included only if
This behavior applies to both changes and rows in Sequin.
To set REPLICA IDENTITY
to FULL
for a table:
PostgreSQL 12 and 13
Sequin relies on the pg_logical_emit_message
function for heartbeat messages and backfills. This function is included automatically in Postgres 14 and later.
For Postgres 12 and 13, we support a table-based replacement: public.sequin_logical_messages
.
You can create this table in your database with the following SQL:
This table is used by Sequin to replace the pg_logical_emit_message
function. It experiences very low write throughput and will not accumulate significant storage or IOPS.
This table must be included in your publication so that Sequin receives messages written to it. If you have created your publication with ALL TABLES
, then this is done automatically. Otherwise, you can add the table to your publication with the following SQL:
Backfills
For Postgres 12 and 13, we do not support backfills, which rely heavily on the pg_logical_emit_message
function.
If you require backfills, we recommend upgrading to Postgres 14 or later. If this is not an option, please contact support to discuss alternative approaches.
Monitoring
Sequin will run health checks against your database connection automatically. You can view the status of the connection at any time in your database’s “Overview” page.