t8y2--dbx/docs/pips/PIP-0001-database-connection-timeout-recovery.md

PIP-0001: 数据库连接空闲失效恢复机制

状态

Proposed

摘要

本 PIP 提议改进 DBX 在 PostgreSQL、openGauss、MySQL 连接空闲失效后的恢复机制，解决 Windows 环境下常见的查询永久执行中、取消无效、连接树持续加载、必须重启应用才能恢复的问题。

核心改动是将连接池检出、连接健康检查、SQL 执行、取消、清理和前端状态恢复纳入统一的超时与恢复模型，避免任一阶段永久挂起。

详细分析和实施计划见：

• docs/pips/plans/2026-06-24-database-connection-timeout-recovery.md

背景

用户在 Windows 环境下反馈，数据库连接建立后一段时间不活动，再次执行查询时会出现：

• 查询结果区域持续显示执行中。
• 点击中断无法停止。
• 连接状态持续转圈，刷新无效。
• 退出并重启应用后恢复。
• PostgreSQL、openGauss、MySQL 均受影响。

该问题不是单一数据库驱动或 SQL 语句问题。三个数据库共同受影响，说明问题边界位于 DBX 的连接生命周期管理、超时控制、取消机制和前端状态收敛层。

问题定义

当数据库连接空闲后，底层 TCP 连接或数据库会话可能被以下因素静默失效：

• 数据库服务端 idle timeout。
• VPN、NAT、防火墙、代理的空闲连接回收。
• Windows 睡眠、网络切换、Wi-Fi/VPN 断开后恢复。
• TCP 半开连接未及时被操作系统发现。

此时 DBX 仍可能持有旧连接池，并且前端仍认为连接有效。下一次操作可能卡在：

• ensureConnected
• checkConnectionHealth
• pool checkout
• pool recycle/verify
• MySQL ping
• PostgreSQL SET search_path
• SQL 执行或结果读取
• PostgreSQL cancel request
• MySQL KILL QUERY
• 连接树元数据刷新

当前系统缺少覆盖以上完整链路的统一执行预算，因此用户看到的现象是“前端一直执行中”，而真正的卡点可能在查询执行之前或取消请求本身。

目标

1. 空闲连接失效后，查询、刷新、取消操作都必须在可预期时间内完成或返回明确错误。
2. 用户无需重启应用即可通过清池、重连恢复。
3. PostgreSQL、openGauss、MySQL 的恢复行为保持一致。
4. 前端执行中、取消中、加载中状态必须有兜底清理机制。
5. 日志能够定位卡住阶段，便于后续排查。

非目标

1. 不保证所有服务端 SQL 一定被成功取消。客户端取消和服务端终止是两个不同结果。
2. 不改变 query_timeout_secs = 0 表示禁用 SQL 查询超时的语义。
3. 不重构所有数据库驱动，仅先覆盖 PostgreSQL、openGauss、MySQL 及共享连接管理链路。
4. 不改变连接配置的存储结构，除非提供向后兼容默认值。

提案

1. 引入数据库操作执行预算

为每次数据库操作建立统一预算，覆盖：

• 连接池等待。
• 新建连接。
• 回收验证。
• 健康检查。
• SQL 执行。
• 取消请求。
• 清理连接池。

建议模型：

pub struct DbOperationBudget {
    pub checkout_timeout: Duration,
    pub connect_timeout: Duration,
    pub recycle_timeout: Duration,
    pub query_timeout: Option<Duration>,
    pub cancel_timeout: Duration,
    pub cleanup_timeout: Duration,
}

其中 query_timeout = None 仅表示 SQL 执行不设上限；连接检出、健康检查、取消和清理仍必须有安全上限。

SQL 执行超时与基础设施超时的边界原则

本 PIP 区分两类超时，语义不可混淆：

1. SQL 执行超时 — 遵循用户配置

• query_timeout_secs = 0：表示 SQL 执行本身不设超时。前端不得静默将其变为有限值（如 60s）。现有代码已正确处理：前端 withFrontendQueryTimeout 在 timeoutSecs === 0 时直接返回 promise 不加超时；后端 resolve_query_timeout 在 Some(0) 时返回 None。
• query_timeout_secs > 0：SQL 执行超时为用户配置值。前端兜底超时设为配置值的 2 倍，让后端先触发自己的超时，前端超时仅作为网络异常下的兜底。
• query_timeout_secs 缺失或无效：使用默认值 60s（DEFAULT_QUERY_TIMEOUT_SECS）。

2. 基础设施超时 — 始终有硬性上限

以下阶段与 SQL 执行无关，即使用户设置 query_timeout_secs = 0，也必须有硬性超时上限，否则可能导致应用永久挂起：

• pool checkout（连接池等待）
• pool create（新建连接）
• pool recycle（回收验证）
• 健康检查（ping）
• 取消请求（PostgreSQL cancel / MySQL KILL QUERY）
• 连接池清理

这些超时值由 DbOperationBudget 中对应的非 Option 字段控制，不受 query_timeout_secs 影响。

checkout 阶段的 cancel token 集成

deadpool-postgres 的 pool.get() 不原生接受 CancellationToken。当前代码中 pool.get().await 为裸调用，无法在 checkout 阶段响应取消请求。

统一 checkout helper 应使用 tokio::select! 包装 pool.get() 以支持取消：

async fn checkout_with_cancel(
    pool: &Pool,
    cancel_token: Option<CancellationToken>,
    checkout_timeout: Duration,
) -> Result<deadpool_postgres::Object, String> {
    let get_future = tokio::time::timeout(checkout_timeout, pool.get());
    match cancel_token {
        Some(token) => {
            tokio::select! {
                biased;
                _ = token.cancelled() => Err("cancelled during pool checkout".to_string()),
                result = get_future => result.map_err(|e| e.to_string()).and_then(|r| r.map_err(|e| e.to_string())),
            }
        }
        None => get_future.await.map_err(|e| e.to_string()).and_then(|r| r.map_err(|e| e.to_string())),
    }
}

当取消触发时，pool.get() future 被 drop，deadpool 内部会正确回滚等待状态。checkout timeout 通过 tokio::time::timeout 实现，超时错误应归类为连接错误并触发清池。

2. 补齐 PostgreSQL/openGauss pool timeout

PostgreSQL/openGauss 共用 PoolKind::Postgres。创建 deadpool-postgres pool 时应显式配置：

• wait timeout
• create timeout
• recycle timeout

同时在项目层统一包装 pool.get()，确保 checkout/recycle 阶段错误可被归类为连接池失效并触发恢复。

3. 统一 MySQL checkout 和 cancel 保护

MySQL 现有 get_conn_with_health_check 是有效的局部保护，但需要纳入统一执行预算。

需要补齐：

• kill_query_with_opts 的建连 timeout。
• KILL QUERY 执行 timeout。
• 元数据、事务、导出等路径中的直接 pool.get_conn() 审计。
• MySQL tcp_keepalive 默认配置。

4. 改进取消机制

取消请求必须覆盖两个阶段：

• SQL 已经在服务端执行：发送 PostgreSQL cancel 或 MySQL KILL QUERY。
• 尚未进入 SQL 执行，例如卡在 checkout/health check：取消客户端任务，标记连接池可疑，并按策略清理 pool。

PostgreSQL TLS 连接取消必须使用与原连接兼容的 TLS connector，避免当前 cancel_query(NoTls) 在 TLS 场景下失败。

TLS cancel 改造说明

当前代码 cancel_postgres_query 使用 NoTls 调用 pg_cancel_token.cancel_query(NoTls)。tokio_postgres::CancelToken::cancel_query 需要显式传入 MakeSslConnect 参数，不会自动升级到 SSL。若 PostgreSQL 服务器配置了 hostssl 或强制 TLS，NoTls 的 cancel 请求会被服务器拒绝。

改造步骤：

1. 验证阶段：在改造前先编写测试验证当前驱动版本在 TLS 连接场景下 cancel_query(NoTls) 的实际行为，确认是否确实失败（服务器是否接受非 TLS cancel 请求取决于 pg_hba.conf 配置）。
2. 存储 TLS connector：在创建连接池时，将 MakeRustlsConnect 实例（或等价 TLS 配置）与 CancelToken 一并存储，使 cancel 时能重建正确的 TLS 连接。
3. 重建 connector：由于 MakeRustlsConnect 不一定实现 Clone，可能需要在 cancel 时从原始 pg_config 和 SSL 配置重新构建 connector。
4. 不降低证书校验：cancel connector 必须使用与原连接相同的证书校验级别，不能为了 cancel 成功而降低安全性。

改造后的 cancel_postgres_query 签名应类似：

async fn cancel_postgres_query(
    pg_cancel_token: tokio_postgres::CancelToken,
    tls: tokio_postgres_rustls::MakeRustlsConnect,
) {
    match tokio::time::timeout(Duration::from_secs(5), pg_cancel_token.cancel_query(tls)).await {
        Ok(Ok(())) => {}
        Ok(Err(err)) => log::warn!("Failed to send PostgreSQL cancel request: {err}"),
        Err(_) => log::warn!("Timed out sending PostgreSQL cancel request"),
    }
}

5. 前端状态兜底恢复

前端需要对以下阶段设置超时并清理状态：

• ensureConnected
• checkConnectionHealth
• executeMulti
• cancelQuery
• 连接树元数据刷新

各阶段超时值定义

阶段	超时值	计算规则	说明
ensureConnected（首次连接）	connect_timeout_secs + 2s	connectionAttemptTimeoutMs(config)	已有实现，复用现有逻辑。Agent 驱动类型有 30s 下限。
ensureConnected（健康检查快路径）	5s	固定值	当 hasRecentConnectionHealthCheck 为 true 时跳过；否则调用 checkConnectionHealth，需加 5s 超时。当前代码缺少此超时。
checkConnectionHealth	max(connect_timeout_secs * 2, 5s)	基于连接超时倍数	健康检查应在连接超时的 2 倍内完成，但不低于 5s。当前代码无超时保护。
executeMulti（SQL 执行）	query_timeout_secs > 0 时为 query_timeout_secs * 2；query_timeout_secs = 0 时为 0（不设超时）	前端超时是后端超时的 2 倍，让后端先触发自己的超时	现有实现已正确处理：queryTimeoutSecs === 0 ? 0 : frontendTimeoutSecs。前端超时仅作为兜底，不是 SQL 执行本身的超时控制。
cancelQuery	10s	固定值	取消请求应在 10s 内返回。超时后强制清理 isCancelling 状态。当前代码无超时保护。
连接树元数据刷新	max(query_timeout_secs + 5s, 15s)	复用 metadataLoadTimeoutMs	已有实现，query_timeout_secs = 0 时使用 60s。

所有超时触发后必须清理：

• isExecuting
• isCancelling
• executionId
• 连接节点 isLoading

若错误表明连接失效，应调用连接丢失处理，并提供重新连接入口。

6. 默认启用更适合桌面环境的 keepalive

当前默认值不一致问题

现有代码存在两层 keepalive 默认值不一致：

• Rust 模型层：default_keepalive_interval_secs() 返回 60（开启），通过 #[serde(default = "default_keepalive_interval_secs")] 生效。从 Rust API（web 后端、测试代码等）直接创建的 ConnectionConfig 默认 keepalive 为 60 秒。
• 前端 UI 层：ConnectionDialog.vue 中 config.keepalive_interval_secs = ... ?? 0（关闭）。从前端保存的连接配置默认 keepalive 为 0（关闭）。

这意味着从前端 UI 创建的连接和从 Rust API 直接创建的连接在 keepalive 行为上不一致。P1-1 必须统一两层默认值策略。

统一策略

应用层 keepalive 统一默认开启：

• 默认间隔：30 秒（前后端统一使用此值作为默认值）。
• 修改 default_keepalive_interval_secs() 返回 30，同步修改前端 ConnectionDialog.vue 的 fallback 值为 30。
• 用户可以关闭（设为 0）。
• 关闭时提示可能受 VPN/NAT/防火墙 idle timeout 影响。

驱动层建议：

• PostgreSQL/openGauss：默认注入或设置短周期 TCP keepalive。
• MySQL：设置 tcp_keepalive=30000 或等价 builder 参数。

keepalive 是预防手段，不能替代超时和清池恢复。

7. 增加阶段化日志

每个查询或刷新操作输出阶段日志：

• ensureConnected
• pool.checkout
• pool.recycle
• ping
• schema.set
• query.execute
• result.fetch
• cancel
• cleanup

日志应包含：

• trace_id
• connection_id
• database
• db_type
• pool_key
• client_session_id
• stage
• elapsed_ms
• timeout_ms
• error

兼容性

查询超时

query_timeout_secs = 0 继续表示不限制 SQL 执行时间。这一语义在前后端必须保持一致：

• 后端：resolve_query_timeout(Some(0)) 返回 None，SQL 执行不受 tokio::time::timeout 约束。
• 前端：withFrontendQueryTimeout 在 timeoutSecs === 0 时直接返回 promise，不施加前端超时。

本 PIP 不得在任何路径中静默将 query_timeout_secs = 0 变为有限 SQL 超时。连接检出、健康检查、取消、清理属于基础设施阶段，必须有独立于 query_timeout_secs 的硬性上限（见"SQL 执行超时与基础设施超时的边界原则"）。

MySQL session-scoped pool

MySQL session-scoped pool 用于保留临时表、用户变量等会话状态。清理策略不得在正常连续查询时破坏该行为。只有明确空闲超时、连接失效、用户关闭 tab 或用户强制断开时才清理。

PostgreSQL search_path

PostgreSQL/openGauss 的 schema 执行上下文行为保持不变，但 SET search_path 和 RESET search_path 必须纳入超时和错误恢复。

清池操作的并发安全

清池操作（remove_pool_by_key、remove_connection_pools_detached、close_database_pool）通过 RwLock 保护 connections HashMap。需要明确以下并发场景：

1. 清池对在途查询的影响

• 已 checkout 的连接不受影响：当 pool.get() 成功返回 Object 后，调用方持有该连接的引用。即使 pool 从 HashMap 中移除，已 checkout 的连接仍可正常使用，直到 Object 被 drop 时归还到原 pool（此时原 pool 可能已被关闭，连接被直接丢弃）。
• 新 checkout 请求失败：pool 从 HashMap 移除后，新的 pool.get() 请求将找不到 pool，触发重连流程。
• 结论：清池操作是安全的，不会中断在途查询，但新请求会触发重连。

2. base pool 与 session-scoped pool 的清理顺序

• close_database_pool 先收集所有需要清理的 key（base pool key + session pool keys），然后统一获取写锁批量移除。
• 清理顺序：先停止 keepalive task → 清理 pool_activity → 获取 connections 写锁批量移除 → 关闭移除的 pools。
• 要求：不允许在持有 connections 写锁的同时执行 pool 内部操作（如 close_pool_kind），避免死锁。当前代码在 drop 写锁后才调用 close_pool_kind，符合此要求。

3. 并发清池的竞态条件

• 多个操作可能同时触发同一 pool 的清理（如超时清理 + 用户手动断开）。remove_pool_by_key 通过写锁保证幂等性：第二次调用时 remove 返回 None，不会重复关闭。
• 要求：P2 实施时确保所有清池入口都通过 remove_pool_by_key 或 drain_connection_pools 统一路径，不绕过写锁直接操作 HashMap。

分阶段实施

阶段 1：止血

目标：避免永久卡死。

范围：

• PostgreSQL/openGauss pool checkout、create、recycle 加 timeout。
• MySQL cancel 加 timeout。
• 前端 ensureConnected、checkConnectionHealth、cancelQuery 加兜底超时。
• 超时后清理 UI 执行状态。

验收：

• 数据库不可达时，查询、取消、刷新都能在可预期时间内返回。

阶段 2：自动恢复

目标：空闲失效后可自动重连或明确失败。

范围：

• 统一 checkout helper。
• pool checkout/ping timeout 进入连接错误分类。
• 连接错误后清理对应 pool。
• 添加强制清池和重新连接入口。

timeout 错误消息格式与 is_connection_error 匹配

当前 is_connection_error 通过 lower.contains("timed out") 匹配超时错误，仅排除 starts_with("query timed out after ") 格式。需要确保以下各 timeout 场景的错误消息能被正确分类：

场景	错误来源	错误消息格式（lowercase）	当前是否匹配	处理方式
DBX query timeout	tokio::time::timeout	"query timed out after {n} seconds"	已排除（is_dbx_query_timeout_error）	保持排除，不触发清池
PostgreSQL pool checkout timeout	deadpool-postgres PoolError::Timeout(TimeoutType::Wait)	"pool wait timeout"	不匹配（是 "timeout" 不是 "timed out"）	需新增匹配 "pool" + "timeout" 组合，或匹配 deadpool 的 TimeoutType 枚举变体
PostgreSQL pool create timeout	deadpool-postgres PoolError::Timeout(TimeoutType::Create)	"pool create timeout"	不匹配	同上
PostgreSQL pool recycle timeout	deadpool-postgres PoolError::Timeout(TimeoutType::Recycle)	"pool recycle timeout"	不匹配	同上
checkout helper 超时（tokio::time::timeout 包装）	自定义 tokio::time::timeout	"elapsed" 或自定义消息	不匹配	checkout helper 应返回包含 "connection" 或 "checkout timed out" 的错误消息
MySQL ping timeout	自定义 tokio::time::timeout	自定义消息	取决于消息内容	确保消息包含 "connection" 或 "timed out"
Agent RPC timeout	Agent 驱动	"agent rpc call timed out ..."	已排除（is_agent_rpc_timeout_error）	保持排除

实施要求：

1. checkout helper 返回的错误消息应包含 "checkout timed out" 或 "connection" 关键词，确保 is_connection_error 能正确匹配。
2. 对于 deadpool 的 PoolError::Timeout，应在错误转换层（如 pg_pool_error_to_string）统一添加 "timed out" 关键词，或在 is_connection_error 中新增 "pool" + "timeout" 组合匹配。
3. P2 实施时需编写单元测试覆盖以上每种 timeout 场景的错误分类。

验收：

• 数据库恢复后，不重启应用即可重新查询。

阶段 3：预防

目标：减少空闲失效概率。

范围：

• 默认开启应用层 keepalive。
• PostgreSQL/openGauss 设置短周期 TCP keepalive。
• MySQL 设置 tcp_keepalive。
• 对齐 idle timeout 和 driver inactive TTL。

验收：

• 常规 Windows/VPN/NAT 环境下，空闲后连接可用或能自动恢复。

阶段 4：可观测性

目标：后续问题可定位。

范围：

• 阶段化日志。
• 连接诊断信息。
• 断链复现脚本和 QA 手册。

验收：

• 用户报告“执行中”时，可以从日志判断卡在具体阶段。

测试计划

自动化测试

• PostgreSQL/openGauss：pool checkout timeout、query timeout、cancel timeout。
• MySQL：ping timeout、kill query timeout、connection error 分类。
• 前端：执行超时后清理 tab 状态；取消超时后清理 isCancelling；连接树刷新失败后清理 loading。

手工测试

Windows 环境验证：

1. 建立 PostgreSQL/openGauss/MySQL 连接。
2. 执行 SELECT 1。
3. 停止数据库或断开 VPN。
4. 再次执行 SELECT 1。
5. 验证 UI 不永久执行中。
6. 恢复数据库或 VPN。
7. 验证无需重启应用即可重连恢复。

取消验证：

• PostgreSQL/openGauss：SELECT pg_sleep(60)。
• MySQL：SELECT SLEEP(60)。
• 点击取消后，UI 必须在 2 到 5 秒内退出取消中状态。

风险

• 过早清理 session-scoped pool 可能破坏会话状态。
• TLS cancel 改造需要复用正确证书配置，不能降低证书校验。
• 默认 keepalive 会增加少量后台请求。
• 部分半开 TCP 场景难以稳定自动化复现。
• 将所有 timeout 都视为连接失效可能误伤慢网络，需要区分 query timeout 与 checkout/ping/cancel timeout。

回滚策略

可独立回滚：

• keepalive 默认值。
• 新增 UI 诊断入口。
• 连接参数默认注入策略。

不建议回滚：

• pool checkout timeout。
• cancel timeout。
• UI 状态兜底清理。

这些属于防止应用永久挂起的基础安全边界。

验收标准

1. PostgreSQL、openGauss、MySQL 空闲失效后，查询不会永久执行中。
2. 中断操作不会永久取消中。
3. 连接树刷新不会永久加载中。
4. 数据库或网络恢复后，不重启应用即可重新连接。
5. 日志能指出失败阶段。
6. 自动化和手工测试覆盖查询、取消、健康检查、元数据刷新、空闲清理和重连恢复。

相关文档

• docs/pips/plans/2026-06-24-database-connection-timeout-recovery.md