Database setup

Set up Drizzle without coupling modules to your database

Use Drizzle as the PostgreSQL migration and query layer while keeping ContractSpec modules portable. Compose schemas from module contributions, apply migrations explicitly, seed deterministic fixtures, and bind AuthOS, BillingOS, and RBAC through host-owned adapters.

Install the database boundary

bun add drizzle-orm drizzle-kit @lssm-tech/lib.schema @lssm-tech/integration.provider-database @lssm-tech/lib.identity-rbac

Drizzle owns SQL schema and migrations. ContractSpec owns portable entities, domain contracts, RBAC policy semantics, and governed database operation envelopes.

Recommended setup flow

• Compose database entities from module schema contributions before writing Drizzle tables by hand.
• Generate or maintain a Drizzle PostgreSQL schema from the composed model, then keep the Drizzle schema as migration input.
• Use drizzle-kit generate for migration files, drizzle-kit migrate for applying them, and custom migrations for RLS, seed prerequisites, or unsupported DDL.
• Bind runtime reads and writes through @lssm-tech/integration.provider-database instead of importing Drizzle into modules such as AuthOS or BillingOS.
• Seed tenants, users, roles, permissions, and minimal domain fixtures in deterministic order after migrations and before UI demos/tests.
• Fail closed on RBAC data access: tenant id, actor id, policy decision, idempotency key, audit refs, and expected write sets must be explicit for governed writes.

Drizzle configuration

Keep drizzle.config.ts, src/db/schema.ts, and the drizzle/ migration folder in the host app or deployment package. Do not place provider credentials or migration side effects inside reusable modules.

1// drizzle.config.ts
2import { defineConfig } from "drizzle-kit";
3
4export default defineConfig({
5  dialect: "postgresql",
6  schema: "./src/db/schema.ts",
7  out: "./drizzle",
8  dbCredentials: { url: process.env.DATABASE_URL! },
9  strict: true,
10});

Compose module schemas

Start with reusable contributions such as identityRbacSchemaContribution, then add host-owned entities for AuthOS adapters and BillingOS persistence. Generate Drizzle tables from that composed source or keep a reviewed generated schema checked in.

1import { composeModuleDatabaseSchemas } from "@lssm-tech/lib.schema";
2import { identityRbacSchemaContribution } from "@lssm-tech/lib.identity-rbac/entities";
3
4const schemaSource = composeModuleDatabaseSchemas([
5  identityRbacSchemaContribution,
6  authHostSchemaContribution,
7  billingHostSchemaContribution,
8]);
9
10await writeFile("src/db/schema.ts", schemaSource);

Bind modules through providers and ports

Use @lssm-tech/integration.provider-database for tenant-scoped providers, governed reads, and governed mutations. AuthOS and BillingOS should receive host adapters, not raw Drizzle clients.

1import { createTenantScopedDatabaseProvider } from "@lssm-tech/integration.provider-database/impls";
2
3const tenantDb = createTenantScopedDatabaseProvider({
4  provider: postgresDatabaseProvider,
5  tenantId: session.tenantId,
6});
7
8export const billingPorts = {
9  searchCustomers: (query) => customerRepository.search(tenantDb, query),
10  searchSellableItems: (query) => priceBookRepository.search(tenantDb, query),
11};

Seed in dependency order

• Tenant/workspace rows and environment metadata.
• Identity rows: users, accounts, sessions, organizations, members, teams.
• RBAC rows: roles, permissions, policy bindings, and deny fixtures.
• Domain fixtures: BillingOS customers, price books, quotes, invoices, and payment evidence.
• Audit and replay rows used by governed mutation tests.