@damoxing/datasource-manager

Китайская документация: README.zh-CN.md

HTTP-независимый менеджер жизненного цикла нескольких источников данных.

Он отвечает за:

• загрузку конфигурации источников данных

• отслеживание состояния источников данных

• универсальное разрешение ключей маршрутов с совместимостью jgbh

• поддержание активности (heartbeat)

• восстановление пула соединений

• однократный повтор при ошибках соединения

• корректное завершение работы

Основной менеджер не привязан к HTTP. Он может работать внутри Express, воркера, CLI или другого Node.js-сервиса.

Адаптеры баз данных включены для Oracle, OceanBase (режимы Oracle / MySQL), MySQL, DM, PostgreSQL, GaussDB/openGauss и Kingbase. Драйверы являются опциональными peer-зависимостями и загружаются только при использовании соответствующего адаптера.

Контракт адаптера

Экземпляр адаптера должен предоставлять:

{
    isOracle: Boolean,
    adapterType: String,
    initialize: async () => {},
    close: async () => {},
    all: async (sql, params) => [],
    get: async (sql, params) => row,
    run: async (sql, params) => result,
    exec: async (sql) => {},
    transaction: async (work) => result
}

withConnection(callback) является опциональным.

Related MCP server: telemetry-mcp

Использование

CommonJS:

const {
    DataSourceManager,
    createDefaultAdapterFactories
} = require('@damoxing/datasource-manager');

const manager = new DataSourceManager({
    config,
    logger,
    shutdownSignals: ['SIGTERM'],
    adapterFactories: createDefaultAdapterFactories(logger),
});

await manager.initialize();

const db = manager.getByJgbh('1001');
const row = await db.get('SELECT 1 AS health_check');

await manager.closeAll();

ESM:

import {
    DataSourceManager,
    createDefaultAdapterFactories
} from '@damoxing/datasource-manager';

const manager = new DataSourceManager({
    config,
    logger,
    adapterFactories: createDefaultAdapterFactories(logger),
});

Используйте getByRouteKey() для нового кода, не привязанного к конкретной бизнес-логике:

const db = manager.getByRouteKey('tenant-a');

getByJgbh() остается в качестве обертки для обратной совместимости.

MCP-сервер для Codex

Этот пакет включает MCP-сервер stdio, чтобы Codex мог просматривать настроенные источники данных через тот же менеджер и уровень адаптеров:

npm run build
DAMOXING_MCP_CONFIG=/absolute/path/to/datasources.json node dist/cjs/mcp/server.js

После установки пакета точка входа в bin:

damoxing-datasource-mcp

MCP-сервер предоставляет инструменты для проверки состояния, запросов только для чтения, метаданных таблиц/процедур, планов выполнения, а также фиксированные физические сессии, доступные только через MCP:

• damoxing_open_session

• damoxing_session_query

• damoxing_session_exec

• damoxing_session_commit

• damoxing_session_rollback

• damoxing_cancel_session_operation

• damoxing_get_notices

• damoxing_get_audit_events

• damoxing_close_session

Все операции с одним и тем же sessionId используют одно и то же арендованное соединение с базой данных и выполняются последовательно. Сессии, совместимые с PostgreSQL, работают внутри явной транзакции; закрытие и очистка при аномальном разрыве соединения выполняют откат перед освобождением аренды. Потерянное фиксированное соединение никогда не восстанавливается на другом соединении.

Фиксированные сессии по умолчанию доступны только для чтения. Открытие сессии с возможностью записи требует DAMOXING_MCP_ALLOW_WRITE=true и confirmWrite=true. Идентификаторы источников данных, перечисленные в DAMOXING_MCP_PRODUCTION_DATASOURCES, блокируются, если не установлен DAMOXING_MCP_ALLOW_PRODUCTION_DEBUG=true и вызов не передает confirmProduction=true. Деструктивный SQL дополнительно требует DAMOXING_MCP_ALLOW_DESTRUCTIVE=true и confirmDestructive=true.

Политика сессий может быть ограничена с помощью:

• DAMOXING_MCP_MAX_SESSIONS (по умолчанию 5)

• DAMOXING_MCP_MAX_SESSIONS_PER_DATASOURCE (по умолчанию 2)

• DAMOXING_MCP_SESSION_IDLE_TIMEOUT_MS (по умолчанию 300000)

• DAMOXING_MCP_SESSION_MAX_LIFETIME_MS (по умолчанию 1800000)

• DAMOXING_MCP_SESSION_CLEANUP_INTERVAL_MS (по умолчанию 30000)

• DAMOXING_MCP_AUDIT_MAX_EVENTS (по умолчанию 1000)

Реестр MCP-сессий ведет ограниченный журнал аудита в памяти. События аудита содержат действие, результат, идентификаторы источника данных/сессии, затраченное время, количество строк, тип SQL, нормализованный отпечаток SQL, а также количество/имена параметров. Текст SQL и значения параметров никогда не сохраняются. Используйте damoxing_get_audit_events для получения сокращенных событий.

Менеджер фиксированных сессий, реестр, таймер и зарезервированные соединения создаются лениво точкой входа MCP. Импорт @damoxing/datasource-manager напрямую не загружает MCP SDK и не создает MCP-ресурсы.

Результаты интеграции фиксированных сессий из локальной лаборатории OrbStack от 15 июля 2026 года:

Запустите npm run test:integration:session:pg, npm run test:integration:session:opengauss, npm run test:integration:session:oracle и npm run test:integration:session:dm, чтобы повторить проверенную матрицу.

Этот этап является основой для фиксированных сессий, а не полной отладкой хранимых процедур. Структурированные значения OUT/INOUT, дескрипторы курсоров/выборка, профилирование процедур и нативные точки останова остаются в планах разработки.

Навык репозитория находится по адресу skills/damoxing-database-mcp.

Вывод состояния

getHealth() возвращает стабильную, очищенную схему:

{
    generatedAt,
    initialized,
    strictRouting,
    defaultDatasourceId,
    routeCount,
    heartbeat: {
        enabled,
        running,
        intervalMs
    },
    shutdownHooks: {
        installed,
        signals
    },
    summary: {
        total,
        ready,
        failed,
        unhealthy,
        byStatus: {
            configured,
            initializing,
            ready,
            unhealthy,
            failed,
            recovering,
            closed
        }
    },
    datasources: [
        {
            id,
            type,
            status,
            jgbhCount,
            routeKeyCount,
            isDefault,
            lastHeartbeatAt,
            lastReadyAt,
            lastRecoverAt,
            lastStatusChangeAt,
            lastError
        }
    ]
}

Конфигурация источника данных никогда не включается в вывод состояния, поэтому пароли и строки подключения не раскрываются.

Логирование

Ошибки источников данных логируются со структурированным контекстом в качестве второго аргумента логгера:

{
    datasourceId,
    type,
    jgbh,
    jgbhList,
    routeKeys,
    status,
    lastError,
    error
}

Логирование текста SQL включено по умолчанию. Логирование параметров SQL отключено по умолчанию, чтобы избежать утечки производственных секретов.

Используйте опции адаптера для управления логированием параметров:

const adapterFactories = createDefaultAdapterFactories({
    logger,
    logSql: true,
    logParams: 'redacted',
    redactKeys: ['password', 'token', 'secret'],
    redactValue: '[REDACTED]'
});

logParams принимает:

• false или 'off': не логировать параметры SQL

• true или 'redacted': логировать параметры с удалением конфиденциальных ключей

• 'raw': логировать необработанные параметры только для локальной отладки

Корректное завершение работы

Используйте shutdownSignals для закрытия всех пулов при получении сигнала процессом:

const manager = new DataSourceManager({
    shutdownSignals: ['SIGTERM', 'SIGINT'],
    exitOnShutdownSignal: true,
    adapterFactories,
    config
});

closeAll() останавливает таймеры heartbeat, удаляет хуки завершения, закрывает адаптеры и помечает источники данных как closed.

Формат конфигурации

{
    "strict_routing": true,
    "default_datasource": "oracle_main",
    "datasources": [
        {
            "id": "oracle_main",
            "type": "oracle",
            "jgbh_list": ["1001"],
            "route_keys": ["tenant-a"],
            "config": {}
        }
    ]
}

Управление пулом

Используйте нормализованные опции пула на уровне источника данных или в config.pool:

{
    "id": "pg_main",
    "type": "pg",
    "pool": {
        "minPoolSize": 1,
        "maxPoolSize": 10,
        "acquireTimeoutMs": 3000,
        "connectTimeoutMs": 3000,
        "idleTimeoutMs": 60000,
        "maxLifetimeMs": 1800000,
        "keepaliveMs": 30000
    },
    "config": {}
}

Менеджер сопоставляет поддерживаемые опции с каждым драйвером и логирует неподдерживаемые опции с контекстом источника данных. Недопустимые значения, такие как minPoolSize > maxPoolSize, приводят к ошибке при построении конфигурации.

applyPoolGovernance(type, config, pool) экспортируется для тестов и диагностики.

Метрики

getMetrics() возвращает счетчики, датчики и сводки задержек без текста SQL, параметров, паролей или строк подключения:

const metrics = manager.getMetrics();

Метрики в настоящее время отслеживают инициализацию, heartbeat, восстановление, успех/неудачу запросов, ошибки соединения, повторы и ошибки соединения транзакций.

Управление во время выполнения

Источники данных могут быть изменены во время выполнения:

await manager.addDatasource({ id: 'tenant_a', type: 'pg', route_keys: ['TENANT_A'], config: {} });
await manager.updateDatasource('tenant_a', { id: 'tenant_a', type: 'pg', route_keys: ['TENANT_A'], config: {} });
await manager.removeDatasource('tenant_a');
await manager.reloadConfig(nextConfig);

updateDatasource() инициализирует и проверяет замену перед закрытием старого пула. Если инициализация замены не удалась, старый источник данных остается активным.

Группы чтения/записи

Маршрутизация групп не зависит от HTTP:

{
    "groups": {
        "tenant_a": {
            "write": "tenant_a_master",
            "read": [
                "tenant_a_read_1",
                { "id": "tenant_a_read_2", "weight": 2 }
            ],
            "strategy": "round-robin",
            "fallbackToWrite": true
        }
    }
}

const readDb = manager.getReadHandle('tenant_a');
const writeDb = manager.getWriteHandle('tenant_a');

Стратегии чтения: round-robin, random, weighted и first-ready. Нездоровые реплики чтения пропускаются.

Секреты конфигурации

Значения конфигурации поддерживают интерполяцию окружения, ссылки на окружение, хуки разрешения секретов и зашифрованные значения:

const manager = new DataSourceManager({
    env: process.env,
    secretResolver: async key => loadSecret(key),
    decryptor: async value => decrypt(value),
    config
});

{
    "password": "env:DB_PASSWORD",
    "token": "secret:database/token",
    "connectString": "postgres://app:${DB_PASSWORD}@localhost/db",
    "encrypted": "ENC(ciphertext)"
}

Разрешенные секреты удаляются из вывода состояния, вывода метрик, структурированного состояния ошибок источников данных и журналов менеджера.

Правило повтора

Ошибки, связанные с соединением, могут быть повторены один раз после восстановления пула.

Транзакции не воспроизводятся автоматически. Если транзакция завершается ошибкой соединения, менеджер перестраивает пул и повторно выбрасывает исходную ошибку.

npm-пакет

Этот пакет написан на TypeScript в каталоге src/ и собирается в оба модульных формата:

• CommonJS: dist/cjs/index.js

• ESM: dist/esm/index.mjs

• Типы: dist/types/index.d.ts

Соберите локально перед публикацией:

npm install
npm run release:check

Вывод ESM компилируется из TypeScript с помощью esbuild. Корневые и адаптерные агрегированные импорты сохраняют ленивую загрузку драйверов баз данных, поэтому импорт пакета не загружает немедленно oracledb, dmdb или pg.

Встроенные драйверы баз данных объявлены как опциональные peer-зависимости:

• oracledb для Oracle

• mysql2 для MySQL и обоих режимов арендаторов OceanBase Oracle/MySQL

• dmdb для DM

• pg для PostgreSQL, GaussDB/openGauss и Kingbase

Импорт корня пакета не загружает эти драйверы немедленно. Доступ к классам адаптеров или создание адаптера через createDefaultAdapterFactories() загружает только тот драйвер, который требуется для данного типа источника данных.

См. RELEASE.md для получения информации о семантическом версионировании, реестре, токене, подтверждении происхождения и окончательном контрольном списке публикации.

См. ROADMAP.md для получения информации о бэклоге и приоритетах корпоративного фреймворка источников данных.