Skip to content

0006. Drizzle ORM

  • Status: Accepted
  • Date: 2026-10-01

Context

BizOS uses PostgreSQL with one control-plane database and one database per tenant. The data layer must open connections to many tenant databases at runtime, run the same migrations against every tenant database, keep each DDD module owning its own tables, and stay fully typed in TypeScript.

Options considered

  1. TypeORM: mature NestJS integration, but decorator entities mix persistence into the domain, and its typing and migration tooling are weaker.
  2. Prisma: excellent developer experience, but one generated client per schema and a separate query engine make per-tenant connections and per-module schemas awkward.
  3. MikroORM: good unit-of-work model, but heavier and more opinionated than we need.
  4. Drizzle ORM: schema defined in plain TypeScript, SQL-like typed queries, a lightweight instance per connection pool, and drizzle-kit for generated SQL migrations.

Decision

Use Drizzle ORM with the node-postgres (pg) driver, and drizzle-kit to generate and apply migrations. Use stable releases until Drizzle 1.0 is final.

Consequences

  • A Drizzle instance per tenant pool is cheap, so TenantDatabaseManager can serve many tenant databases.
  • Schema files live in each module's infrastructure/, keeping persistence out of domain/; repositories map between rows and domain objects.
  • Migrations are plain SQL files reviewed in pull requests.
  • Drizzle has no NestJS module of its own; we provide one in @bizos/api-shared.
  • Moving to Drizzle 1.0 will need an upgrade pass when it is released.