pg_tide

Transactional outbox, idempotent inbox, and relay pipelines for PostgreSQL 18+.

pg_tide gives your PostgreSQL database a built-in messaging backbone. Publish events within your existing transactions — no dual-writes, no distributed transactions, no message brokers required at the database layer.

When you're ready to fan out to Kafka, NATS, Redis Streams, or any other system, the pg-tide relay binary bridges the gap — reading from outboxes, delivering to external sinks, and writing back to inboxes with exactly-once semantics.

The Problem pg_tide Solves

Most applications eventually need to publish events to other systems. A customer places an order — and the warehouse needs to know, the analytics pipeline needs to know, the email service needs to send a confirmation. The naive approach is deceptively simple: save the order to your database, then publish an event to your message broker.

But what happens when the broker publish fails after the database commit? Or when your application crashes between the two operations? You get silent data loss — the order exists but nobody downstream knows about it. This is the dual-write problem, and it's one of the most common sources of data inconsistency in distributed systems.

pg_tide eliminates this entire class of bugs by implementing the transactional outbox pattern as a PostgreSQL extension. Your application writes both the business data and the event in a single database transaction. They succeed or fail together — atomically, consistently, and durably. A separate relay process then delivers committed events to downstream systems, retrying indefinitely until delivery succeeds.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                    PostgreSQL 18+                             │
│                                                              │
│  Your Application                                            │
│       │                                                      │
│       ├──▶ INSERT INTO orders (...)  ─┐                      │
│       │                               ├── Same transaction   │
│       └──▶ SELECT tide.outbox_publish ─┘                     │
│                        │                                     │
│            tide.tide_outbox_messages                          │
│                        │                                     │
└────────────────────────┼─────────────────────────────────────┘
                         │  pg_notify wakes relay
                         ▼
┌──────────────────────────────────────────────────────────────┐
│                   pg-tide relay binary                         │
│                                                               │
│  Polls outbox ──▶ Delivers to sink ──▶ Commits offset         │
└──────────────────────────────────────────────────────────────┘
                         │
                         ▼
          NATS · Kafka · Redis · RabbitMQ · SQS · Webhooks

Key Features

At a Glance

-- Create an outbox (one-time setup)
SELECT tide.outbox_create('orders', p_retention_hours := 48);

-- Publish within your business transaction
BEGIN;
  INSERT INTO orders (id, total) VALUES (42, 99.99);
  SELECT tide.outbox_publish('orders',
    '{"order_id": 42, "total": 99.99}'::jsonb,
    '{"event_type": "order.created"}'::jsonb
  );
COMMIT;

-- Configure a relay pipeline
SELECT tide.relay_set_outbox('orders-nats', 'orders', 'nats',
  '{"url": "nats://localhost:4222", "subject": "orders.events"}'::jsonb
);

-- Start the relay — messages flow automatically
-- pg-tide --postgres-url "postgres://user:pass@localhost:5432/mydb"

Who Is This For?

pg_tide is built for:

• Backend engineers building applications on PostgreSQL who need reliable event publishing
• Platform teams providing messaging infrastructure without the operational burden of a full streaming platform
• DBAs who want messaging capabilities that integrate naturally with their existing PostgreSQL operational practices

If PostgreSQL is your source of truth and you need events to flow reliably to other systems, pg_tide is designed for you.

Glossary

Key terms used throughout this documentation:

Documentation Guide

This documentation is organized to match your learning journey:

1. Evaluate — decide if pg_tide is right for your use case
2. Getting Started — install and build your first pipeline
3. Concepts — understand the mechanics in depth
4. SQL Reference — complete API documentation
5. Relay Guide — configure and operate the relay binary
6. Tutorials — guided walkthroughs of common patterns
7. Operations — production deployment and maintenance
8. Integrations — platform-specific guidance

License

pg_tide is released under the Apache-2.0 license.