Events

During ongoing replication, Supabase ETL delivers events decoded from Postgres logical replication via write_events(). This page documents their Rust shapes and PostgreSQL semantics.

Event Overview

Data Modification Events

These events carry row data and are associated with specific tables.

Row Images

Data modification events use row-image helper types:

pub enum UpdatedTableRow {
    Full(TableRow),
    Partial(PartialTableRow),
}

pub enum OldTableRow {
    Full(TableRow),
    Key(TableRow),
}

TableRow is a complete dense row. Its values are ordered to match the replicated table-column order.

PartialTableRow is used when an update row is not complete. It exposes:

• total_columns(): the number of replicated columns in the table schema;
• values(): present values in replicated table-column order, excluding missing columns;
• missing_column_indexes(): zero-based replicated-column indexes for values ETL could not reconstruct.

OldTableRow::Full(row) contains a complete old row. OldTableRow::Key(row) contains only replica-identity columns, densely packed in replicated table-column order.

Insert

A new row was added to a table.

pub struct InsertEvent {
    pub commit_lsn: PgLsn,
    pub tx_ordinal: u64,
    pub replicated_table_schema: ReplicatedTableSchema,
    pub table_row: TableRow,
}

Update

An existing row was modified.

pub struct UpdateEvent {
    pub commit_lsn: PgLsn,
    pub tx_ordinal: u64,
    pub replicated_table_schema: ReplicatedTableSchema,
    pub updated_table_row: UpdatedTableRow,
    pub old_table_row: Option<OldTableRow>,
}

updated_table_row is the authoritative post-update payload:

• UpdatedTableRow::Full when ETL knows every replicated column value after decoding the update.
• UpdatedTableRow::Partial when PostgreSQL emitted UnchangedToast fields that ETL could not reconstruct safely.

old_table_row provides optional context for row matching, key changes, and reconstruction.

Unchanged Toast

PostgreSQL may encode an unchanged toasted value as UnchangedToast in the update's new tuple instead of resending the full column value. ETL can turn the update into UpdatedTableRow::Full only when that value can be recovered from the old-side row image:

• a FULL old row can recover unchanged toasted values for any replicated column;
• a key-only old row can recover unchanged toasted values only for replica-identity columns included in that key image;
• no old row means unchanged toasted values cannot be recovered from the event.

When any UnchangedToast field cannot be recovered, ETL emits UpdatedTableRow::Partial with known values and missing column indexes instead of pretending the unknown value is NULL or a replacement value.

Destinations that need complete replacement rows, full before/after comparison, or complete audit records should require REPLICA IDENTITY FULL for tables with toasted columns, or keep enough prior state to fill missing values themselves.

Old Row Mapping

ETL maps PostgreSQL pgoutput update tuple markers directly:

PostgreSQL chooses which old-side marker to emit from the table's replica identity:

For UPDATE, PostgreSQL only sends an old key image under DEFAULT or USING INDEX when it determines the old key must be logged. In practice, that happens when:

• any replica-identity column changed, or
• any replica-identity column contains external data, such as a toasted value that must be available from the old tuple.

That means non-identity updates under DEFAULT or USING INDEX often arrive with old_table_row = None. Under FULL, PostgreSQL sends a full old row for every published update. A FULL update with old_table_row = None is not a pgoutput shape.

When handling updates:

1. Treat updated_table_row as the post-update payload and handle UpdatedTableRow::Partial explicitly.
2. Treat OldTableRow::Key as replica-identity values, not necessarily the primary key. Use OldTableRow::Full for complete before-images.
3. If old_table_row is None, match or upsert from the new row according to the destination's keying model.

Delete

A row was removed from a table.

pub struct DeleteEvent {
    pub commit_lsn: PgLsn,
    pub tx_ordinal: u64,
    pub replicated_table_schema: ReplicatedTableSchema,
    pub old_table_row: Option<OldTableRow>,
}

For DELETE, valid PostgreSQL publications send an old-side image:

Important implications:

• Deletes do not carry a new row image. old_table_row is the delete payload.
• OldTableRow::Key(row) again means replica-identity columns only, not necessarily the table's primary key.
• Consumers that require full old rows for deletes need REPLICA IDENTITY FULL.
• The Rust field is optional at the event API boundary, but PostgreSQL pgoutput populates it for every published delete. Tables without usable replica identity fail at the source when they publish deletes.
• Destination implementations should decide up front whether key-only deletes are enough. If they are not, require REPLICA IDENTITY FULL for those tables.

Truncate

One or more tables were truncated (all rows deleted).

pub struct TruncateEvent {
    pub commit_lsn: PgLsn,
    pub tx_ordinal: u64,
    pub options: i8,
    pub truncated_tables: Vec<ReplicatedTableSchema>,
}

Transaction Events

These events mark transaction boundaries.

Begin

Marks the start of a transaction.

pub struct BeginEvent {
    pub commit_lsn: PgLsn,
    pub tx_ordinal: u64,
    pub timestamp: i64,
    pub xid: u32,
}

Commit

Marks successful transaction completion.

pub struct CommitEvent {
    pub commit_lsn: PgLsn,
    pub tx_ordinal: u64,
    pub flags: i8,
    pub end_lsn: PgLsn,
    pub timestamp: i64,
}

Schema Events

Relation

Provides table schema information. Sent before data events for a table and again after supported schema changes.

pub struct RelationEvent {
    pub replicated_table_schema: ReplicatedTableSchema,
}

Relation messages are connection-local protocol metadata. PostgreSQL can emit the same relation again after a reconnect even when the source schema did not change. A RelationEvent therefore has no durable event sequence key and does not consume a transaction ordinal.

PostgreSQL pgoutput builds relation messages by walking the table descriptor in pg_attribute.attnum order and skipping columns that are not published. It sends tuple data in the same order as the relation message.

ETL builds replication and identity masks from relation-message column names, so the order is not needed to decide which columns are included. That name-based matching is sound because PostgreSQL live column names are unique within a table schema version. The order matters only after the masks are applied: stored table schemas are also ordered by attnum, so ReplicatedTableSchema::column_schemas() becomes a positional view that matches the tuple payloads exactly, even when a publication filters columns.

For DDL behavior, including add/drop/rename semantics, default and nullability handling, and current limitations, see Schema Changes.

Begin/Commit Behavior

During initial sync, parallel Table Sync Workers may deliver Begin and Commit markers more than once. Ignore them if you do not need transaction markers; otherwise deduplicate them by commit_lsn plus tx_ordinal. Row writes must still be idempotent because ETL provides at-least-once delivery.

Understanding Event Sequence Keys

Transaction and data events include a commit LSN (Log Sequence Number) plus a transaction-local ordinal. Together, these fields provide stable ordering for idempotent destination writes. Relation events are not sequenced because they are connection-local protocol metadata.

commit_lsn and tx_ordinal

Events in one transaction share a commit_lsn; tx_ordinal distinguishes their order. Use the pair as a sequence key for ordered writes and replay detection. See Logical Replication for LSN background.

Event Batching

ETL batches events before calling write_events(). A batch may contain events from multiple tables, multiple transactions, and mixed event types. Schema changes do not end a batch: because batching is driven by size and time, one batch may contain multiple Relation events and multiple schema changes.

Ordering requirement: Process events for the same destination row in order. Events for independent rows may be processed concurrently.