@xemahq/biome-database-nest 0.12.0 → 0.12.2

package/src/lib/bootstrap.ts

@@ -1,433 +0,0 @@
-import { createHash } from 'node:crypto';
-import { readFileSync } from 'node:fs';
-import { writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { Logger } from '@nestjs/common';
-import { PrismaMigrationRunner } from '@xemahq/migration-runner-prisma';
-import {
-  composeBiomeDatabaseUrl,
-  ensureBiomeDbSearchPath,
-} from '@xemahq/platform-common';
-import { Client } from 'pg';
-
-import { resolveBiomeDatabaseConfigFromEnv } from './config';
-import { fetchSystemDatabaseConfig } from './control-plane-client';
-import {
-  resolveControlPlaneBaseUrl,
-  type ControlPlaneDiscoveryOptions,
-} from './control-plane-discovery';
-import {
-  BiomeDatabaseMigrationMode,
-} from './migration-mode';
-import { DEFAULT_BIOME_DB_KEY } from './schema-name';
-
-import type { BiomeDatabaseConfig } from './config';
-import type { KernelState } from '@xemahq/kernel-contracts/kernel-state';
-
-/** One database whose schema and Prisma migrations the application owns. */
-export interface BiomeDatabaseDeclaration {
-  /** Defaults to `'primary'`. */
-  readonly key?: string;
-  /** Directory containing `prisma/` (cwd for `prisma migrate deploy`). */
-  readonly workspaceDir: string;
-}
-
-
-interface BootstrapBiomeDatabasesCommonOptions {
-  readonly biomeId: string;
-  /**
-   * A service bearer, or a factory that mints one. Required whenever the
-   * selected credential path is the control plane. Its address is discovered
-   * from the service registry via {@link kernelState}.
-   */
-  readonly serviceToken?: string | (() => Promise<string>);
-  /**
-   * The app's `KernelState` backend (injected via `KERNEL_STATE_TOKEN`). Used to
-   * discover the `org-database-pool-api` control-plane address from the service
-   * registry. Required on the control-plane path; unused when every declared
-   * database explicitly resolves from the environment.
-   */
-  readonly kernelState: KernelState;
-  /** Optional bounded-backoff tuning for control-plane discovery. */
-  readonly controlPlaneDiscovery?: ControlPlaneDiscoveryOptions;
-}
-
-export interface ApplicationManagedBootstrapOptions
-  extends BootstrapBiomeDatabasesCommonOptions {
-  readonly migrationMode: BiomeDatabaseMigrationMode.ApplicationManaged;
-  readonly databases: readonly BiomeDatabaseDeclaration[];
-  /**
-   * Postgres extensions this biome needs, ensured in the SHARED `public` schema
-   * BEFORE migrations run (e.g. `['vector']` for pgvector). A Postgres
-   * extension can exist in only ONE schema per database, so installing it in
-   * each biome's own schema would make whichever biome migrates first win and
-   * every later biome fail to resolve the type. Installing in `public` (which
-   * every biome's search_path includes) keeps it shared. `CREATE EXTENSION IF
-   * NOT EXISTS` is idempotent; only declare extensions the biome actually uses
-   * so non-Postgres-extension environments (local dev) are unaffected.
-   */
-  readonly requiredExtensions?: readonly string[];
-}
-
-
-export type BootstrapBiomeDatabasesOptions =
-  ApplicationManagedBootstrapOptions;
-
-const LOG_PREFIX = '[biome-database]';
-
-/**
- * Boot-progress sink. A published SDK must not write to the host's raw
- * stdout: this bootstrap runs from a service's `main.ts`, so its output
- * belongs on the same Nest logger transport as the rest of that service's
- * boot. `Logger`'s static/instance API works before `NestFactory.create`,
- * which is exactly when this runs.
- */
-const bootstrapLogger = new Logger('BiomeDatabaseBootstrap');
-
-function upperKeySuffix(key: string): string {
-  return key === DEFAULT_BIOME_DB_KEY
-    ? ''
-    : `_${key.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
-}
-
-async function resolveServiceToken(
-  serviceToken: string | (() => Promise<string>) | undefined,
-): Promise<string> {
-  if (serviceToken === undefined) {
-    throw new Error(
-      `${LOG_PREFIX} no local DB_* override and no serviceToken supplied — ` +
-        'cannot authenticate to the control plane.',
-    );
-  }
-  return typeof serviceToken === 'function' ? serviceToken() : serviceToken;
-}
-
-/**
- * Resolve config for one database: local `DB_*` override FIRST, control plane
- * as the fallback. Throws if neither yields a config (no silent default). The
- * control-plane base URL is obtained via {@link getControlPlaneBaseUrl}, which
- * discovers `org-database-pool-api` from the service registry (memoized across
- * databases so discovery runs at most once per bootstrap).
- */
-async function resolveDatabaseConfig(
-  opts: BootstrapBiomeDatabasesCommonOptions,
-  key: string,
-  getControlPlaneBaseUrl: () => Promise<string>,
-): Promise<BiomeDatabaseConfig> {
-  const local = resolveBiomeDatabaseConfigFromEnv(process.env, key);
-  if (local !== null) {
-    return local;
-  }
-  const baseUrl = await getControlPlaneBaseUrl();
-  const token = await resolveServiceToken(opts.serviceToken);
-  return fetchSystemDatabaseConfig(baseUrl, token, {
-    biomeId: opts.biomeId,
-    ...(key !== DEFAULT_BIOME_DB_KEY ? { dbKey: key } : {}),
-  });
-}
-
-
-/**
- * If the config carries an inline CA PEM, write it to a deterministic temp file
- * and rewrite `sslParams` so `sslrootcert` points at it. Returns the config to
- * use downstream. When no inline CA is present, the config is returned as-is
- * (any already-mounted `sslrootcert` path in `sslParams` is preserved).
- */
-async function materializeInlineCaCert(
-  biomeId: string,
-  key: string,
-  config: BiomeDatabaseConfig,
-): Promise<BiomeDatabaseConfig> {
-  if (config.caCertPem === undefined || config.caCertPem === '') {
-    return config;
-  }
-  const hash = createHash('sha256')
-    .update(`${biomeId}:${key}`)
-    .digest('hex')
-    .slice(0, 16);
-  const certPath = join(tmpdir(), `xema-biome-db-ca-${hash}.crt`);
-  await writeFile(certPath, config.caCertPem, { mode: 0o600 });
-
-  const params = new URLSearchParams(config.sslParams ?? '');
-  params.set('sslrootcert', certPath);
-  if (!params.has('sslmode')) {
-    params.set('sslmode', 'verify-full');
-  }
-  bootstrapLogger.log(
-    `${LOG_PREFIX} biome=${biomeId} key=${key}: wrote inline CA cert to ${certPath}`,
-  );
-  return { ...config, sslParams: params.toString() };
-}
-
-/**
- * Ensure `config.schema` exists. No-op when the config has no schema (dedicated
- * DB). Uses a per-schema advisory lock inside a txn so concurrent replicas
- * serialize the `CREATE SCHEMA IF NOT EXISTS`.
- */
-/**
- * Build the node-postgres `ssl` option from the config's `sslParams` /
- * `caCertPem`. Managed Postgres (e.g. DigitalOcean) REQUIRES TLS — a raw
- * `Client` with no `ssl` is rejected at connect. We mirror libpq `sslmode`:
- *   - absent / `disable`            → no TLS
- *   - `require` / `prefer`          → encrypt, do NOT verify the chain/host
- *   - `verify-ca` / `verify-full`   → verify against the CA (the CA comes from
- *                                     inline `caCertPem` or the `sslrootcert`
- *                                     file path in `sslParams`)
- */
-function buildPgSsl(
-  config: BiomeDatabaseConfig,
-): false | { ca?: string; rejectUnauthorized: boolean } {
-  const params = new URLSearchParams(config.sslParams ?? '');
-  const sslmode = params.get('sslmode');
-  if (sslmode === null || sslmode === 'disable') {
-    return false;
-  }
-  const verify = sslmode === 'verify-ca' || sslmode === 'verify-full';
-  const caPath = params.get('sslrootcert');
-  const ca =
-    config.caCertPem ?? (caPath ? readFileSync(caPath, 'utf8') : undefined);
-  return {
-    ...(ca !== undefined ? { ca } : {}),
-    rejectUnauthorized: verify,
-  };
-}
-
-function isValidExtensionName(name: string): boolean {
-  return /^[a-z0-9_]+$/i.test(name);
-}
-
-async function ensureSchemaExists(
-  biomeId: string,
-  key: string,
-  config: BiomeDatabaseConfig,
-  requiredExtensions: readonly string[],
-): Promise<void> {
-  const schema = config.schema;
-  const hasSchema = schema !== undefined && schema !== '';
-  if (!hasSchema && requiredExtensions.length === 0) {
-    return;
-  }
-  const client = new Client({
-    host: config.host,
-    port: config.port,
-    database: config.database,
-    user: config.username,
-    password: config.password,
-    ssl: buildPgSsl(config),
-  });
-  await client.connect();
-  try {
-    // Shared extensions FIRST, in `public` (a Postgres extension can live in
-    // only ONE schema per DB; `public` is in every biome's search_path so the
-    // type/ops resolve everywhere). Idempotent; runs before migrate so a
-    // migration's own `CREATE EXTENSION IF NOT EXISTS` no-ops.
-    for (const ext of requiredExtensions) {
-      if (!isValidExtensionName(ext)) {
-        throw new Error(
-          `${LOG_PREFIX} biome=${biomeId}: invalid extension name "${ext}".`,
-        );
-      }
-      await client.query(
-        `CREATE EXTENSION IF NOT EXISTS "${ext}" SCHEMA public`,
-      );
-      bootstrapLogger.log(
-        `${LOG_PREFIX} biome=${biomeId} key=${key}: ensured extension "${ext}" in public`,
-      );
-    }
-    if (hasSchema) {
-      await client.query('BEGIN');
-      await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [
-        schema,
-      ]);
-      await client.query(`CREATE SCHEMA IF NOT EXISTS "${schema}"`);
-      await client.query('COMMIT');
-      bootstrapLogger.log(
-        `${LOG_PREFIX} biome=${biomeId} key=${key}: ensured schema "${schema}" exists`,
-      );
-    }
-  } catch (err) {
-    await client.query('ROLLBACK').catch(() => undefined);
-    throw err;
-  } finally {
-    await client.end();
-  }
-}
-
-/** Build the direct connection URL for a resolved database config. */
-function buildDirectConnectionUrl(
-  biomeId: string,
-  key: string,
-  config: BiomeDatabaseConfig,
-): string {
-  const directUrl = composeBiomeDatabaseUrl({
-    user: config.username,
-    password: config.password,
-    host: config.host,
-    port: String(config.port),
-    database: config.database,
-    ...(config.schema !== undefined ? { schema: config.schema } : {}),
-    ...(config.sslParams !== undefined ? { sslParams: config.sslParams } : {}),
-  });
-  if (directUrl === null) {
-    throw new Error(
-      `${LOG_PREFIX} biome=${biomeId} key=${key}: incomplete config — cannot form a database URL.`,
-    );
-  }
-  return ensureBiomeDbSearchPath(directUrl);
-}
-
-async function runMigrations(
-  biomeId: string,
-  key: string,
-  workspaceDir: string,
-  migrateUrl: string,
-): Promise<void> {
-  bootstrapLogger.log(
-    `${LOG_PREFIX} biome=${biomeId} key=${key}: running prisma migrate deploy (cwd=${workspaceDir})`,
-  );
-  // The migrate connection MUST carry `public` in its search_path (not just the
-  // biome schema) so migrations resolve SHARED objects that live in `public` —
-  // notably the pgvector `vector`/`halfvec` types and their operator classes.
-  // pgvector can only be installed in ONE schema per database; the shared
-  // xema_biomes DB keeps it in `public`. Without `,public` here, a biome whose
-  // schema is the migrate target cannot see `public.vector` and CREATE TABLE
-  // with a `vector` column fails (`type "vector" does not exist`). The runtime
-  // URL already gets this via `ensureBiomeDbSearchPath`; the migrate URL needs
-  // it too. `ensureBiomeDbSearchPath` is idempotent.
-  const result = await new PrismaMigrationRunner().run({
-    workspaceDir,
-    connectionUrl: migrateUrl,
-    env: {},
-  });
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `${LOG_PREFIX} biome=${biomeId} key=${key}: migrations failed (exit ${result.exitCode}):\n${result.output}`,
-    );
-  }
-}
-
-/**
- * Build the STEADY-STATE runtime URL. When the config declares a transaction
- * pooler (`poolerHost`), the runtime connection is routed through it — the fix
- * for connection fan-out across many replicas × biomes — while `migrateUrl`
- * (direct) is what schema-create and `prisma migrate deploy` already used.
- *
- * The app→pooler leg is normally in-cluster plaintext (`sslmode=disable` by
- * default); the pooler terminates the managed-Postgres TLS on its own upstream
- * leg. Both URLs carry the libpq `search_path` option (via
- * `ensureBiomeDbSearchPath`) so RAW queries resolve to the biome schema — the
- * pooler must be configured to track `search_path` per-client (PgBouncer ≥1.23
- * `track_extra_parameters = search_path`) so transaction pooling stays correct.
- *
- * No pooler declared → returns the direct runtime URL (current behavior).
- */
-function buildRuntimeUrl(
-  biomeId: string,
-  key: string,
-  config: BiomeDatabaseConfig,
-  directUrl: string,
-): string {
-  if (config.poolerHost === undefined || config.poolerHost === '') {
-    return ensureBiomeDbSearchPath(directUrl);
-  }
-  const pooledUrl = composeBiomeDatabaseUrl({
-    user: config.username,
-    password: config.password,
-    host: config.poolerHost,
-    port: String(config.poolerPort ?? config.port),
-    database: config.database,
-    ...(config.schema !== undefined ? { schema: config.schema } : {}),
-    sslParams: config.poolerSslParams ?? 'sslmode=disable',
-  });
-  if (pooledUrl === null) {
-    throw new Error(
-      `${LOG_PREFIX} biome=${biomeId} key=${key}: incomplete config — cannot form a pooled runtime URL.`,
-    );
-  }
-  bootstrapLogger.log(
-    `${LOG_PREFIX} biome=${biomeId} key=${key}: runtime routed through pooler ${config.poolerHost}:${config.poolerPort ?? config.port}`,
-  );
-  return ensureBiomeDbSearchPath(pooledUrl);
-}
-
-
-
-
-/**
- * Export the resolved connection into the env the unchanged-shape
- * `PrismaService` reads. The primary DB lands on `DATABASE_URL`/`DB_SCHEMA`;
- * additional keys land on `DATABASE_URL_<KEY>`/`DB_SCHEMA_<KEY>`.
- */
-function exportResolvedEnv(
-  key: string,
-  config: BiomeDatabaseConfig,
-  runtimeUrl: string,
-): void {
-  const suffix = upperKeySuffix(key);
-  process.env[`DATABASE_URL${suffix}`] = runtimeUrl;
-  if (config.schema !== undefined && config.schema !== '') {
-    process.env[`DB_SCHEMA${suffix}`] = config.schema;
-  }
-}
-
-/**
- * Bootstrap every declared biome database according to its explicit migration
- * ownership mode.
- *
- * Application-managed mode retains schema/extension creation and Prisma
- * migration execution. Externally-managed mode performs no DDL and never
- * invokes the migration runner: it resolves only the explicitly selected
- * runtime credential, proves its least-privilege contract and migration
- * compatibility, then exports the verified runtime URL.
- */
-export async function bootstrapBiomeDatabases(
-  opts: BootstrapBiomeDatabasesOptions,
-): Promise<void> {
-  // Discover the control-plane address at most once, and only when a database
-  // actually needs it (i.e. has no local DB_* override).
-  let cachedBaseUrl: string | undefined;
-  const getControlPlaneBaseUrl = async (): Promise<string> => {
-    if (cachedBaseUrl === undefined) {
-      cachedBaseUrl = await resolveControlPlaneBaseUrl(
-        opts.kernelState,
-        opts.controlPlaneDiscovery,
-      );
-    }
-    return cachedBaseUrl;
-  };
-
-  if (opts.migrationMode === BiomeDatabaseMigrationMode.ApplicationManaged) {
-    for (const decl of opts.databases) {
-      const key = decl.key ?? DEFAULT_BIOME_DB_KEY;
-      bootstrapLogger.log(
-        `${LOG_PREFIX} biome=${opts.biomeId} key=${key}: resolving config for mode=${opts.migrationMode}`,
-      );
-      const rawConfig = await resolveDatabaseConfig(
-        opts,
-        key,
-        getControlPlaneBaseUrl,
-      );
-      const config = await materializeInlineCaCert(
-        opts.biomeId,
-        key,
-        rawConfig,
-      );
-      const directUrl = buildDirectConnectionUrl(opts.biomeId, key, config);
-      await ensureSchemaExists(
-        opts.biomeId,
-        key,
-        config,
-        opts.requiredExtensions ?? [],
-      );
-      await runMigrations(opts.biomeId, key, decl.workspaceDir, directUrl);
-      const runtimeUrl = buildRuntimeUrl(opts.biomeId, key, config, directUrl);
-      exportResolvedEnv(key, config, runtimeUrl);
-      bootstrapLogger.log(
-        `${LOG_PREFIX} biome=${opts.biomeId} key=${key}: bootstrap complete`,
-      );
-    }
-    return;
-  }
-}

package/src/lib/config.ts

@@ -1,183 +0,0 @@
-import { DEFAULT_BIOME_DB_KEY } from './schema-name';
-
-/**
- * Fully-resolved connection facts for one biome database. Mirrors the standard
- * `DB_*` env contract but carries the inline CA option so a biome running on
- * its own runner needs no pre-mounted certificate file.
- */
-export interface BiomeDatabaseConfig {
-  readonly host: string;
-  readonly port: number;
-  readonly database: string;
-  /** Per-biome schema; `undefined` means a dedicated DB / the `public` schema. */
-  readonly schema?: string;
-  readonly username: string;
-  readonly password: string;
-  /** Monotonic credential generation returned by external provisioning. */
-  /** Pre-formed SSL query params, e.g. `sslmode=verify-full&sslrootcert=/path`. */
-  readonly sslParams?: string;
-  /** Inline CA PEM; the bootstrap writes it to a temp file and points sslrootcert at it. */
-  readonly caCertPem?: string;
-  readonly poolMax?: number;
-  /**
-   * When set, the STEADY-STATE runtime connection is routed through this
-   * transaction pooler (e.g. PgBouncer) at `poolerHost[:poolerPort]`, while
-   * schema-create and `prisma migrate deploy` still go DIRECT to `host:port`.
-   *
-   * A transaction pooler multiplexes many short-lived app connections onto a
-   * small set of server connections — the fix for connection-fan-out across
-   * many replicas × many biomes. It MUST NOT carry migrations: `migrate deploy`
-   * needs session-level state (advisory locks, DDL, prepared-statement lifetime)
-   * that transaction pooling breaks. Hence the direct-vs-pooled split.
-   *
-   * Absent → the runtime uses the direct `host` (current behavior; local dev,
-   * or any cluster without a pooler deployed). Opt-in, per-deployment.
-   */
-  readonly poolerHost?: string;
-  /** Pooler port; defaults to `port` when a `poolerHost` is set without one. */
-  readonly poolerPort?: number;
-  /**
-   * SSL params for the app→pooler leg. The pooler→Postgres leg terminates the
-   * managed-TLS in the pooler's OWN config, so the in-cluster app→pooler hop is
-   * normally plaintext. Defaults to `sslmode=disable` when a `poolerHost` is set.
-   */
-  readonly poolerSslParams?: string;
-}
-
-/** Per-dbKey env-var suffix, e.g. `analytics` → `_ANALYTICS`; primary → ''. */
-function envSuffixForKey(dbKey: string | undefined): string {
-  if (dbKey === undefined || dbKey === '' || dbKey === DEFAULT_BIOME_DB_KEY) {
-    return '';
-  }
-  return `_${dbKey.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
-}
-
-/**
- * Read a `DB_<NAME>` var, preferring the dbKey-suffixed variant and falling
- * back to the unsuffixed base. `fallbackToBase=false` reads ONLY the suffixed
- * variant (used for fields that must not be shared across keys, e.g. DB_NAME).
- */
-function readDbVar(
-  env: NodeJS.ProcessEnv,
-  base: string,
-  suffix: string,
-  fallbackToBase: boolean,
-): string | undefined {
-  const suffixed = env[`${base}${suffix}`];
-  if (suffixed !== undefined && suffixed !== '') {
-    return suffixed;
-  }
-  if (!fallbackToBase || suffix === '') {
-    return undefined;
-  }
-  const baseVal = env[base];
-  return baseVal !== undefined && baseVal !== '' ? baseVal : undefined;
-}
-
-/**
- * Resolve a {@link BiomeDatabaseConfig} from the standard `DB_*` env contract.
- *
- * This is the LOCAL-DEV OVERRIDE path. For a non-default `dbKey`, identity
- * fields (`DB_NAME`, `DB_SCHEMA`) are read from the suffixed variant ONLY,
- * while shared connection fields (host/port/user/password/ssl/pool) fall back
- * to the base var when the suffixed one is absent.
- *
- * Returns `null` when `DB_HOST` is absent entirely — the caller treats that as
- * "no local override → use the control plane". If `DB_HOST` IS set but a
- * mandatory field (port/user/password/database) is missing, this THROWS: a
- * partial override is a misconfiguration that must be loud, never silently
- * ignored.
- */
-export function resolveBiomeDatabaseConfigFromEnv(
-  env: NodeJS.ProcessEnv = process.env,
-  dbKey?: string,
-): BiomeDatabaseConfig | null {
-  const suffix = envSuffixForKey(dbKey);
-
-  const host = readDbVar(env, 'DB_HOST', suffix, true);
-  if (host === undefined) {
-    return null;
-  }
-
-  const portRaw = readDbVar(env, 'DB_PORT', suffix, true);
-  const username = readDbVar(env, 'DB_USER', suffix, true);
-  const password = readDbVar(env, 'DB_PASSWORD', suffix, true);
-  // Identity fields are per-key — never inherit the base name/schema for a
-  // non-default key, or two keys would alias the same database.
-  const database = readDbVar(env, 'DB_NAME', suffix, suffix === '');
-  const schema = readDbVar(env, 'DB_SCHEMA', suffix, suffix === '');
-  const missing: string[] = [];
-  if (portRaw === undefined) {
-    missing.push(`DB_PORT${suffix}`);
-  }
-  if (username === undefined) {
-    missing.push(`DB_USER${suffix}`);
-  }
-  if (password === undefined) {
-    missing.push(`DB_PASSWORD${suffix}`);
-  }
-  if (database === undefined) {
-    missing.push(`DB_NAME${suffix}`);
-  }
-  if (missing.length > 0) {
-    throw new Error(
-      `Partial biome database config for dbKey "${dbKey ?? DEFAULT_BIOME_DB_KEY}": ` +
-        `DB_HOST${suffix} is set but the following are missing: ${missing.join(', ')}. ` +
-        `Provide all of them or none.`,
-    );
-  }
-
-  const port = Number.parseInt(portRaw as string, 10);
-  if (!Number.isInteger(port) || port <= 0) {
-    throw new Error(
-      `Invalid DB_PORT${suffix} value "${portRaw}" — expected a positive integer.`,
-    );
-  }
-
-  const sslParams = readDbVar(env, 'DB_SSL_PARAMS', suffix, true);
-
-  // Optional transaction-pooler override for the RUNTIME leg (migrations stay
-  // direct). All three are optional; a `DB_POOLER_HOST` with no port defaults
-  // to the direct port at compose time.
-  const poolerHost = readDbVar(env, 'DB_POOLER_HOST', suffix, true);
-  const poolerPortRaw = readDbVar(env, 'DB_POOLER_PORT', suffix, true);
-  const poolerPort =
-    poolerPortRaw !== undefined
-      ? Number.parseInt(poolerPortRaw, 10)
-      : undefined;
-  if (
-    poolerPortRaw !== undefined &&
-    (!Number.isInteger(poolerPort) || poolerPort! <= 0)
-  ) {
-    throw new Error(
-      `Invalid DB_POOLER_PORT${suffix} value "${poolerPortRaw}" — expected a positive integer.`,
-    );
-  }
-  const poolerSslParams = readDbVar(env, 'DB_POOLER_SSL_PARAMS', suffix, true);
-
-  const poolMaxRaw = readDbVar(env, 'DB_POOL_MAX', suffix, true);
-  const poolMax =
-    poolMaxRaw !== undefined ? Number.parseInt(poolMaxRaw, 10) : undefined;
-  if (
-    poolMaxRaw !== undefined &&
-    (!Number.isInteger(poolMax) || poolMax! <= 0)
-  ) {
-    throw new Error(
-      `Invalid DB_POOL_MAX${suffix} value "${poolMaxRaw}" — expected a positive integer.`,
-    );
-  }
-
-  return {
-    host,
-    port,
-    database: database as string,
-    username: username as string,
-    password: password as string,
-    ...(schema !== undefined ? { schema } : {}),
-    ...(sslParams !== undefined ? { sslParams } : {}),
-    ...(poolMax !== undefined ? { poolMax } : {}),
-    ...(poolerHost !== undefined ? { poolerHost } : {}),
-    ...(poolerPort !== undefined ? { poolerPort } : {}),
-    ...(poolerSslParams !== undefined ? { poolerSslParams } : {}),
-  };
-}