如何在PHP Sqlsrv中设置查询及存储过程执行超时？

我之前处理过不少PHP调用SQL Server存储过程超时的问题，结合官方文档和实际踩坑经验，给你梳理一套完整的解决办法：

1. 核心：设置Sqlsrv的超时参数 #

Sqlsrv提供了两种超时配置，分别对应连接阶段和查询执行阶段，重点要配置的是查询执行阶段的超时：

连接超时（可选） #

如果是连接数据库的时候就超时，在连接字符串里添加ConnectionTimeout参数，单位是秒：

$connectionInfo = array(
    "UID" => "你的用户名",
    "PWD" => "你的密码",
    "Database" => "目标数据库",
    "ConnectionTimeout" => 10, // 连接超时10秒，按需调整
);
$conn = sqlsrv_connect("你的服务器地址", $connectionInfo);

查询执行超时（关键） #

针对存储过程的执行超时，需要在sqlsrv_prepare或sqlsrv_query时设置QueryTimeout选项，这个参数会告诉Sqlsrv扩展：如果查询执行超过指定秒数，就自动终止请求并返回错误：

$options = array(
    "QueryTimeout" => 30, // 30秒超时，根据你的业务场景调整
);

2. 完整的存储过程调用+超时处理示例 #

下面是一个可直接复用的代码模板，包含超时判断和错误提示：

// 先设置PHP脚本超时，确保比Sqlsrv的查询超时更长，避免脚本先挂掉
ini_set('max_execution_time', 40); // 比如设40秒，比QueryTimeout的30秒多10秒

// 1. 建立数据库连接
$connectionInfo = array(
    "UID" => "db_user",
    "PWD" => "db_pwd",
    "Database" => "your_db",
    "ConnectionTimeout" => 10,
);
$conn = sqlsrv_connect("server_name", $connectionInfo);

if (!$conn) {
    die("数据库连接失败: " . print_r(sqlsrv_errors(), true));
}

// 2. 准备存储过程调用语句和参数
$sql = "EXEC SP_Name @Param1 = ?, @Param2 = ?";
$params = array("参数1值", "参数2值");

// 3. 设置查询超时选项
$options = array(
    "QueryTimeout" => 30, // 执行超时30秒
);

// 4. 准备并执行查询
$stmt = sqlsrv_prepare($conn, $sql, $params, $options);
if ($stmt === false) {
    die("语句准备失败: " . print_r(sqlsrv_errors(), true));
}

if (!sqlsrv_execute($stmt)) {
    $errors = sqlsrv_errors();
    foreach ($errors as $error) {
        // 识别超时错误（SQLSTATE为HYT00）
        if ($error['SQLSTATE'] === 'HYT00') {
            echo "<p>存储过程执行超时，已自动终止操作</p>";
        } else {
            echo "<p>执行错误: " . $error['message'] . "</p>";
        }
    }
    // 清理资源
    sqlsrv_free_stmt($stmt);
    sqlsrv_close($conn);
    exit;
}

// 5. 处理存储过程返回的结果（如果有）
while ($row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC)) {
    // 处理你的数据，比如echo $row['column_name'];
}

// 6. 清理资源
sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);

3. 超时后自动终止存储过程的说明 #

当QueryTimeout触发时，Sqlsrv扩展会自动向SQL Server发送取消查询的请求，存储过程会被立即终止，不需要额外手动处理。不过要注意：

• 如果存储过程里包含事务，超时后事务会处于未提交状态，建议在存储过程内部添加错误处理逻辑，比如TRY...CATCH块自动回滚事务
• 确保SQL Server账号有足够的权限取消查询（一般执行存储过程的权限就足够）

4. 额外排查500错误的建议 #

有时候500错误不一定是超时导致的，你可以做这些排查：

• 开启PHP错误日志：在php.ini里设置error_log = /path/to/php_errors.log，查看具体的错误详情
• 检查max_execution_time：如果PHP脚本本身的超时时间比Sqlsrv的查询超时短，会直接触发500错误，所以一定要确保前者更长
• 在SSMS里测试存储过程：先手动执行EXEC SP_Name，看看实际执行时间和是否有报错，排除存储过程本身的性能或语法问题

内容的提问来源于stack exchange，提问作者Robin Bronston