Documentation Index
Fetch the complete documentation index at: /docs/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
Reference
Transaction Annotations
Reference for Sequin transaction annotations. Attach rich contextual metadata to your Postgres change data capture (CDC) events.
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.
If no annotations are set, the field will be
Protocol
Set annotations inside a transaction using the functionpg_logical_emit_message:
select pg_logical_emit_message(true, prefix, content);
Message prefixes
| Prefix | Description |
|---|---|
sequin:transaction_annotations.set | Sets annotations for all following changes in the current transaction |
sequin:transaction_annotations.clear | Clears 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 themetadata.transaction_annotations field of messages:
{
"metadata": {
"transaction_annotations": {
// Your annotation fields
}
}
}
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
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.