Transaction Annotations

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

​

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
• Annotations are only supported for change messages. They are not supported for row messages.

​

Message format

Annotations appear in the metadata.transaction_annotations field of change 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;

​

Related