diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43273ef661..72300ff0bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,6 +59,16 @@ pnpm publish:dry-run For Docker or deployment changes, run the relevant Docker Compose or Docker build checks from `deploy/`. +## Database Driver Metadata + +When adding or changing a database type, update `crates/dbx-core/assets/database-drivers.manifest.json` first. The manifest is the shared source for driver mode, MCP/CLI routing, agent keys, and core capability expectations. Then run: + +```bash +cargo test -p dbx-core --test database_capabilities +pnpm --filter @dbx-app/node-core exec tsx --test tests/driver-manifest.test.ts +pnpm --filter @dbx-app/mcp-server exec tsx --test tests/driver-manifest.test.ts +``` + ## Pull Requests - Keep changes focused and reviewable. diff --git a/crates/dbx-core/assets/database-drivers.manifest.json b/crates/dbx-core/assets/database-drivers.manifest.json new file mode 100644 index 0000000000..1a6b548a36 --- /dev/null +++ b/crates/dbx-core/assets/database-drivers.manifest.json @@ -0,0 +1,464 @@ +{ + "schemaVersion": 1, + "drivers": [ + { + "dbType": "mysql", + "label": "MySQL", + "runtimeMode": "native", + "mcpMode": "direct", + "singleConnectionPool": false, + "metadataConnectionScoped": true, + "skipTcpProbe": false, + "defaultPort": 3306 + }, + { + "dbType": "postgres", + "label": "PostgreSQL", + "runtimeMode": "native", + "mcpMode": "direct", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": false, + "defaultPort": 5432 + }, + { + "dbType": "sqlite", + "label": "SQLite", + "runtimeMode": "file", + "mcpMode": "direct", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true + }, + { + "dbType": "redis", + "label": "Redis", + "runtimeMode": "native", + "mcpMode": "bridge", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": false, + "defaultPort": 6379 + }, + { + "dbType": "duckdb", + "label": "DuckDB", + "runtimeMode": "file", + "mcpMode": "bridge", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true + }, + { + "dbType": "clickhouse", + "label": "ClickHouse", + "runtimeMode": "native", + "mcpMode": "bridge", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": false, + "defaultPort": 8123 + }, + { + "dbType": "sqlserver", + "label": "SQL Server", + "runtimeMode": "native", + "mcpMode": "bridge", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": false, + "defaultPort": 1433 + }, + { + "dbType": "mongodb", + "label": "MongoDB (Legacy)", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "mongodb", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 27017 + }, + { + "dbType": "oracle", + "label": "Oracle", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "oracle", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 1521, + "driverProfiles": [ + { "profile": "oracle-10g", "label": "Oracle 10g", "agentKey": "oracle-10g" } + ] + }, + { + "dbType": "elasticsearch", + "label": "Elasticsearch", + "runtimeMode": "native", + "mcpMode": "bridge", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": false, + "defaultPort": 9200 + }, + { + "dbType": "doris", + "label": "Doris", + "runtimeMode": "native", + "mcpMode": "direct", + "singleConnectionPool": false, + "metadataConnectionScoped": true, + "skipTcpProbe": false, + "defaultPort": 9030 + }, + { + "dbType": "starrocks", + "label": "StarRocks", + "runtimeMode": "native", + "mcpMode": "direct", + "singleConnectionPool": false, + "metadataConnectionScoped": true, + "skipTcpProbe": false, + "defaultPort": 9030 + }, + { + "dbType": "redshift", + "label": "Redshift", + "runtimeMode": "native", + "mcpMode": "direct", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": false, + "defaultPort": 5439 + }, + { + "dbType": "dameng", + "label": "达梦 DM8", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "dameng", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 5236 + }, + { + "dbType": "kingbase", + "label": "人大金仓 KingbaseES", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "kingbase", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 54321 + }, + { + "dbType": "highgo", + "label": "瀚高 HighGo", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "highgo", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 5866 + }, + { + "dbType": "vastbase", + "label": "Vastbase", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "vastbase", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 5432 + }, + { + "dbType": "goldendb", + "label": "GoldenDB", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "goldendb", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 3306 + }, + { + "dbType": "gaussdb", + "label": "GaussDB", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "gaussdb", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 8000 + }, + { + "dbType": "yashandb", + "label": "崖山 YashanDB", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "yashandb", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 1688 + }, + { + "dbType": "databricks", + "label": "Databricks SQL", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "databricks", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 443 + }, + { + "dbType": "saphana", + "label": "SAP HANA", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "saphana", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 30015 + }, + { + "dbType": "teradata", + "label": "Teradata", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "teradata", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 1025 + }, + { + "dbType": "vertica", + "label": "Vertica", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "vertica", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 5433 + }, + { + "dbType": "firebird", + "label": "Firebird", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "firebird", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 3050 + }, + { + "dbType": "exasol", + "label": "Exasol", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "exasol", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 8563 + }, + { + "dbType": "opengauss", + "label": "openGauss", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "opengauss", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 5432 + }, + { + "dbType": "oceanbase-oracle", + "label": "OceanBase Oracle Mode", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "oceanbase-oracle", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 2881 + }, + { + "dbType": "gbase", + "label": "GBase", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "gbase", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 5258 + }, + { + "dbType": "access", + "label": "Microsoft Access", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "access", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true + }, + { + "dbType": "h2", + "label": "H2", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "h2", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 9092 + }, + { + "dbType": "snowflake", + "label": "Snowflake", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "snowflake", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 443 + }, + { + "dbType": "trino", + "label": "Trino (Presto)", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "trino", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 8080 + }, + { + "dbType": "hive", + "label": "Apache Hive", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "hive", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 10000 + }, + { + "dbType": "db2", + "label": "IBM DB2", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "db2", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 50000 + }, + { + "dbType": "informix", + "label": "IBM Informix", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "informix", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 9088 + }, + { + "dbType": "neo4j", + "label": "Neo4j", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "neo4j", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 7687 + }, + { + "dbType": "cassandra", + "label": "Apache Cassandra", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "cassandra", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 9042 + }, + { + "dbType": "bigquery", + "label": "Google BigQuery", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "bigquery", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true + }, + { + "dbType": "kylin", + "label": "Apache Kylin", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "kylin", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 7070 + }, + { + "dbType": "sundb", + "label": "SunDB", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "sundb", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 22581 + }, + { + "dbType": "tdengine", + "label": "TDengine", + "runtimeMode": "agent", + "mcpMode": "bridge", + "agentKey": "tdengine", + "singleConnectionPool": false, + "metadataConnectionScoped": false, + "skipTcpProbe": true, + "defaultPort": 6041 + }, + { + "dbType": "jdbc", + "label": "JDBC", + "runtimeMode": "external", + "mcpMode": "bridge", + "singleConnectionPool": true, + "metadataConnectionScoped": false, + "skipTcpProbe": true + } + ] +} diff --git a/crates/dbx-core/tests/database_capabilities.rs b/crates/dbx-core/tests/database_capabilities.rs index 660d72b611..e5ac4a7c14 100644 --- a/crates/dbx-core/tests/database_capabilities.rs +++ b/crates/dbx-core/tests/database_capabilities.rs @@ -1,7 +1,49 @@ +use dbx_core::agent_service::AGENT_TYPES; use dbx_core::database_capabilities::{ agent_key, is_agent_type, is_metadata_connection_scoped, is_single_connection_pool, skips_tcp_probe, }; use dbx_core::models::connection::DatabaseType; +use serde::Deserialize; + +#[derive(Debug, Deserialize)] +#[serde(rename_all = "camelCase")] +struct DriverManifest { + drivers: Vec, +} + +#[derive(Debug, Deserialize)] +#[serde(rename_all = "camelCase")] +struct DriverManifestEntry { + db_type: DatabaseType, + label: String, + runtime_mode: String, + #[serde(default)] + agent_key: Option, + #[serde(default)] + single_connection_pool: bool, + #[serde(default)] + metadata_connection_scoped: bool, + #[serde(default)] + skip_tcp_probe: bool, + #[serde(default)] + driver_profiles: Vec, +} + +#[derive(Debug, Deserialize)] +#[serde(rename_all = "camelCase")] +struct DriverProfileEntry { + profile: String, + label: String, + agent_key: String, +} + +fn driver_manifest() -> DriverManifest { + let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("assets").join("database-drivers.manifest.json"); + let json = std::fs::read_to_string(&path).unwrap_or_else(|err| { + panic!("failed to read driver manifest {}: {err}", path.display()); + }); + serde_json::from_str(&json).expect("driver manifest should be valid JSON") +} #[test] fn maps_agent_database_types_to_driver_keys() { @@ -86,3 +128,69 @@ fn skips_tcp_probe_for_local_file_plugin_and_agent_types() { assert!(!skips_tcp_probe(&DatabaseType::Postgres)); assert!(!skips_tcp_probe(&DatabaseType::Mysql)); } + +#[test] +fn driver_manifest_matches_core_database_capabilities() { + let manifest = driver_manifest(); + + for driver in &manifest.drivers { + assert_eq!( + is_agent_type(&driver.db_type), + driver.runtime_mode == "agent", + "agent classification mismatch for {:?}", + driver.db_type + ); + assert_eq!( + agent_key(&driver.db_type, None), + driver.agent_key.as_deref(), + "agent key mismatch for {:?}", + driver.db_type + ); + assert_eq!( + is_single_connection_pool(&driver.db_type), + driver.single_connection_pool, + "single-pool mismatch for {:?}", + driver.db_type + ); + assert_eq!( + is_metadata_connection_scoped(&driver.db_type), + driver.metadata_connection_scoped, + "metadata scope mismatch for {:?}", + driver.db_type + ); + assert_eq!( + skips_tcp_probe(&driver.db_type), + driver.skip_tcp_probe, + "TCP probe behavior mismatch for {:?}", + driver.db_type + ); + + for profile in &driver.driver_profiles { + assert_eq!( + agent_key(&driver.db_type, Some(&profile.profile)), + Some(profile.agent_key.as_str()), + "profile agent key mismatch for {:?}/{}", + driver.db_type, + profile.profile + ); + } + } +} + +#[test] +fn driver_manifest_matches_agent_driver_store_entries() { + let manifest = driver_manifest(); + let mut expected: std::collections::BTreeMap<&str, &str> = std::collections::BTreeMap::new(); + for driver in manifest.drivers.iter().filter(|driver| driver.runtime_mode == "agent") { + expected.insert( + driver.agent_key.as_deref().expect("agent drivers should have an agent key"), + driver.label.as_str(), + ); + for profile in &driver.driver_profiles { + expected.insert(profile.agent_key.as_str(), profile.label.as_str()); + } + } + let actual: std::collections::BTreeMap<&str, &str> = AGENT_TYPES.iter().copied().collect(); + + assert_eq!(actual, expected); +} diff --git a/packages/mcp-server/src/index.ts b/packages/mcp-server/src/index.ts index b8415ba40e..0f3d55f9d7 100644 --- a/packages/mcp-server/src/index.ts +++ b/packages/mcp-server/src/index.ts @@ -27,6 +27,9 @@ function mdTable(headers: string[], rows: string[][]): string { return `${header}\n${sep}\n${body}`; } +export const DBX_CONNECTION_TYPE_DESCRIPTION = + "Database type: postgres, mysql, sqlite, redis, duckdb, clickhouse, sqlserver, mongodb, oracle, elasticsearch, doris, starrocks, redshift, dameng, kingbase, highgo, vastbase, goldendb, gaussdb, yashandb, databricks, saphana, teradata, vertica, firebird, exasol, opengauss, oceanbase-oracle, gbase, h2, snowflake, trino, hive, db2, informix, neo4j, cassandra, bigquery, kylin, sundb, tdengine, jdbc, access"; + export function createDbxMcpServer(backend: Backend, options: { isWebMode?: boolean } = {}): McpServer { const isWebMode = options.isWebMode ?? !!process.env.DBX_WEB_URL; const server = new McpServer({ @@ -131,9 +134,7 @@ export function createDbxMcpServer(backend: Backend, options: { isWebMode?: bool name: z.string().describe("Connection name"), db_type: z .string() - .describe( - "Database type: postgres, mysql, sqlite, redis, duckdb, clickhouse, sqlserver, mongodb, oracle, elasticsearch, doris, starrocks, redshift, dameng, kingbase, highgo, vastbase, goldendb, gaussdb, h2, snowflake, trino, hive, db2, informix, neo4j, cassandra, bigquery, kylin, sundb, tdengine, jdbc, access", - ), + .describe(DBX_CONNECTION_TYPE_DESCRIPTION), host: z.string().describe("Database host"), port: z.number().optional().describe("Database port (TDengine defaults to 6041)"), username: z.string().default("").describe("Username"), diff --git a/packages/mcp-server/tests/driver-manifest.test.ts b/packages/mcp-server/tests/driver-manifest.test.ts new file mode 100644 index 0000000000..36401f6634 --- /dev/null +++ b/packages/mcp-server/tests/driver-manifest.test.ts @@ -0,0 +1,22 @@ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { fileURLToPath } from "node:url"; +import test from "node:test"; +import { DBX_CONNECTION_TYPE_DESCRIPTION } from "../src/index.js"; + +interface DriverManifest { + drivers: Array<{ dbType: string }>; +} + +function loadManifest(): DriverManifest { + const path = fileURLToPath(new URL("../../../crates/dbx-core/assets/database-drivers.manifest.json", import.meta.url)); + return JSON.parse(readFileSync(path, "utf8")) as DriverManifest; +} + +test("add connection database type description includes every manifest database type", () => { + const manifest = loadManifest(); + + for (const driver of manifest.drivers) { + assert.match(DBX_CONNECTION_TYPE_DESCRIPTION, new RegExp(`\\b${driver.dbType}\\b`)); + } +}); diff --git a/packages/node-core/src/diagnostics.ts b/packages/node-core/src/diagnostics.ts index 69f5499ad9..927341c4c9 100644 --- a/packages/node-core/src/diagnostics.ts +++ b/packages/node-core/src/diagnostics.ts @@ -18,6 +18,16 @@ export const BRIDGE_REQUIRED_TYPES = [ "vastbase", "goldendb", "gaussdb", + "yashandb", + "databricks", + "saphana", + "teradata", + "vertica", + "firebird", + "exasol", + "opengauss", + "oceanbase-oracle", + "gbase", "tdengine", "h2", "snowflake", diff --git a/packages/node-core/tests/driver-manifest.test.ts b/packages/node-core/tests/driver-manifest.test.ts new file mode 100644 index 0000000000..96fd25af5d --- /dev/null +++ b/packages/node-core/tests/driver-manifest.test.ts @@ -0,0 +1,26 @@ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { fileURLToPath } from "node:url"; +import test from "node:test"; +import { BRIDGE_REQUIRED_TYPES, DIRECT_QUERY_TYPES } from "../src/diagnostics.js"; + +interface DriverManifest { + drivers: Array<{ + dbType: string; + mcpMode: "direct" | "bridge" | "unsupported"; + }>; +} + +function loadManifest(): DriverManifest { + const path = fileURLToPath(new URL("../../../crates/dbx-core/assets/database-drivers.manifest.json", import.meta.url)); + return JSON.parse(readFileSync(path, "utf8")) as DriverManifest; +} + +test("diagnostic query mode lists match the driver manifest", () => { + const manifest = loadManifest(); + const directTypes = manifest.drivers.filter((driver) => driver.mcpMode === "direct").map((driver) => driver.dbType); + const bridgeTypes = manifest.drivers.filter((driver) => driver.mcpMode === "bridge").map((driver) => driver.dbType); + + assert.deepEqual([...DIRECT_QUERY_TYPES].sort(), directTypes.sort()); + assert.deepEqual([...BRIDGE_REQUIRED_TYPES].sort(), bridgeTypes.sort()); +});