@arki/db 0.1.0 → 0.1.2

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';