Transaction annotations allow you to attach metadata to database changes. When you set annotations, all change messages following the annotation will include the annotations in their metadata.

​
Protocol

Set annotations inside a transaction using the function pg_logical_emit_message:

select pg_logical_emit_message(true, prefix, content);

​
Message prefixes

PrefixDescription
sequin:transaction_annotations.setSets annotations for all following changes in the current transaction
sequin:transaction_annotations.clearClears annotations for all following changes in the current transaction

​
Behavior

​
Scope

  • Annotations are transaction-scoped
  • They apply to all changes following the annotation within the transaction
  • Setting new annotations overwrites previous annotations in the same transaction

​
Limitations

  • Must be valid JSON
  • Cannot be set outside a transaction

​
Message format

Annotations appear in the metadata.transaction_annotations field of messages:

{
  "metadata": {
    "transaction_annotations": {
      // Your annotation fields
    }
  }
}

If no annotations are set, the field will be null.

​
Examples

​
Setting annotations

select pg_logical_emit_message(true, 'sequin:transaction_annotations.set', '{
  "username": "paul.atreides",
  "source": "web_ui",
  "request_id": "req_123"
}');

​
Clearing annotations

select pg_logical_emit_message(true, 'sequin:transaction_annotations.clear', '');

​
Overwriting annotations

begin;
  -- Set initial annotations
  select pg_logical_emit_message(true, 'sequin:transaction_annotations.set', '{
    "username": "paul.atreides"
  }');

  -- These annotations replace the previous ones for all following changes in the transaction
  select pg_logical_emit_message(true, 'sequin:transaction_annotations.set', '{
    "username": "gurney.halleck"
  }');
commit;

Payloads reference

Learn about message shapes and how annotations appear in messages.

How to annotate changes

Step-by-step guide on adding annotations to your database changes.

Create audit logs

Learn how to use annotations to create rich audit logs.