DEV Community: Rodrigo Nogueira

The dual-write problem in NestJS, solved with Drizzle: a transactional outbox + idempotent inbox

Rodrigo Nogueira — Fri, 03 Jul 2026 22:00:26 +0000

Somewhere in most event-driven backends, there's a method that looks like this:

async placeOrder(input: PlaceOrderInput) {
  await this.db.insert(orders).values(input);          // 1. write the row
  await this.kafka.send({ topic: 'order.placed', … }); // 2. publish the event
}

It looks fine, and it has a bug. If the process crashes between 1 and 2, the order exists but the event never happened — downstream consumers silently miss it. Swap the order and you get the opposite failure: an event for an order that was rolled back. There is no try/catch arrangement that fixes this, because a database and a broker cannot commit atomically. This is the dual-write problem.

The boring, proven fix is the transactional outbox: don't publish in step 2. Instead, write the event into an outbox_events table in the same database transaction as the business row. A background worker then relays committed rows to the broker. The transaction is the only atomic boundary you have — so put both writes inside it.

That gives you at-least-once delivery, which means the consumer side needs the mirror-image pattern: an idempotent inbox that deduplicates redeliveries, so the side effect runs exactly once even when Kafka delivers twice.

@nest-native/messaging — part of nest-native, a set of NestJS integrations — packages this pair as a library, after the pattern was first built by hand inside a reference application. It's the outbox/inbox pattern for the Drizzle ORM + NestJS stack — a niche the existing NestJS outbox libraries (which target TypeORM and MikroORM — see nestjs-outbox and nestjs-inbox-outbox, both solid) don't cover.

The producer half: enqueue inside your transaction

The library ships the tables as Drizzle factories per dialect (SQLite, Postgres, MySQL). You add them to your schema and generate a migration like any other table:

// schema.ts
export { outboxEvents, inboxEvents } from '@nest-native/messaging/sqlite'; // or /postgres, /mysql

Transactions ride on @nestjs-cls/transactional with its Drizzle adapter — the same @Transactional() decorator you'd use anyway:

MessagingModule.forRoot({
  drizzleInstanceToken: DRIZZLE,          // your Drizzle DI token
  outboxStore: new SqliteOutboxStore(),   // or PostgresOutboxStore / MysqlOutboxStore
  inboxStore: new SqliteInboxStore(),
  transport,                              // where the claimer relays to — below
}),

Then the business code:

@Injectable()
export class OrderService {
  constructor(
    @InjectTransaction() private readonly db: AppDatabase,
    private readonly producer: OutboxProducer<SqliteOutboxStore>,
  ) {}

  @Transactional()
  placeOrder(id: string, item: string) {
    this.db.insert(orders).values({ id, item }).run();
    this.producer.enqueue({
      topic: 'order.placed',
      payload: { id, item },
      idempotencyKey: `order:${id}`,
    });
  }
}

The order row and the outbox row commit together, or roll back together. A throw after enqueue produces no phantom event; a crash after commit loses nothing, because the event is durably in your database.

(One nuance the library handles for you: better-sqlite3 transactions are synchronous while Postgres/MySQL are async. The per-dialect stores own that difference — on SQLite enqueue returns the row directly inside the sync transaction body; on Postgres you await it. Same code shape either way.)

Relaying: the claimer and the worker

A claimer polls for committed rows, publishes each through a transport, and applies retry-with-backoff on failure — including reclaiming rows from a worker that died mid-flight:

// scripts/start-worker.ts
const app = await NestFactory.createApplicationContext(AppModule);
await runWorkerLoop(app.get(OutboxClaimer), {
  pollIntervalMs: 2_000,
  signal: shutdownSignal, // AbortSignal wired to SIGTERM
});

For Kafka the transport is one line, built on @nest-native/kafka (Confluent's official JS client underneath):

MessagingModule.forRootAsync({
  drizzleInstanceToken: DRIZZLE,
  outboxStore: new SqliteOutboxStore(),
  inboxStore: new SqliteInboxStore(),
  inject: [KafkaProducerService],
  useTransport: (producer) => new KafkaOutboxTransport(producer),
}),

Don't have Kafka yet? There's an in-process transport (@nest-native/messaging/in-process) — a topic→handler registry with the same at-least-once semantics — so a modular monolith can adopt the pattern today and swap the transport for a broker later without touching a line of domain code.

The consumer half: exactly-once effects

Kafka is at-least-once by contract, so redelivery is a when, not an if. The inbox primitive is a single method:

const outcome = await inbox.runOnce(dedupKey, source, () => {
  // your side effect — runs in the SAME transaction as the dedup row
  this.audit.record({ … });
});
// 'processed' on the first delivery, 'duplicate' on any redelivery

runOnce inserts a (source, message_key) row protected by a unique index and runs your side effect in the same transaction. A redelivery violates the index → 'duplicate' → the side effect is skipped. If your side effect throws, the dedup row rolls back with it, so the retry reprocesses cleanly. That composition — unique index + shared transaction — is the entire trick, and it's provable in the database.

For Kafka consumers the library wraps the full delivery decision (validate → dedup → ack / dead-letter / redeliver) in an engine you delegate to from a thin @KafkaConsumer shell:

@KafkaConsumer('order.placed', { groupId: 'orders-service' })
export class OrderConsumer {
  constructor(private readonly inbox: KafkaInboxConsumer, private readonly audit: OrderAuditService) {}

  @KafkaHandler()
  async handle(@KafkaMessage() payload: unknown, @KafkaHeaders() headers: Headers, @KafkaCtx() ctx: KafkaContext) {
    await this.inbox.consume<OrderPlaced>({
      source: 'order.placed:orders-service',
      context: ctx, headers, payload,
      validate: isOrderPlaced,                                   // poison message → DLQ, then ack
      sideEffect: (order, dedupKey) => this.audit.record(order, dedupKey),
      dlqTopic: 'order.placed.DLQ',
    });
  }
}

Poison messages (unparseable, unkeyable) go to a dead-letter topic instead of redelivering forever; transient failures rethrow so the broker redelivers; duplicates ack silently.

Testing without a broker

Everything above runs in tests with no infrastructure: an in-memory outbox transport (@nest-native/messaging/testing) for the producer half, and @nest-native/kafka/testing's in-memory broker for the full pipeline — including redelivery:

await broker.emit('order.placed', publishedMessage); // redeliver the same message
await broker.idle();                                 // wait for handler pipelines to settle
expect(auditRows).toHaveLength(1);                   // side effect ran exactly once

The library itself is tested at 100% coverage against real SQLite, real in-process Postgres (pglite), and the in-memory broker.

See the whole thing running

The pattern is one chapter of a larger, runnable story: the nest-native reference app is a multi-tenant work-tracking SaaS where every task write emits task.created/assigned/completed through this outbox, a consumer builds an activity feed through this inbox, the event contracts are published as an AsyncAPI 3.0 catalog, and a streaming AI assistant summarizes the activity — six libraries, one coherent journey, green tests, no Docker required for the default profile.

Honest scope

This is the app-level outbox. At larger scale you may prefer CDC (Debezium + Kafka Connect) tailing the WAL — different trade-offs, no app code, more infrastructure.
If you're on TypeORM or MikroORM, the libraries linked above already serve you well. @nest-native/messaging exists specifically because nothing covered Drizzle.
Delivery is at-least-once end to end; the inbox gives you exactly-once effects, which is the guarantee that actually matters — exactly-once delivery across a network isn't something any tool can promise.

Docs: nest-native.dev/messaging · Source: github.com/nest-native/messaging. Feedback and issues welcome — especially if you hit a case the pattern doesn't cover.

A NestJS reference app that proves six nest-native libraries under realistic backend pressure

Rodrigo Nogueira — Mon, 25 May 2026 15:37:52 +0000

TL;DR: nest-native/reference-app is a production-shaped multi-tenant work-tracking SaaS — think a small Linear — that composes all six nest-native libraries the way a real product would: Drizzle persistence, a typed tRPC API, domain events emitted in the same transaction as the writes, a Kafka backbone with exactly-once consumer effects, a published AsyncAPI 3.0 catalog, and a streaming AI assistant. Every guarantee has a test. It runs with zero infrastructure by default (SQLite, no broker, offline AI), and the same domain code runs against real Kafka by setting one env var.

What changed since this post first went up

This post originally covered a two-library app (nest-drizzle-native + nest-trpc-native). Since then:

The libraries moved to the nest-native org and are published scoped: @nest-native/drizzle and @nest-native/trpc.
The family grew to six packages — @nest-native/kafka, @nest-native/messaging, @nest-native/asyncapi, and @nest-native/ai-sdk joined.
The reference app grew from "prove the wiring" into a story: one product where each library earns its place, and where the reliable-messaging half was battle-tested hard enough that it got extracted into a library.

Everything below describes the app as it is today.

The org, in one paragraph

nest-native publishes decorator-first NestJS integrations that should feel like official NestJS packages — modules, DI, decorators, guards/interceptors, lifecycle hooks — while staying honest about the tool underneath. Drizzle stays SQL-first; tRPC stays tRPC; the outbox is a real table, not magic. Every package ships with "dependencies": {} (you install only the peers you use), 100% test coverage as a hard CI gate, runnable samples, and documented non-goals.

The problem this app exists to solve

Library docs cover their slice; nobody covers the seams. And the seams are where backends actually get built:

How does "current user / current organization" reach a tRPC procedure, a guard, and a repository three calls deep — through one request-scoped mechanism?
How do I write a row and publish an event without a crash window between them?
How do consumers survive Kafka's at-least-once redelivery without double-applying effects?
Where do other teams find my event contracts — and how do I keep those contracts from drifting apart across producer, consumer, and docs?
How do I ship a streaming AI endpoint that tests offline, deterministically, in CI?

The reference app answers all of these in one codebase, as a coherent product rather than a pile of demos.

The story: one journey through six libraries

The product is a multi-tenant work-tracking SaaS. Follow one journey and every library shows up exactly where a real system would reach for it:

An org invites a teammate — one @Transactional() method writes the user, membership, project, and audit rows and enqueues a user.invited event, atomically.
They work tasks — create → assign → complete; each write emits task.created / task.assigned / task.completed in the same transaction.
Events flow over the backbone — a background claimer relays committed events (in-process by default; Kafka in production), and consumers build an activity feed read-model, deduplicated against redelivery.
The contracts are published — an AsyncAPI 3.0 catalog at /asyncapi documents every event, generated from the same Zod schemas the code validates with.
AI reads the activity — a streaming assistant turns a project's recent activity into a status update, token by token.

Library	Its job in the story
`@nest-native/drizzle`	Persistence: repositories (`@DrizzleRepository`, `@InjectTransaction`), tenant-scoped queries, migrations
`@nest-native/trpc`	The typed API: `@Router`/`@Query`/`@Mutation`, generated `AppRouter`, superjson, guards
`@nest-native/messaging`	Reliable events: transactional outbox + idempotent inbox on Drizzle
`@nest-native/kafka`	The backbone: `KafkaOutboxTransport` + `@KafkaConsumer` read-models
`@nest-native/asyncapi`	The event catalog other teams integrate against
`@nest-native/ai-sdk`	The streaming assistant (`@AiStream`), offline-testable

The central proof: five writes, one transaction, zero lost events

The onboarding workflow is still the crown jewel. inviteUser() writes five rows — user, membership, project link, audit event, and the outbox event — inside a single @Transactional() method:

@Transactional()
inviteUser(input: InviteUserInput) {
  const user = this.users.create(...);
  this.memberships.create(...);
  // ...audit row...
  this.outbox.enqueue({
    topic: 'user.invited',
    payload,                        // a plain typed interface — no casts
    idempotencyKey: `user.invited:${orgId}:${user.id}`,
  });
}

A throw anywhere rolls back everything — no phantom event. A crash after commit loses nothing — the event is durably in the database. The tests prove both directions (happy path, rollback safety, crash recovery), because "trust me" is not a delivery guarantee.

No lost events, no double effects

The dual-write problem ("write the row, then publish — and pray nothing crashes in between") is solved by @nest-native/messaging: the enqueue above is just an insert into an outbox_events table, and a background claimer relays committed rows with retry/backoff and stuck-claim recovery:

The consumer half is the mirror image: delivery is at-least-once by contract, so the idempotent inbox dedups redeliveries via a unique (source, message_key) row written in the same transaction as the side effect — exactly-once effects, provable in the database. The app's activity feed is built exactly this way, and the test suite redelivers messages on purpose and asserts the side effect ran once.

Two profiles, one codebase:

Default — no broker: the outbox dispatches through an in-process topic→handler registry (@nest-native/messaging/in-process). SQLite in a file. This is what CI runs.
Kafka — set KAFKA_BROKERS and the same domain code relays through KafkaOutboxTransport, with @KafkaConsumers (via @nest-native/kafka, on Confluent's official client) on the other side. Same event bodies, same dedup keys, same wire headers.

A typed API that doesn't lie

The tRPC layer (@nest-native/trpc) is decorator-first (@Router('tasks'), @Query, @Mutation, Zod I/O) with a generated AppRouter consumed by a typed client in CI. Three details worth stealing:

superjson end-to-end — activity.list returns real Date objects, and the generated router carries a type-level transformer marker: a client that forgets to configure superjson fails to compile. Both directions are CI steps.
Validation errors clients can use — an errorFormatter flattens ZodErrors so a failing mutation surfaces error.data.zodError.fieldErrors.title on the typed client.
Cache headers where they're safe — responseMeta sets cache-control only on the public ping query; everything tenant-scoped stays uncached, and tests assert both presence and absence.

Your events, documented

@nest-native/asyncapi publishes an AsyncAPI 3.0 document at /asyncapi (plus -json/-yaml) describing all four domain events. The payload schemas are defined once as Zod objects — the same definitions derive the TypeScript types (z.infer), the runtime guards (safeParse), and the catalog schemas. Producer, consumer, and documentation cannot drift apart, and the document validates against @asyncapi/parser in the test suite.

AI over your data, tested offline

POST /projects/:id/assistant streams a status update summarizing the project's recent activity, via @nest-native/ai-sdk's @AiStream (SSE, abort on client disconnect). By default it streams from an offline mock model built from the real activity digest — deterministic, no API key, CI-safe. Set OPENAI_API_KEY and a real provider swaps in with no code change. (Adopting the AI SDK is also why the app requires Node ≥ 22 — ai@7 demands it.)

Try it in 30 seconds

git clone https://github.com/nest-native/reference-app && cd reference-app
nvm use            # Node >= 22
npm install
DATABASE_URL=./reference-app.db npm run db:migrate
DATABASE_URL=./reference-app.db npm run seed
AUTH_SECRET=dev-secret-must-be-at-least-32-characters-xxxxx \
  DATABASE_URL=./reference-app.db npm run start:dev

tRPC at /trpc, health at /health, the AsyncAPI catalog at /asyncapi, the AI assistant at POST /projects/1/assistant
Seed login: admin@acme.test / admin123!
The outbox worker runs as its own process: npm run start:worker
No Docker, no broker, no API keys required for any of it

The loop that makes it honest

The app isn't just a showcase — it's the feedback loop for the libraries, and it has teeth. Recent examples, all shipped upstream because building this app surfaced them:

The in-process outbox transport was hand-rolled here first, proved generic, and was extracted into @nest-native/messaging/in-process.
The app's hand-written AI mock became @nest-native/ai-sdk/testing (createMockLanguageModel) — and deleted every copy-pasted mock in the family.
enqueue() becoming generic (killing as unknown as Record<string, unknown> casts), the in-memory Kafka broker gaining an awaitable idle() (killing sleep(50) in tests), and AsyncAPI accepting Zod schemas directly — all of it started as friction in this codebase.
The app's install even caught a broken peer-dependency range in a fresh release before any user hit it.

If something feels awkward here, that's treated as a library bug — fixed upstream, in its own PR, with its own tests.

What it deliberately is not

Not a starter kit or boilerplate — it optimizes for being read, not forked. Copy patterns, not the repo.
Not 100%-covered — the 100% bar belongs to the libraries; the app's suite is pragmatic and targets the guarantees (rollback, crash recovery, dedup, catalog validity, stream framing).
Not a CDC system — the outbox is the app-level answer; Debezium-style log tailing is a different trade-off and an explicit non-goal.
Not affiliated with the NestJS core team.

Where to find it

The app: github.com/nest-native/reference-app — start with the README's story, then docs/architecture.md
The org + all six packages: github.com/nest-native
Docs hub: nest-native.dev

Feedback, issues, and "this seam is still awkward" reports are the most useful thing you can send — that's literally the mechanism this whole stack improves by.

Introducing @nest-native/drizzle: A Nest-native Drizzle ORM integration

Rodrigo Nogueira — Sun, 17 May 2026 05:11:11 +0000

Renamed: this project was originally published as nest-drizzle-native and is now the scoped @nest-native/drizzle (repo: nest-native/drizzle). Same library, same public API — only the package name changed. To migrate: npm uninstall nest-drizzle-native && npm install @nest-native/drizzle, then update imports to @nest-native/drizzle.

@nest-native/drizzle is a community package designed to make Drizzle ORM feel entirely natural inside NestJS applications.

The core concept is straightforward: preserve Drizzle's explicit, SQL-first philosophy while giving NestJS projects the module, dependency injection, repository, testing, and transaction ergonomics they expect.

The Motivation

Drizzle is excellent because it stays close to SQL and avoids heavy, opaque ORM magic.

NestJS, on the other hand, provides applications with a strong architectural shape built around modules, providers, decorators, testing utilities, lifecycle hooks, and clear dependency boundaries.

A bridge between those two worlds allows teams to build scalable enterprise architectures without turning Drizzle into something it is not. Existing solutions often act as thin connection wrappers, leaving developers to manually solve complex enterprise patterns like cross-service transactions or DTO co-generation.

What it supports today

DrizzleModule.forRoot(), forRootAsync(), and forFeature()
@InjectDrizzle() for direct Drizzle client injection
@DrizzleRepository() for query-focused provider classes
@Transactional() / @InjectTransaction() powered natively via @nestjs-cls/transactional
Named connections for multi-database applications
Testing utilities for clean module and repository testing
Zero runtime dependencies in the published library package
Runnable samples covering transactions, DTO validation, optional drizzle-zod validation, Swagger/OpenAPI integration, raw SQL execution, and various driver setups

Let's look at the code

The biggest pain point of using Drizzle in a structured backend is transaction management. Passing a tx object through five layers of injected services completely breaks Dependency Injection.

With @nest-native/drizzle, transactions are propagated through the CLS transaction context used by @nestjs-cls/transactional, allowing them to flow seamlessly across your services just by using a decorator:

import { Injectable } from '@nestjs/common';
import { Transactional } from '@nest-native/drizzle';
import { AuditService } from './audit.service';
import { UsersRepository } from './users.repository';
import { CreateUserDto } from './create-user.dto';

@Injectable()
export class UsersService {
  constructor(
    private readonly usersRepository: UsersRepository,
    private readonly auditService: AuditService,
  ) {}

  @Transactional()
  async createUser(data: CreateUserDto) {
    const user = await this.usersRepository.insert(data);

    await this.auditService.logAction('USER_CREATED', user.id);

    return user;
  }
}

The repository itself is a clean Nest provider that keeps Drizzle's query builder visible instead of hiding SQL behind an Active Record layer:

import { eq } from 'drizzle-orm';
import {
  DrizzleRepository,
  InjectDrizzle,
} from '@nest-native/drizzle';
import type { AppDatabase } from './database';
import { users } from './schema';
import { CreateUserDto } from './create-user.dto';

@DrizzleRepository()
export class UsersRepository {
  constructor(@InjectDrizzle() private readonly db: AppDatabase) {}

  async insert(data: CreateUserDto) {
    const [user] = await this.db
      .insert(users)
      .values(data)
      .returning();

    return user;
  }

  async findById(id: string) {
    const [user] = await this.db
      .select()
      .from(users)
      .where(eq(users.id, id))
      .limit(1);

    return user;
  }
}

What it does not try to do

The goal is strictly to avoid re-creating TypeORM or an Active Record layer.

Developers still write real, functional Drizzle queries. The library simply provides those queries with a native NestJS structure through decorators and context management, eliminating the need to pass transaction callbacks (tx) down through multiple layers of services.

Links

Docs: https://nest-native.dev/drizzle/
GitHub: https://github.com/nest-native/drizzle
npm: https://www.npmjs.com/package/@nest-native/drizzle
Releases: https://github.com/nest-native/drizzle/releases/latest

Community feedback from NestJS and Drizzle users is highly encourage — especially regarding real-world transaction patterns, testing strategies, multi-database setups, and production adoption. Feel free to open issues or contribute to the repository!

nest-trpc-native: Full NestJS Power + tRPC Type Safety with Zero Runtime Overhead

Rodrigo Nogueira — Tue, 17 Mar 2026 17:24:47 +0000

Hey NestJS + tRPC community! 👋

I’m excited to release nest-trpc-native v0.3.0 — a decorator-first, native-feeling tRPC integration for NestJS.

No adapter glue code in your app layer. No compromise on NestJS features.

You write tRPC routers like Nest classes, with full support for dependency injection, guards, interceptors, pipes, filters, request-scoped providers, and end-to-end type safety.

Why this matters

Most tRPC + NestJS approaches push you toward one side:

Keep all NestJS lifecycle features, but lose clean tRPC developer experience, or
Keep pure tRPC style, but lose NestJS enhancers and request-scoped DI.

nest-trpc-native is designed so you can have both.

Core Features

@Router('users') + @Query(), @Mutation(), @Subscription()
Full support for @UseGuards(), @UseInterceptors(), @UsePipes(ValidationPipe), @UseFilters()
@Input() and @TrpcContext() for parameter extraction
Auto-generated router types (autoSchemaFile: 'src/@generated/server.ts')
Works with Express and Fastify
Zod or classic class-validator validation
Zero runtime dependencies in nest-trpc-native itself (host app controls Nest/tRPC peers)
Monorepo-friendly sample layout
Microservice transport pattern demonstrated in a focused sample

Router Example (NestJS style)

@Router('users')
@UseGuards(AuthGuard)
export class UsersRouter {
  constructor(private readonly usersService: UsersService) {}

  @Query({ input: FindOneSchema, output: UserSchema.nullable() })
  @UsePipes(new ValidationPipe({ transform: true }))
  findOne(
    @Input() input: { id: number },
    @TrpcContext('requestId') requestId: string,
  ) {
    return this.usersService.findById(input.id);
  }

  @Mutation({ input: CreateUserSchema, output: UserSchema })
  create(@Input() input: { name: string; email: string }) {
    return this.usersService.create(input);
  }
}

Client side stays fully type-safe:

const user = await trpc.users.findOne.query({ id: 123 });
// autocomplete + compile-time safety

Installation

npm install nest-trpc-native @trpc/server
npm install @nestjs/common @nestjs/core reflect-metadata rxjs
# optional:
npm install zod

Then register the module:

TrpcModule.forRoot({
  path: '/trpc',
  autoSchemaFile: 'src/@generated/server.ts',
})

Samples You Can Run Now

sample/00-showcase: full integration baseline (guards, interceptors, pipes, filters, request scope, Express/Fastify, typed clients, subscriptions)
sample/11-microservice-transport: tRPC edge gateway + Nest microservice transport (TCP)

From repo root:

npm run showcase

Docs, Repo, and NPM

Docs: https://rodrigobnogueira.github.io/nest-trpc-native/docs/introduction

Repo: https://github.com/rodrigobnogueira/nest-trpc-native

NPM: https://www.npmjs.com/package/nest-trpc-native

Try it, break it, open issues, and share feedback.

Thanks!