@fluojs/drizzle

@fluojs/drizzle

English 한국어

Drizzle ORM integration for fluo with a transaction-aware database wrapper and an optional dispose hook.

Table of Contents

• Installation
• When to Use
• Quick Start
• Common Patterns
  • Use DrizzleDatabase.current() inside repositories
  • Manual transaction boundaries
  • Request-scoped transactions with an interceptor
  • Shutdown and status contracts
• Manual Module Composition
• Public API Overview
• Related Packages
• Example Sources

Installation

npm install @fluojs/drizzle drizzle-orm
# Install the driver for your Drizzle adapter as well, for example:
npm install pg

When to Use

• when Drizzle should participate in the same module, DI, and lifecycle model as the rest of the app
• when repositories need a single current() seam that switches between the root handle and the active transaction handle
• when application shutdown should also run an explicit cleanup hook for the underlying driver resources

Quick Start

import { ConfigService } from '@fluojs/config';
import { Module } from '@fluojs/core';
import { DrizzleModule } from '@fluojs/drizzle';
import { drizzle } from 'drizzle-orm/node-postgres';
import { Pool } from 'pg';

@Module({
  imports: [
    DrizzleModule.forRootAsync({
      inject: [ConfigService],
      useFactory: async (config: ConfigService) => {
        const pool = new Pool({
          connectionString: config.getOrThrow<string>('DATABASE_URL'),
        });

        return {
          database: drizzle(pool),
          dispose: async () => {
            await pool.end();
          },
        };
      },
    }),
  ],
})
export class AppModule {}

Common Patterns

Use DrizzleDatabase.current() inside repositories

import { DrizzleDatabase } from '@fluojs/drizzle';
import { eq } from 'drizzle-orm';
import { users } from './schema';

export class UserRepository {
  constructor(private readonly db: DrizzleDatabase) {}

  async findById(id: string) {
    return this.db.current().select().from(users).where(eq(users.id, id));
  }
}

Manual transaction boundaries

await this.db.transaction(async () => {
  const tx = this.db.current();
  await tx.insert(users).values(user);
  await tx.insert(profiles).values(profile);
});

Nested calls reuse the active transaction boundary. If a nested call passes transaction options while a boundary is already active, the package rejects those nested options instead of silently changing the existing transaction.

When database.transaction(...) is unavailable and strictTransactions is false, transaction() and requestTransaction() fall back to direct execution; request-scoped calls still honor AbortSignal.

Request-scoped transactions with an interceptor

import { UseInterceptors } from '@fluojs/http';
import { DrizzleTransactionInterceptor } from '@fluojs/drizzle';

@UseInterceptors(DrizzleTransactionInterceptor)
class UsersController {}

Shutdown and status contracts

DrizzleTransactionInterceptor runs each HTTP request through DrizzleDatabase.requestTransaction(...). During application shutdown, DrizzleDatabase aborts any still-active request transaction, waits for open request and manual transaction callbacks to settle or roll back, and only then runs the optional dispose(database) hook. This ordering lets drivers finish commit/rollback/cleanup work before pools or externally managed resources are closed. Nested requestTransaction(...) calls opened inside an existing request boundary observe the ambient request abort signal while still reusing the active Drizzle transaction. Nested requestTransaction(...) calls opened inside an existing manual transaction boundary also join shutdown settlement tracking without opening a second Drizzle transaction, and their settlement handle remains tracked until the outer manual transaction settles so shutdown drains that outer boundary before dispose(database) runs. The platform status activity count is intentionally shorter lived: once the nested request callback settles, details.activeRequestTransactions is decremented even if the outer manual transaction continues running. New transaction(...) and requestTransaction(...) calls are rejected once shutdown begins, so disposal cannot overtake a late transaction that starts after the shutdown boundary is crossed. If the request signal aborts after the request callback has completed but before the underlying Drizzle transaction runner finishes committing or rolling back, requestTransaction(...) waits for that runner to settle first and then rejects with the abort reason. This keeps Drizzle cleanup serialized with request cancellation while making the late request abort visible to the caller instead of returning the completed callback result.

createDrizzlePlatformStatusSnapshot(...) and DrizzleDatabase.createPlatformStatusSnapshot() expose the same contract to diagnostics surfaces:

• readiness.status is not-ready while Drizzle is shutting down or stopped, and when strictTransactions is enabled without database.transaction(...) support.
• health.status is degraded while request transactions are draining during shutdown and unhealthy after disposal.
• details.activeRequestTransactions, details.lifecycleState, details.strictTransactions, and details.supportsTransaction describe the current request transaction and transaction-capability state.
• details.transactionContext: 'als' identifies the async-local transaction context used by request and service transaction boundaries.
• ownership.externallyManaged: true and ownership.ownsResources: false mean the package runs your configured dispose hook but does not claim ownership of the underlying driver resources.

Manual Module Composition

Use DrizzleModule.forRoot(...) / forRootAsync(...) to register Drizzle. When you need to compose Drizzle support inside a custom defineModule(...) registration, import the module entrypoint there as well.

import { defineModule } from '@fluojs/runtime';
import { DrizzleDatabase, DrizzleModule, DrizzleTransactionInterceptor } from '@fluojs/drizzle';

const database = {
  transaction: async <T>(callback: (tx: typeof database) => Promise<T>) => callback(database),
};

class ManualDrizzleModule {}

defineModule(ManualDrizzleModule, {
  exports: [DrizzleDatabase, DrizzleTransactionInterceptor],
  imports: [DrizzleModule.forRoot({ database })],
});

Public API Overview

• DrizzleModule.forRoot(options) / DrizzleModule.forRootAsync(options)
• DrizzleDatabase
• DrizzleTransactionInterceptor
• DRIZZLE_DATABASE, DRIZZLE_DISPOSE, DRIZZLE_HANDLE_PROVIDER, DRIZZLE_OPTIONS
• createDrizzlePlatformStatusSnapshot(...)
• DrizzleDatabaseLike
• DrizzleModuleOptions
• DrizzleHandleProvider

DRIZZLE_HANDLE_PROVIDER is an alias token for the lifecycle-aware DrizzleDatabase wrapper. Health integrations such as @fluojs/terminus use this token to read createPlatformStatusSnapshot() before falling back to raw database pings.

DrizzleModule

• DrizzleModule.forRoot(options) / DrizzleModule.forRootAsync(options)
• forRootAsync(...) accepts DI-aware Drizzle options whose factory returns the database/dispose/transaction settings; pass global on the top-level async registration when the providers should be visible globally.
• forRootAsync(...) resolves options once per application container. Reusing the same module definition across tests or multi-app processes creates isolated database/dispose results for each container instead of sharing a memoized factory result.
• Supports strictTransactions: true to throw if transaction support is missing.

Related Packages

• @fluojs/runtime: owns module startup and shutdown sequencing
• @fluojs/http: provides the interceptor pipeline used for request transactions
• @fluojs/prisma and @fluojs/mongoose: alternate ORM/ODM integrations with the same fluo runtime model

Example Sources

• packages/drizzle/src/vertical-slice.test.ts
• packages/drizzle/src/module.test.ts
• packages/drizzle/src/public-api.test.ts