Skip to content

armgit / dbx

Public Imported from GitHub
0

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。

feat(mcp): configure stateful session idle timeout

cowkinge1f46cf9a82a
diff --git a/crates/dbx-mcp/src/backend.rs b/crates/dbx-mcp/src/backend.rs
index 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.rs
index 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.rs
index 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.rs
index 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.mdx
index 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.mdx
index 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.md
index 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` |