How to annotate database changes
Add contextual metadata to your database changes
Sequin allows you to annotate database changes with additional context using annotations. This is useful for:
- Audit trails: Track who made changes and from where
- Debugging: Add request IDs and other debugging context
- Business context: Include business-specific metadata about changes
- Change grouping: Group related changes across tables
How it works
Transaction annotations are JSON objects that you attach to a transaction. Any changes that occur within that transaction following the annotation statement will include the annotations in their metadata.
To set annotations:
The annotations will be included in the metadata.transaction_annotations
field of all change messages in that transaction:
Usage
Setting annotations
Annotations must be set within the transaction they’re annotating, before changes are made:
Clearing annotations
Annotations are automatically cleared at the end of each transaction. You can also explicitly clear them, ensuring they will not be included in any changes following the clear statement:
Common use cases
Audit logs
Transaction annotations are particularly useful for audit logs. They allow you to capture who made changes and why:
See Create audit logs for a complete guide.
Request tracing
Add request context to help with debugging:
Business workflows
Group related changes with workflow context:
Was this page helpful?