Skip to content

Best Practices

  • Back to Transactional Outbox Overview

    Return to the Transactional Outbox overview page with all topics.

    Back to Overview

Overview

  1. Always commit — Always call commit() after adding events (including after get_many / publish loops)
  2. Use transactions — Ensure outbox operations are in the same transaction as business logic
  3. Register events — Register all event types on an OutboxedEventMap (prefer an isolated instance)
  4. Handle failures — Implement retry logic in the publisher process
  5. Monitor status — Track NOT_PRODUCED events for debugging. Rows that fail to deserialize (or whose event_name is not registered) are marked NOT_PRODUCED and spend the same flush_counter budget as broker publish failures, so they stop filling the selectable batch after the limit
  6. Use compression — Enable compression for large payloads
  7. Batch processing — Process events in batches for efficiency

  8. Codecs — Keep JSON as the default; register Protobuf (or a custom EventCodec) only per event that needs it. Changing a codec for an already-registered name does not rewrite pending rows — keep the reader compatible with bytes already stored, or drain the outbox first

  9. Event Producing — How to produce events without outbox

  10. FastStream Integration — Kafka and RabbitMQ message broker configuration
  11. Dependency Injection — How to inject outbox repository
  12. Protobuf Integration — Opt-in Protobuf codecs for outbox and brokers