Drizzle API

Generated public TypeScript reference for @relkit/drizzle.

Common APIs

• defineDrizzleService
• defineModel
• activateDrizzleService

For configuration and examples, read Database, local docker, drizzle.

For a complete workflow, follow register users in a transaction, email password sign in.

Public imports

• @relkit/drizzle — 23 exports
• @relkit/drizzle/sqlite — 24 exports
• @relkit/drizzle/pg — 24 exports
• @relkit/drizzle/mysql — 24 exports

All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API’s inline sample, a maintained repository usage, or the shared module walkthrough.

activate.ts

Validates the selected ORM before loading runtime activation or calling the native factory.

activateDrizzleService

Acquires a database using the existing owner after selected dependency validation.

Signature

declare const activateDrizzleService: <
  Service extends DrizzleServiceDescriptor<any, any, any, any>,
>(
  service: Service,
  env: Readonly<Record<string, unknown>>,
  options?: DrizzleActivationOptions,
) => Promise<DrizzleActivation<Service>>;

Source

activation.ts

activateDrizzleService

Activates a service once per descriptor object and returns its client, context, and close hook. Repeated calls share the first activation; close does not evict the cached activation. Isolated acquisition bypasses that cache and transfers close ownership to the caller.

Example

import { activateDrizzleService, defineDrizzleService } from "@relkit/drizzle";
import { integer, sqliteTable } from "drizzle-orm/sqlite-core";

if (typeof Bun !== "undefined") {
  const { Database } = await import("bun:sqlite");
  const { drizzle } = await import("drizzle-orm/bun-sqlite");
  const users = sqliteTable("users", { id: integer().primaryKey() });
  const service = defineDrizzleService({
    schema: { users },
    client: () => drizzle({ client: new Database(":memory:") }),
    dispose: (database) => database.$client.close(),
  });
  const active = await activateDrizzleService(service, {});
  try {
    console.assert(active.context.users !== undefined);
  } finally {
    await active.close();
  }
}

Signature

declare const activateDrizzleService: <
  Service extends DrizzleServiceDescriptor<any, any, any, any>,
>(
  service: Service,
  env: Readonly<Record<string, unknown>>,
  options?: DrizzleActivationOptions,
) => Promise<DrizzleActivation<Service>>;

Source

Since v0.1.0

DrizzleActivation

Signature

declare const DrizzleActivation: DrizzleActivation<Service>;

Source

DrizzleActivationOptions

Signature

declare const DrizzleActivationOptions: DrizzleActivationOptions;

Source

activation.types.ts

DrizzleActivation (interface)

Frozen public activation; resource ownership ends at close.

Signature

export interface DrizzleActivation<Service extends DrizzleServiceDescriptor<any, any, any, any>> {
  /** Native escape hatch; callers must use admitted APIs to guarantee orderly close. */
  readonly client: Service extends DrizzleServiceDescriptor<any, infer Client, any, any>
    ? Client
    : never;
  readonly context: DatabaseContext<Service>;
  /**
   * Stops admission and releases the owner after admitted native work settles.
   * @returns Shared close Promise; later calls observe the same completion.
   */
  readonly close: () => Promise<void>;
}

Source

DrizzleActivationOptions (interface)

Acquisition policy for an application that owns its database lifetime.

Signature

export interface DrizzleActivationOptions {
  /** Bypasses descriptor sharing; the caller must close this activation. */
  readonly isolated?: boolean;
  /** Configured observation services captured by the compatibility owner. */
  readonly instrumentation?: Context.Context<never>;
}

Source

context.ts

createDatabaseContext

Constructs models without acquiring another client.

See

• activateDrizzleService for the checked public owner lifecycle.

Signature

declare const createDatabaseContext: <Service extends DrizzleServiceDescriptor<any, any, any, any>>(
  service: Service,
  runtime: DrizzleServiceRuntime,
  database: unknown,
  run: ContextRunner,
) => DatabaseContext<Service>;

Source

context.types.ts

ContextRunner (type alias)

Executes work at the existing owner edge; transaction children borrow their parent lease.

Signature

type ContextRunner = <A>(effect: Effect.Effect<A, DrizzleFailure>, operation: string) => Promise<A>;

Source

coordination.ts

withDrizzleSqliteWork

Coordinates raw specialized SDK work with portable SQLite operations.

Signature

declare const withDrizzleSqliteWork: <A, E, R>(
  activation: object,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E | DrizzleFailure, R>;

Source

failure.ts

DrizzleFailure (class)

Expected native database, validation or owner-admission failure.

Signature

declare class DrizzleFailure

Source

nativeCall

Suspends an uncancellable SDK call until actual completion.

See

• runDrizzlePromise for execution at the owning runtime boundary.

Signature

declare const nativeCall: <A>(
  operation: string,
  run: () => A | PromiseLike<A>,
) => Effect.Effect<A, DrizzleFailure, never>;

Source

runDrizzlePromise

Executes a compatibility edge retaining original native rejection identity.

Example

import { Effect, Layer, ManagedRuntime } from "effect";
import { runDrizzlePromise } from "@relkit/drizzle/internal";
const owner = ManagedRuntime.make(Layer.empty);
try {
  await runDrizzlePromise(owner, Effect.succeed(1));
} finally {
  await owner.dispose();
}

Signature

declare const runDrizzlePromise: <A, E, R, ER>(
  runtime: ManagedRuntime.ManagedRuntime<R, ER>,
  effect: Effect.Effect<A, E, R>,
  options?: Effect.RunOptions,
) => Promise<A>;

Source

squashDrizzleCause

Translates one native failure without erasing mixed cleanup/interruption causes.

Signature

declare const squashDrizzleCause: <E>(cause: Cause.Cause<E>) => unknown;

Source

index.ts

Lazy Drizzle declarations and stable Promise model/transaction compatibility APIs.

ApplicationEnv

Signature

declare const ApplicationEnv: Readonly<Record<string, string>>;

Source

BaseOperations

Signature

declare const BaseOperations: BaseOperations<T>;

Source

DatabaseContext

Signature

declare const DatabaseContext: DatabaseContext<Service>;

Source

DeleteArgs

Signature

declare const DeleteArgs: DeleteArgs<T>;

Source

DrizzleActivationOptions

Signature

declare const DrizzleActivationOptions: DrizzleActivationOptions;

Source

DrizzleCapability

Signature

declare const DrizzleCapability: DrizzleCapability;

Source

DrizzleOverrides

Signature

declare const DrizzleOverrides: DrizzleOverrides<Tables>;

Source

DrizzleServiceDescriptor

Signature

declare const DrizzleServiceDescriptor: DrizzleServiceDescriptor<Id, Client, Schema, Models>;

Source

FindManyArgs

Signature

declare const FindManyArgs: FindManyArgs<T>;

Source

FindOneArgs

Signature

declare const FindOneArgs: FindOneArgs<T>;

Source

InsertArgs

Signature

declare const InsertArgs: InsertArgs<T>;

Source

ModelDescriptor

Signature

declare const ModelDescriptor: ModelDescriptor<T, Extensions>;

Source

ModelExtensionContext

Signature

declare const ModelExtensionContext: ModelExtensionContext<T, Database>;

Source

Row

Signature

declare const Row: {
  [
    K in keyof {
      [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true
        ? T["_"]["columns"][Key]["_"]["data"]
        : T["_"]["columns"][Key]["_"]["data"] | null;
    }
  ]: {
    [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true
      ? T["_"]["columns"][Key]["_"]["data"]
      : T["_"]["columns"][Key]["_"]["data"] | null;
  }[K];
};

Source

TableOverrides

Signature

declare const TableOverrides: TableOverrides<T>;

Source

TableZodSchemas

Signature

declare const TableZodSchemas: TableZodSchemas<T>;

Source

Update

Signature

declare const Update: Partial<{
  [
    K in keyof ({
      [
        Key in keyof T["_"]["columns"] & string as RequiredKeyOnly<Key, T["_"]["columns"][Key]>
      ]: T["_"]["columns"][Key]["_"]["notNull"] extends true
        ? T["_"]["columns"][Key]["_"]["data"]
        : T["_"]["columns"][Key]["_"]["data"] | null;
    } & {
      [
        Key in keyof T["_"]["columns"] & string as OptionalKeyOnly<
          Key,
          T["_"]["columns"][Key],
          false
        >
      ]?:
        | (T["_"]["columns"][Key]["_"]["notNull"] extends true
            ? T["_"]["columns"][Key]["_"]["data"]
            : T["_"]["columns"][Key]["_"]["data"] | null)
        | undefined;
    })
  ]: ({
    [
      Key in keyof T["_"]["columns"] & string as RequiredKeyOnly<Key, T["_"]["columns"][Key]>
    ]: T["_"]["columns"][Key]["_"]["notNull"] extends true
      ? T["_"]["columns"][Key]["_"]["data"]
      : T["_"]["columns"][Key]["_"]["data"] | null;
  } & {
    [
      Key in keyof T["_"]["columns"] & string as OptionalKeyOnly<Key, T["_"]["columns"][Key], false>
    ]?:
      | (T["_"]["columns"][Key]["_"]["notNull"] extends true
          ? T["_"]["columns"][Key]["_"]["data"]
          : T["_"]["columns"][Key]["_"]["data"] | null)
      | undefined;
  })[K];
}>;

Source

UpdateArgs

Signature

declare const UpdateArgs: UpdateArgs<T>;

Source

UpsertArgs

Signature

declare const UpsertArgs: UpsertArgs<T>;

Source

Where

Signature

declare const Where: Partial<{
  [
    K in keyof {
      [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true
        ? T["_"]["columns"][Key]["_"]["data"]
        : T["_"]["columns"][Key]["_"]["data"] | null;
    }
  ]: {
    [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true
      ? T["_"]["columns"][Key]["_"]["data"]
      : T["_"]["columns"][Key]["_"]["data"] | null;
  }[K];
}>;

Source

activateDrizzleService

Signature

declare const activateDrizzleService: <
  Service extends DrizzleServiceDescriptor<any, any, any, any>,
>(
  service: Service,
  env: Readonly<Record<string, unknown>>,
  options?: DrizzleActivationOptions,
) => Promise<DrizzleActivation<Service>>;

Source

defineDrizzleService

Signature

declare const defineDrizzleService: <
  Client,
  const Schema extends Readonly<Record<string, unknown>>,
  const Models extends DrizzleModelMap<TablesOf<Schema>> = {},
>(
  options: DefineDrizzleServiceOptions<Client, Schema, Models>,
) => DrizzleServiceDescriptor<string, Client, Schema, Models>;

Source

defineModel

Signature

declare const defineModel: <
  const T extends Table,
  const Extensions extends ModelExtensionMap<T>,
>(options: {
  readonly table: T;
  readonly extend: NonEmptyExtensions<Extensions>;
}) => ModelDescriptor<T, Extensions>;

Source

internal.ts

Server-only runtime ownership, typed failures and borrowed-work composition.

DrizzleActivation

Signature

declare const DrizzleActivation: DrizzleActivation<Service>;

Source

DrizzleFailure

Signature

declare const DrizzleFailure: typeof DrizzleFailure;

Source

DrizzleOwner

Signature

declare const DrizzleOwner: typeof DrizzleOwner;

Source

DrizzleOwnerInterface

Signature

declare const DrizzleOwnerInterface: DrizzleOwnerInterface;

Source

DrizzleServiceDescriptor

Signature

declare const DrizzleServiceDescriptor: DrizzleServiceDescriptor<Id, Client, Schema, Models>;

Source

activateDrizzleService

Signature

declare const activateDrizzleService: <
  Service extends DrizzleServiceDescriptor<any, any, any, any>,
>(
  service: Service,
  env: Readonly<Record<string, unknown>>,
  options?: DrizzleActivationOptions,
) => Promise<DrizzleActivation<Service>>;

Source

drizzleInstrumentationOf

Signature

declare const drizzleInstrumentationOf: (activation: object) => Context<never>;

Source

drizzleOwnerLayer

Signature

declare const drizzleOwnerLayer: (
  declaration: DrizzleServiceRuntime,
  env: Readonly<Record<string, unknown>>,
) => Layer<DrizzleOwner, DrizzleFailure, never>;

Source

drizzleRuntimeOf

Signature

declare const drizzleRuntimeOf: (value: object) => DrizzleServiceRuntime;

Source

inheritNativeLeases

Signature

declare const inheritNativeLeases: <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;

Source

nativeCall

Signature

declare const nativeCall: <A>(
  operation: string,
  run: () => A | PromiseLike<A>,
) => Effect<A, DrizzleFailure, never>;

Source

observeSpecializedOperation

Signature

declare const observeSpecializedOperation: <A, E, R>(
  operation: `database.${string}` | `auth.${string}`,
  effect: Effect<A, E, R>,
) => Effect<A, E, R>;

Source

operationEffect

Signature

declare const operationEffect: (
  binding: ModelBinding,
  name: string,
  args: unknown,
) => Effect<unknown, DrizzleFailure>;

Source

redactSpecializedTrace

Signature

declare const redactSpecializedTrace: <A, E, R>(
  effect: Effect<A, E, R>,
) => Effect<A, E, Exclude<R, never>>;

Source

runDrizzlePromise

Signature

declare const runDrizzlePromise: <A, E, R, ER>(
  runtime: ManagedRuntime<R, ER>,
  effect: Effect<A, E, R>,
  options?: RunOptions,
) => Promise<A>;

Source

runDrizzleWorkPromise

Signature

declare const runDrizzleWorkPromise: <A, E>(activation: object, effect: Effect<A, E>) => Promise<A>;

Source

runSpecializedTrace

Signature

declare const runSpecializedTrace: <A>(operation: string, run: () => Promise<A>) => Promise<A>;

Source

squashDrizzleCause

Signature

declare const squashDrizzleCause: <E>(cause: Cause<E>) => unknown;

Source

withDrizzleSqliteWork

Signature

declare const withDrizzleSqliteWork: <A, E, R>(
  activation: object,
  effect: Effect<A, E, R>,
) => Effect<A, E | DrizzleFailure, R>;

Source

withDrizzleWork

Signature

declare const withDrizzleWork: <A, E, R>(
  activation: object,
  effect: Effect<A, E, R>,
) => Effect<A, E | DrizzleFailure, R>;

Source

metadata.ts

Extracts native table and column metadata for portable model validation and activation. Dialect table utilities avoid importing unrelated native driver database declarations.

dialectFor

Resolves a supported table dialect using Drizzle’s entity guards.

Throws

TypeError for unsupported entities.

Signature

declare const dialectFor: (table: Table) => "pg" | "mysql" | "sqlite";

Source

extractTables

Filters relations and other schema values from supported tables.

Throws

TypeError when no supported table exists.

Signature

declare const extractTables: (schema: Readonly<Record<string, unknown>>) => TableMap;

Source

inspectTables

Discovers one consistent dialect and unique table selectors.

Throws

TypeError for absent tables or mixed/unsupported dialects.

Signature

declare const inspectTables: (tables: TableMap) => {
  readonly dialect: "pg" | "mysql" | "sqlite";
  readonly metadata: Readonly<Record<string, TableMetadata>>;
};

Source

model.ts

Declares frozen model extensions and binds their native calls to the owning database admission scope. Dialect leaves provide precise database methods while shared descriptors preserve authored operation inference.

defineModel

Adds named table methods with an injected table and transaction-aware Drizzle client. Use service overrides, not extensions, to replace the six reserved CRUD operations. Select a dialect entrypoint when an extension uses the injected native database.

Throws

TypeError for missing, non-callable or reserved extensions.

Example

import { defineModel } from "@relkit/drizzle/sqlite";
import { integer, sqliteTable } from "drizzle-orm/sqlite-core";

const users = sqliteTable("users", { id: integer().primaryKey() });
const model = defineModel({
  table: users,
  extend: { firstTen: ({ table, database }) => database.select().from(table).limit(10) },
});
console.assert(model.extensionNames.includes("firstTen"));

Signature

declare const defineModel: <
  const T extends Table,
  const Extensions extends ModelExtensionMap<T>,
>(options: {
  readonly table: T;
  readonly extend: NonEmptyExtensions<Extensions>;
}) => ModelDescriptor<T, Extensions>;

Source

Since v0.1.0

RESERVED_OPERATIONS

Reserved base operations; authored extensions may not shadow these names.

Signature

declare const RESERVED_OPERATIONS: readonly [
  "findOne",
  "findMany",
  "insert",
  "update",
  "upsert",
  "delete",
];

Source

createBoundModel

Binds public Promise methods to the owning Effect workflows.

Signature

declare const createBoundModel: (binding: ModelBinding, model?: ModelDescriptorAny) => object;

Source

modelRuntimeOf

Resolves hidden pure extension metadata.

Throws

TypeError for invalid descriptors.

Signature

declare const modelRuntimeOf: (value: ModelDescriptorAny) => ModelRuntime;

Source

model.types.ts

Native model injection contracts without an implicit database driver selection.

DefineModel (type alias)

Native model authoring signature specialized by an explicitly selected dialect entrypoint.

Signature

type DefineModel<Database> = <
  const T extends Table,
  const Extensions extends ModelExtensionMap<T, Database>,
>(options: {
  readonly table: T;
  readonly extend: NonEmptyExtensions<Extensions>;
}) => ModelDescriptor<T, Extensions>;

Source

ModelDescriptor (interface)

Frozen lazy model descriptor retaining authored extension types.

Signature

export interface ModelDescriptor<
  T extends Table,
  Extensions extends ModelExtensionMap<T> = ModelExtensionMap<T>,
> {
  readonly table: T;
  readonly extensionNames: readonly Extract<keyof Extensions, string>[];
  readonly [MODEL_TYPES]: Extensions;
}

Source

ModelDescriptorAny (type alias)

Internal erased model descriptor used for pure discovery.

Signature

type ModelDescriptorAny = ModelDescriptor<Table, ModelExtensionMap<Table>>;

Source

ModelExtension (type alias)

Authored native extension with inferred caller arguments/results.

Signature

type ModelExtension<T extends Table, Database = never> = (
  context: ModelExtensionContext<T, Database>,
  ...args: any[]
) => unknown;

Source

ModelExtensionContext (interface)

Injected table and transaction-bound native database.

Signature

export interface ModelExtensionContext<T extends Table, Database = never> {
  readonly table: T;
  readonly database: Database;
}

Source

ModelExtensionMap (type alias)

Named authored extension functions.

Signature

type ModelExtensionMap<T extends Table, Database = never> = Readonly<
  Record<string, ModelExtension<T, Database>>
>;

Source

NonEmptyExtensions (type alias)

Rejects declarations without any custom methods.

Signature

type NonEmptyExtensions<Extensions extends Readonly<Record<string, unknown>>> =
  keyof Extensions extends never ? never : Extensions;

Source

mutations.ts

insert

Inserts one row, recovering MySQL rows via a declared unique key.

Signature

declare const insert: (
  binding: ModelBinding,
  data: unknown,
) => Effect.Effect<unknown, DrizzleFailure, never>;

Source

remove

Deletes one row while preserving dialect return behavior.

Signature

declare const remove: (
  binding: ModelBinding,
  where: Record<string, unknown>,
) => Effect.Effect<{} | null, DrizzleFailure, never>;

Source

update

Updates one selected row with dialect-aware returning/recovery.

Signature

declare const update: (
  binding: ModelBinding,
  where: Record<string, unknown>,
  data: unknown,
) => Effect.Effect<{} | null, DrizzleFailure, never>;

Source

mysql.ts

mysql native model typing; imports only this selected dialect’s upstream declarations.

“./index.js” (namespace export)

Re-exports all named exports from the “./index.js” module.

Signature

export * from "./index.js";

Source

DialectDatabase (type alias)

Native database injected into model extensions for the selected dialect.

Signature

type DialectDatabase = Omit<MySqlAsyncDatabase<any, any>, "query">;

Source

defineModel

Declares lazy native extensions with this dialect’s real transaction client type.

Signature

declare const defineModel: DefineModel<DialectDatabase>;

Source

native-leases.ts

NativeLeases

Effect-local owner/physical-client leases, absent for independent callers.

Signature

declare const NativeLeases: Context.Reference<NativeLeaseContext>;

Source

closeNativeLease

Drains retained descendants, then atomically closes the token at zero.

Signature

declare const closeNativeLease: (lease: NativeLease) => Effect.Effect<void, never, never>;

Source

inheritNativeLeases

Carries active parent leases into a new native Promise execution edge.

Signature

declare const inheritNativeLeases: <A, E, R>(
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;

Source

makeNativeLease

Creates an Effect-owned descendant lease.

Signature

declare const makeNativeLease: (key: object) => Effect.Effect<
  {
    key: object;
    state: Ref.Ref<{ accepting: boolean; closing: boolean; borrowers: number }>;
    drained: Latch.Latch;
  },
  never,
  never
>;

Source

releaseNativeLease

Releases one retained descendant after safe native settlement.

Signature

declare const releaseNativeLease: (lease: NativeLease) => Effect.Effect<void, never, never>;

Source

retainNativeLease

Retains a still-active parent token atomically.

Signature

declare const retainNativeLease: (lease: NativeLease) => Effect.Effect<boolean, never, never>;

Source

runWithNativeLeases

Makes native SDK callbacks inherit the currently retained Effect leases.

Signature

declare const runWithNativeLeases: <A>(leases: NativeLeaseContext, run: () => A) => A;

Source

native-leases.types.ts

NativeLease (interface)

Effect-owned ephemeral lease with a drain barrier for retained descendants.

Signature

export interface NativeLease {
  readonly key: object;
  readonly state: Ref.Ref<{
    readonly accepting: boolean;
    readonly closing: boolean;
    readonly borrowers: number;
  }>;
  readonly drained: Latch.Latch;
}

Source

NativeLeaseContext (interface)

Native transport for exact owner and physical client capabilities.

Signature

export interface NativeLeaseContext {
  readonly owner?: NativeLease;
  readonly sqlite?: NativeLease;
}

Source

operation-tracing.ts

observeSpecializedOperation

Observes specialized work once through the configured caller sinks.

Example

import { Effect } from "effect";
import { observeSpecializedOperation } from "@relkit/drizzle/internal";
await Effect.runPromise(observeSpecializedOperation("auth.session", Effect.succeed(null)));

Signature

declare const observeSpecializedOperation: <A, E, R>(
  operation: `database.${string}` | `auth.${string}`,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;

Source

runSpecializedTrace

Bridges invocation parenting without capturing native rows or auth sessions.

Signature

declare const runSpecializedTrace: <A>(operation: string, run: () => Promise<A>) => Promise<A>;

Source

operations.ts

operationEffect

Composes overrides and MySQL write/recovery transaction ownership.

Example

Compose a page with an existing owner and table binding
```ts
import { Effect } from "effect";
import type { ManagedRuntime } from "effect";
import { DrizzleFailure, DrizzleOwner, operationEffect, runDrizzlePromise } from "@relkit/drizzle/internal";
function page(owner: ManagedRuntime.ManagedRuntime<DrizzleOwner, DrizzleFailure>, binding: Parameters<typeof operationEffect>[0]) {
  return runDrizzlePromise(owner, Effect.gen(function* () {
    const service = yield* DrizzleOwner;
    return yield* service.work(operationEffect(binding, "findMany", { limit: 10 }));
  }));
}

**Signature**

```ts
declare const operationEffect: (binding: ModelBinding, name: string, args: unknown) => Effect.Effect<unknown, DrizzleFailure>

Source

runOperation

Runs one lazy CRUD workflow at its compatibility edge.

Signature

declare const runOperation: (
  binding: ModelBinding,
  name: string,
  args: unknown,
) => Promise<unknown>;

Source

operations.types.ts

BaseOperations (interface)

Stable public Promise CRUD contract over one table.

Signature

export interface BaseOperations<T extends Table> {
  /**
   * Selects one row by a complete unique key.
   * @param args - Unique selector.
   * @returns Matching row or null, rejecting invalid selectors/native failures.
   */
  findOne(args: FindOneArgs<T>): Promise<Row<T> | null>;

  /**
   * Selects a bounded ordered page.
   * @param args - Optional filters, ordering and pagination.
   * @returns Validated rows in driver order.
   */
  findMany(args?: FindManyArgs<T>): Promise<Row<T>[]>;

  /**
   * Inserts one row without automatic retries.
   * @param args - Insert values.
   * @returns Validated inserted row.
   */
  insert(args: InsertArgs<T>): Promise<Row<T>>;

  /**
   * Updates one selected row without automatic retries.
   * @param args - Unique selector and partial update values.
   * @returns Updated row or null when absent.
   */
  update(args: UpdateArgs<T>): Promise<Row<T> | null>;

  /**
   * Selects then inserts or updates using portable dialect semantics.
   * @param args - Unique selector and create/update branches.
   * @returns Resulting row; this portable read/write sequence is not an atomic SQL upsert.
   */
  upsert(args: UpsertArgs<T>): Promise<Row<T>>;

  /**
   * Removes one selected row without automatic retries.
   * @param args - Complete unique selector.
   * @returns Deleted row or null when absent.
   */
  delete(args: DeleteArgs<T>): Promise<Row<T> | null>;
}

Source

DeleteArgs (interface)

Complete unique selector for deletion.

Signature

export interface DeleteArgs<T extends Table> {
  readonly where: Where<T>;
}

Source

FindManyArgs (interface)

Bounded ordered page filters; default limit is 100.

Signature

export interface FindManyArgs<T extends Table> {
  readonly where?: Where<T>;
  readonly orderBy?: {
    readonly field: Extract<keyof Row<T>, string>;
    readonly direction: "asc" | "desc";
  };
  readonly limit?: number;
  readonly offset?: number;
}

Source

FindOneArgs (interface)

Complete unique selector for one row.

Signature

export interface FindOneArgs<T extends Table> {
  readonly where: Where<T>;
}

Source

Insert (type alias)

Insert values retaining nullable, default and generated-column inference.

Signature

type Insert<T extends Table> = InferInsertModel<T>;

Source

InsertArgs (interface)

Single-row insertion values.

Signature

export interface InsertArgs<T extends Table> {
  readonly data: Insert<T>;
}

Source

Row (type alias)

Persisted row inferred from a table.

Signature

type Row<T extends Table> = InferSelectModel<T>;

Source

Update (type alias)

Partial insert-compatible update values.

Signature

type Update<T extends Table> = Partial<Insert<T>>;

Source

UpdateArgs (interface)

Complete selector and partial update values.

Signature

export interface UpdateArgs<T extends Table> {
  readonly where: Where<T>;
  readonly data: Update<T>;
}

Source

UpsertArgs (interface)

Selector and separate create/update branches.

Signature

export interface UpsertArgs<T extends Table> {
  readonly where: Where<T>;
  readonly create: Insert<T>;
  readonly update: Update<T>;
}

Source

Where (type alias)

Column equality filter; unique operations require a complete selector.

Signature

type Where<T extends Table> = Partial<Row<T>>;

Source

operations.utils.ts

call

Calls a checked native method with its original receiver.

Throws

TypeError when the method is unavailable.

Signature

declare const call: (target: unknown, name: string, ...args: unknown[]) => unknown;

Source

clause

Builds equality predicates, treating null as SQL IS NULL.

Throws

TypeError for undefined values or unknown columns.

Signature

declare const clause: (binding: ModelBinding, where: Record<string, unknown>) => SQL | undefined;

Source

columnFor

Resolves one declared column.

Throws

TypeError for unknown fields.

Signature

declare const columnFor: (binding: ModelBinding, key: string) => Column;

Source

hasMethod

Inspects a native capability without invoking it.

Signature

declare const hasMethod: (target: unknown, name: string) => boolean;

Source

integer

Checks bounded pagination without coercing strings.

Throws

TypeError for invalid pagination.

Signature

declare const integer: (value: unknown, name: string, fallback: number, maximum?: number) => number;

Source

isRecord

Checks argument records without invoking getters.

Signature

declare const isRecord: (value: unknown) => value is Record<string, unknown>;

Source

record

Requires a plain argument record.

Throws

TypeError for null, arrays and scalar arguments.

Signature

declare const record: (value: unknown) => Record<string, unknown>;

Source

recoverable

Finds a complete key for MySQL row recovery after writes.

Signature

declare const recoverable: (
  binding: ModelBinding,
  value: Record<string, unknown>,
) => Record<string, unknown> | undefined;

Source

requiredRow

Requires a successful mutation row.

Throws

TypeError when no row was returned.

Signature

declare const requiredRow: (value: unknown) => unknown;

Source

selector

Requires a complete non-null unique selector.

Throws

TypeError for invalid keys or incomplete uniqueness.

Signature

declare const selector: (binding: ModelBinding, value: unknown) => Record<string, unknown>;

Source

owner.ts

DrizzleOwner (class)

Client lifetime/admission contract, substitutable through live/test Layers.

See

• drizzleOwnerLayer for checked acquisition/provisioning/cleanup composition.

Signature

declare class DrizzleOwner

Source

drizzleInstrumentationOf

Reads the observation context captured at activation.

Signature

declare const drizzleInstrumentationOf: (activation: object) => Context.Context<never>;

Source

drizzleOwnerLayer

Acquires one client into a Layer scope.

Example

import { ManagedRuntime } from "effect";
import { sqliteTable, integer } from "drizzle-orm/sqlite-core";
import { defineDrizzleService } from "@relkit/drizzle";
import { DrizzleOwner, drizzleOwnerLayer, drizzleRuntimeOf } from "@relkit/drizzle/internal";
const records = sqliteTable("records", { id: integer().primaryKey() });
const declaration = drizzleRuntimeOf(
  defineDrizzleService({ schema: { records }, client: () => ({}) }),
);
const owner = ManagedRuntime.make(drizzleOwnerLayer(declaration, {}));
try {
  await owner.runPromise(DrizzleOwner);
} finally {
  await owner.dispose();
}

Signature

declare const drizzleOwnerLayer: (
  declaration: DrizzleServiceRuntime,
  env: Readonly<Record<string, unknown>>,
) => Layer.Layer<DrizzleOwner, DrizzleFailure, never>;

Source

makeDrizzleOwner

Creates the service contract for live acquisition or deterministic fake clients.

See

• drizzleOwnerLayer for the owning Layer and execution boundary.

Signature

declare const makeDrizzleOwner: (
  client: unknown,
) => Effect.Effect<DrizzleOwnerInterface, never, never>;

Source

owners

Weak association preserving the exact frozen public activation shape.

Signature

declare const owners: WeakMap<object, OwnerBinding>;

Source

runDrizzleWorkPromise

Executes one admitted Promise compatibility edge.

See

• withDrizzleWork for the equivalent Effect-native borrowed lease.

Signature

declare const runDrizzleWorkPromise: <A, E>(
  activation: object,
  effect: Effect.Effect<A, E>,
) => Promise<A>;

Source

withDrizzleWork

Admits lazy work and releases its lease after safe native settlement.

Example

Compose work with an existing activation
```ts
import { Effect } from "effect";
import { activateDrizzleService } from "@relkit/drizzle";
import { withDrizzleWork } from "@relkit/drizzle/internal";
function borrowedWork(active: Awaited<ReturnType<typeof activateDrizzleService>>) {
  return withDrizzleWork(active, Effect.succeed(1));
}

**Signature**

```ts
declare const withDrizzleWork: <A, E, R>(activation: object, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | DrizzleFailure, R>

Source

owner.types.ts

AdmissionState (interface)

Atomic owner admission state; close is monotonic.

Signature

export interface AdmissionState {
  readonly closing: boolean;
  readonly active: number;
}

Source

DrizzleOwnerInterface (interface)

Shared live/test contract for one client lifetime.

Signature

export interface DrizzleOwnerInterface {
  readonly client: unknown;
  readonly admission: Ref.Ref<AdmissionState>;
  readonly drained: Latch.Latch;

  /**
   * Admits lazy work while preserving its caller requirements and causes.
   * @typeParam A - Successful caller result.
   * @typeParam E - Caller typed failure.
   * @typeParam R - Required caller services.
   * @param effect - SDK adapter work retaining its lease until native settlement.
   * @returns Lazy caller work or a typed closed-owner admission failure.
   */
  readonly work: <A, E, R>(
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E | DrizzleFailure, R>;

  /**
   * Marks admission closed monotonically.
   * @returns Lazy state transition; already admitted work retains its lease.
   */
  readonly beginClose: () => Effect.Effect<void>;

  /**
   * Awaits all previously admitted native work.
   * @returns Lazy drain barrier; resource disposal must follow this completion.
   */
  readonly awaitDrained: () => Effect.Effect<void>;
}

Source

OwnerBinding (interface)

Private association; the public activation remains frozen.

Signature

export interface OwnerBinding {
  readonly dialect: "sqlite" | "pg" | "mysql";
  readonly service: DrizzleOwnerInterface;
  readonly runtime: ManagedRuntime.ManagedRuntime<DrizzleOwner, DrizzleFailure>;
  readonly instrumentation: Context.Context<never>;
  readonly run: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
}

Source

pg.ts

pg native model typing; imports only this selected dialect’s upstream declarations.

“./index.js” (namespace export)

Re-exports all named exports from the “./index.js” module.

Signature

export * from "./index.js";

Source

DialectDatabase (type alias)

Native database injected into model extensions for the selected dialect.

Signature

type DialectDatabase = Omit<PgAsyncDatabase<any, any>, "query">;

Source

defineModel

Declares lazy native extensions with this dialect’s real transaction client type.

Signature

declare const defineModel: DefineModel<DialectDatabase>;

Source

queries.ts

checked

Converts expected synchronous argument/native-builder exceptions.

Signature

declare const checked: <A>(run: () => A) => Effect.Effect<A, DrizzleFailure>;

Source

findMany

Selects a bounded ordered page.

Signature

declare const findMany: (
  binding: ModelBinding,
  args: Record<string, unknown>,
) => Effect.Effect<Array<unknown>, DrizzleFailure, never>;

Source

findOne

Selects one unique row and validates persisted data.

Signature

declare const findOne: (
  binding: ModelBinding,
  where: Record<string, unknown>,
) => Effect.Effect<{} | null, DrizzleFailure, never>;

Source

rows

Awaits native rows then validates sequentially without starting new SDK work.

Signature

declare const rows: (
  binding: ModelBinding,
  query: unknown,
) => Effect.Effect<Array<unknown>, DrizzleFailure, never>;

Source

runtime-types.ts

DRIZZLE_RUNTIME

Stable hidden descriptor brand; shared across module copies.

Signature

declare const DRIZZLE_RUNTIME: unique symbol;

Source

DrizzleServiceRuntime (interface)

Pure declaration dependencies; accessing this object never acquires a client.

Signature

export interface DrizzleServiceRuntime {
  readonly client: (context: { readonly env: Readonly<Record<string, unknown>> }) => unknown;
  readonly dispose?: (database: any) => unknown;
  readonly schema: Readonly<Record<string, unknown>>;
  readonly tables: TableMap;
  readonly models: DrizzleModelMap<TableMap>;
  readonly overrides: DrizzleOverrides<TableMap>;
  readonly metadata: Readonly<Record<string, TableMetadata>>;
  readonly zodSchemas: Readonly<Record<string, TableZodSchemas<Table>>>;
  readonly effectSchemas: Readonly<Record<string, ReturnType<typeof effectSchemasFor>>>;
  readonly dialect: "pg" | "mysql" | "sqlite";
}

Source

MODEL_RUNTIME

Stable hidden model descriptor brand.

Signature

declare const MODEL_RUNTIME: unique symbol;

Source

ModelBinding (interface)

Table operations bound to an owner or an already admitted transaction.

Signature

export interface ModelBinding {
  /**
   * Executes work at its owning runtime edge.
   * @typeParam A - Successful result.
   * @param effect - Lazy typed operation.
   * @param operation - Bounded diagnostic label.
   * @returns Public result or original native failure.
   */
  readonly run: <A>(effect: Effect.Effect<A, DrizzleFailure>, operation: string) => Promise<A>;
  readonly drizzle: unknown;
  readonly table: Table;
  readonly dialect: "pg" | "mysql" | "sqlite";
  readonly inTransaction: boolean;
  readonly metadata: TableMetadata;
  readonly override: Readonly<Record<string, unknown>>;
  readonly schemas: ReturnType<typeof effectSchemasFor>;
}

Source

ModelRuntime (interface)

Opaque authored extensions retaining their native injected database contract.

Signature

export interface ModelRuntime {
  readonly table: Table;
  readonly extend: Readonly<Record<string, (context: any, ...args: any[]) => unknown>>;
}

Source

TableMetadata (interface)

Pure table-column and complete unique-selector metadata.

Signature

export interface TableMetadata {
  readonly columns: Readonly<Record<string, unknown>>;
  readonly selectors: readonly (readonly string[])[];
}

Source

service.ts

defineDrizzleService

Defines the application’s Drizzle service, table operations, and model customizations. The client factory runs at activation, not during descriptor discovery.

Throws

TypeError for invalid declarations, dialects, models or overrides.

Example

import { defineDrizzleService } from "@relkit/drizzle";
import { integer, sqliteTable } from "drizzle-orm/sqlite-core";

const users = sqliteTable("users", { id: integer().primaryKey() });
const service = defineDrizzleService({
  schema: { users },
  client: () => {
    throw new Error("Configure a Drizzle driver before activation");
  },
});
console.assert(service.capability.dialect === "sqlite");

Signature

declare const defineDrizzleService: <
  Client,
  const Schema extends Readonly<Record<string, unknown>>,
  const Models extends DrizzleModelMap<TablesOf<Schema>> = {},
>(
  options: DefineDrizzleServiceOptions<Client, Schema, Models>,
) => DrizzleServiceDescriptor<string, Client, Schema, Models>;

Source

Since v0.1.0

DefineDrizzleServiceOptions

Signature

declare const DefineDrizzleServiceOptions: DefineDrizzleServiceOptions<Client, Schema, Models>;

Source

drizzleRuntimeOf

Resolves hidden runtime metadata without acquiring a client.

Throws

TypeError for unbranded declarations.

Signature

declare const drizzleRuntimeOf: (value: object) => DrizzleServiceRuntime;

Source

service.types.ts

DefineDrizzleServiceOptions (interface)

Lazy authoring options preserving native client and model extension inference.

Signature

export interface DefineDrizzleServiceOptions<
  Client,
  Schema extends Readonly<Record<string, unknown>>,
  Models extends DrizzleModelMap<TablesOf<Schema>>,
> {
  readonly id?: string;
  readonly schema: Schema;
  /**
   * Acquires a native client when the owner Layer is first built.
   * @param context - First activation environment.
   * @returns Native client or acquisition Promise; failures retain native identity.
   */
  readonly client: (context: { readonly env: ApplicationEnv }) => Client | Promise<Client>;
  readonly models?: Models;
  readonly overrides?: DrizzleOverrides<TablesOf<Schema>>;
  /**
   * Releases the owned native client once admitted work has drained.
   * @param database - Successfully acquired client.
   * @returns Optional native completion; failure remains visible at close.
   */
  readonly dispose?: (database: Client) => unknown | Promise<unknown>;
}

Source

sqlite.ts

sqlite native model typing; imports only this selected dialect’s upstream declarations.

“./index.js” (namespace export)

Re-exports all named exports from the “./index.js” module.

Signature

export * from "./index.js";

Source

DialectDatabase (type alias)

Native database injected into model extensions for the selected dialect.

Signature

type DialectDatabase = Omit<SQLiteAsyncDatabase<any, any, any>, "query">;

Source

defineModel

Declares lazy native extensions with this dialect’s real transaction client type.

Signature

declare const defineModel: DefineModel<DialectDatabase>;

Source

table.schemas.ts

decodeTableValue

Validates unknown native rows or write data at the domain boundary.

Signature

declare const decodeTableValue: (
  schema: Schema.Codec<unknown, unknown>,
  value: unknown,
) => Effect.Effect<unknown, DrizzleFailure, never>;

Source

effectSchemasFor

Generates pinned Drizzle/Effect contracts without acquiring a database.

Signature

declare const effectSchemasFor: (table: Table) => Readonly<{
  select: BuildSchema<"select", Columns, { [x: string]: any }>;
  insert: BuildSchema<"insert", Columns, { [x: string]: any }>;
  update: BuildSchema<
    "update",
    Columns,
    { [k: string]: () => Schema.Codec<unknown, unknown, never, never> }
  >;
}>;

Source

trace-redaction.ts

redactSpecializedTrace

Protects configured tracers without changing authoritative workflow exits.

Signature

declare const redactSpecializedTrace: <A, E, R>(
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, Exclude<R, never>>;

Source

specializedTracer

Adapts span completion before an external exporter can inspect native causes.

Signature

declare const specializedTracer: (tracer: Tracer.Tracer) => Tracer.Tracer;

Source

transaction.ts

transactionEffect

Executes a portable transaction under the physical SQLite client lock.

Signature

declare const transactionEffect: <A>(
  database: unknown,
  dialect: "sqlite" | "pg" | "mysql",
  run: (database: unknown, lease: NativeLease) => Promise<A>,
) => Effect.Effect<A, DrizzleFailure, never>;

Source

withSqlitePermit

Serializes conflicting SQLite work at the physical client boundary.

Signature

declare const withSqlitePermit: <A, E, R>(
  database: unknown,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E | DrizzleFailure, R>;

Source

withTransactionWork

Retains a transaction callback while one child operation executes.

Signature

declare const withTransactionWork: <A, E, R>(
  lease: NativeLease,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, DrizzleFailure | E, R>;

Source

types.ts

Portable database contracts; native model database types belong to selected dialect entrypoints.

ApplicationEnv (type alias)

Application declaration augmentation, falling back to string environment values.

Signature

type ApplicationEnv = keyof Relkit.ApplicationEnv extends never
  ? Readonly<Record<string, string>>
  : Readonly<Relkit.ApplicationEnv>;

Source

BaseOperations

Signature

declare const BaseOperations: BaseOperations<T>;

Source

DatabaseContext (type alias)

Public transaction-aware table operations and unchanged Zod schemas.

Signature

type DatabaseContext<Service extends DrizzleServiceDescriptor<any, any, any, any>> = {
  readonly [Name in keyof TablesOf<Service[typeof SERVICE_TYPES]["schema"]>]: BaseOperations<
    TablesOf<Service[typeof SERVICE_TYPES]["schema"]>[Name]
  > &
    (Name extends keyof Service[typeof SERVICE_TYPES]["models"]
      ? ConsumerExtensions<Service[typeof SERVICE_TYPES]["models"][Name]>
      : {});
} & {
  /**
   * Runs a callback in a portable transaction without nested portable transactions.
   * @typeParam Value - Callback result.
   * @param run - Callback receiving transaction-bound table operations.
   * @returns Callback result after native commit, or original failure after rollback.
   */
  readonly transaction: <Value>(
    run: (context: DatabaseContext<Service>) => MaybePromise<Value>,
  ) => Promise<Value>;
  readonly zodSchemas: {
    readonly [Name in keyof TablesOf<Service[typeof SERVICE_TYPES]["schema"]>]: TableZodSchemas<
      TablesOf<Service[typeof SERVICE_TYPES]["schema"]>[Name]
    >;
  };
};

Source

DeleteArgs

Signature

declare const DeleteArgs: DeleteArgs<T>;

Source

DrizzleCapability (interface)

Pure compiler-visible dialect, tables, constraints and custom methods.

Signature

export interface DrizzleCapability {
  readonly kind: "drizzle";
  readonly dialect: "pg" | "mysql" | "sqlite";
  readonly tables: readonly {
    readonly name: string;
    readonly databaseName: string;
    readonly columns: readonly {
      readonly key: string;
      readonly name: string;
      readonly dataType: string;
      readonly notNull: boolean;
      readonly hasDefault: boolean;
      readonly primaryKey: boolean;
      readonly unique: boolean;
    }[];
    readonly selectors: readonly (readonly string[])[];
    readonly customMethods: readonly string[];
  }[];
}

Source

DrizzleModelMap (type alias)

Optional table-keyed model declarations.

Signature

type DrizzleModelMap<Tables extends TableMap> = Partial<{
  readonly [Name in keyof Tables]: ModelDescriptor<Tables[Name], any>;
}>;

Source

DrizzleOverrides (type alias)

Table-keyed override declarations.

Signature

type DrizzleOverrides<Tables extends TableMap> = {
  readonly [Name in keyof Tables]?: TableOverrides<Tables[Name]>;
};