@verdeect/kit 0.0.0-stage → 1.0.0-rc.1

package/dist/database/db.js

@@ -0,0 +1,234 @@
+// Db (prd.md §3.3, AC-4.1–AC-4.5, AC-4.16, UC-5). Эталон — O db.ts + pool-client.ts (withPoolClient, новый Drizzle на
+// клиент, afterCommit через WeakMap). Из I — отслеживание пачек для остановки (batchRuns). По PRD: read без тенанта —
+// TenantRequiredError, readGlobal — пул чтения без транзакции, afterCommit в read-only — AfterCommitInReadOnlyError,
+// setLocal. Срок пула учитывает сам пул (kit-database.module.ts, KT-19 п. 3).
+import { Logger } from '@nestjs/common';
+import { sql } from 'drizzle-orm';
+import { isConnectionError } from '../internal/pg-errors.js';
+import { bindTxContext } from '../internal/tx-context.js';
+import { sanitizeError } from '../observability/sanitize-error.js';
+import { captureError } from '../observability/sentry.js';
+import { TENANT_SETTING } from './tenant.js';
+/** `Db.read` без тенанта: чтение без компании — только `Db.readGlobal` (строгий RLS, P0). */
+export class TenantRequiredError extends Error {
+    name = 'TenantRequiredError';
+    constructor() {
+        super('Db.read: нет тенанта в DbContext — для чтения без компании используйте Db.readGlobal');
+    }
+}
+/** `Db.afterCommit` в read-only транзакции или на `readGlobal`: задачи после `COMMIT` там невозможны. */
+export class AfterCommitInReadOnlyError extends Error {
+    name = 'AfterCommitInReadOnlyError';
+    constructor() {
+        super('Db.afterCommit: read-only транзакция или readGlobal — задача после COMMIT невозможна');
+    }
+}
+/**
+ * `Db.afterCommit` с дескриптором, который не является транзакцией этого `Db` (другой `Db`, `DRIZZLE`, вложенная
+ * `tx.transaction()`): задача никогда бы не выполнилась — ошибка вместо молчаливой потери.
+ */
+export class AfterCommitOutsideTransactionError extends Error {
+    name = 'AfterCommitOutsideTransactionError';
+    constructor() {
+        super('Db.afterCommit: нужна транзакция этого Db (Db.transaction) — не вложенная и не другого Db');
+    }
+}
+/** Имя переменной `Db.setLocal`. */
+const LOCAL_NAME = /^app\.[a-z_]{1,48}$/;
+/** Служебные переменные пакета: задаются только `DbContext` в `transaction`/`read`, не `setLocal` (KT-22 п. 1). */
+const RESERVED_LOCALS = new Set([TENANT_SETTING]);
+const internals = new WeakMap();
+function internalsOf(db) {
+    const value = internals.get(db);
+    if (value === undefined) {
+        throw new TypeError('Db: объект не создан конструктором Db');
+    }
+    return value;
+}
+/** Основной пул `Db` (для `runExclusive`). */
+export function mainPoolOf(db) {
+    return internalsOf(db).main;
+}
+/**
+ * Транзакция `Db` (тенант, `afterCommit`) на уже выданном клиенте — например, на соединении блокировки `runExclusive`,
+ * без второго соединения пула (KT-22 п. 4). Клиент не возвращается в пул: им владеет вызывающий.
+ */
+export function transactionOn(db, client, ctx, fn) {
+    return internalsOf(db).runOn(client, ctx, fn);
+}
+/** Идёт остановка `Db` (шаг 3): новые пачки не начинаются. */
+export function isStopping(db) {
+    return internalsOf(db).stopping;
+}
+/** Регистрирует проход пачек: `beforeApplicationShutdown` дожидается его. */
+export function trackBatchRun(db, run) {
+    const { batchRuns } = internalsOf(db);
+    batchRuns.add(run);
+    const forget = () => void batchRuns.delete(run);
+    run.then(forget, forget);
+    return run;
+}
+/**
+ * Выделенный клиент пула на одну единицу работы; возвращается в пул всегда. Обрыв (событие `error` клиента или
+ * ошибка соединения из `work`) — `release(err)`: pg-pool уничтожает клиента, пул не исчерпывается (AC-4.4). drizzle-orm
+ * 0.45.4 выполняет BEGIN вне try/finally своей transaction() — поэтому клиент берётся здесь, а не Drizzle над пулом.
+ */
+export async function withPoolClient(pool, work, onBroken) {
+    const client = await pool.connect();
+    let broken;
+    const onError = (error) => {
+        broken ??= error;
+    };
+    client.on('error', onError);
+    try {
+        return await work(client);
+    }
+    catch (error) {
+        if (broken === undefined && isConnectionError(error)) {
+            broken = error instanceof Error ? error : new Error('соединение БД разорвано');
+        }
+        throw error;
+    }
+    finally {
+        client.removeListener('error', onError);
+        client.release(broken);
+        if (broken !== undefined) {
+            onBroken?.(broken);
+        }
+    }
+}
+/**
+ * Работа сервиса с БД под строгим RLS (§3.3): один `set_config('app.tenant', …, true)` на транзакцию, чтение без
+ * тенанта — только `readGlobal`, задачи после `COMMIT`, своя переменная `app.*`. Собирается `KitDatabaseModule`.
+ */
+export class Db {
+    logger = new Logger('Db');
+    afterCommitTasks = new WeakMap();
+    transactions = new WeakSet();
+    readOnly = new WeakSet();
+    drizzle;
+    readPool;
+    reader;
+    /** @param options пулы (с учётом срока — KitDatabaseModule) и драйвер Drizzle. */
+    constructor(options) {
+        this.drizzle = options.drizzle;
+        this.readPool = options.read;
+        this.reader = options.drizzle(options.read);
+        this.readOnly.add(this.reader);
+        internals.set(this, {
+            main: options.main,
+            runOn: (client, ctx, fn) => this.run(ctx, fn, false, client),
+            batchRuns: new Set(),
+            stopping: false,
+        });
+    }
+    /** Транзакция чтения и записи на основном пуле с тенантом `ctx.tenant` (`null` — строки компаний не видны). */
+    transaction(ctx, fn) {
+        return this.run(ctx, fn, false);
+    }
+    /**
+     * Read-only транзакция на пуле чтения (`statement_timeout` 5 с) с тенантом.
+     * @throws {TenantRequiredError} в `ctx` нет тенанта (до подключения).
+     */
+    read(ctx, fn) {
+        if (ctx.tenant === null || ctx.tenant === '') {
+            return Promise.reject(new TenantRequiredError());
+        }
+        return this.run(ctx, fn, true);
+    }
+    /** Чтение без компании (глобальные таблицы): пул чтения без транзакции и без `set_config`. */
+    async readGlobal(fn) {
+        return fn(this.reader);
+    }
+    /**
+     * Задача после `COMMIT` транзакции `tx` — по порядку, до возврата результата `transaction`; при откате не
+     * выполняется; ошибка задачи — `error`-лог и GlitchTip, не пробрасывается. Только для того, что можно потерять.
+     * @throws {AfterCommitInReadOnlyError} `tx` — транзакция `read` или дескриптор `readGlobal`.
+     * @throws {AfterCommitOutsideTransactionError} `tx` — не транзакция этого `Db` (другой `Db`, вложенная).
+     */
+    afterCommit(tx, task) {
+        if (this.readOnly.has(tx)) {
+            throw new AfterCommitInReadOnlyError();
+        }
+        if (!this.transactions.has(tx)) {
+            throw new AfterCommitOutsideTransactionError();
+        }
+        const tasks = this.afterCommitTasks.get(tx) ?? [];
+        tasks.push(task);
+        this.afterCommitTasks.set(tx, tasks);
+    }
+    /**
+     * Переменная транзакции `app.*` (`set_config(name, value, true)`), имя и значение — параметрами (AC-4.16).
+     * Служебная `app.tenant` запрещена: тенант задаётся только `DbContext` в `transaction`/`read`.
+     * @throws {TypeError} имя вне `^app\.[a-z_]{1,48}$`, служебное имя пакета или `tx` — не транзакция `Db`.
+     */
+    async setLocal(tx, name, value) {
+        if (!LOCAL_NAME.test(name)) {
+            throw new TypeError('Db.setLocal: имя вне ^app\\.[a-z_]{1,48}$');
+        }
+        if (RESERVED_LOCALS.has(name)) {
+            throw new TypeError(`Db.setLocal: ${name} — служебная переменная пакета; тенант задаётся только DbContext в Db.transaction или Db.read`);
+        }
+        if (!this.transactions.has(tx)) {
+            throw new TypeError('Db.setLocal: нужна транзакция Db.transaction или Db.read');
+        }
+        await tx.execute(sql `select set_config(${name}, ${value}, true)`);
+    }
+    /** Шаг 3 остановки: новые пачки `deleteInBatches` не начинаются, идущие дорабатывают. */
+    async beforeApplicationShutdown() {
+        const state = internalsOf(this);
+        state.stopping = true;
+        this.logger.debug({ batches: state.batchRuns.size }, 'Db: остановка, ожидание пачек');
+        await Promise.allSettled([...state.batchRuns]);
+    }
+    async run(ctx, fn, readOnly, held) {
+        const pool = readOnly ? this.readPool : mainPoolOf(this);
+        let current;
+        // ponytail: экземпляр Drizzle на транзакцию (без схемы — микросекунды); кэш — если покажет профиль.
+        const onClient = (client) => this.drizzle(client).transaction(async (tx) => {
+            current = tx;
+            this.transactions.add(tx);
+            bindTxContext(tx, ctx);
+            if (readOnly) {
+                this.readOnly.add(tx);
+            }
+            await tx.execute(sql `select set_config('app.tenant', ${ctx.tenant ?? ''}, true)`);
+            return fn(tx);
+        }, { accessMode: readOnly ? 'read only' : 'read write' });
+        try {
+            const result = held === undefined
+                ? await withPoolClient(pool, onClient, (error) => this.logger.debug({ traceId: ctx.traceId, err: sanitizeError(error) }, 'Db: соединение сломано, клиент уничтожен'))
+                : await onClient(held);
+            await this.runAfterCommit(current, ctx.traceId);
+            return result;
+        }
+        catch (error) {
+            if (current !== undefined) {
+                this.afterCommitTasks.delete(current);
+            }
+            this.logger.debug({
+                tenant: ctx.tenant,
+                traceId: ctx.traceId,
+                readOnly,
+                err: sanitizeError(error),
+            }, 'Db: транзакция откатилась');
+            throw error;
+        }
+    }
+    async runAfterCommit(tx, traceId) {
+        const tasks = tx === undefined ? undefined : this.afterCommitTasks.get(tx);
+        if (tx === undefined || tasks === undefined) {
+            return;
+        }
+        this.afterCommitTasks.delete(tx);
+        for (const task of tasks) {
+            try {
+                await task();
+            }
+            catch (error) {
+                this.logger.error({ traceId, err: sanitizeError(error) }, 'Db.afterCommit: задача упала');
+                captureError(error);
+            }
+        }
+    }
+}

package/dist/database/if-newer.d.ts

@@ -0,0 +1,9 @@
+import { type SQL } from 'drizzle-orm';
+import { type PgColumn } from 'drizzle-orm/pg-core';
+/** Колонка времени последнего применённого события: `timestamp with time zone`, nullable. */
+export declare function occurredAtColumn(name: string): import("drizzle-orm/pg-core").PgTimestampBuilderInitial<string>;
+/**
+ * Условие `WHERE` обновления: `(<column> IS NULL OR <column> < occurredAt)`. `rowCount` 0 — нормальный итог для
+ * устаревшего события.
+ */
+export declare function ifNewer(column: PgColumn, occurredAt: Date): SQL;

package/dist/database/if-newer.js

@@ -0,0 +1,15 @@
+// occurredAtColumn, ifNewer (prd.md §3.3, AC-4.13, UC-6): порядок по occurredAt — помощник обработчика, не поведение
+// подписчика (inventory §4 п. 9). Файл без pg.
+import { sql } from 'drizzle-orm';
+import { timestamp } from 'drizzle-orm/pg-core';
+/** Колонка времени последнего применённого события: `timestamp with time zone`, nullable. */
+export function occurredAtColumn(name) {
+    return timestamp(name, { withTimezone: true, mode: 'date' });
+}
+/**
+ * Условие `WHERE` обновления: `(<column> IS NULL OR <column> < occurredAt)`. `rowCount` 0 — нормальный итог для
+ * устаревшего события.
+ */
+export function ifNewer(column, occurredAt) {
+    return sql `(${column} IS NULL OR ${column} < ${occurredAt})`;
+}

package/dist/database/index.d.ts

@@ -0,0 +1,17 @@
+import './pg.js';
+export { deleteInBatches } from './batches.js';
+export type { KitDeleteInBatchesOptions, KitDeleteInBatchesResult } from './batches.js';
+export { AfterCommitInReadOnlyError, AfterCommitOutsideTransactionError, Db, TenantRequiredError, } from './db.js';
+export type { AfterCommitTask, DbReader, DbTx } from './db.js';
+export { ifNewer, occurredAtColumn } from './if-newer.js';
+export { DRIZZLE, DRIZZLE_READ, KitDatabaseModule } from './kit-database.module.js';
+export type { KitDatabaseModuleOptions } from './kit-database.module.js';
+export { runMigrations } from './migrations.js';
+export type { KitRunMigrationsOptions } from './migrations.js';
+export { prepareDatabase } from './prepare-database.js';
+export type { KitPrepareDatabaseOptions, KitPrepareDatabaseResult } from './prepare-database.js';
+export { runExclusive } from './run-exclusive.js';
+export { tenantColumn, tenantPolicy } from './tenant.js';
+export type { DbContext } from './tenant.js';
+export { newId, ulid } from '../internal/ids.js';
+export { isConnectionError, isPoolTimeout, isUniqueViolation } from '../internal/pg-errors.js';

package/dist/database/index.js

@@ -0,0 +1,13 @@
+// Точка входа @verdeect/kit/database (prd.md §3.3, E4): явный список экспортов. Первый импорт — ./pg.js: без pg ошибка
+// AC-1.2 при импорте подпути, раньше остальных модулей (requirePeer синхронно, без top-level await — П15).
+import './pg.js';
+export { deleteInBatches } from './batches.js';
+export { AfterCommitInReadOnlyError, AfterCommitOutsideTransactionError, Db, TenantRequiredError, } from './db.js';
+export { ifNewer, occurredAtColumn } from './if-newer.js';
+export { DRIZZLE, DRIZZLE_READ, KitDatabaseModule } from './kit-database.module.js';
+export { runMigrations } from './migrations.js';
+export { prepareDatabase } from './prepare-database.js';
+export { runExclusive } from './run-exclusive.js';
+export { tenantColumn, tenantPolicy } from './tenant.js';
+export { newId, ulid } from '../internal/ids.js';
+export { isConnectionError, isPoolTimeout, isUniqueViolation } from '../internal/pg-errors.js';

package/dist/database/kit-database.module.d.ts

@@ -0,0 +1,47 @@
+import { type DynamicModule, type OnApplicationShutdown, type OnModuleInit } from '@nestjs/common';
+import type { KitDatabaseEnv } from '../config/fragments.js';
+import { HealthRegistry } from '../observability/health-registry.js';
+import type { KitMetrics } from '../observability/metrics.js';
+import { type Pool } from './pg.js';
+/** Drizzle основного пула со схемой сервиса — запросы вне `Db` (`drizzle(pool, {schema})`). */
+export declare const DRIZZLE: unique symbol;
+/** Drizzle пула чтения со схемой сервиса (read-only, `statement_timeout` 5 с). */
+export declare const DRIZZLE_READ: unique symbol;
+/**
+ * Параметры старта соединений пула чтения (эталон O): одиночный запрос — read-only транзакция, срок 5 с, `app.tenant`
+ * пуст с подключения.
+ */
+export declare const READ_POOL_OPTIONS = "-c default_transaction_read_only=on -c statement_timeout=5000 -c app.tenant=";
+/** Пулы `/database`. */
+export interface KitPools {
+    /** Основной пул. */
+    readonly main: Pool;
+    /** Пул чтения. */
+    readonly read: Pool;
+}
+/** Опции `KitDatabaseModule.forRoot`. */
+export interface KitDatabaseModuleOptions {
+    /** Объект схемы Drizzle сервиса (`import * as schema`) — для `DRIZZLE` и `DRIZZLE_READ`. */
+    readonly schema: Record<string, unknown>;
+}
+/** Основной пул и пул чтения на `DATABASE_URL` с учётом срока; адрес не логируется. */
+export declare function createPools(env: KitDatabaseEnv, options?: {
+    readonly metrics?: KitMetrics;
+}): Promise<KitPools>;
+/**
+ * Глобальный модуль БД сервиса (§3.3): `Db`, `DRIZZLE`, `DRIZZLE_READ`; пробы `database` и `database-read` (критичные,
+ * при `createHttpApp`), метрика срока пула; пулы закрываются на шаге 4 (`onApplicationShutdown`). Окружение —
+ * `envDatabase` из `KitConfigModule`. Соединений на реплику — `2 × DB_POOL_MAX`.
+ */
+export declare class KitDatabaseModule implements OnModuleInit, OnApplicationShutdown {
+    private readonly pools;
+    private readonly health?;
+    private readonly logger;
+    constructor(pools: KitPools, health?: HealthRegistry | undefined);
+    /** Модуль БД со схемой Drizzle сервиса. */
+    static forRoot(options: KitDatabaseModuleOptions): DynamicModule;
+    /** Пробы `/health` обоих пулов — `select 1` (без `Db.read`: ему нужен тенант). */
+    onModuleInit(): void;
+    /** Шаг 4 остановки: закрытие пулов после HTTP и фоновых задач. */
+    onApplicationShutdown(): Promise<void>;
+}

package/dist/database/kit-database.module.js

@@ -0,0 +1,181 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var KitDatabaseModule_1;
+// KitDatabaseModule.forRoot({schema}) (prd.md §3.3, AC-4.4, AC-4.5, UC-8). Эталон — O drizzle.provider.ts +
+// database.module.ts: пулы main/read, READ_POOL_OPTIONS, обработчики error/connect, проба database, onApplicationShutdown
+// — шаг 4. По PRD и KT-19 п. 3: срок пула учитывается на уровне пула (обёртка connect экземпляра) — метрика с меткой
+// pool, captureThrottled и метка ошибки tagPoolTimeout; пробы database и database-read; KitLifecycle не используется.
+import { Inject, Logger, Module, Optional, } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { isPoolTimeout, tagPoolTimeout } from '../internal/pg-errors.js';
+import { KIT_METRICS } from '../internal/tokens.js';
+import { HealthRegistry } from '../observability/health-registry.js';
+import { sanitizeError } from '../observability/sanitize-error.js';
+import { captureThrottled } from '../observability/sentry.js';
+import { Db } from './db.js';
+import { loadDrizzle, loadPg } from './pg.js';
+/** Drizzle основного пула со схемой сервиса — запросы вне `Db` (`drizzle(pool, {schema})`). */
+export const DRIZZLE = Symbol('DRIZZLE');
+/** Drizzle пула чтения со схемой сервиса (read-only, `statement_timeout` 5 с). */
+export const DRIZZLE_READ = Symbol('DRIZZLE_READ');
+/** Пулы основной и чтения (внутренний токен). */
+const KIT_PG_POOLS = Symbol('KIT_PG_POOLS');
+/** Окружение модуля (внутренний токен). */
+const KIT_DATABASE_ENV = Symbol('KIT_DATABASE_ENV');
+/** Предел запроса пула чтения, мс. */
+const READ_STATEMENT_TIMEOUT_MS = 5000;
+/**
+ * Параметры старта соединений пула чтения (эталон O): одиночный запрос — read-only транзакция, срок 5 с, `app.tenant`
+ * пуст с подключения.
+ */
+export const READ_POOL_OPTIONS = `-c default_transaction_read_only=on -c statement_timeout=${READ_STATEMENT_TIMEOUT_MS} -c app.tenant=`;
+const logger = new Logger('KitDatabase');
+/**
+ * Учёт срока пула (AC-4.5, KT-19 п. 3): обёртка `connect` экземпляра — через неё идут и транзакции `Db`, и
+ * `pool.query` (`DRIZZLE`, `readGlobal`). Срок помечается именем пула один раз: метрика, `captureThrottled`, `warn`.
+ */
+function instrumentPoolTimeouts(pool, name, metrics) {
+    const report = (error) => {
+        if (!isPoolTimeout(error) || !tagPoolTimeout(error, name)) {
+            return;
+        }
+        metrics?.dbPoolWaitTimeouts.inc({ pool: name });
+        captureThrottled(`db-pool-timeout:${name}`, error);
+        logger.warn({ pool: name }, 'пул БД: истёк срок ожидания клиента');
+    };
+    const original = pool.connect.bind(pool);
+    const connect = (callback) => {
+        if (typeof callback === 'function') {
+            return original((error, ...rest) => {
+                if (error) {
+                    report(error);
+                }
+                callback(error, ...rest);
+            });
+        }
+        return original().catch((error) => {
+            report(error);
+            throw error;
+        });
+    };
+    // boundary: pg-pool connect перегружен (промис и обратный вызов) — обёртка сохраняет оба вида.
+    pool.connect = connect;
+}
+/** Основной пул и пул чтения на `DATABASE_URL` с учётом срока; адрес не логируется. */
+export async function createPools(env, options = {}) {
+    const pg = await loadPg();
+    const create = (name) => {
+        const pool = new pg.Pool({
+            connectionString: env.DATABASE_URL,
+            max: env.DB_POOL_MAX,
+            connectionTimeoutMillis: env.DB_POOL_ACQUIRE_TIMEOUT_MS,
+            ...(name === 'read' ? { options: READ_POOL_OPTIONS } : {}),
+        });
+        const onError = (error) => logger.warn({ pool: name, err: sanitizeError(error) }, 'пул БД: ошибка простаивающего клиента');
+        pool.on('error', onError);
+        // pg-pool снимает свой обработчик 'error' с выданного клиента: без своего обрыв уронил бы процесс.
+        pool.on('connect', (client) => void client.on('error', onError));
+        instrumentPoolTimeouts(pool, name, options.metrics);
+        logger.debug({ pool: name, max: env.DB_POOL_MAX }, 'пул БД: создан');
+        return pool;
+    };
+    return { main: create('main'), read: create('read') };
+}
+function databaseEnv(config) {
+    if (config === undefined) {
+        throw new Error('KitDatabaseModule: модуль сервиса не импортирует KitConfigModule.forRoot({schema}) с envDatabase');
+    }
+    return {
+        DATABASE_URL: config.getOrThrow('DATABASE_URL'),
+        DB_POOL_MAX: config.getOrThrow('DB_POOL_MAX'),
+        DB_POOL_ACQUIRE_TIMEOUT_MS: config.getOrThrow('DB_POOL_ACQUIRE_TIMEOUT_MS'),
+    };
+}
+/**
+ * Глобальный модуль БД сервиса (§3.3): `Db`, `DRIZZLE`, `DRIZZLE_READ`; пробы `database` и `database-read` (критичные,
+ * при `createHttpApp`), метрика срока пула; пулы закрываются на шаге 4 (`onApplicationShutdown`). Окружение —
+ * `envDatabase` из `KitConfigModule`. Соединений на реплику — `2 × DB_POOL_MAX`.
+ */
+let KitDatabaseModule = KitDatabaseModule_1 = class KitDatabaseModule {
+    pools;
+    health;
+    logger = new Logger(KitDatabaseModule_1.name);
+    constructor(pools, health) {
+        this.pools = pools;
+        this.health = health;
+    }
+    /** Модуль БД со схемой Drizzle сервиса. */
+    static forRoot(options) {
+        const withSchema = async (pool) => (await loadDrizzle()).drizzle(pool, { schema: options.schema });
+        return {
+            module: KitDatabaseModule_1,
+            global: true,
+            providers: [
+                {
+                    provide: KIT_DATABASE_ENV,
+                    useFactory: databaseEnv,
+                    inject: [{ token: ConfigService, optional: true }],
+                },
+                {
+                    provide: KIT_PG_POOLS,
+                    useFactory: (env, metrics) => createPools(env, { metrics }),
+                    inject: [KIT_DATABASE_ENV, { token: KIT_METRICS, optional: true }],
+                },
+                {
+                    provide: DRIZZLE,
+                    useFactory: (pools) => withSchema(pools.main),
+                    inject: [KIT_PG_POOLS],
+                },
+                {
+                    provide: DRIZZLE_READ,
+                    useFactory: (pools) => withSchema(pools.read),
+                    inject: [KIT_PG_POOLS],
+                },
+                {
+                    provide: Db,
+                    useFactory: async (pools) => new Db({ ...pools, drizzle: (await loadDrizzle()).drizzle }),
+                    inject: [KIT_PG_POOLS],
+                },
+            ],
+            exports: [Db, DRIZZLE, DRIZZLE_READ],
+        };
+    }
+    /** Пробы `/health` обоих пулов — `select 1` (без `Db.read`: ему нужен тенант). */
+    onModuleInit() {
+        if (this.health === undefined) {
+            return;
+        }
+        const probe = (pool) => async () => {
+            await pool.query('select 1');
+            return true;
+        };
+        this.health.register('database', probe(this.pools.main), { critical: true });
+        this.health.register('database-read', probe(this.pools.read), { critical: true });
+    }
+    /** Шаг 4 остановки: закрытие пулов после HTTP и фоновых задач. */
+    async onApplicationShutdown() {
+        const { main, read } = this.pools;
+        this.logger.log({
+            main: { total: main.totalCount, idle: main.idleCount },
+            read: { total: read.totalCount, idle: read.idleCount },
+        }, 'пулы БД: закрытие');
+        await Promise.all([main.end(), read.end()]);
+    }
+};
+KitDatabaseModule = KitDatabaseModule_1 = __decorate([
+    Module({}),
+    __param(0, Inject(KIT_PG_POOLS)),
+    __param(1, Optional()),
+    __metadata("design:paramtypes", [Object, HealthRegistry])
+], KitDatabaseModule);
+export { KitDatabaseModule };

package/dist/database/migrations.d.ts

@@ -0,0 +1,42 @@
+import type { Logger } from 'pino';
+/** Таблица журнала миграций в схеме сервиса. */
+export declare const MIGRATIONS_TABLE = "__migrations";
+/** Неверное использование (нет журнала drizzle-kit в папке); CLI переводит в код `USAGE`. */
+export declare class KitUsageError extends Error {
+    readonly name = "KitUsageError";
+}
+/** Параметры `runMigrations` (prd.md §3.3). */
+export interface KitRunMigrationsOptions {
+    /** Адрес БД под ролью владельца `<svc>_owner`. */
+    readonly url: string;
+    /** Папка миграций drizzle-kit (с `meta/_journal.json`). */
+    readonly folder: string;
+    /** Схема сервиса — и схема журнала `<schema>.__migrations`. */
+    readonly schema: string;
+}
+/** Параметры `moveJournal`. */
+export interface KitMoveJournalOptions {
+    /** Адрес БД под ролью владельца. */
+    readonly url: string;
+    /** Схема старого журнала `<from>.__drizzle_migrations` (обычно `drizzle`). */
+    readonly from: string;
+    /** Схема сервиса — журнал назначения `<to>.__migrations`. */
+    readonly to: string;
+}
+/**
+ * Применяет SQL-миграции drizzle-kit из `folder` под ролью владельца; журнал — `<schema>.__migrations`.
+ * Повтор — `{applied: 0}`.
+ * @throws {TypeError} схема вне формата имени сервиса.
+ * @throws {KitUsageError} в папке нет `meta/_journal.json`.
+ */
+export declare function runMigrations(options: KitRunMigrationsOptions, logger?: Logger): Promise<{
+    readonly applied: number;
+}>;
+/**
+ * Переносит журнал `<from>.__drizzle_migrations` в `<to>.__migrations` (строки, которых нет по `hash`), удаляет старый
+ * журнал и пустую схему `<from>` — в одной транзакции. Повтор — `{moved: 0}`.
+ * @throws {TypeError} схема вне формата или `from === to`.
+ */
+export declare function moveJournal(options: KitMoveJournalOptions, logger?: Logger): Promise<{
+    readonly moved: number;
+}>;