25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。
TypeScript aicliclickhousedatabasedatabase-clientdatabase-managementdockerguimcpmongodbmysqlpostgresqlredisrustsql-serversqlitetaurivue
use std::time::Duration;
use serde_json::Value;
use crate::connection::{AppState, PoolKind};
use crate::models::connection::{ConnectionConfig, DatabaseType};
use crate::query_execution_sql::{is_safe_dameng_autotrace_sql, is_safe_explain_sql_for_database};
/// Acquires an estimated plan for an agent-backed connection.
///
/// `timeout_secs` overrides the connection's own query timeout for this call
/// (`None` keeps the connection default). Overrides are host-owned: the plugin
/// Host plan API clamps the value before it gets here.
pub async fn get_agent_explain_info_core(
state: &AppState,
connection_id: &str,
database: Option<&str>,
schema: Option<&str>,
sql: &str,
mode: Option<&str>,
timeout_secs: Option<u64>,
) -> Result<String, String> {
get_agent_explain_info_core_with_execution_id(state, connection_id, database, schema, sql, mode, timeout_secs, None)
.await
}
/// DB2 estimated plans run in an isolated session, with optional UI cancellation.
/// Other dialects retain their existing native acquisition contract.
#[allow(clippy::too_many_arguments)]
pub async fn get_agent_explain_info_core_with_execution_id(
state: &AppState,
connection_id: &str,
database: Option<&str>,
schema: Option<&str>,
sql: &str,
mode: Option<&str>,
timeout_secs: Option<u64>,
execution_id: Option<&str>,
) -> Result<String, String> {
let mode = mode.unwrap_or("explain");
let (database_type, timeout_secs) = {
let configs = state.configs.read().await;
let config = configs.get(connection_id).ok_or_else(|| "Connection config not found".to_string())?.clone();
let database_type = explain_database_type(&config);
let timeout_secs = timeout_secs.unwrap_or_else(|| config.effective_query_timeout_secs());
(database_type, timeout_secs)
};
if !is_safe_agent_explain_sql(sql, mode, database_type) {
return Err("unsafe".to_string());
}
if database_type == DatabaseType::Db2 && !mode.eq_ignore_ascii_case("explain") {
return Err("DB2 supports estimated execution plans only".to_string());
}
let database_for_pool = database.filter(|value| !value.trim().is_empty());
let client_session_id =
(database_type == DatabaseType::Db2).then(|| format!("db2-plan-{}:explain", uuid::Uuid::new_v4()));
// Install before pool creation: cancellation must also reclaim a late install.
let _cleanup_guard = match client_session_id.as_deref() {
Some(session_id) => Some(
state
.workload_session_pool_cleanup_guard(connection_id, database_for_pool, session_id)
.await
.ok_or_else(|| "DB2 execution plans require an isolated session".to_string())?,
),
None => None,
};
let execution_id = if database_type == DatabaseType::Db2 {
execution_id.filter(|id| !id.trim().is_empty()).or(client_session_id.as_deref())
} else {
None
};
let registered = execution_id.map(|id| {
state.running_queries.register_task(
id.to_string(),
crate::query_cancel::RunningTaskMetadata {
kind: crate::query_cancel::RunningTaskKind::Explain,
connection_id: Some(connection_id.to_string()),
database: database_for_pool.map(str::to_string),
client_session_id: client_session_id.clone(),
..Default::default()
},
)
});
let cancel_token = registered.as_ref().map(|registration| registration.token());
let pool_creation =
state.get_or_create_pool_for_session(connection_id, database_for_pool, client_session_id.as_deref());
let pool_key = match cancel_token.as_ref() {
Some(token) => tokio::select! {
biased;
_ = token.cancelled() => return Err("Query canceled".to_string()),
result = pool_creation => result?,
},
None => pool_creation.await?,
};
if let Some(id) = execution_id {
state.running_queries.set_pool_key(id, pool_key.clone());
}
enum ExplainTarget {
Agent(std::sync::Arc<crate::db::agent_driver::PooledAgentClient>),
External {
config: std::sync::Arc<ConnectionConfig>,
session: std::sync::Arc<crate::plugins::PluginDriverSession>,
},
}
let target = {
let pool_handle = state.pool_handle(&pool_key).await;
let pool = pool_handle.as_ref().ok_or_else(|| "Connection not found".to_string())?;
match pool {
PoolKind::Agent(client) => ExplainTarget::Agent(client.clone()),
PoolKind::ExternalDriver { config, session, .. } => {
ExplainTarget::External { config: config.clone(), session: session.clone() }
}
_ => return Err("Connection is not an agent-based connection".to_string()),
}
};
let params = serde_json::json!({
"sql": sql,
"database": database.unwrap_or_default(),
"schema": schema.unwrap_or_default(),
"timeoutSecs": timeout_secs as i64,
"mode": mode,
});
let result: Value = match target {
ExplainTarget::Agent(client) => {
let mut client = match cancel_token.as_ref() {
Some(token) => tokio::select! {
biased;
_ = token.cancelled() => return Err("Query canceled".to_string()),
guard = client.lock() => guard,
},
None => client.lock().await,
};
if database_type == DatabaseType::Db2 {
let timeout = (timeout_secs > 0).then(|| Duration::from_secs(timeout_secs));
client.get_explain_info_with_timeout_and_cancel(params, timeout, cancel_token).await?
} else {
client.get_explain_info(params).await?
}
}
ExplainTarget::External { config, session } => {
let mut params = params;
params["connection"] = serde_json::to_value(config.as_ref()).map_err(|error| error.to_string())?;
let timeout = (timeout_secs > 0).then(|| Duration::from_secs(timeout_secs));
session.invoke_with_timeout("getExplainInfo", params, timeout).await?
}
};
decode_agent_explain_result(result)
}
/// Resolves the dialect an EXPLAIN must be generated for. Doris' MySQL-based
/// connection profiles are Doris dialects, not MySQL. A custom JDBC connection
/// is only known to be Oracle when its configuration says so; every other
/// custom JDBC connection stays `Jdbc` and therefore gets no plan acquisition.
/// Shared with the plugin Host plan API so both paths agree on which dialects
/// are treatable.
pub(crate) fn explain_database_type(config: &ConnectionConfig) -> DatabaseType {
if crate::db::doris::is_config(config) {
return DatabaseType::Doris;
}
if config.db_type != DatabaseType::Jdbc {
return config.db_type;
}
let oracle_hint = [
config.connection_string.as_deref(),
config.jdbc_driver_class.as_deref(),
config.driver_profile.as_deref(),
config.driver_label.as_deref(),
config.database_info.as_ref().and_then(|info| info.product_name.as_deref()),
config.database_info.as_ref().and_then(|info| info.server_comment.as_deref()),
config.database_info.as_ref().and_then(|info| info.driver_name.as_deref()),
]
.into_iter()
.flatten()
.chain(config.jdbc_driver_paths.iter().map(String::as_str))
.any(|value| value.to_ascii_lowercase().contains("oracle"));
if oracle_hint {
DatabaseType::Oracle
} else {
DatabaseType::Jdbc
}
}
fn is_safe_agent_explain_sql(sql: &str, mode: &str, database_type: DatabaseType) -> bool {
if mode.eq_ignore_ascii_case("autotrace") {
is_safe_dameng_autotrace_sql(sql)
} else {
is_safe_explain_sql_for_database(sql, Some(database_type))
}
}
fn decode_agent_explain_result(result: Value) -> Result<String, String> {
match result {
Value::String(plan) => Ok(plan),
Value::Object(object) => Ok(object.get("plan").and_then(Value::as_str).unwrap_or_default().to_string()),
value => Err(format!("Unexpected result type from getExplainInfo: {value:?}")),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[cfg(unix)]
use crate::connection::PoolKind;
use crate::models::connection::DatabaseType;
#[cfg(unix)]
use crate::plugins::{
InstalledPlugin, PluginDriverManifest, PluginDriverSession, PluginManifest, PluginRuntimeEnv,
};
use crate::query_execution_sql::{build_explain_sql, ExplainSqlOptions};
#[cfg(unix)]
use std::sync::Arc;
#[test]
fn allows_oracle_dml_explain_without_relaxing_autotrace() {
let update = "UPDATE AA_PAY_VOUCHER_TEMP t SET t.AGENCY_ID = '1'";
assert!(is_safe_agent_explain_sql(update, "explain", DatabaseType::Oracle));
assert!(!is_safe_agent_explain_sql(update, "autotrace", DatabaseType::Oracle));
assert!(!is_safe_agent_explain_sql(update, "explain", DatabaseType::Dameng));
assert!(!is_safe_agent_explain_sql("DROP TABLE AA_PAY_VOUCHER_TEMP", "explain", DatabaseType::Oracle));
}
#[test]
fn decodes_string_and_object_agent_explain_results() {
assert_eq!(decode_agent_explain_result(Value::String("plan text".to_string())).unwrap(), "plan text");
assert_eq!(
decode_agent_explain_result(serde_json::json!({ "plan": "object plan", "has_actual_stats": false }))
.unwrap(),
"object plan"
);
assert!(decode_agent_explain_result(serde_json::json!(["unexpected"])).is_err());
}
#[test]
fn resolves_doris_profiles_to_doris_explain_sql_without_changing_mysql() {
let cases = [
(DatabaseType::Doris, None, DatabaseType::Doris, "EXPLAIN SELECT 1"),
(DatabaseType::Mysql, Some("doris"), DatabaseType::Doris, "EXPLAIN SELECT 1"),
(DatabaseType::Mysql, Some("selectdb"), DatabaseType::Doris, "EXPLAIN SELECT 1"),
(DatabaseType::Mysql, None, DatabaseType::Mysql, "EXPLAIN FORMAT=JSON SELECT 1"),
(DatabaseType::Mysql, Some("mysql"), DatabaseType::Mysql, "EXPLAIN FORMAT=JSON SELECT 1"),
];
for (raw_type, driver_profile, expected_type, expected_sql) in cases {
let config: ConnectionConfig = serde_json::from_value(serde_json::json!({
"id": "dialect-test",
"name": "Dialect test",
"db_type": raw_type.as_str(),
"driver_profile": driver_profile,
"host": "127.0.0.1",
"port": 9030,
"username": "user",
"password": "secret"
}))
.unwrap();
let resolved_type = explain_database_type(&config);
assert_eq!(resolved_type, expected_type, "{raw_type:?} + {driver_profile:?}");
let explain = build_explain_sql(ExplainSqlOptions {
database_type: Some(resolved_type),
format: None,
analyze: None,
sql: "SELECT 1".to_string(),
});
assert_eq!(explain.sql.as_deref(), Some(expected_sql), "{raw_type:?} + {driver_profile:?}");
}
}
#[test]
fn infers_only_oracle_custom_jdbc_for_oracle_explain_safety() {
let oracle: ConnectionConfig = serde_json::from_value(serde_json::json!({
"id": "oracle-jdbc",
"name": "Oracle JDBC",
"db_type": "jdbc",
"host": "127.0.0.1",
"port": 1521,
"username": "system",
"password": "oracle",
"connection_string": "jdbc:oracle:thin:@127.0.0.1:1521:XE"
}))
.unwrap();
let unknown: ConnectionConfig = serde_json::from_value(serde_json::json!({
"id": "unknown-jdbc",
"name": "Unknown JDBC",
"db_type": "jdbc",
"host": "127.0.0.1",
"port": 9000,
"username": "user",
"password": "secret",
"connection_string": "jdbc:unknown://127.0.0.1:9000/app"
}))
.unwrap();
assert_eq!(explain_database_type(&oracle), DatabaseType::Oracle);
assert_eq!(explain_database_type(&unknown), DatabaseType::Jdbc);
assert!(is_safe_agent_explain_sql("UPDATE T SET C = 1", "explain", explain_database_type(&oracle)));
assert!(!is_safe_agent_explain_sql("UPDATE T SET C = 1", "explain", explain_database_type(&unknown)));
}
#[cfg(unix)]
#[tokio::test]
async fn routes_oracle_jdbc_explain_through_the_external_driver_session() {
use std::os::unix::fs::PermissionsExt;
let dir = std::env::temp_dir().join(format!("dbx-agent-explain-{}", uuid::Uuid::new_v4()));
std::fs::create_dir_all(&dir).unwrap();
let executable = dir.join("plugin.sh");
std::fs::write(
&executable,
"#!/bin/sh\nwhile IFS= read -r line; do\n id=$(printf '%s' \"$line\" | sed -E 's/.*\"id\":([0-9]+).*/\\1/')\n printf '{\"id\":%s,\"result\":{\"plan\":\"TABLE ACCESS FULL DUAL\"}}\\n' \"$id\"\ndone\n",
)
.unwrap();
let mut permissions = std::fs::metadata(&executable).unwrap().permissions();
permissions.set_mode(0o755);
std::fs::set_permissions(&executable, permissions).unwrap();
let plugin = InstalledPlugin::new(
PluginManifest {
id: "jdbc".to_string(),
name: "JDBC".to_string(),
version: "test".to_string(),
protocol_version: 1,
executable: Some("plugin.sh".to_string()),
drivers: vec![PluginDriverManifest {
id: "jdbc".to_string(),
label: "JDBC".to_string(),
kind: "external".to_string(),
database_type: Some("jdbc".to_string()),
}],
..PluginManifest::default()
},
dir.clone(),
env!("CARGO_PKG_VERSION"),
);
let session = Arc::new(
PluginDriverSession::start_for_test(plugin, "jdbc".to_string(), PluginRuntimeEnv::default()).await.unwrap(),
);
let config: crate::models::connection::ConnectionConfig = serde_json::from_value(serde_json::json!({
"id": "oracle-jdbc",
"name": "Oracle JDBC",
"db_type": "jdbc",
"host": "127.0.0.1",
"port": 1521,
"username": "system",
"password": "oracle",
"database": "ORCL",
"connection_string": "jdbc:oracle:thin:@127.0.0.1:1521:ORCL",
"jdbc_driver_class": "oracle.jdbc.OracleDriver",
"query_timeout_secs": 30
}))
.unwrap();
let storage = crate::persistence::test_storage::open(&dir.join("storage.db")).await.unwrap();
let state = AppState::new(storage);
state.configs.write().await.insert(config.id.clone(), config.clone());
state
.update_connection_pools(|connections| {
connections.insert(
"oracle-jdbc".to_string(),
PoolKind::ExternalDriver {
driver_id: "jdbc".to_string(),
config: Arc::new(config),
session: session.clone(),
},
);
})
.await;
let plan = get_agent_explain_info_core(
&state,
"oracle-jdbc",
Some("ORCL"),
Some("SYSTEM"),
"UPDATE T SET C = 1",
Some("explain"),
None,
)
.await
.unwrap();
assert_eq!(plan, "TABLE ACCESS FULL DUAL");
session.shutdown().await.unwrap();
drop(state);
std::fs::remove_dir_all(dir).unwrap();
}
}