升级 SQL Server 的 PHP 驱动程序

将SQLSRV和PDO_SQLSRV一起升级,使两个扩展使用相同的版本系列。 PHP 驱动使用 Microsoft ODBC 驱动 for SQL Server,升级前请查看系统需求。

升级会改变加载到PHP进程中的本地代码。 混合部署可能继续运行上一个版本,PHP启动时失败,或向CLI和Web应用暴露不同版本的驱动。 对每个PHP运行时进行盘点,并保留之前的文件和配置,直到验证完成。

版本 5.14.0 需要 PHP 8.4、8.5 或 8.6 以及 Microsoft ODBC 驱动程序 17 或 18。 如果使用 PHP 8.3 或更早版本,请在安装这些驱动程序之前先升级 PHP。 在 PHP 8.3 上,PIE 选择了 5.14.0,构建失败。 有关错误及修复方法,请参见 PHP 8.3 上的 PIE 构建失败。 要继续使用 PHP 8.3,请使用 pie install microsoft/sqlsrv:5.13.3 和 pie install microsoft/pdo_sqlsrv:5.13.3 安装 5.13.3。 从 5.14.0 开始的新版本通过 PHP 扩展安装程序(PIE)发布,而非 PHP 扩展社区库(PECL)。 运行 pecl upgrade 不会安装 5.14.0。

选择升级路径

当前安装 目标安装 Procedure
PIE PIE 用相同的 PHP 可执行文件或显式指定 php-config 运行 PIE,然后验证每个 SAPI
PECL PIE 为受支持的 PHP 运行时安装两个 PIE 包,替换旧的驱动程序条目,并保留 PDO 加载顺序
Windows 已发布 ZIP Windows 已发布 ZIP 替换两个版本化的 DLL,并同时更新两个配置条目
Windows 已发布 ZIP PIE 安装两个 PIE 包,用 PIE 条目替换版本化的 DLL 条目,并删除重复项
Linux 或 macOS 已发布存档 PIE 安装两个 PIE 包,将归档文件名条目替换为 sqlsrv.so 和 pdo_sqlsrv.so,并保留 PDO 加载顺序
Linux 或 macOS PIE 新的PHP小版本 安装新的PHP开发工具,为该PHP安装构建两个扩展,并分别配置每个SAPI

在你拿到回滚副本之前,不要覆盖之前的二进制文件。 当应用同时使用两个 API 时,不要只升级一个扩展。

升级之前

  1. 记录PHP可执行文件、配置文件、架构、线程安全模式及当前驱动版本。

    php --version
    php --ini
    php --ri sqlsrv
    php --ri pdo_sqlsrv
    
  2. 备份 php.ini 文件以及任何特定于扩展的 .ini 文件,这些文件会加载 sqlsrv 或 pdo_sqlsrv。

  3. 请查看目标PHP版本和操作系统 的支持矩阵 。

  4. 请查看 系统需求中的ODBC兼容性表。 当目标驱动版本要求时,在PHP驱动升级前或升级期间安装支持的ODBC版本。

  5. 计划重启所有加载PHP的进程,包括Web服务器、 PHP FastCGI进程管理器(PHP-FPM)、队列工作者和长期运行的命令行工作者。

  6. 记录每个运行时的基线:

    • 由 php --ri pdo_sqlsrv 和 php --ri sqlsrv 显示的 ExtensionVer。
    • 加载的配置文件和扫描的 .ini 目录
    • 扩展目录和活动驱动程序文件名。
    • 一个使用应用程序所依赖的每个 API 的通过应用冒烟测试。
  7. 准备回滚:

    • 如果您更改 PHP 次版本,请保留之前的 PHP 运行时可供使用。 记录为每个 Web 服务器和工作进程配置的可执行文件。
    • 保留之前的 SQLSRV 和 PDO_SQLSRV 文件副本。
    • 保留每个已更改的 php.ini 或特定于扩展的 .ini 文件的副本。
    • 如果升级更改了原来的ODBC包版本,请记录下来。
    • 定义如何在本机扩展文件被替换时停止流量或辅助角色。

在Windows上使用PIE升级

使用PHP 扩展安装程序(PIE)配合为应用程序服务的PHP可执行文件。 首先,下载并验证PIE。 在执行任一安装命令前,先切走应用请求流量,并停止使用该 PHP 安装的 Web 服务器、FastCGI 进程和工作进程。 在两个扩展及其配置都准备好之前,防止它们自动重启。 为PIE保留一个单独的命令行会话。

暂时注释PIE使用的CLI配置中现有的SQLSRV和PDO_SQLSRV扩展条目。 否则,运行PIE的PHP进程可能会保持旧DLL的加载状态,阻止替换。 请确保 PIE 的先决条件扩展已启用。

从包含 pie.phar的目录中分别安装两个软件包:

php .\pie.phar install microsoft/sqlsrv
php .\pie.phar install microsoft/pdo_sqlsrv

PIE 安装php_sqlsrv.dll和php_pdo_sqlsrv.dll。 在每个活动配置中,将带版本号的 ZIP 条目(例如 extension=php_sqlsrv_85_ts_x64.dll 和 extension=php_pdo_sqlsrv_85_ts_x64.dll)替换为:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

启用这两个条目,并删除重复的 SQLSRV 和 PDO_SQLSRV 条目,即使 PIE 报告自动启用成功。 如果网页服务器使用了不同的PHP安装,请重复该安装的升级和配置更改。

重启每个PHP进程,然后分别使用对应的可执行文件运行php --ri sqlsrv和php --ri pdo_sqlsrv。 确认 ExtensionVer 报告两个驱动程序的目标版本。 对于网页应用,在创建临时页面之前,先phpinfo()。 验证两个数值后,删除页面。

升级 Windows ZIP 安装

  1. 从Microsoft Drivers for PHP for SQL Server releases页面下载目标版本的 Windows ZIP。

  2. 请确认新的动态链接库(DLL)名称是否与PHP小版本、架构和线程安全模式相符。 在替换文件之前,先停止PHP Web服务器或工作进程。

  3. 替换 PHP 扩展目录中的两个 php_sqlsrv_*.dll 和 php_pdo_sqlsrv_*.dll 文件。 如果文件名仍然匹配,就保留现有 extension= 条目。 否则,就一起更新它们。

  4. 如果目标PHP驱动需要较新的受支持版本,安装或升级 Microsoft ODBC Driver for SQL Server。

  5. 重启所有使用被替换DLL的PHP进程。 运行中的进程会让旧的本地扩展保持加载,直到它退出。

在Linux或macOS上升级,使用PIE

  1. 如果没有安装 PIE,请遵循 PIE 设置和平台先决条件。 请确认PHP开发工具和ODBC开发包已安装。 在交互式会话中,PIE 可以通过平台包管理器提示安装缺失的构建工具。 在非交互式会话中,先安装它们再运行 PIE。

  2. 升级前先选择 PHP 安装项。 对于版本化安装,可以在两个安装命令中添加PIE的 --with-php-config 选项。 例如,当预期配置工具为 pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv 时,使用 /usr/bin/php-config8.4。 将同样的选项应用到 microsoft/pdo_sqlsrv。 对于 Alpine 的版本化可执行文件,请使用 Alpine 安装命令。

  3. 排空应用流量,停止使用该 PHP 安装的 Web 服务器、PHP-FPM 进程和工作进程。 在两个扩展及其配置都准备好之前,防止它们自动重启。 为PIE保留一个单独的命令行会话。

    暂时注释PIE使用的CLI配置中现有的SQLSRV和PDO_SQLSRV扩展条目。 请确保 PIE 的先决条件扩展已启用。

  4. 分别升级这两个软件包。 这些命令使用 PIE 默认的 PHP 安装:

    pie install microsoft/sqlsrv
    pie install microsoft/pdo_sqlsrv
    
  5. 检查应用程序所使用的 PHP 安装的每个已活动配置。 如果之前的手动安装使用了如 extension=SQLSRV_8.4_NTS.so 和 extension=PDO_SQLSRV_8.4_NTS.so这样的归档文件名,则用 PIE 安装的文件名替换这些条目:

    extension=sqlsrv.so
    extension=pdo_sqlsrv.so
    

    重新启用两个驱动程序条目,并删除重复的。 请将 PDO_SQLSRV 保存在扫描配置文件中,该文件在 PDO 后加载,详见 在 Linux 和 macOS 上加载驱动程序。 对你的应用程序使用的命令行、PHP-FPM、网页服务器和工作者配置也进行同样的配置更改。

  6. 当目标版本要求时,升级适用于 SQL Server 的 Microsoft ODBC 驱动程序。

  7. 重启每个使用升级PHP安装的CLI工作程序、队列工作程序、网页服务器和 PHP-FPM 服务。

重启并验证

替换扩展文件并不会更新已经加载过旧二进制文件的PHP进程。 在验证升级前,先重启 Web 服务器、PHP-FPM 以及所有长时间运行的 PHP 工作进程。

  1. 验证命令行运行时:

    php --ri sqlsrv
    php --ri pdo_sqlsrv
    php -m | findstr /I "sqlsrv pdo_sqlsrv"
    

    在 Linux 或 macOS 上,将最后一个命令替换为 php -m | grep -E 'sqlsrv|pdo_sqlsrv'。

  2. 对于网页应用,在创建临时页面之前,先phpinfo()。 验证两个驱动程序的已加载配置文件、扩展目录以及 ExtensionVer。 确认 ExtensionVer 报告的是目标版本后,删除该页面。

  3. 如果您的应用同时使用这两者,请对现有应用运行一次同时测试 SQLSRV 和 PDO_SQLSRV 的冒烟测试。 在检查过程中保持连接配置不变,这样升级测试时就不会同时测试无关的连接变更。

如果驱动程序加载失败,将PHP小版本、架构、线程安全模式、扩展目录和ODBC安装与升级前记录的数值进行比较。

验证这两个 API 和版本

将此程序保存为 verify-driver-upgrade.php:

<?php
$results = [
    'SQLSRV' => [
        'loaded' => extension_loaded('sqlsrv') && function_exists('sqlsrv_connect'),
        'version' => phpversion('sqlsrv'),
    ],
    'PDO_SQLSRV' => [
        'loaded' => extension_loaded('pdo_sqlsrv')
            && in_array('sqlsrv', PDO::getAvailableDrivers(), true),
        'version' => phpversion('pdo_sqlsrv'),
    ],
];

$failed = false;
foreach ($results as $name => $result) {
    $version = $result['version'] === false ? 'unknown' : $result['version'];
    echo "$name: " . ($result['loaded'] ? 'loaded' : 'missing') . ", version $version" . PHP_EOL;
    $failed = $failed || !$result['loaded'] || $result['version'] === false;
}

exit($failed ? 1 : 0);

使用 CLI 可执行文件暂时通过每个 Web 运行时运行程序。 确认已报告的两个版本是否与你安装的版本一致。 验证后删除网页副本。

该程序验证了PHP扩展层。 之后运行未更改的应用烟雾测试,以验证 ODBC 加载、连接选项、认证、数据库访问、返回的 PHP 类型和清理行为。

在升级前后验证数据库行为

升级前后使用相同的程序和连接设置。 保持测试不变可以将驱动程序变更与应用或连接配置变更区分开。

通过回答提示为测试账户设置 SQL_SERVER_NAME、 SQL_DATABASE、 SQL_UID和 SQL_PWD 环境变量。 输入原始值,不使用shell引号或驱动编码。 不要在命令行或录制的终端会话中包含凭证。

在 Windows PowerShell 中,输入服务器名称和数据库名称,然后使用凭据对话框或提示输入测试账户的凭据:

$env:SQL_SERVER_NAME = Read-Host "Server name (tcp:<server>,1433)"
$env:SQL_DATABASE = Read-Host "Database name"
$credential = Get-Credential -Message "Enter the database test account"
if ($null -eq $credential) {
    throw "Database test credentials are required."
}
$env:SQL_UID = $credential.UserName
$env:SQL_PWD = $credential.GetNetworkCredential().Password
Remove-Variable credential

在Linux或macOS上,使用Bash。 读取任何值前先禁用命令追踪。 密码提示不会回显你的输入:

set +x
IFS= read -r -p 'Server name (tcp:<server>,1433): ' SQL_SERVER_NAME
IFS= read -r -p 'Database name: ' SQL_DATABASE
IFS= read -r -p 'User name: ' SQL_UID
IFS= read -r -s -p 'Password: ' SQL_PWD
printf '\n'
export SQL_SERVER_NAME SQL_DATABASE SQL_UID SQL_PWD

环境包含明文密码,因此 PHP 可以读取该密码。 这些变量只在测试会话中使用,不要打印,测试后清除。

将该程序保存为 test-driver-upgrade.php。 保持环境值不变。 该程序会将右大括号加倍并添加外层大括号,然后将数据库名称、用户名和密码传递给驱动程序。 这种编码保留了字面大括号,并防止分号分隔连接选项。

<?php
$serverName = getenv('SQL_SERVER_NAME');
$database = getenv('SQL_DATABASE');
$uid = getenv('SQL_UID');
$pwd = getenv('SQL_PWD');

if ($serverName === false || $serverName === ''
    || $database === false || $database === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    fwrite(STDERR, "Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD." . PHP_EOL);
    exit(1);
}

$database = '{' . str_replace('}', '}}', $database) . '}';
$uid = '{' . str_replace('}', '}}', $uid) . '}';
$pwd = '{' . str_replace('}', '}}', $pwd) . '}';

$connectionOptions = [
    "Database" => $database,
    "UID" => $uid,
    "PWD" => $pwd,
    "Encrypt" => 1,
    "TrustServerCertificate" => 0,
];

$sqlsrvConnection = sqlsrv_connect($serverName, $connectionOptions);
if ($sqlsrvConnection === false) {
    foreach (sqlsrv_errors() as $error) {
        fwrite(
            STDERR,
            "SQLSRV {$error['SQLSTATE']} ({$error['code']}): {$error['message']}" . PHP_EOL
        );
    }
    exit(1);
}

$sqlsrvStatement = sqlsrv_query($sqlsrvConnection, "SELECT 1 AS TEST_VALUE");
if ($sqlsrvStatement === false) {
    foreach (sqlsrv_errors() as $error) {
        fwrite(
            STDERR,
            "SQLSRV {$error['SQLSTATE']} ({$error['code']}): {$error['message']}" . PHP_EOL
        );
    }
    sqlsrv_close($sqlsrvConnection);
    exit(1);
}

$sqlsrvRow = sqlsrv_fetch_array($sqlsrvStatement, SQLSRV_FETCH_ASSOC);
if ($sqlsrvRow === false || $sqlsrvRow === null || (int) $sqlsrvRow['TEST_VALUE'] !== 1) {
    fwrite(STDERR, "SQLSRV returned an unexpected result." . PHP_EOL);
    sqlsrv_free_stmt($sqlsrvStatement);
    sqlsrv_close($sqlsrvConnection);
    exit(1);
}

echo "SQLSRV query: 1" . PHP_EOL;
sqlsrv_free_stmt($sqlsrvStatement);
sqlsrv_close($sqlsrvConnection);

$failed = false;
try {
    $pdoConnection = new PDO(
        "sqlsrv:server=$serverName;Database=$database;Encrypt=1;TrustServerCertificate=0",
        $uid,
        $pwd,
        [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
    );
    $pdoStatement = $pdoConnection->query("SELECT 1 AS TEST_VALUE");
    $pdoRow = $pdoStatement->fetch(PDO::FETCH_ASSOC);
    if ($pdoRow === false || (int) $pdoRow['TEST_VALUE'] !== 1) {
        throw new RuntimeException("PDO_SQLSRV returned an unexpected result.");
    }

    echo "PDO_SQLSRV query: 1" . PHP_EOL;
} catch (Throwable $exception) {
    fwrite(STDERR, $exception->getMessage() . PHP_EOL);
    $failed = true;
} finally {
    unset($pdoStatement);
    unset($pdoConnection);
}

exit($failed ? 1 : 0);

在升级前运行程序并保存成功的输出。 在重启所有PHP进程后,再次运行未更改的文件:

php test-driver-upgrade.php

两次运行都应有:

SQLSRV query: 1
PDO_SQLSRV query: 1

如果升级后运行失败,保留相同的SQLSTATE或异常。 然后将失败情况与基线、扩展版本、活跃配置、ODBC版本和进程重启状态进行比较。 当部署窗口内无法纠正不匹配时,将两个PHP扩展一起回滚。

验证后,删除测试文件并清除临时环境变量。 在 PowerShell 中,运行:

Remove-Item .\verify-driver-upgrade.php, .\test-driver-upgrade.php
Remove-Item Env:\SQL_SERVER_NAME, Env:\SQL_DATABASE, Env:\SQL_UID, Env:\SQL_PWD

在 Linux 或 macOS 上运行:

rm verify-driver-upgrade.php test-driver-upgrade.php
unset SQL_SERVER_NAME SQL_DATABASE SQL_UID SQL_PWD

回滚未成功的升级

  1. 停止受影响的网络服务器、PHP-FPM 池和长时间运行的工作进程。

  2. 如果你更改了 PHP 小版本,请恢复之前的 PHP 运行时,并将每个 Web 服务器和工作者指向该安装。

  3. 恢复之前的两个驱动程序文件。 将之前的 SQLSRV 和PDO_SQLSRV配置条目一起恢复。

  4. 只有在新版本导致失败且旧包仍被你恢复的PHP驱动版本支持时,才恢复之前的ODBC包。

  5. 重启进程,重新运行基线版本检查和应用烟雾测试。

  6. 保留失败的升级日志和确切的 PHP 启动或连接错误。 它们有助于识别故障是源自PHP加载、操作系统加载器、ODBC还是数据库连接。

排查升级问题

问题 可能的原因 纠正措施
PIE成功了,但ExtensionVer没有变化 旧的版本化条目仍然会加载之前的文件 替换旧条目,删除重复,重启所有PHP进程
SQLSRV 和 PDO_SQLSRV 报告不同的版本 只有一个扩展被替换,或者有一个SAPI配置过时 每个运行时一起升级和配置两个扩展
CLI报告目标版本,但网站没有 Web SAPI 使用另一个 PHP 安装,或者未重启 比较配置目录和扩展目录,然后重新启动正确的进程
PHP 在启动时报告架构或符号错误 扩展和PHP构建不匹配 恢复之前的文件,然后重建或选择正确的PHP小版本、架构和线程安全模式的文件
扩展加载,但连接在更改 ODBC 后会失败 ODBC 配置、证书行为、认证或网络访问发生变化 在回滚或更改连接设置之前,先捕获 SQLSTATE 和原生错误
工作进程发生故障,而新的 Web 请求成功 长时间运行的工作线程仍持有之前的扩展程序或配置 排空并重启所有工作进程