@damoxing/datasource-manager

Chinesische Dokumentation: README.zh-CN.md

HTTP-agnostischer Multi-Datenquellen-Lebenszyklus-Manager.

Er verwaltet:

• Laden der Datenquellenkonfiguration

• Statusverfolgung der Datenquellen

• Generische Route-Key-Auflösung mit jgbh-Kompatibilität

• Heartbeat

• Pool-Wiederherstellung

• Einmaligen Wiederholungsversuch bei Verbindungsfehlern

• Graceful Shutdown

Der Kern-Manager ist nicht an HTTP gebunden. Er kann in Express, einem Worker, einer CLI oder einem anderen Node.js-Dienst ausgeführt werden.

Datenbankadapter sind für Oracle, OceanBase (Oracle / MySQL-Modus), MySQL, DM, PostgreSQL, GaussDB/openGauss und Kingbase enthalten. Treiber sind optionale Peer-Abhängigkeiten und werden nur geladen, wenn der entsprechende Adapter verwendet wird.

Adapter-Vertrag

Eine Adapterinstanz sollte Folgendes bereitstellen:

{
    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) ist optional.

Related MCP server: telemetry-mcp

Verwendung

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),
});

Verwenden Sie getByRouteKey() für neuen, nicht geschäftsspezifischen Code:

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

getByJgbh() bleibt als Kompatibilitäts-Wrapper erhalten.

MCP-Server für Codex

Dieses Paket enthält einen stdio-MCP-Server, sodass Codex konfigurierte Datenquellen durch dieselbe Manager- und Adapterschicht inspizieren kann:

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

Nach der Paketinstallation lautet der Bin-Eintrag:

damoxing-datasource-mcp

Der MCP-Server stellt Health-, Read-Only-Abfrage-, Tabellen-/Routinen-Metadaten-, Explain-Plan-Tools und MCP-spezifische feste physische Sitzungen bereit:

• 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

Alle Operationen mit derselben sessionId verwenden dieselbe geliehene Datenbankverbindung und werden serialisiert. PostgreSQL-kompatible Sitzungen laufen innerhalb einer expliziten Transaktion; das Schließen und die Bereinigung bei abnormaler Verbindung führen einen Rollback durch, bevor die Ausleihe freigegeben wird. Eine verlorene feste Verbindung wird niemals auf einer anderen Verbindung wiederholt.

Feste Sitzungen sind standardmäßig schreibgeschützt. Das Öffnen einer Lese-/Schreibsitzung erfordert DAMOXING_MCP_ALLOW_WRITE=true und confirmWrite=true. Datenquellen-IDs, die in DAMOXING_MCP_PRODUCTION_DATASOURCES aufgeführt sind, werden abgelehnt, es sei denn, DAMOXING_MCP_ALLOW_PRODUCTION_DEBUG=true ist gesetzt und der Aufruf übergibt confirmProduction=true. Destruktives SQL erfordert zusätzlich DAMOXING_MCP_ALLOW_DESTRUCTIVE=true und confirmDestructive=true.

Die Sitzungsrichtlinie kann eingegrenzt werden mit:

• DAMOXING_MCP_MAX_SESSIONS (Standard 5)

• DAMOXING_MCP_MAX_SESSIONS_PER_DATASOURCE (Standard 2)

• DAMOXING_MCP_SESSION_IDLE_TIMEOUT_MS (Standard 300000)

• DAMOXING_MCP_SESSION_MAX_LIFETIME_MS (Standard 1800000)

• DAMOXING_MCP_SESSION_CLEANUP_INTERVAL_MS (Standard 30000)

• DAMOXING_MCP_AUDIT_MAX_EVENTS (Standard 1000)

Das MCP-Sitzungsregister führt eine begrenzte In-Memory-Prüfpfad. Prüfereignisse enthalten Aktion, Ergebnis, Datenquellen-/Sitzungskennungen, verstrichene Zeit, Zeilenanzahlen, SQL-Art, einen normalisierten SQL-Fingerabdruck sowie Parameteranzahlen/-namen. SQL-Text und Parameterwerte werden niemals gespeichert. Verwenden Sie damoxing_get_audit_events, um die geschwärzten Ereignisse abzurufen.

Der Manager für feste Sitzungen, das Register, der Timer und die reservierten Verbindungen werden vom MCP-Einstiegspunkt lazy erstellt. Das direkte Importieren von @damoxing/datasource-manager lädt das MCP-SDK nicht und erstellt keine MCP-Ressourcen.

Ergebnisse der Integration fester Sitzungen aus dem lokalen OrbStack-Labor vom 15. Juli 2026:

Führen Sie npm run test:integration:session:pg, npm run test:integration:session:opengauss, npm run test:integration:session:oracle und npm run test:integration:session:dm aus, um die verifizierte Matrix zu wiederholen.

Diese Phase ist das Fundament für feste Sitzungen, nicht die vollständige Debugging von gespeicherten Routinen. Strukturierte OUT/INOUT-Werte, Cursor-Handles/-Fetch, Routine-Profiling und native Haltepunkte bleiben Aufgaben für die Roadmap.

Die Repository-Fähigkeit befindet sich unter skills/damoxing-database-mcp.

Health-Ausgabe

getHealth() gibt ein stabiles, bereinigtes Schema zurück:

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

Die Datenquellenkonfiguration ist niemals in der Health-Ausgabe enthalten, sodass Passwörter und Verbindungszeichenfolgen nicht offengelegt werden.

Protokollierung

Datenquellenfehler werden mit strukturiertem Kontext als zweitem Logger-Argument protokolliert:

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

Die Protokollierung von SQL-Text ist standardmäßig aktiviert. Die Protokollierung von SQL-Parametern ist standardmäßig deaktiviert, um die Offenlegung von Produktionsgeheimnissen zu vermeiden.

Verwenden Sie Adapteroptionen, um die Parameterprotokollierung zu steuern:

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

logParams akzeptiert:

• false oder 'off': SQL-Parameter nicht protokollieren

• true oder 'redacted': Parameter mit geschwärzten sensiblen Schlüsseln protokollieren

• 'raw': Rohe Parameter nur für lokales Debugging protokollieren

Graceful Shutdown

Verwenden Sie shutdownSignals, um alle Pools zu schließen, wenn der Prozess ein Signal empfängt:

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

closeAll() stoppt Heartbeat-Timer, entfernt Shutdown-Hooks, schließt Adapter und markiert Datenquellen als closed.

Konfigurationsform

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

Pool-Governance

Verwenden Sie normalisierte Pool-Optionen auf Datenquellenebene oder unter config.pool:

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

Der Manager ordnet unterstützte Optionen jedem Treiber zu und protokolliert nicht unterstützte Optionen mit Datenquellenkontext. Ungültige Werte, wie z. B. minPoolSize > maxPoolSize, schlagen während der Konfigurationserstellung fehl.

applyPoolGovernance(type, config, pool) wird für Tests und Diagnosen exportiert.

Metriken

getMetrics() gibt Zähler, Messwerte und Latenzzusammenfassungen ohne SQL-Text, Parameter, Passwörter oder Verbindungszeichenfolgen zurück:

const metrics = manager.getMetrics();

Metriken verfolgen derzeit Initialisierung, Heartbeat, Wiederherstellung, Abfrageerfolg/-fehlschlag, Verbindungsfehler, Wiederholungsversuche und Transaktionsverbindungsfehler.

Laufzeit-Governance

Datenquellen können zur Laufzeit geändert werden:

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() initialisiert und pingt den Ersatz, bevor der alte Pool geschlossen wird. Wenn die Ersatzinitialisierung fehlschlägt, bleibt die alte Datenquelle aktiv.

Lese-/Schreibgruppen

Das Gruppen-Routing ist HTTP-agnostisch:

{
    "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');

Lesestrategien sind round-robin, random, weighted und first-ready. Nicht gesunde Lesereplikate werden übersprungen.

Konfigurationsgeheimnisse

Konfigurationswerte unterstützen Umgebungsinterpolation, Umgebungsreferenzen, Secret-Resolver-Hooks und verschlüsselte Werte:

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)"
}

Aufgelöste Geheimnisse werden aus der Health-Ausgabe, der Metrikausgabe, dem strukturierten Datenquellenfehlerzustand und den Managerprotokollen geschwärzt.

Wiederholungsregel

Verbindungsähnliche Fehler können nach der Pool-Wiederherstellung einmal wiederholt werden.

Transaktionen werden nicht automatisch wiederholt. Wenn eine Transaktion mit einem Verbindungsfehler fehlschlägt, baut der Manager den Pool neu auf und wirft den ursprünglichen Fehler erneut.

npm-Paketierung

Dieses Paket ist in TypeScript unter src/ verfasst und erstellt beide Modulformate:

• CommonJS: dist/cjs/index.js

• ESM: dist/esm/index.mjs

• Typen: dist/types/index.d.ts

Vor der Veröffentlichung lokal bauen:

npm install
npm run release:check

Die ESM-Ausgabe wird mit esbuild aus TypeScript kompiliert. Root- und Adapter-Aggregatimporte halten Datenbanktreiber lazy, sodass das Importieren des Pakets nicht sofort oracledb, dmdb oder pg lädt.

Integrierte Datenbanktreiber werden als optionale Peer-Abhängigkeiten deklariert:

• oracledb für Oracle

• mysql2 für MySQL und beide OceanBase Oracle/MySQL-Tenant-Modi

• dmdb für DM

• pg für PostgreSQL, GaussDB/openGauss und Kingbase

Das Importieren des Paket-Roots lädt diese Treiber nicht sofort. Der Zugriff auf Adapterklassen oder das Erstellen eines Adapters über createDefaultAdapterFactories() lädt nur den Treiber, der von diesem Datenquellentyp benötigt wird.

Siehe RELEASE.md für Semver, Registry, Token, Provenance und die abschließende Checkliste zur Veröffentlichung.

Siehe ROADMAP.md für das Enterprise-Datenquellen-Framework-Backlog und die Prioritätenreihenfolge.