Skip to main content

Introduction

oncebox is a Spring Boot library that implements the Transactional Outbox pattern on the publishing side and the inbox (idempotent consumer) pattern on the receiving side.

On the publishing side, events are stored in an outbox_events table in the same transaction as your business data. Background pollers read them by event type and publish them to Apache Kafka or RabbitMQ, retrying failures with a per-type backoff and moving events that exhaust their retries to a dead letter queue.

On the receiving side, the inbox records the id of every consumed event, so a message that the broker delivers again is recognised and skipped.

No log-based CDC (Debezium) is involved: everything runs inside your application on plain SQL, which keeps the setup simple, portable and explicit.

Key features​

  • Atomic persistence - events are stored in the same transaction as the business change.
  • At-least-once delivery - a batch is marked processed only after the broker acknowledges it; failures are retried with configurable backoff per event type.
  • Effectively-once processing - the transactional inbox records an event id in the same transaction as its handling, so a redelivered event never changes data twice.
  • At-most-once processing - the non-transactional inbox records the id before handling, so a side effect such as sending an email is never repeated.
  • Dead letter queue - events that fail after all retries are moved to a DLQ table and managed through a REST API.
  • Adaptive polling - the polling delay grows while there is nothing to do and drops as soon as work appears.
  • Self-healing - batches stuck after a crash are returned to the queue, and their late outcome is fenced off.
  • Background maintenance - processed outbox events, resolved DLQ events and old inbox records are cleaned up.
  • Observability - Micrometer metrics with ready-made Grafana dashboards.

Supported infrastructure​

ComponentSupported versions
DatabasesPostgreSQL 16+, MySQL 8.0.13+, Oracle 23+
BrokersApache Kafka 3.7+, RabbitMQ 3.12+
Inbox cacheAny Spring CacheManager, Redis 7+ is tested
RuntimeJava 21, Spring Boot 3.5

Modules​

ArtifactRequiredPurpose
oncebox-starteryesAuto-configuration of the outbox and the inbox
oncebox-postgresqlone ofPostgreSQL repositories
oncebox-mysqlone ofMySQL repositories
oncebox-oracleone ofOracle repositories
oncebox-kafkaone ofKafka sender (publisher side)
oncebox-rabbitone ofRabbitMQ sender (publisher side)
oncebox-flywaynoApplies the oncebox migrations with Flyway, see Schema Migrations
oncebox-liquibasenoApplies the oncebox migrations with Liquibase
oncebox-aopno@OutboxPublish support, pulled in by the starter; needs spring-boot-starter-aop
oncebox-dlq-apinoREST API for the dead letter queue
oncebox-inbox-cachenoCaching of consumed event ids through Spring's CacheManager
oncebox-metricsnoMicrometer metrics

The core types live in oncebox-core, which comes in transitively.

When not to use it​

  • You need ordering. Events are processed in parallel by type; there is no ordering guarantee within or across event types. See Delivery Guarantees.
  • You scale to many instances polling one table. SKIP LOCKED polling degrades as the number of instances grows. See Core Concepts.

Next steps​