Supported databases

Sequin works with any PostgreSQL database version 12 or higher that supports Logical Replication.

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:

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

Please create a strong password for Sequin’s database user. You can generate a secure password using the following command:

openssl rand -base64 24

Enabling logical replication

Sequin requires logical replication to be enabled on your database. You can check if it’s enabled:

show wal_level;

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 set wal_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.

As a best practice, create the publication before creating the replication slot. Creating the slot first can create a race condition that can lead to data loss.

Creating a publication

The simplest publication includes all tables:

create publication sequin_publication for all tables;

To specify a subset of tables, use the following command:

create publication sequin_publication for table table1, table2, table3;

Or all tables in a schema:

create publication sequin_publication for all tables in schema public;

Working with partitioned tables

When using partitioned tables, you have two options to ensure Sequin captures changes correctly:

  • Enable publish_via_partition_root:

    -- Create publication for a partitioned table
    create publication sequin_publication for table orders 
    with (publish_via_partition_root = true);
    
    -- Or modify an existing publication
    alter publication sequin_publication set (publish_via_partition_root = true);
    
  • Add each partition table explicitly to the publication:

    create publication sequin_publication for table
        orders_2024_q1,
        orders_2024_q2,
        orders_2024_q3,
        orders_2024_q4;
    

Choose the first option if you’re dynamically creating partitions. The second option is fine if you have a fixed set of partitions.

If you created your publication using for all tables or for all tables in schema, partitioned tables will work automatically without additional configuration.

Modifying Publications

To add or remove tables from a publication, use the ALTER PUBLICATION statement:

-- Drop all tables
alter publication sequin_publication drop all tables;
-- Add tables
alter publication sequin_publication add table table1, table2, table3;
-- Drop tables
alter publication sequin_publication drop table table1, table2, table3;
-- Add all tables in a schema
alter publication sequin_publication add all tables in schema my_schema;
-- Drop all tables in a schema
alter publication sequin_publication drop all tables in schema my_schema;

Deleting a Publication

You can delete a publication using the DROP PUBLICATION statement:

drop publication sequin_publication;

Replication slots

Replication slots ensure that PostgreSQL retains WAL (Write-Ahead Log) data needed by Sequin.

Creating a Replication Slot

create replication slot sequin_slot;

Deleting a Replication Slot

drop replication slot sequin_slot;

Best practices

As a best practice, create the publication before creating the replication slot. Creating the slot first can create a race condition that can lead to data loss.

Monitor slot lag Excessive lag in a replication slot can cause WAL buildup and disk space issues. Monitor lag with:

select * from pg_replication_slots;

Clean up unused slots: Delete slots that are no longer in use to prevent WAL retention:

select pg_drop_replication_slot('sequin_slot');

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.

Was this page helpful?