@arki/db 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arki/db",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Drizzle ORM repositories and database helpers for ARKI — Postgres + PGlite runtimes, projection builder, branded ID factory, and env-aware connection pooling.",
   "license": "MIT",
   "repository": {
@@ -98,15 +98,21 @@
   },
   "files": [
     "dist/**",
+    "src/**",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/tests/**",
+    "!src/**/test/**",
+    "!src/**/__tests__/**",
     "README.md",
     "LICENSE",
     "package.json"
   ],
   "dependencies": {
-    "@arki/assert": "0.0.1",
-    "@arki/contracts": "0.0.1",
-    "@arki/env": "0.0.2",
-    "@arki/log": "0.0.1",
+    "@arki/assert": "0.0.2",
+    "@arki/contracts": "0.0.2",
+    "@arki/env": "0.0.3",
+    "@arki/log": "0.0.2",
     "@electric-sql/pglite": "^0.4.5",
     "@paralleldrive/cuid2": "^3.3.0",
     "@t3-oss/env-core": "^0.13.10",
@@ -116,7 +122,7 @@
     "zod": "4.3.5"
   },
   "peerDependencies": {
-    "@arki/dot": "^0.1.1"
+    "@arki/dot": "^0.1.2"
   },
   "peerDependenciesMeta": {
     "@arki/dot": {

package/src/builder.ts

@@ -0,0 +1,359 @@
+import type { AnyRelations } from 'drizzle-orm';
+import { defineRelations } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type { PoolConfig } from 'pg';
+
+import { debugProjection } from './debug.js';
+import { initDbWithOptions } from './init.js';
+
+/**
+ * Projection middleware context
+ */
+export type ProjectionMiddlewareContext = {
+  next: () => Promise<void>;
+  meta: {
+    name: string;
+    eventCount: number;
+  };
+};
+
+/**
+ * Projection middleware function
+ */
+export type ProjectionMiddleware = (context: ProjectionMiddlewareContext) => Promise<void>;
+
+/**
+ * Projection handler context
+ */
+export type ProjectionHandlerContext<TRepos, TRelations extends AnyRelations = AnyRelations> = {
+  repo: TRepos;
+  db: NodePgDatabase<TRelations>;
+};
+
+/**
+ * Projection handler function
+ */
+export type ProjectionHandler<TEvent, TRepos, TRelations extends AnyRelations = AnyRelations> = (
+  events: TEvent[],
+  context: ProjectionHandlerContext<TRepos, TRelations>,
+) => Promise<void>;
+
+/**
+ * Projection builder interface
+ */
+export type ProjectionBuilder<
+  TEvent = never,
+  TRepos = never,
+  TRelations extends AnyRelations = AnyRelations,
+> = {
+  named<TName extends string>(name: TName): ProjectionBuilderWithName<TEvent, TRepos, TRelations, TName>;
+};
+
+export type ProjectionBuilderWithName<
+  _TEvent,
+  TRepos,
+  TRelations extends AnyRelations,
+  TName extends string,
+> = {
+  on<TEventType extends { type: string }>(
+    eventTypes: readonly TEventType['type'][] | TEventType['type'][],
+  ): ProjectionBuilderWithEvents<TEventType, TRepos, TRelations, TName>;
+};
+
+export type ProjectionBuilderWithEvents<
+  TEvent,
+  TRepos,
+  TRelations extends AnyRelations,
+  TName extends string,
+> = {
+  handle(handler: ProjectionHandler<TEvent, TRepos, TRelations>): ProjectionDefinition<TName>;
+};
+
+/**
+ * Emmett-compatible projection definition.
+ */
+export type ProjectionDefinition<TName extends string = string> = {
+  name: TName;
+  canHandle: string[];
+  handle: (events: { type: string }[]) => Promise<void>;
+};
+
+/**
+ * Database builder with projection support
+ */
+export type DbBuilder<TRelations extends AnyRelations, TRepos extends Record<string, unknown>> = {
+  readonly db: NodePgDatabase<TRelations>;
+  readonly isDev: boolean;
+
+  registerRepository<K extends string, R>(
+    key: K,
+    factory: (db: NodePgDatabase<TRelations>) => R,
+  ): DbBuilder<TRelations, TRepos & Record<K, R>>;
+
+  projectionMiddleware(fn: ProjectionMiddleware): ProjectionMiddleware;
+
+  readonly projection: ProjectionBuilderRoot<TRepos, TRelations>;
+};
+
+/**
+ * Projection builder root that can have middleware applied
+ */
+export type ProjectionBuilderRoot<TRepos, TRelations extends AnyRelations = AnyRelations> = {
+  use(middleware: ProjectionMiddleware): ProjectionBuilderRoot<TRepos, TRelations>;
+} & ProjectionBuilder<never, TRepos, TRelations>;
+
+/**
+ * Schema configuration step
+ */
+export type SchemaBuilder<TRelations extends AnyRelations> = {
+  create(options: {
+    connectionString: string;
+    isDev?: boolean;
+    poolConfig?: Partial<PoolConfig>;
+  }): DbBuilder<TRelations, Record<string, never>>;
+};
+
+/**
+ * Initial builder step
+ */
+export type InitialBuilder = {
+  /**
+   * Set the database tables. Internally builds a relations config via
+   * `defineRelations()` so consumers keep passing a plain table record.
+   *
+   * Use this for backends that don't define explicit relations and rely on
+   * auto-derivation (no joins). For explicit RQBv2 relations, prefer
+   * `.relations(...)` with a `defineRelations(tables, cb)` result.
+   */
+  schema<TSchema extends Record<string, unknown>>(
+    schema: TSchema,
+  ): SchemaBuilder<ReturnType<typeof defineRelations<TSchema>>>;
+
+  /**
+   * Pass a pre-built relations object (the result of
+   * `defineRelations(tables, cb)`) so the database knows about every table
+   * AND the explicit one/many relations declared by the application.
+   */
+  relations<TRelations extends AnyRelations>(relations: TRelations): SchemaBuilder<TRelations>;
+};
+
+/**
+ * Applies a middleware chain around a core handler function.
+ */
+function applyMiddleware(
+  middleware: ProjectionMiddleware[],
+  name: string,
+  eventCount: number,
+  coreHandler: () => Promise<void>,
+): Promise<void> {
+  const meta = { name, eventCount };
+
+  let next = coreHandler;
+  for (let i = middleware.length - 1; i >= 0; i--) {
+    const mw = middleware[i]!;
+    const currentNext = next;
+    next = () => mw({ next: currentNext, meta });
+  }
+
+  return next();
+}
+
+class ProjectionBuilderImpl<
+  TEvent,
+  TRepos,
+  TRelations extends AnyRelations,
+  TName extends string = string,
+>
+  implements
+    ProjectionBuilder<TEvent, TRepos, TRelations>,
+    ProjectionBuilderWithName<TEvent, TRepos, TRelations, TName>,
+    ProjectionBuilderWithEvents<TEvent, TRepos, TRelations, TName>,
+    ProjectionBuilderRoot<TRepos, TRelations>
+{
+  private _name?: string;
+  private _eventTypes?: string[];
+  private _middleware: ProjectionMiddleware[] = [];
+
+  constructor(
+    private readonly repos: TRepos,
+    private readonly _db: NodePgDatabase<TRelations>,
+    middleware?: ProjectionMiddleware[],
+  ) {
+    if (middleware) {
+      this._middleware = [...middleware];
+    }
+  }
+
+  named<N extends string>(name: N): ProjectionBuilderWithName<TEvent, TRepos, TRelations, N> {
+    debugProjection('[builder] Setting projection name: %s', name);
+    this._name = name;
+    return this as unknown as ProjectionBuilderImpl<TEvent, TRepos, TRelations, N>;
+  }
+
+  on<TEventType extends { type: string }>(
+    eventTypes: readonly TEventType['type'][] | TEventType['type'][],
+  ): ProjectionBuilderWithEvents<TEventType, TRepos, TRelations, TName> {
+    debugProjection('[builder] Registering event types: %o', eventTypes);
+    this._eventTypes = [...eventTypes];
+    return this as unknown as ProjectionBuilderImpl<TEventType, TRepos, TRelations, TName>;
+  }
+
+  handle(handler: ProjectionHandler<TEvent, TRepos, TRelations>): ProjectionDefinition<TName> {
+    if (!this._name) {
+      debugProjection('[builder] Error: Projection name is required');
+      throw new Error('Projection name is required. Call .named() first.');
+    }
+    if (!this._eventTypes) {
+      debugProjection('[builder] Error: Event types are required');
+      throw new Error('Event types are required. Call .on() first.');
+    }
+
+    const name = this._name as TName;
+    const eventTypes = this._eventTypes;
+    const middleware = this._middleware;
+    const repos = this.repos;
+    const db = this._db;
+
+    debugProjection('[builder] Creating projection definition (name: %s, eventTypes: %o, middlewareCount: %d)',
+      name, eventTypes, middleware.length);
+
+    return {
+      name,
+      canHandle: eventTypes,
+      handle: async (events: { type: string }[]) => {
+        const context: ProjectionHandlerContext<TRepos, TRelations> = { repo: repos, db };
+        const coreHandler = () => handler(events as TEvent[], context);
+
+        if (middleware.length > 0) {
+          await applyMiddleware(middleware, name, events.length, coreHandler);
+        } else {
+          await coreHandler();
+        }
+      },
+    };
+  }
+
+  use(middleware: ProjectionMiddleware): ProjectionBuilderRoot<TRepos, TRelations> {
+    debugProjection('[builder] Adding projection middleware (currentCount: %d)', this._middleware.length);
+    const newBuilder = new ProjectionBuilderImpl<TEvent, TRepos, TRelations, TName>(this.repos, this._db, [
+      ...this._middleware,
+      middleware,
+    ]);
+    debugProjection('[builder] Middleware added (newCount: %d)', this._middleware.length + 1);
+    return newBuilder;
+  }
+}
+
+class DbBuilderImpl<TRelations extends AnyRelations, TRepos extends Record<string, unknown>>
+  implements DbBuilder<TRelations, TRepos>
+{
+  readonly db: NodePgDatabase<TRelations>;
+  readonly isDev: boolean;
+  private _repos?: TRepos;
+  private readonly _repoFactories: Map<string, (db: NodePgDatabase<TRelations>) => unknown>;
+
+  constructor(
+    db: NodePgDatabase<TRelations>,
+    isDev: boolean,
+    repoFactories?: Map<string, (db: NodePgDatabase<TRelations>) => unknown>,
+  ) {
+    this.db = db;
+    this.isDev = isDev;
+    this._repoFactories = repoFactories ?? new Map();
+  }
+
+  registerRepository<K extends string, R>(
+    key: K,
+    factory: (db: NodePgDatabase<TRelations>) => R,
+  ): DbBuilder<TRelations, TRepos & Record<K, R>> {
+    debugProjection('[builder] Registering repository (key: %s, currentCount: %d)', key, this._repoFactories.size);
+    const newFactories = new Map(this._repoFactories);
+    newFactories.set(key, factory);
+    debugProjection('[builder] Repository registered (key: %s, newCount: %d)', key, newFactories.size);
+    return new DbBuilderImpl<TRelations, TRepos & Record<K, R>>(this.db, this.isDev, newFactories) as DbBuilder<
+      TRelations,
+      TRepos & Record<K, R>
+    >;
+  }
+
+  projectionMiddleware(fn: ProjectionMiddleware): ProjectionMiddleware {
+    return fn;
+  }
+
+  get projection(): ProjectionBuilderRoot<TRepos, TRelations> {
+    if (!this._repos) {
+      debugProjection('[builder] Initializing repositories from factories (count: %d)', this._repoFactories.size);
+      const repos: Record<string, unknown> = {};
+      for (const [key, factory] of this._repoFactories) {
+        debugProjection('[builder] Creating repository: %s', key);
+        repos[key] = factory(this.db);
+      }
+      this._repos = repos as TRepos;
+      debugProjection('[builder] All repositories initialized');
+    }
+    debugProjection('[builder] Creating projection builder');
+    return new ProjectionBuilderImpl<never, TRepos, TRelations>(this._repos, this.db);
+  }
+}
+
+class SchemaBuilderImpl<TRelations extends AnyRelations> implements SchemaBuilder<TRelations> {
+  constructor(private readonly relations: TRelations) {}
+
+  create(options: {
+    connectionString: string;
+    isDev?: boolean;
+    poolConfig?: Partial<PoolConfig>;
+  }): DbBuilder<TRelations, Record<string, never>> {
+    debugProjection('[builder] Creating database builder (isDev: %s, hasPoolConfig: %s)',
+      options.isDev ?? false, !!options.poolConfig);
+
+    const poolConfig: PoolConfig = {
+      connectionString: options.connectionString,
+      ...options.poolConfig,
+    };
+
+    debugProjection('[builder] Initializing database with pool config');
+    const db = initDbWithOptions<TRelations>(poolConfig, {
+      relations: this.relations,
+      logger: options.isDev,
+    });
+
+    debugProjection('[builder] Database builder created successfully');
+    return new DbBuilderImpl<TRelations, Record<string, never>>(db, options.isDev ?? false);
+  }
+}
+
+class InitialBuilderImpl implements InitialBuilder {
+  schema<TSchema extends Record<string, unknown>>(
+    schema: TSchema,
+  ): SchemaBuilder<ReturnType<typeof defineRelations<TSchema>>> {
+    debugProjection('[builder] Setting database schema (deriving relations via defineRelations)');
+    const relations = defineRelations(schema) as ReturnType<typeof defineRelations<TSchema>>;
+    return new SchemaBuilderImpl(relations);
+  }
+
+  relations<TRelations extends AnyRelations>(relations: TRelations): SchemaBuilder<TRelations> {
+    debugProjection('[builder] Setting database relations (explicit RQBv2)');
+    return new SchemaBuilderImpl(relations);
+  }
+}
+
+/**
+ * Initialize the database builder.
+ *
+ * @example
+ * ```typescript
+ * const d = initDb
+ *   .schema(schema)
+ *   .create({
+ *     connectionString: env.DB_URL,
+ *     isDev: process.env.NODE_ENV === 'development',
+ *   });
+ *
+ * const db = d.db;
+ * const projection = d.projection.named('my-proj').on(['EventA']).handle(async (events, ctx) => {
+ *   // handler
+ * });
+ * ```
+ */
+export const initDb: InitialBuilder = new InitialBuilderImpl();

package/src/bun.ts

@@ -0,0 +1,58 @@
+import { SQL } from 'bun';
+import type { AnyRelations } from 'drizzle-orm';
+import type { BunSQLDatabase } from 'drizzle-orm/bun-sql/postgres';
+import { drizzle } from 'drizzle-orm/bun-sql/postgres';
+import type { DrizzlePgConfig } from 'drizzle-orm/pg-core/utils';
+
+import { debugInit } from './debug.js';
+import { env } from './env.js';
+
+/**
+ * Initialize database with Bun's native SQL driver.
+ * @param connectionString - PostgreSQL connection string.
+ * @param config - Drizzle pg configuration.
+ */
+export const initDb = <TRelations extends AnyRelations>(
+  connectionString: string,
+  config: Omit<DrizzlePgConfig<TRelations>, 'relations'> & { relations: TRelations },
+): BunSQLDatabase<TRelations> => {
+  debugInit('[bun] Initializing database with connection string (logger: %s)', !!config.logger);
+
+  const client = new SQL(connectionString);
+
+  const db = drizzle<TRelations>({ ...config, client });
+
+  debugInit('[bun] Database initialized successfully with Bun SQL driver');
+
+  return db;
+};
+
+/**
+ * Create a database connection using environment configuration with Bun SQL.
+ * @param config - Drizzle pg configuration.
+ * @throws Error if DB_URL is not configured.
+ */
+export function createDb<TRelations extends AnyRelations>(
+  config: Omit<DrizzlePgConfig<TRelations>, 'relations'> & { relations: TRelations },
+): BunSQLDatabase<TRelations> {
+  debugInit('[bun] Creating database from environment configuration');
+
+  const connectionUrl = env.DB_URL;
+  if (!connectionUrl) {
+    debugInit('[bun] Database creation failed: DB_URL not configured');
+    throw new Error('Database URL is not configured. Please set DB_URL environment variable.');
+  }
+
+  const db = initDb(connectionUrl, {
+    ...config,
+    logger: config.logger ?? (env.DB_LOGGING || env.NODE_ENV === 'development'),
+  });
+
+  debugInit('[bun] Database created successfully');
+
+  return db;
+}
+
+export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';
+
+export type { BunSQLDatabase } from 'drizzle-orm/bun-sql/postgres';

package/src/client/README.md

@@ -0,0 +1,5 @@
+# @arki/db/client
+
+Reserved client-side surface of `@arki/db`. V1 contains only type-level re-exports
+(zero runtime cost). Future Drizzle-on-client / Tier-3 sync work (Electric / PowerSync /
+Zero adapters) will land here. See [packages/offline/docs/2026-05-16-arki-offline-design.md](../../../offline/docs/2026-05-16-arki-offline-design.md).

package/src/client/ids.ts

@@ -0,0 +1,11 @@
+/**
+ * Branded ID type re-exports for the client surface.
+ *
+ * V1: @arki/contracts does not yet export named branded ID types.
+ * Future versions will re-export them here once they are defined, e.g.:
+ *
+ *   export type { UserId, OrgId, AssetId } from '@arki/contracts';
+ *
+ * See packages/offline/docs/2026-05-16-arki-offline-design.md §3.3.
+ */
+export type {};

package/src/client/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @arki/db/client — types-only client surface.
+ *
+ * V1 is intentionally empty: this subpath claims the namespace for future
+ * Drizzle-on-client / Tier-3 sync work (Electric / PowerSync / Zero adapters).
+ * No runtime imports are allowed here — this file must remain free of any
+ * server-only dependencies (postgres, drizzle-orm connection utilities, etc.).
+ *
+ * See packages/offline/docs/2026-05-16-arki-offline-design.md §3.3.
+ */
+export type * from './ids.js';

package/src/connection-options.ts

@@ -0,0 +1,49 @@
+import { debugFactory } from './debug.js';
+import { env } from './env.js';
+
+/**
+ * Get database connection options from environment variables
+ * @returns Connection options object for pg Pool
+ */
+export function getDbConnectionOptions() {
+  debugFactory('[factory] Retrieving database connection options from environment');
+
+  const connectionUrl = env.DB_URL;
+  const options = {
+    connectionString: connectionUrl,
+    min: env.DB_POOL_MIN,
+    max: env.DB_POOL_MAX,
+    idleTimeoutMillis: env.DB_POOL_IDLE_TIMEOUT,
+    connectionTimeoutMillis: env.DB_POOL_CONNECTION_TIMEOUT,
+    statement_timeout: env.DB_STATEMENT_TIMEOUT,
+    query_timeout: env.DB_QUERY_TIMEOUT,
+    idle_in_transaction_session_timeout: env.DB_IDLE_IN_TRANSACTION_SESSION_TIMEOUT,
+  };
+
+  debugFactory('[factory] Connection options retrieved (hasUrl: %s)', !!connectionUrl);
+
+  return options;
+}
+
+/**
+ * Get individual database connection parameters from environment variables
+ * Useful when DB_URL is not available but individual parameters are set
+ * @returns Connection parameters object
+ */
+export function getDbConnectionParams() {
+  debugFactory('[factory] Retrieving database connection parameters from environment');
+
+  const params = {
+    user: env.PGUSER,
+    password: env.PGPASSWORD,
+    host: env.PGHOST,
+    port: env.PGPORT,
+    database: env.PGDATABASE,
+    ssl: env.PGSSLMODE === 'disable' ? false : { rejectUnauthorized: env.PGSSLMODE === 'verify-full' },
+  };
+
+  debugFactory('[factory] Connection parameters retrieved (host: %s, port: %d, database: %s, ssl: %s)',
+    params.host, params.port, params.database, env.PGSSLMODE);
+
+  return params;
+}

package/src/debug.ts

@@ -0,0 +1,24 @@
+import { createDebugLogger } from '@arki/log/debug';
+
+/**
+ * Debug logger for database initialization and connection operations
+ * Enable with: DEBUG=db:init
+ */
+export const debugInit = createDebugLogger('db:init');
+
+/**
+ * Debug logger for database factory operations
+ * Enable with: DEBUG=db:factory
+ */
+export const debugFactory = createDebugLogger('db:factory');
+
+/**
+ * Debug logger for projection builder operations
+ * Enable with: DEBUG=db:projection
+ */
+export const debugProjection = createDebugLogger('db:projection');
+
+/**
+ * Enable all database debug logs
+ * Enable with: DEBUG=db:*
+ */

package/src/dot.ts

@@ -0,0 +1,200 @@
+/**
+ * DOT adapter for `@arki/db`.
+ *
+ * Wraps the Drizzle database initialization as a DOT pip. The pip
+ * opens a database connection in `boot`, publishes the Drizzle handle as
+ * `services.db`, and tears down the underlying client in `dispose`
+ * (reverse declaration order).
+ *
+ * Two drivers are supported:
+ *   - `'pg'` (default) — `node-postgres` pool. Reads `DB_URL` and the
+ *     `DB_POOL_*` env vars via `@arki/db`'s built-in env loader.
+ *   - `'pglite'` — embedded PGlite. Pass `dataDir`, or `memory: true` for
+ *     an in-memory instance. Use for tests, single-binary apps, or local
+ *     development without a real Postgres server.
+ *
+ * @example
+ * ```ts
+ * import { defineApp } from '@arki/dot';
+ * import { db } from '@arki/db/dot';
+ * import { defineRelations } from '@arki/db/orm';
+ * import { schema } from './schema';
+ *
+ * const relations = defineRelations(schema, (b) => ({ ... }));
+ *
+ * // Node-postgres (default), reads DB_URL from env:
+ * const app = await defineApp('my-app')
+ *   .use(db({ relations }))
+ *   .boot();
+ *
+ * // PGlite in-memory (great for tests):
+ * const testApp = await defineApp('test')
+ *   .use(db({ driver: 'pglite', memory: true, relations }))
+ *   .boot();
+ * ```
+ *
+ * To mount a second database scope (e.g. primary + reporting) in the same
+ * app, rename the published wire key at the mount site:
+ *
+ * ```ts
+ * import { rename } from '@arki/dot';
+ *
+ * .use(db({ relations }))
+ * .use(rename(db({ driver: 'pglite', memory: true, relations }), { db: 'reportsDb' }, 'reports-db'))
+ * ```
+ *
+ * The `@arki/dot` package is an OPTIONAL peer of `@arki/db`. Importing
+ * this adapter without `@arki/dot` installed will fail at module load —
+ * that is intentional: the adapter only makes sense in a DOT app.
+ */
+
+import type { AnyRelations, Logger } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type { PgliteDatabase } from 'drizzle-orm/pglite';
+
+import type { EmptyShape, Pip } from '@arki/dot/pip';
+import { pip, DotPipError } from '@arki/dot/pip';
+
+import type { PgliteInitOptions } from './runtime-local.js';
+import { env } from './env.js';
+import { createDb } from './factory.js';
+import { initDbRuntimeLocal } from './runtime-local.js';
+
+/**
+ * Stable error codes thrown by the db pip. Exported so consumers and
+ * coding agents can match against them — never parse the message.
+ *
+ * @see packages/dot/docs/principles.md — principle 1.3 ("errors are part
+ * of the API") and principle 4 ("agent-discoverable everywhere").
+ */
+export const DB_PIP_ERROR_CODES = {
+  /** boot was called without a configured DB_URL (pg driver). */
+  dbUrlNotConfigured: 'DB_PIP_E001',
+} as const;
+
+/**
+ * Common options shared by all DB driver variants.
+ */
+type BaseDbDotOptions<TRelations extends AnyRelations> = {
+  /** Drizzle 1.0 relations config (build via `defineRelations`). */
+  readonly relations: TRelations;
+  /** Drizzle logger override — `true`/`false` or a custom `Logger` instance. */
+  readonly logger?: boolean | Logger;
+};
+
+/** Options for the node-postgres driver (the default). */
+export type PgDbDotOptions<TRelations extends AnyRelations> = BaseDbDotOptions<TRelations> & {
+  /** Driver discriminant. Defaults to `'pg'` when omitted. */
+  readonly driver?: 'pg';
+};
+
+/** Options for the embedded-PGlite driver. */
+export type PgliteDbDotOptions<TRelations extends AnyRelations> = BaseDbDotOptions<TRelations> &
+  PgliteInitOptions & {
+    /** Driver discriminant. */
+    readonly driver: 'pglite';
+  };
+
+/** Discriminated union of all supported driver option shapes. */
+export type DbDotOptions<TRelations extends AnyRelations> = PgDbDotOptions<TRelations> | PgliteDbDotOptions<TRelations>;
+
+/**
+ * Services published by the db adapter. Keyed by the driver — for the
+ * default `'pg'` driver, `services.db` is a `NodePgDatabase<TRelations>`;
+ * for `'pglite'` it is a `PgliteDatabase<TRelations>`.
+ */
+export type DbServices<TRelations extends AnyRelations, TDriver extends 'pg' | 'pglite' = 'pg'> = {
+  readonly db: TDriver extends 'pglite' ? PgliteDatabase<TRelations> : NodePgDatabase<TRelations>;
+};
+
+/**
+ * Build a DOT pip that opens a Drizzle database and publishes it as
+ * a service. The kernel calls `dispose` in reverse declaration order to
+ * close the underlying pool / PGlite instance.
+ */
+export function db<TRelations extends AnyRelations>(
+  options: PgDbDotOptions<TRelations>,
+): Pip<EmptyShape, DbServices<TRelations, 'pg'>>;
+export function db<TRelations extends AnyRelations>(
+  options: PgliteDbDotOptions<TRelations>,
+): Pip<EmptyShape, DbServices<TRelations, 'pglite'>>;
+export function db<TRelations extends AnyRelations>(
+  options: DbDotOptions<TRelations>,
+): Pip<EmptyShape, DbServices<TRelations, 'pg' | 'pglite'>> {
+  const driver = options.driver ?? 'pg';
+
+  if (driver === 'pglite') {
+    const pgliteOptions = options as PgliteDbDotOptions<TRelations>;
+    // PGlite path: open the embedded instance and Drizzle handle in boot.
+    // We capture the raw PGlite client at boot-time so `dispose` can close
+    // it deterministically. `services.db` is the Drizzle handle only —
+    // exposing the PGlite client would leak driver-specific surface.
+    let pgliteHandle: { close: () => Promise<void> } | undefined;
+    return pip({
+      name: 'db',
+      version: '0.1.0',
+      configure(ctx) {
+        ctx.registerService('db', 'db');
+      },
+      async boot(): Promise<DbServices<TRelations, 'pglite'>> {
+        const { db: handle, pglite } = await initDbRuntimeLocal<TRelations>(
+          {
+            ...(pgliteOptions.dataDir === undefined ? {} : { dataDir: pgliteOptions.dataDir }),
+            ...(pgliteOptions.memory === undefined ? {} : { memory: pgliteOptions.memory }),
+            ...(pgliteOptions.extensions === undefined ? {} : { extensions: pgliteOptions.extensions }),
+          },
+          { relations: pgliteOptions.relations },
+        );
+        pgliteHandle = pglite;
+        return { db: handle };
+      },
+      async dispose() {
+        if (pgliteHandle !== undefined) {
+          await pgliteHandle.close();
+          pgliteHandle = undefined;
+        }
+      },
+    }) as Pip<EmptyShape, DbServices<TRelations, 'pg' | 'pglite'>>;
+  }
+
+  // Node-postgres path: createDb already reads env vars and constructs the
+  // pool. Drizzle owns the pool — closing it goes via the `$client.end()`
+  // path that node-postgres exposes through Drizzle's handle.
+  return pip({
+    name: 'db',
+    version: '0.1.0',
+    configure(ctx) {
+      ctx.registerService('db', 'db');
+    },
+    boot(): DbServices<TRelations, 'pg'> {
+      // Validate at the pip boundary so the DOT lifecycle gets a coded
+      // error. `createDb` still throws raw `Error` for non-DOT consumers
+      // (its public contract is unchanged); the check here makes sure we
+      // never reach it without a URL.
+      if (env.DB_URL === undefined || env.DB_URL === '') {
+        throw new DotPipError({
+          code: DB_PIP_ERROR_CODES.dbUrlNotConfigured,
+          message: '[db] DB_URL is not configured.',
+          remediation:
+            'Set DB_URL in the environment before booting the app, or switch the pip to the pglite driver for in-process databases.',
+          docsUrl: 'https://arki.dev/dot/errors/db-pip-e001',
+        });
+      }
+      const handle = createDb<TRelations>({
+        relations: options.relations,
+        ...(options.logger === undefined ? {} : { logger: options.logger }),
+      });
+      return { db: handle };
+    },
+    async dispose({ db: handle }) {
+      // Drizzle exposes the underlying pg.Pool as `$client`. We call its
+      // `end()` to drain in-flight queries and close all sockets.
+      const pgHandle = handle as NodePgDatabase<TRelations> & {
+        $client?: { end: () => Promise<void> };
+      };
+      if (pgHandle.$client !== undefined) {
+        await pgHandle.$client.end();
+      }
+    },
+  }) as Pip<EmptyShape, DbServices<TRelations, 'pg' | 'pglite'>>;
+}

package/src/env.ts

@@ -0,0 +1,92 @@
+import { defineEnv } from '@arki/env/core';
+
+import { z } from '@arki/contracts';
+
+export const env = defineEnv({
+  name: '@arki/db',
+  /**
+   * Environment variables schema for database services (PostgreSQL)
+   */
+  server: {
+    // General Configuration
+    NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+
+    // Database Connection - Primary method (connection string)
+    // DB_URL is the canonical @arki/db name. DATABASE_URL (PG/Coolify/12-factor
+    // standard) is also accepted as a fallback via the runtimeEnv alias below,
+    // which resolves to this same `env.DB_URL` field so consumers don't change.
+    DB_URL: z.url(),
+
+    // Database Connection - Individual parameters (alternative to DB_URL)
+    PGUSER: z.string().optional(),
+    PGPASSWORD: z.string().optional(),
+    PGHOST: z.string().default('localhost'),
+    PGPORT: z.coerce.number().default(5432),
+    PGDATABASE: z.string().optional(),
+    PGSSLMODE: z.enum(['disable', 'allow', 'prefer', 'require', 'verify-ca', 'verify-full']).default('prefer'),
+
+    // Connection Pool Configuration
+    DB_POOL_MIN: z.coerce.number().default(2),
+    DB_POOL_MAX: z.coerce.number().default(20),
+    DB_POOL_IDLE_TIMEOUT: z.coerce.number().default(30_000), // 30 seconds
+    DB_POOL_CONNECTION_TIMEOUT: z.coerce.number().default(2000), // 2 seconds
+
+    // Database Behavior Configuration
+    DB_LOGGING: z.coerce.boolean().default(false),
+    DB_MIGRATIONS_FOLDER: z.string().default('./migrations'),
+    DB_SCHEMA: z.string().default('public'),
+
+    // Performance and Reliability
+    DB_STATEMENT_TIMEOUT: z.coerce.number().default(30_000), // 30 seconds
+    DB_QUERY_TIMEOUT: z.coerce.number().default(60_000), // 1 minute
+    DB_IDLE_IN_TRANSACTION_SESSION_TIMEOUT: z.coerce.number().default(10_000), // 10 seconds
+
+    // Development and Testing
+    DB_SEED_ON_START: z
+      .string()
+      .optional()
+      .transform(val => val === 'true'),
+    DB_DROP_ON_START: z
+      .string()
+      .optional()
+      .transform(val => val === 'true'),
+  },
+
+  client: {},
+  clientPrefix: '',
+
+  /**
+   * Destructure all variables from `process.env` to make sure they aren't tree-shaken away.
+   */
+  runtimeEnv: {
+    NODE_ENV: process.env['NODE_ENV'],
+    // Resolve from `DB_URL` (canonical) first, falling back to `DATABASE_URL`
+    // (PG/Coolify/12-factor standard) so deployments using the standard name
+    // still work. Closes the silent divergence between app schemas keyed on
+    // DATABASE_URL and this package's DB_URL schema.
+    DB_URL: process.env['DB_URL'] ?? process.env['DATABASE_URL'],
+    PGUSER: process.env['PGUSER'],
+    PGPASSWORD: process.env['PGPASSWORD'],
+    PGHOST: process.env['PGHOST'],
+    PGPORT: process.env['PGPORT'],
+    PGDATABASE: process.env['PGDATABASE'],
+    PGSSLMODE: process.env['PGSSLMODE'],
+    DB_POOL_MIN: process.env['DB_POOL_MIN'],
+    DB_POOL_MAX: process.env['DB_POOL_MAX'],
+    DB_POOL_IDLE_TIMEOUT: process.env['DB_POOL_IDLE_TIMEOUT'],
+    DB_POOL_CONNECTION_TIMEOUT: process.env['DB_POOL_CONNECTION_TIMEOUT'],
+    DB_LOGGING: process.env['DB_LOGGING'],
+    DB_MIGRATIONS_FOLDER: process.env['DB_MIGRATIONS_FOLDER'],
+    DB_SCHEMA: process.env['DB_SCHEMA'],
+    DB_STATEMENT_TIMEOUT: process.env['DB_STATEMENT_TIMEOUT'],
+    DB_QUERY_TIMEOUT: process.env['DB_QUERY_TIMEOUT'],
+    DB_IDLE_IN_TRANSACTION_SESSION_TIMEOUT: process.env['DB_IDLE_IN_TRANSACTION_SESSION_TIMEOUT'],
+    DB_SEED_ON_START: process.env['DB_SEED_ON_START'],
+    DB_DROP_ON_START: process.env['DB_DROP_ON_START'],
+  },
+
+  options: {
+    skipValidation:
+      !!process.env['SKIP_ENV_VALIDATION'] || !!process.env['CI'] || process.env['NODE_ENV'] === 'test',
+  },
+});

package/src/factory.ts

@@ -0,0 +1,47 @@
+import type { AnyRelations, Logger } from 'drizzle-orm';
+
+import { getDbConnectionOptions } from './connection-options.js';
+import { debugFactory } from './debug.js';
+import { env } from './env.js';
+import { initDbWithOptions } from './init.js';
+
+/**
+ * Create a database connection using environment configuration.
+ *
+ * `relations` is required (mark the field even when empty) so TypeScript can
+ * infer the precise relations type for `db.query.*` autocomplete. Use
+ * `defineRelations(schema, callback)` to build the value.
+ *
+ * @throws Error if DB_URL is not configured.
+ */
+export function createDb<TRelations extends AnyRelations>(
+  config: {
+    relations: TRelations;
+    logger?: boolean | Logger | undefined;
+  },
+) {
+  debugFactory('[factory] Creating database from environment configuration');
+
+  const connectionUrl = env.DB_URL;
+  if (!connectionUrl) {
+    debugFactory('[factory] Database creation failed: DB_URL not configured');
+    throw new Error('Database URL is not configured. Please set DB_URL environment variable.');
+  }
+
+  const connectionOptions = getDbConnectionOptions();
+
+  debugFactory('[factory] Connection options (min: %d, max: %d, idleTimeout: %dms, connTimeout: %dms)',
+    connectionOptions.min, connectionOptions.max,
+    connectionOptions.idleTimeoutMillis, connectionOptions.connectionTimeoutMillis);
+
+  const db = initDbWithOptions<TRelations>(connectionOptions, {
+    ...config,
+    logger: config.logger ?? (env.DB_LOGGING || env.NODE_ENV === 'development'),
+  });
+
+  debugFactory('[factory] Database created successfully');
+
+  return db;
+}
+
+export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';

package/src/id-factory.ts

@@ -0,0 +1,172 @@
+import { createId as createCuid } from '@paralleldrive/cuid2';
+import type { PgColumn } from 'drizzle-orm/pg-core';
+import { varchar } from 'drizzle-orm/pg-core';
+
+import { COLUMN_ZOD_SCHEMA, z } from '@arki/contracts';
+
+// Core ID creation
+export const createId = () => createCuid();
+
+export const createPrefixedId = <T extends string>(prefix: T): `${T}${string}` => {
+  return `${prefix}${createId()}`;
+};
+
+/**
+ * Stash a Zod schema on a Drizzle column builder so that
+ * `@arki/contracts`'s `createSelectSchema`/`createInsertSchema`/`createUpdateSchema`
+ * wrappers auto-apply it as a refine — turning the brand from a phantom-only
+ * type into a real runtime check.
+ *
+ * The builder's `config` object is the SAME reference passed to the constructed
+ * column (see `PgVarcharBuilder.build` → `new PgVarchar(table, this.config)`),
+ * so writing here is readable from the column later.
+ */
+function tagColumnSchema<TBuilder>(builder: TBuilder, schema: z.ZodTypeAny): TBuilder {
+  const cfg = (builder as unknown as { config: Record<string | symbol, unknown> }).config;
+  cfg[COLUMN_ZOD_SCHEMA] = schema;
+  return builder;
+}
+
+/**
+ * Type-safe ID factory that generates all ID-related utilities at once
+ *
+ * @param prefix - The prefix for the ID type (e.g., 'pt', 'usr', 'ant')
+ * @returns An object with create function, schema, and column helpers
+ *
+ * @example
+ * ```typescript
+ * export type PoetId = `pt${string}`;
+ * const poetId = createIdFactory<'pt', PoetId>('pt');
+ *
+ * export const createPoetId = poetId.create;
+ * export const poetIdSchema = poetId.schema;
+ *
+ * export const poets = schema.table('poets', {
+ *   id: poetId.primaryColumn(),
+ *   // ... other columns
+ * });
+ * ```
+ */
+export function createIdFactory<TPrefix extends string, TId extends `${TPrefix}${string}`>(prefix: TPrefix) {
+  /**
+   * Zod validation schema for the ID type. Uses refine instead of transform
+   * for better type safety; auto-applied at parse time by @arki/contracts'
+   * schema wrappers when this factory's columns appear on the table.
+   */
+  const schema = z
+    .string()
+    .startsWith(prefix)
+    .brand<TId>()
+    .transform(id => id as TId);
+
+  const factory = {
+    /**
+     * Creates a new ID with the specified prefix
+     */
+    create: (): TId => createPrefixedId(prefix) as TId,
+    /**
+     * Creates a new ID with the specified prefix
+     */
+    make: (): TId => createPrefixedId(prefix) as TId,
+    /**
+     * Creates a new ID with the specified prefix
+     */
+    new: (): TId => createPrefixedId(prefix) as TId,
+
+    schema,
+
+    /**
+     * Drizzle column helper for primary key columns
+     * Automatically configures as varchar(256), not null, primary key, with proper type and default
+     */
+    primaryColumn: (name = 'id') =>
+      tagColumnSchema(
+        varchar(name, { length: 256 })
+          .notNull()
+          .primaryKey()
+          .$type<TId>()
+          .$defaultFn(() => createPrefixedId(prefix) as TId),
+        schema,
+      ),
+
+    optionalColumn: (name: string) =>
+      tagColumnSchema(
+        varchar(name, { length: 256 })
+          .$type<TId | null>()
+          .$defaultFn(() => null),
+        schema,
+      ),
+
+    requiredColumn: (name: string) =>
+      tagColumnSchema(
+        varchar(name, { length: 256 })
+          .notNull()
+          .$type<TId>()
+          .$defaultFn(() => createPrefixedId(prefix) as TId),
+        schema,
+      ),
+
+    /**
+     * Drizzle column helper for foreign key reference columns
+     * Configures as varchar(256), not null, with proper type (no default or primary key)
+     */
+    reference: (name: string) =>
+      tagColumnSchema(varchar(name, { length: 256 }).notNull().$type<TId>(), schema),
+
+    /**
+     * Drizzle column helper for optional foreign key reference columns
+     * Configures as varchar(256), nullable, with proper type
+     */
+    optionalReference: (name: string) =>
+      tagColumnSchema(varchar(name, { length: 256 }).$type<TId>(), schema),
+
+    /**
+     * Drizzle column helper for foreign key reference with relation
+     * Configures as varchar(256), not null, with proper type and foreign key constraint
+     */
+    foreignKey: (
+      name: string,
+      referenceFn: () => PgColumn,
+      options?: { onDelete?: 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default' },
+    ) =>
+      tagColumnSchema(
+        varchar(name, { length: 256 }).notNull().$type<TId>().references(referenceFn, options),
+        schema,
+      ),
+
+    /**
+     * Drizzle column helper for optional foreign key reference with relation
+     * Configures as varchar(256), nullable, with proper type and foreign key constraint
+     */
+    optionalForeignKey: (
+      name: string,
+      referenceFn: () => PgColumn,
+      options?: { onDelete?: 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default' },
+    ) =>
+      tagColumnSchema(
+        varchar(name, { length: 256 }).$type<TId>().references(referenceFn, options),
+        schema,
+      ),
+
+    /**
+     * Creates a foreign key factory bound to a specific table
+     * This allows creating multiple foreign keys to the same table without repeating the reference
+     */
+    createForeignKeyFactory: (referenceFn: () => PgColumn) => ({
+      required: (
+        name: string,
+        options?: { onDelete?: 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default' },
+      ) => factory.foreignKey(name, referenceFn, options),
+      optional: (
+        name: string,
+        options?: { onDelete?: 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default' },
+      ) => factory.optionalForeignKey(name, referenceFn, options),
+    }),
+  };
+
+  return factory;
+}
+
+// Re-export drizzle and zod utilities
+export * from 'drizzle-orm';
+export { createInsertSchema, createSelectSchema, createSchemaFactory, createUpdateSchema } from 'drizzle-orm/zod';

package/src/id.ts

@@ -0,0 +1,12 @@
+import { createId as createCuid } from '@paralleldrive/cuid2';
+
+export const createId = () => {
+  return createCuid();
+};
+
+export const createPrefixedId = <T extends string>(prefix: T): `${T}${string}` => {
+  return `${prefix}${createId()}`;
+};
+
+// Re-export the new ID factory
+export * from './id-factory.js';

package/src/init.bun.ts

@@ -0,0 +1,58 @@
+import type { AnyRelations } from 'drizzle-orm';
+import type { DrizzlePgConfig } from 'drizzle-orm/pg-core/utils';
+import { drizzle } from 'drizzle-orm/bun-sql/postgres';
+import { SQL } from 'bun';
+
+import { debugInit } from './debug.js';
+
+debugInit('[init.bun] Using Bun SQL (native) for database connections');
+
+export const initDb = <TRelations extends AnyRelations>(
+  connectionString: string,
+  config: Omit<DrizzlePgConfig<TRelations>, 'relations'> & { relations: TRelations },
+) => {
+  debugInit('[init.bun] Initializing database with connection string (logger: %s)', !!config.logger);
+
+  const client = new SQL(connectionString);
+  const db = drizzle<TRelations>({ ...config, client });
+
+  debugInit('[init.bun] Database initialized successfully');
+
+  return db;
+};
+
+export const initDbWithOptions = <TRelations extends AnyRelations>(
+  poolConfig: {
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    user?: string;
+    password?: string;
+    min?: number;
+    max?: number;
+  },
+  config: Omit<DrizzlePgConfig<TRelations>, 'relations'> & { relations: TRelations },
+) => {
+  debugInit('[init.bun] Initializing database with pool config (min: %d, max: %d, logger: %s)',
+    poolConfig.min ?? 0, poolConfig.max ?? 10, !!config.logger);
+
+  const client = poolConfig.connectionString
+    ? new SQL(poolConfig.connectionString)
+    : new SQL({
+        hostname: poolConfig.host,
+        port: poolConfig.port,
+        database: poolConfig.database,
+        username: poolConfig.user,
+        password: poolConfig.password,
+      });
+
+  const db = drizzle<TRelations>({ ...config, client });
+
+  debugInit('[init.bun] Database initialized with custom pool configuration');
+
+  return db;
+};
+
+export { createDb } from './factory.js';
+export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';

package/src/init.ts

@@ -0,0 +1,48 @@
+import type { AnyRelations } from 'drizzle-orm';
+import type { DrizzlePgConfig } from 'drizzle-orm/pg-core/utils';
+import type { PoolConfig } from 'pg';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import pg from 'pg';
+
+import { debugInit } from './debug.js';
+
+const Pool = pg.Pool;
+debugInit('[init] Using pg (pure JS) for database connections');
+
+export const initDb = <TRelations extends AnyRelations>(
+  connectionString: string,
+  config: Omit<DrizzlePgConfig<TRelations>, 'relations'> & { relations: TRelations },
+) => {
+  debugInit('[init] Initializing database with connection string (logger: %s)', !!config.logger);
+
+  const client = new Pool({
+    connectionString,
+  });
+
+  const db = drizzle<TRelations>({ ...config, client });
+  debugInit('[init] Database initialized successfully');
+
+  return db;
+};
+
+export const initDbWithOptions = <TRelations extends AnyRelations>(
+  poolConfig: PoolConfig,
+  config: Omit<DrizzlePgConfig<TRelations>, 'relations'> & { relations: TRelations },
+) => {
+  debugInit(
+    '[init] Initializing database with pool config (min: %d, max: %d, logger: %s)',
+    poolConfig.min ?? 0,
+    poolConfig.max ?? 10,
+    !!config.logger,
+  );
+
+  const client = new Pool(poolConfig);
+
+  const db = drizzle<TRelations>({ ...config, client });
+  debugInit('[init] Database initialized with custom pool configuration');
+
+  return db;
+};
+
+export { createDb } from './factory.js';
+export { getDbConnectionOptions, getDbConnectionParams } from './connection-options.js';

package/src/orm.ts

@@ -0,0 +1,9 @@
+export * from 'drizzle-orm';
+// `drizzle-orm/zod` replaces the standalone drizzle-zod package in 1.0.
+// Named re-export prevents an IsNever collision with drizzle-orm's main types.
+export {
+  createInsertSchema,
+  createSchemaFactory,
+  createSelectSchema,
+  createUpdateSchema,
+} from 'drizzle-orm/zod';

package/src/pg.ts

@@ -0,0 +1 @@
+export * from 'drizzle-orm/pg-core';

package/src/runtime-local.ts

@@ -0,0 +1,48 @@
+import type { AnyRelations } from 'drizzle-orm';
+import { PGlite, type Extension } from '@electric-sql/pglite';
+import { drizzle, type PgliteDatabase } from 'drizzle-orm/pglite';
+
+import { debugInit } from './debug.js';
+
+export type PgliteInitOptions = {
+  /** Path to the PGlite data directory. Defaults to `./.local/db`. */
+  dataDir?: string;
+  /** Use an in-memory database (overrides dataDir). */
+  memory?: boolean;
+  /** PGlite extensions to load (e.g. `{ vector }` from `@electric-sql/pglite/vector`). */
+  extensions?: Record<string, Extension>;
+};
+
+/**
+ * Initialize a PGlite-backed Drizzle database for embedded local development.
+ *
+ * Returns the raw PGlite instance alongside the Drizzle handle so callers can
+ * share it with `@arki/queue/runtime-local` (one process, one PGlite).
+ *
+ * @example
+ * ```ts
+ * import { initDbRuntimeLocal } from '@arki/db/runtime-local';
+ * const { db, pglite } = await initDbRuntimeLocal({ dataDir: './.local/db' }, { relations });
+ * ```
+ */
+export async function initDbRuntimeLocal<TRelations extends AnyRelations>(
+  options: PgliteInitOptions,
+  config: { relations: TRelations },
+): Promise<{ db: PgliteDatabase<TRelations>; pglite: PGlite }> {
+  const url = options.memory === true ? 'memory://' : (options.dataDir ?? './.local/db');
+  debugInit('[runtime-local] Initializing PGlite at: %s', url);
+
+  const pglite = options.extensions
+    ? new PGlite(url, { extensions: options.extensions })
+    : new PGlite(url);
+  await pglite.waitReady;
+  debugInit('[runtime-local] PGlite ready');
+
+  const db = drizzle({
+    client: pglite,
+    relations: config.relations,
+  }) as PgliteDatabase<TRelations>;
+
+  debugInit('[runtime-local] Drizzle database initialized');
+  return { db, pglite };
+}