Skip to main content
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.