How do you implement the outbox pattern with Kafka in NestJS to guarantee exactly-once message delivery?

Q: How do you implement the outbox pattern with Kafka in NestJS to guarantee exactly-once message delivery?

// Outbox entity @Entity('outbox') export class OutboxEvent { @PrimaryGeneratedColumn('uuid') id: string; @Column() aggregateType: string; @Column() eventType: string; @Column('jsonb') payload: object; @Column({ default: false }) published: boolean; @CreateDateColumn() createdAt: Date; } // Write to outbox in the SAME transaction as the business entity async placeOrder(dto: CreateOrderDto): Promise { return this.dataSource.transaction(async manager => { const order = await manager.save(Order, dto); await manager.save(OutboxEvent, { aggregateType: 'Order', eventType: 'OrderPlaced', payload: { orderId: order.id, ...dto }, }); return order; // both writes commit or both roll back }); } // Relay — polls outbox and publishes to Kafka @Injectable() export class OutboxRelayService { @Interval(1000) async relay(): Promise { const events = await this.outboxRepo.find({ where: { published: false }, order: { createdAt: 'ASC' }, take: 100, }); for (const event of events) { await firstValueFrom(this.kafkaClient.emit(event.eventType, event.payload)); await this.outboxRepo.update(event.id, { published: true }); } } } The event and business entity are written atomically — no event is lost even if the process crashes after the DB write. The relay is idempotent — if it crashes mid-relay, unpublished events are picked up on the next poll. Use a distributed lock (Redis SETNX) if multiple relay instances run concurrently to prevent duplicate publishes. Mark events as published after Kafka confirms receipt — not before. Add a dead-letter column for events that fail repeatedly so operators can inspect and replay them.

Difficulty: 7/10

outbox pattern, Kafka exactly-once, NestJS transaction management

Write the domain event to an outbox table in the same database transaction as the business entity write. A separate relay service polls the outbox and publishes unpublished events to Kafka, then marks them as published. This guarantees the event is eventually published even if the app crashes between the write and the publish.

Outbox entity, transactional write, and relay publisher

Outbox pattern guarantees and design notes:

1
The event and business entity are written atomically — no event is lost even if the process crashes after the DB write.

How do you implement the outbox pattern with Kafka in NestJS to guarantee exactly-once message delivery?

Difficulty: 7/10

outbox pattern, Kafka exactly-once, NestJS transaction management

Write the domain event to an outbox table in the same database transaction as the business entity write. A separate relay service polls the outbox and publishes unpublished events to Kafka, then marks them as published. This guarantees the event is eventually published even if the app crashes between the write and the publish.

Outbox entity, transactional write, and relay publisher

Outbox pattern guarantees and design notes:

1
The event and business entity are written atomically — no event is lost even if the process crashes after the DB write.

How do you implement the outbox pattern with Kafka in NestJS to guarantee exactly-once message delivery?

How do you implement the outbox pattern with Kafka in NestJS to guarantee exactly-once message delivery?

Scenario Questions

Follow-up Questions