wehub-resource-sync
471 lines
20 KiB
Markdown
471 lines
20 KiB
Markdown
# 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 执行。
|
||
- 取消请求。
|
||
- 清理连接池。
|
||
|
||
建议模型：
|
||
|
||
```rust
|
||
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()` 以支持取消：
|
||
|
||
```rust
|
||
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` 签名应类似：
|
||
|
||
```rust
|
||
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`
|