3. 超时问题引入：超时的定义、超时对数据库迁移的影响、超时导致的常见错误类型

在分布式系统与长时间运行的数据库迁移任务中，超时（Timeout） 是最常见且最具破坏力的异常之一。超时并非简单的“任务运行慢了”，而是系统在预期时间内未收到预期响应时触发的保护性中断。理解超时的本质、影响路径以及典型错误模式，是设计可靠重试与恢复机制的前提。

3.1 超时的定义与分类

超时本质上是一个时间约束：系统为某个操作设定一个最大等待时间（Deadline），若在该时间内操作未完成或未返回确认，则判定为失败。在数据库迁移场景中，超时可从不同维度分类：

3.2 超时对数据库迁移的影响路径

超时对迁移的影响并非单一维度的“任务失败”，而是通过以下路径逐级放大破坏力：

1. 连接中断 → 上下文丢失：客户端超时断开后，数据库端的事务上下文、临时表、会话变量可能被清理或残留，导致迁移工具无法获知当前进度。
2. 锁持有时间延长 → 死锁与阻塞：超时发生时，若数据库未自动回滚，写锁或元数据锁可能持续持有，阻塞后续迁移步骤甚至业务查询。
3. 部分写入 → 数据不一致：批量迁移中，超时可能导致部分行已写入目标库、部分未写入，且没有原子性保证，产生“幽灵数据”或“缺失行”。
4. 重试风暴 → 系统过载：不合理的重试策略（如立即重试、指数退避过短）会在超时后瞬间发起大量重复请求，压垮数据库连接池或 IO 带宽。
5. 状态机紊乱 → 迁移卡死：迁移编排器因超时进入错误状态，但实际数据库端操作已成功，导致状态机无法推进，需要人工介入修复。

3.3 超时导致的常见错误类型

在实际迁移工程中，超时引发的错误可归纳为以下五种典型模式。每种模式都有其独特的错误特征、根因和恢复难度。

3.4 超时错误的典型代码表现

以下代码片段展示了在 Go 语言迁移工具中，超时错误的常见捕获与判断模式：

// 示例：Go 中捕获数据库超时错误
import (
    "context"
    "database/sql"
    "errors"
    "time"
)

func runMigration(ctx context.Context, db *sql.DB) error {
    // 设置 30 秒语句超时
    timeoutCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
    defer cancel()

    _, err := db.ExecContext(timeoutCtx, "ALTER TABLE large_table ADD COLUMN new_col INT")
    if err != nil {
        // 判断是否为超时错误
        if errors.Is(err, context.DeadlineExceeded) {
            // 超时后需要主动查询数据库端操作状态
            // 例如：检查 ALTER TABLE 是否仍在执行或已回滚
            return fmt.Errorf("迁移超时: %w, 需检查数据库端状态", err)
        }
        // 其他数据库错误（如锁等待超时）
        var pgErr *pq.Error
        if errors.As(err, &pgErr) && pgErr.Code == "57014" { // query_canceled
            return fmt.Errorf("语句被取消(超时或管理员干预): %w", err)
        }
        return fmt.Errorf("迁移执行错误: %w", err)
    }
    return nil
}

3.5 超时错误的根本原因分析

要有效处理超时，不能仅停留在“设置更长超时”的层面。以下表格总结了超时背后的深层原因与系统瓶颈：