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
feat(mcp): configure stateful session idle timeout
cowkinge1f46cf9a82a
diff --git a/crates/dbx-mcp/src/backend.rs b/crates/dbx-mcp/src/backend.rsindex c86ac562f2..7dbc2da51c 100644--- a/crates/dbx-mcp/src/backend.rs+++ b/crates/dbx-mcp/src/backend.rs@@ -675,7 +675,7 @@ impl LocalBackend {state,data_dir,transaction_owners: Arc::new(TransactionOwnerRegistry::default()),- transaction_owner_config: TransactionOwnerConfig::default(),+ transaction_owner_config: TransactionOwnerConfig::from_env(),}}@@ -710,7 +710,7 @@ impl LocalBackend {state,data_dir,transaction_owners: Arc::new(TransactionOwnerRegistry::default()),- transaction_owner_config: TransactionOwnerConfig::default(),+ transaction_owner_config: TransactionOwnerConfig::from_env(),})}diff --git a/crates/dbx-mcp/src/server.rs b/crates/dbx-mcp/src/server.rsindex 01dc92c809..93a5a1689e 100644--- a/crates/dbx-mcp/src/server.rs+++ b/crates/dbx-mcp/src/server.rs@@ -1415,7 +1415,7 @@ impl DbxMcpServer {#[tool(name = "dbx_open_session",- description = "Open a stateful query session pinned to a single backend connection. Returns a session ID for dbx_execute_query: USE, SET CATALOG, session variables and temporary tables persist across calls within the session. Close with dbx_close_session when done; idle sessions expire after 30 minutes."+ description = "Open a stateful query session pinned to a single backend connection. Returns a session ID for dbx_execute_query: USE, SET CATALOG, session variables and temporary tables persist across calls within the session. Close with dbx_close_session when done; idle sessions expire after 30 minutes by default (configurable with DBX_SESSION_IDLE_TTL_SECS).")]async fn open_session_tool(&self,diff --git a/crates/dbx-mcp/src/session.rs b/crates/dbx-mcp/src/session.rsindex 89d7acae5e..0f90806f3e 100644--- a/crates/dbx-mcp/src/session.rs+++ b/crates/dbx-mcp/src/session.rs@@ -9,7 +9,20 @@ use crate::transaction::TransactionOwner;/// Idle time after which an MCP session is considered expired and its pinned/// backend connection pool may be reclaimed.-const SESSION_IDLE_TTL: Duration = Duration::from_secs(30 * 60);+pub(crate) const SESSION_IDLE_TTL: Duration = Duration::from_secs(30 * 60);++pub(crate) fn session_idle_ttl_from_env() -> Duration {+ session_idle_ttl_from_value(std::env::var("DBX_SESSION_IDLE_TTL_SECS").ok().as_deref())+}++pub(crate) fn session_idle_ttl_from_value(value: Option<&str>) -> Duration {+ value+ .and_then(|value| value.trim().parse::<u64>().ok())+ .filter(|seconds| *seconds > 0)+ .map(Duration::from_secs)+ .filter(|ttl| Instant::now().checked_add(*ttl).is_some())+ .unwrap_or(SESSION_IDLE_TTL)+}/// Maximum number of concurrent MCP sessions. Bounds how many pinned backend/// connection pools an agent can hold at once.@@ -51,14 +64,20 @@ struct McpSessionState {closing: HashMap<String, McpSession>,}-#[derive(Default)]pub struct McpSessionStore {state: Mutex<McpSessionState>,+ idle_ttl: Duration,+}++impl Default for McpSessionStore {+ fn default() -> Self {+ Self { state: Mutex::new(McpSessionState::default()), idle_ttl: SESSION_IDLE_TTL }+ }}impl McpSessionStore {pub fn new() -> Arc<Self> {- Arc::new(Self::default())+ Arc::new(Self { idle_ttl: session_idle_ttl_from_env(), ..Self::default() })}/// Open a new session bound to `connection_id` + `database`.@@ -67,7 +86,7 @@ impl McpSessionStore {/// reached; expired sessions are swept before the cap is enforced.pub async fn open(&self, connection_id: &str, database: &str) -> McpSessionStoreResult<Result<McpSession, String>> {let mut state = self.state.lock().await;- let expired = sweep_expired(&mut state);+ let expired = sweep_expired(&mut state, self.idle_ttl);if session_count(&state) >= MAX_SESSIONS {return McpSessionStoreResult::new(Err(format!(@@ -87,7 +106,7 @@ impl McpSessionStore {database: &str,) -> McpSessionStoreResult<Result<McpSession, String>> {let mut state = self.state.lock().await;- let expired = sweep_expired(&mut state);+ let expired = sweep_expired(&mut state, self.idle_ttl);if session_count(&state) >= MAX_SESSIONS {return McpSessionStoreResult::new(Err(format!(@@ -124,7 +143,7 @@ impl McpSessionStore {/// Resolve a session id and refresh its idle timer.pub async fn resolve(&self, session_id: &str) -> McpSessionStoreResult<Option<McpSession>> {let mut state = self.state.lock().await;- let expired = sweep_expired(&mut state);+ let expired = sweep_expired(&mut state, self.idle_ttl);let session = state.active.get_mut(session_id).map(|session| {session.last_used = Instant::now();session.clone()@@ -136,7 +155,7 @@ impl McpSessionStore {/// cap until the backend pool is closed successfully.pub async fn begin_close(&self, session_id: &str) -> McpSessionStoreResult<Option<McpSession>> {let mut state = self.state.lock().await;- let expired = sweep_expired(&mut state);+ let expired = sweep_expired(&mut state, self.idle_ttl);let session = state.active.remove(session_id);if let Some(session) = &session {state.closing.entry(session.id.clone()).or_insert_with(|| session.clone());@@ -159,7 +178,7 @@ impl McpSessionStore {#[cfg(test)]pub(crate) async fn expire_for_test(&self, session_id: &str) {self.state.lock().await.active.get_mut(session_id).unwrap().last_used =- Instant::now() - SESSION_IDLE_TTL - Duration::from_secs(1);+ Instant::now() - self.idle_ttl - Duration::from_secs(1);}}@@ -182,12 +201,12 @@ fn session_count(state: &McpSessionState) -> usize {state.opening.len() + state.active.len() + state.closing.len()}-fn sweep_expired(state: &mut McpSessionState) -> Vec<McpSession> {+fn sweep_expired(state: &mut McpSessionState, idle_ttl: Duration) -> Vec<McpSession> {let now = Instant::now();let expired_ids = state.active.iter()- .filter(|(_, session)| now.duration_since(session.last_used) >= SESSION_IDLE_TTL)+ .filter(|(_, session)| now.duration_since(session.last_used) >= idle_ttl).map(|(id, _)| id.clone()).collect::<Vec<_>>();let mut expired = Vec::with_capacity(expired_ids.len());@@ -200,6 +219,67 @@ fn sweep_expired(state: &mut McpSessionState) -> Vec<McpSession> {expired}+#[cfg(test)]+mod ttl_tests {+ use super::*;++ #[test]+ fn positive_seconds_override_the_default() {+ for (value, seconds) in [("1", 1), ("43200", 43200), (" 3600 ", 3600)] {+ assert_eq!(session_idle_ttl_from_value(Some(value)), Duration::from_secs(seconds));+ }+ }++ fn store_with_ttl(value: &str) -> McpSessionStore {+ McpSessionStore { idle_ttl: session_idle_ttl_from_value(Some(value)), ..McpSessionStore::default() }+ }++ #[tokio::test]+ async fn longer_ttl_preserves_sessions_beyond_thirty_minutes_and_resolve_refreshes_idle_time() {+ let store = store_with_ttl("43200");+ let session = store.open("conn-1", "analytics").await.into_parts().0.unwrap();+ store.state.lock().await.active.get_mut(&session.id).unwrap().last_used =+ Instant::now() - Duration::from_secs(3600);+ let (resolved, expired) = store.resolve(&session.id).await.into_parts();+ assert!(expired.is_empty());+ assert!(resolved.unwrap().last_used.elapsed() < Duration::from_secs(1));+ store.expire_for_test(&session.id).await;+ let (resolved, expired) = store.resolve(&session.id).await.into_parts();+ assert!(resolved.is_none());+ assert_eq!(expired.len(), 1);+ assert_eq!(expired[0].id, session.id);+ assert!(store.state.lock().await.closing.contains_key(&session.id));+ store.finish_close(&session.id).await;+ assert!(!store.state.lock().await.closing.contains_key(&session.id));+ }++ #[tokio::test]+ async fn shorter_ttl_is_used_by_every_sweep_entry_point() {+ for entry_point in ["open", "reserve_opening", "resolve", "begin_close"] {+ let store = store_with_ttl("1");+ let session = store.open("conn-1", "").await.into_parts().0.unwrap();+ store.state.lock().await.active.get_mut(&session.id).unwrap().last_used =+ Instant::now() - Duration::from_secs(2);+ let expired = match entry_point {+ "open" => store.open("conn-2", "").await.into_parts().1,+ "reserve_opening" => store.reserve_opening("conn-2", "").await.into_parts().1,+ "resolve" => store.resolve(&session.id).await.into_parts().1,+ _ => store.begin_close(&session.id).await.into_parts().1,+ };+ assert_eq!(expired.len(), 1, "{entry_point}");+ assert_eq!(expired[0].id, session.id);+ }+ }++ #[test]+ fn invalid_or_unrepresentable_values_keep_thirty_minutes() {+ assert_eq!(session_idle_ttl_from_value(None), SESSION_IDLE_TTL);+ for value in ["", " ", "0", "-1", "1.5", "12h", "18446744073709551615", "18446744073709551616"] {+ assert_eq!(session_idle_ttl_from_value(Some(value)), SESSION_IDLE_TTL, "{value:?}");+ }+ }+}+#[cfg(test)]mod tests {use super::*;diff --git a/crates/dbx-mcp/src/transaction.rs b/crates/dbx-mcp/src/transaction.rsindex 07517983b9..df67ed010e 100644--- a/crates/dbx-mcp/src/transaction.rs+++ b/crates/dbx-mcp/src/transaction.rs@@ -188,13 +188,19 @@ pub struct TransactionOwnerConfig {impl Default for TransactionOwnerConfig {fn default() -> Self {Self {- idle_ttl: Duration::from_secs(30 * 60),+ idle_ttl: crate::session::SESSION_IDLE_TTL,operation_timeout: Duration::from_secs(300),cleanup_timeout: Duration::from_secs(5),}}}+impl TransactionOwnerConfig {+ pub(crate) fn from_env() -> Self {+ Self { idle_ttl: crate::session::session_idle_ttl_from_env(), ..Self::default() }+ }+}+#[derive(Debug)]pub struct TransactionResult {pub result: QueryResult,diff --git a/docs/content/docs/mcp.cn.mdx b/docs/content/docs/mcp.cn.mdxindex 17fb8745e0..73a341becd 100644--- a/docs/content/docs/mcp.cn.mdx+++ b/docs/content/docs/mcp.cn.mdx@@ -162,7 +162,7 @@ DBX MCP 当前提供以下工具(具体可用工具取决于构建功能及权- Session 变量和设置- 需要固定连接的显式事务或多步诊断-会话只支持 SQL 连接,并固定到一个连接和数据库。未知、已关闭或过期的 `sessionId` 会失败,不会静默退化为普通查询。完成后应调用 `dbx_close_session`;空闲 30 分钟的会话会被回收,同时最多允许 32 个并发会话。+会话只支持 SQL 连接,并固定到一个连接和数据库。未知、已关闭或过期的 `sessionId` 会失败,不会静默退化为普通查询。完成后应调用 `dbx_close_session`;会话默认空闲 30 分钟后回收,同时最多允许 32 个并发会话。在 MCP 宿主进程设置 `DBX_SESSION_IDLE_TTL_SECS=43200` 可将空闲时间延长为 12 小时,事务专属连接也使用此配置。值必须为正整数秒;未设置、非法值、零、负数或无法表示的时长均保留默认 1800 秒。修改后需重启宿主。使用嵌入式 DBX Web MCP 时,在 Web 服务端设置;使用独立启动器时,在启动器环境中设置。<Callout type="warn">有状态会话不会放宽 SQL 策略。`USE` 只有在会话中才有意义,但写入、DDL、生产保护、连接只读和数据库权限仍按每次请求重新检查。</Callout>@@ -286,6 +286,7 @@ DBX 在 **设置 → MCP** 中保存一份权威策略,并在每次请求时| 变量 | 用途 || --- | --- || `DBX_DATA_DIR` | 覆盖本地 DBX 数据目录 |+| `DBX_SESSION_IDLE_TTL_SECS` | 有状态会话空闲超时,单位为正整数秒,默认 `1800`。非法值、零、负数或无法表示的时长回退默认值;同样适用于事务专属连接。修改后需重启 MCP 宿主进程。 || `DBX_WEB_URL` | 使用 DBX Web/Docker 后端 || `DBX_WEB_PASSWORD` | 登录 DBX Web || `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` | DBX Web 请求的标准系统代理变量;空值表示不走代理。认证格式 `http://user:pass@host:port` |diff --git a/docs/content/docs/mcp.mdx b/docs/content/docs/mcp.mdxindex 84c8706e80..eebd12ea24 100644--- a/docs/content/docs/mcp.mdx+++ b/docs/content/docs/mcp.mdx@@ -162,7 +162,7 @@ Regular `dbx_execute_query` calls are independent. When a workflow must preserve- Session variables and settings- Explicit transactions or multi-step diagnostics that require one connection-Sessions support SQL connections only and are bound to one connection and database. Unknown, closed, or expired IDs fail instead of silently falling back to an ordinary query. Call `dbx_close_session` when finished. Idle sessions are reclaimed after 30 minutes, and the server allows at most 32 concurrent sessions.+Sessions support SQL connections only and are bound to one connection and database. Unknown, closed, or expired IDs fail instead of silently falling back to an ordinary query. Call `dbx_close_session` when finished. Idle sessions are reclaimed after 30 minutes by default, and the server allows at most 32 concurrent sessions. Set `DBX_SESSION_IDLE_TTL_SECS=43200` in the process hosting MCP to allow 12 hours of inactivity, including transaction-owned connections. The value must be positive whole seconds; unset, invalid, zero, negative or unrepresentable values keep the 1800-second default. Restart the host after changing it. For embedded DBX Web MCP, set it on the Web server; for the standalone launcher, set it in the launcher environment.<Callout type="warn">A stateful session does not widen SQL policy. `USE` is meaningful only inside a session, while writes, DDL, production protection, connection read-only state, and database privileges are rechecked for every request.</Callout>@@ -286,6 +286,7 @@ Updated servers do not let `DBX_MCP_ALLOW_WRITES` or `DBX_MCP_ALLOW_DANGEROUS_SQ| Variable | Purpose || --- | --- || `DBX_DATA_DIR` | Override the local DBX data directory |+| `DBX_SESSION_IDLE_TTL_SECS` | Stateful session idle timeout in positive whole seconds (default: `1800`). Invalid, zero, negative or unrepresentable values use the default. Applies to transaction-owned connections too; restart the MCP host after changing it. || `DBX_WEB_URL` | Use a DBX Web/Docker backend || `DBX_WEB_PASSWORD` | Authenticate to DBX Web || `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` | Standard system proxy variables for DBX Web requests; empty value means no proxy. Auth via `http://user:pass@host:port` |diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.mdindex c3b6bfe893..37ddefaa55 100644--- a/packages/mcp-server/README.md+++ b/packages/mcp-server/README.md@@ -314,6 +314,7 @@ SQL text is not included in normal MCP errors or logged by default. Enable tempo| Variable | Purpose || --- | --- || `DBX_DATA_DIR` | Override the local DBX data directory |+| `DBX_SESSION_IDLE_TTL_SECS` | Stateful session idle timeout in positive whole seconds (default: `1800`). Invalid, zero, negative or unrepresentable values use the default. Applies to transaction-owned connections too; restart the MCP host after changing it. || `DBX_WEB_URL` | Use a DBX Web/Docker backend || `DBX_WEB_PASSWORD` | Authenticate to the DBX Web backend || `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` | Standard system proxy variables for DBX Web requests; empty value means no proxy. Auth via `http://user:pass@host:port` |@@ -658,6 +659,7 @@ MongoDB 更新和删除在未启用完全访问时必须提供可验证有效的| 变量 | 用途 || --- | --- || `DBX_DATA_DIR` | 覆盖本地 DBX 数据目录 |+| `DBX_SESSION_IDLE_TTL_SECS` | 有状态会话空闲超时,单位为正整数秒,默认 `1800`。非法值、零、负数或无法表示的时长回退默认值;同样适用于事务专属连接。修改后需重启 MCP 宿主进程。 || `DBX_WEB_URL` | 使用 DBX Web/Docker 后端 || `DBX_WEB_PASSWORD` | DBX Web 登录密码 || `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` | DBX Web 请求的标准系统代理变量;空值表示不走代理。认证格式 `http://user:pass@host:port` |