@damoxing/datasource-manager

中文文档: README.zh-CN.md

HTTP非依存のマルチデータソースライフサイクルマネージャー。

以下の機能を備えています：

• データソース設定の読み込み

• データソース状態の追跡

• 汎用ルートキー解決（jgbh互換性あり）

• ハートビート

• プール復旧

• 接続エラー時のワンショット再試行

• グレースフルシャットダウン

コアマネージャーはHTTPに依存しません。Express、ワーカー、CLI、その他のNode.jsサービス内で実行できます。

データベースアダプターはOracle、OceanBase（Oracle / MySQLモード）、MySQL、DM、PostgreSQL、GaussDB/openGauss、Kingbaseに対応しています。ドライバーはオプションのピア依存関係であり、対応するアダプターが使用された場合にのみ読み込まれます。

アダプター契約

アダプターインスタンスは以下を公開する必要があります：

{
    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()は互換性ラッパーとして残ります。

Codex用MCPサーバー

このパッケージにはstdio MCPサーバーが含まれており、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にリストされているデータソースIDは、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リソースも作成されません。

2026年7月15日のローカルOrbStackラボからの固定セッション統合結果：

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
        }
    ]
}

データソース設定はヘルス出力に含まれないため、パスワードや接続文字列が公開されることはありません。

ロギング

データソースエラーは、構造化されたコンテキストを2番目のロガー引数として記録します：

{
    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()は、ハートビートタイマーを停止し、シャットダウンフックを削除し、アダプターを閉じ、データソースを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();

メトリクスは現在、初期化、ハートビート、復旧、クエリ成功/失敗、接続エラー、再試行、およびトランザクション接続エラーを追跡します。

ランタイムガバナンス

データソースは実行時に変更できます：

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()は、古いプールを閉じる前に、置き換えを初期化してpingします。置き換えの初期化が失敗した場合、古いデータソースはアクティブなままです。

読み取り/書き込みグループ

グループルーティングは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)"
}

解決されたシークレットは、ヘルス出力、メトリクス出力、構造化されたデータソースエラー状態、およびマネージャーログから編集されます。

再試行ルール

接続のようなエラーは、プール復旧後に1回再試行される場合があります。

トランザクションは自動的に再生されません。トランザクションが接続エラーで失敗した場合、マネージャーはプールを再構築し、元のエラーを再スローします。

npmパッケージング

このパッケージはsrc/の下でTypeScriptで作成され、両方のモジュール形式をビルドします：

• 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がすぐに読み込まれることはありません。

組み込みのデータベースドライバーは、オプションのピア依存関係として宣言されています：

• oracledb（Oracle用）

• mysql2（MySQLおよび両方のOceanBase Oracle/MySQLテナントモード用）

• dmdb（DM用）

• pg（PostgreSQL、GaussDB/openGauss、およびKingbase用）

パッケージルートをインポートしても、これらのドライバーはすぐに読み込まれません。アダプタークラスにアクセスしたり、createDefaultAdapterFactories()を通じてアダプターを作成したりすると、そのデータソースタイプに必要なドライバーのみが読み込まれます。

セマンティックバージョニング、レジストリ、トークン、証明、および最終公開チェックリストのガイダンスについては、RELEASE.mdを参照してください。

エンタープライズデータソースフレームワークのバックログと優先順位については、ROADMAP.mdを参照してください。