🪞🐘 Support for Postgres Replicas (#1414)

Co-authored-by: abc3 <sts@abc3.dev>
Co-authored-by: Anthony Accomazzo <accomazz@gmail.com>

Author: 3 people

assets/svelte/databases/Form.svelte

@@ -58,6 +58,15 @@
     publication_name: string;
     slot_name: string;
     useLocalTunnel: boolean;
+    is_replica: boolean;
+    primary: {
+      ssl: boolean;
+      database: string;
+      hostname: string;
+      port: number;
+      username: string;
+      password: string;
+    };
   };
   export let errors: Record<string, any> = {};
   export let submitError: string | null = null;
@@ -69,7 +78,7 @@
   export let showPgVersionWarning: boolean = false;
   export let selfHosted: boolean = false;
 
-  let form = { ...database, ssl: true }; // Set default SSL to true
+  let form = { ...database };
 
   const isEdit = !!form.id;
 
@@ -490,6 +499,133 @@ sequin tunnel --ports=[your-local-port]:${form.name}`;
         {#if databaseErrors.ssl}
           <p class="text-destructive text-sm">{databaseErrors.ssl}</p>
         {/if}
+
+        <div class="flex items-center gap-2">
+          <Switch id="is_replica" bind:checked={form.is_replica} />
+          <Label for="is_replica" class="flex items-center">
+            Replica
+            <Tooltip.Root openDelay={200}>
+              <Tooltip.Trigger>
+                <HelpCircle class="inline-block h-4 w-4 text-gray-400 ml-1" />
+              </Tooltip.Trigger>
+              <Tooltip.Content class="max-w-xs">
+                <p class="text-sm text-gray-500">
+                  <b>Replica</b>
+                  <br />
+                  When connecting a replica to Sequin, Sequin also needs to connect
+                  to the primary database.
+                  <a
+                    href="https://docs.sequinstream.com/reference/databases#using-sequin-with-a-replica"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    class="inline-flex items-center text-link hover:underline"
+                  >
+                    Learn more
+                    <ExternalLinkIcon class="w-3 h-3 ml-1" />
+                  </a>
+                </p>
+              </Tooltip.Content>
+            </Tooltip.Root>
+          </Label>
+        </div>
+
+        {#if form.is_replica}
+          <div transition:slide class="space-y-4 mt-2 bg-muted p-4 rounded-md">
+            <div class="space-y-4">
+              <div class="space-y-2">
+                <Label for="primary_hostname">Primary host</Label>
+                <Input
+                  type="text"
+                  id="primary_hostname"
+                  placeholder="example.com"
+                  bind:value={form.primary.hostname}
+                />
+                {#if databaseErrors.primary?.hostname}
+                  <p class="text-destructive text-sm">
+                    {databaseErrors.primary?.hostname}
+                  </p>
+                {/if}
+              </div>
+
+              <div class="space-y-2">
+                <Label for="primary_port">Primary port</Label>
+                <Input
+                  type="number"
+                  id="primary_port"
+                  placeholder="5432"
+                  bind:value={form.primary.port}
+                />
+                {#if databaseErrors.primary?.port}
+                  <p class="text-destructive text-sm">
+                    {databaseErrors.primary?.port}
+                  </p>
+                {/if}
+              </div>
+
+              <div class="space-y-2">
+                <Label for="primary_database">Primary database</Label>
+                <Input
+                  type="text"
+                  id="primary_database"
+                  placeholder="postgres"
+                  bind:value={form.primary.database}
+                />
+                {#if databaseErrors.primary?.database}
+                  <p class="text-destructive text-sm">
+                    {databaseErrors.primary?.database}
+                  </p>
+                {/if}
+              </div>
+
+              <div class="space-y-2">
+                <Label for="primary_username">Primary username</Label>
+                <Input
+                  type="text"
+                  id="primary_username"
+                  bind:value={form.primary.username}
+                />
+                {#if databaseErrors.primary?.username}
+                  <p class="text-destructive text-sm">
+                    {databaseErrors.primary?.username}
+                  </p>
+                {/if}
+              </div>
+
+              <div class="space-y-2">
+                <Label for="primary_password">Primary password</Label>
+                <div class="relative">
+                  <Input
+                    type={showPassword ? "text" : "password"}
+                    id="primary_password"
+                    bind:value={form.primary.password}
+                  />
+                  <button
+                    type="button"
+                    class="absolute inset-y-0 right-0 flex items-center pr-3"
+                    on:click={togglePasswordVisibility}
+                  >
+                    {#if showPassword}
+                      <EyeOff class="h-4 w-4 text-gray-400" />
+                    {:else}
+                      <Eye class="h-4 w-4 text-gray-400" />
+                    {/if}
+                  </button>
+                </div>
+                {#if databaseErrors.primary?.password}
+                  <p class="text-destructive text-sm">
+                    {databaseErrors.primary?.password}
+                  </p>
+                {/if}
+              </div>
+
+              <div class="flex items-center gap-2">
+                <Switch id="primary_ssl" bind:checked={form.primary.ssl} />
+                <Label for="primary_ssl">Primary SSL</Label>
+              </div>
+            </div>
+          </div>
+        {/if}
+
         {#if poolerType}
           <div transition:slide>
             <Alert variant="default">
@@ -543,6 +679,20 @@ sequin tunnel --ports=[your-local-port]:${form.name}`;
         <CardTitle>Replication configuration</CardTitle>
       </CardHeader>
       <CardContent>
+        <div class="space-y-2">
+          <Label for="publication_name">Publication name</Label>
+          <Input
+            type="text"
+            id="publication_name"
+            bind:value={form.publication_name}
+          />
+          {#if replicationErrors.publication_name}
+            <p class="text-destructive text-sm">
+              {replicationErrors.publication_name}
+            </p>
+          {/if}
+        </div>
+
         <div class="space-y-2">
           <div class="space-y-2">
             <Label for="slot_name">Slot name</Label>
@@ -553,20 +703,6 @@ sequin tunnel --ports=[your-local-port]:${form.name}`;
               </p>
             {/if}
           </div>
-
-          <div class="space-y-2">
-            <Label for="publication_name">Publication name</Label>
-            <Input
-              type="text"
-              id="publication_name"
-              bind:value={form.publication_name}
-            />
-            {#if replicationErrors.publication_name}
-              <p class="text-destructive text-sm">
-                {replicationErrors.publication_name}
-              </p>
-            {/if}
-          </div>
         </div>
 
         <div class="mt-8">

docker/replica-cdc-dev/README.md

@@ -0,0 +1,133 @@
+# PostgreSQL Logical Replication Setup
+
+This directory contains a Docker Compose setup for PostgreSQL logical replication with a primary and replica instance.
+
+## Configuration
+
+- Primary PostgreSQL runs on port `7432`
+- Replica PostgreSQL runs on port `7452`
+- Both instances use the default credentials:
+  - Username: `postgres`
+  - Password: `postgres`
+  - Database: `postgres`
+- Replication user credentials:
+  - Username: `replicator`
+  - Password: `replicator_password`
+
+## Connection Strings
+
+### Primary Database
+```
+postgresql://postgres:postgres@localhost:7432/postgres
+```
+
+### Replica Database
+```
+postgresql://postgres:postgres@localhost:7452/postgres
+```
+
+## Table Structure
+
+The example uses a `test_table` with the following structure:
+```sql
+CREATE TABLE test_table (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(100),
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+## Replication Configuration
+
+- Publication name: `sequin_pub`
+- Subscription name: `sequin_sub`
+- Replication slot name: `sequin_slot`
+
+## Setup
+
+1. Start the containers:
+```bash
+docker-compose up -d
+```
+
+2. Wait for both containers to be healthy (you can check with `docker-compose ps`)
+
+## Testing the Replication
+
+### 1. Insert Data into Primary
+
+Connect to the primary database and insert some test data:
+
+```bash
+# Connect to primary
+docker exec -it postgres-primary psql -U postgres
+
+# Once in psql, insert some test data
+INSERT INTO test_table (name) VALUES ('test1');
+INSERT INTO test_table (name) VALUES ('test2');
+INSERT INTO test_table (name) VALUES ('test3');
+```
+
+### 2. Verify Data on Replica
+
+Connect to the replica database and check if the data was replicated:
+
+```bash
+# Connect to replica
+docker exec -it postgres-replica psql -U postgres
+
+# Once in psql, verify the data
+SELECT * FROM test_table;
+```
+
+### 3. Monitor Replication Status
+
+To check the replication status on the primary:
+
+```bash
+docker exec -it postgres-primary psql -U postgres -c "SELECT * FROM pg_publication;"
+docker exec -it postgres-primary psql -U postgres -c "SELECT * FROM pg_replication_slots;"
+```
+
+To check the subscription status on the replica:
+
+```bash
+docker exec -it postgres-replica psql -U postgres -c "SELECT * FROM pg_subscription;"
+```
+
+## Cleanup
+
+To stop and remove the containers and volumes:
+
+```bash
+docker-compose down -v
+```
+
+## Troubleshooting
+
+If replication is not working:
+
+1. Check if both containers are running:
+```bash
+docker-compose ps
+```
+
+2. Check the logs:
+```bash
+docker-compose logs postgres-primary
+docker-compose logs postgres-replica
+```
+
+3. Verify the replication user and permissions:
+```bash
+docker exec -it postgres-primary psql -U postgres -c "\du"
+```
+
+4. Check if the publication and subscription are active:
+```bash
+# On primary
+docker exec -it postgres-primary psql -U postgres -c "SELECT * FROM pg_publication;"
+
+# On replica
+docker exec -it postgres-replica psql -U postgres -c "SELECT * FROM pg_subscription;"
+``` 

docker/replica-cdc-dev/docker-compose.yaml

@@ -0,0 +1,52 @@
+version: '3.8'
+
+services:
+  postgres-primary:
+    image: postgres:17.4
+    container_name: postgres-primary
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: postgres
+      # Enable logical replication
+      POSTGRES_INITDB_ARGS: "--data-checksums"
+    ports:
+      - "7432:5432"
+    volumes:
+      - postgres-primary-data:/var/lib/postgresql/data
+      - ./init-primary.sh:/docker-entrypoint-initdb.d/init-primary.sh
+    command: >
+      postgres
+      -c wal_level=logical
+      -c max_wal_senders=10
+      -c max_replication_slots=10
+      -c hot_standby=on
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  postgres-replica:
+    image: postgres:17.4
+    container_name: postgres-replica
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: postgres
+    ports:
+      - "7452:5432"
+    volumes:
+      - postgres-replica-data:/var/lib/postgresql/data
+      - ./init-replica.sh:/docker-entrypoint-initdb.d/init-replica.sh
+    depends_on:
+      postgres-primary:
+        condition: service_healthy
+    command: >
+      postgres
+      -c wal_level=logical
+      -c hot_standby=on
+
+volumes:
+  postgres-primary-data:
+  postgres-replica-data: