Actualizar los controladores PHP para SQL Server

Actualiza SQLSRV y PDO_SQLSRV juntos para que ambas extensiones usen la misma familia de versiones. Los controladores PHP usan el controlador Microsoft ODBC para SQL Server, así que revisa los requisitos del sistema antes de actualizar.

Una actualización cambia el código nativo cargado en los procesos PHP. Un despliegue mixto puede continuar ejecutando la versión anterior, fallar durante el inicio de PHP o exponer diferentes versiones de controladores a la CLI y la aplicación web. Haz inventario de cada entorno de ejecución de PHP y conserva los archivos y configuraciones anteriores hasta que termine la verificación.

Elige la ruta de mejora

No sobrescribas los binarios anteriores hasta que tengas una copia de rollback. No actualices solo una extensión cuando la aplicación usa ambas APIs.

Antes de actualizar

1. Registra el ejecutable PHP, el archivo de configuración, la arquitectura, el modo de seguridad de hilos y las versiones actuales de los controladores.

   php --version
   php --ini
   php --ri sqlsrv
   php --ri pdo_sqlsrv
   

2. Haz una copia de seguridad del php.ini archivo y de cualquier archivo específico .ini de extensión que cargue sqlsrv o pdo_sqlsrv.

3. Consulta la matriz de soporte para la versión de PHP y el sistema operativo de destino.

4. Consulta la tabla de compatibilidad ODBC en Requisitos del sistema. Instala una versión ODBC compatible antes o durante la actualización del controlador PHP cuando la versión del driver objetivo lo requiera.

5. Planifica un reinicio de todos los procesos que cargan PHP, incluyendo el servidor web, PHP FastCGI Process Manager (PHP-FPM), los trabajadores de cola y los procesos en línea de comandos de larga ejecución.

6. Registra una línea base de cada ejecución:

   • El ExtensionVer mostrado por php --ri sqlsrv y php --ri pdo_sqlsrv.
   • Se cargó el archivo de configuración y se escaneó el directorio .ini.
   • El directorio de extensiones y los nombres de archivo de los controladores activos.
   • Una prueba de humo de aplicación satisfactoria que usa cada API de la que depende tu aplicación.

7. Preparar una reversión:

   • Mantén disponible el tiempo de ejecución PHP anterior si cambias la versión menor de PHP. Registra el ejecutable configurado para cada servidor web y worker.
   • Guarda copias de los archivos SQLSRV y PDO_SQLSRV anteriores.
   • Guarda copias de cada archivo modificado php.ini o archivo específico de la extensión .ini.
   • Graba la versión anterior del paquete ODBC si la actualización la cambia.
   • Define cómo detener el tráfico o los procesos worker mientras se reemplazan los archivos de extensión nativos.

Actualizar en Windows con PIE

Utiliza el PHP Installer for Extensions (PIE) con el ejecutable PHP que sirve a la aplicación. Primero, descarga y verifica PIE. Antes de ejecutar cualquiera de los comandos de instalación, drena el tráfico de la aplicación y detiene el servidor web, los procesos FastCGI y los trabajadores que usan esta instalación PHP. Evita que se reinicien automáticamente hasta que ambas extensiones y su configuración estén listas. Mantén una sesión de línea de comandos separada para PIE.

Comenta temporalmente las entradas existentes de las extensiones SQLSRV y PDO_SQLSRV en la configuración de CLI utilizada por PIE. De lo contrario, el proceso PHP que ejecuta PIE puede mantener cargadas las DLLs antiguas y evitar su reemplazo. Mantén activadas las extensiones de requisitos previos de PIE.

Desde el directorio que contiene pie.phar, instala ambos paquetes por separado:

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

PIE instala php_sqlsrv.dll y php_pdo_sqlsrv.dll. En cada configuración activa, sustituir las entradas ZIP versionadas como extension=php_sqlsrv_85_ts_x64.dll y extension=php_pdo_sqlsrv_85_ts_x64.dll por:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

Habilitar ambas entradas y eliminar entradas duplicadas de SQLSRV y PDO_SQLSRV incluso si PIE informa que la habilitación automática ha tenido éxito. Si el servidor web usa una instalación PHP diferente, repite la actualización y los cambios de configuración para esa instalación.

Reinicia cada proceso PHP y luego ejecuta php --ri sqlsrv y php --ri pdo_sqlsrv con el ejecutable correspondiente. Confirma que ExtensionVer reporta la versión de destino para ambos controladores. Para una aplicación web, restringe el acceso a la página de diagnóstico antes de crear una página temporal phpinfo(). Verifica ambos valores y luego elimina la página.

Actualizar una instalación de Windows ZIP

1. Descarga el Windows ZIP de la versión objetivo desde la página de versiones de Microsoft Drivers for PHP for SQL Server.

2. Confirma que los nuevos nombres de la biblioteca de enlace dinámico (DLL) coinciden con la versión menor de PHP, la arquitectura y el modo de seguridad de hilos. Detenga el servidor web PHP o los procesos de trabajo antes de reemplazar archivos.

3. Sustituye los archivos php_sqlsrv_*.dll y php_pdo_sqlsrv_*.dll en el directorio de extensiones PHP. Conserva las entradas existentes extension= si los nombres de archivo siguen coincidiendo. Si no, actualízalos juntos.

4. Instala o actualiza el controlador ODBC de Microsoft para SQL Server si el controlador PHP objetivo requiere una versión más nueva soportada.

5. Reinicia todos los procesos PHP que usen las DLLs reemplazadas. Un proceso en ejecución mantiene cargada la antigua extensión nativa hasta que finaliza.

Actualizar en Linux o macOS con PIE

1. Sigue la configuración de PIE y los requisitos previos de la plataforma si PIE no está instalado. Confirma que las herramientas de desarrollo PHP y el paquete ODBC están instalados. En una sesión interactiva, PIE puede solicitar la instalación de herramientas de compilación faltantes a través del gestor de paquetes de la plataforma. En una sesión no interactiva, instálalos antes de ejecutar PIE.

2. Selecciona la instalación de PHP antes de actualizar. Para una instalación versionada, añade la opción de --with-php-config PIE a ambos comandos de instalación. Por ejemplo, use pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv cuando la herramienta de configuración prevista es /usr/bin/php-config8.4. Aplica la misma opción a microsoft/pdo_sqlsrv. Para los ejecutables versionados de Alpine, utiliza los comandos de instalación de Alpine.

3. Redirige el tráfico de la aplicación y detiene el servidor web, los procesos de PHP-FPM y los trabajadores que usan esta instalación de PHP. Evita que se reinicien automáticamente hasta que ambas extensiones y su configuración estén listas. Mantén una sesión de línea de comandos separada para PIE.

   Comenta temporalmente las entradas existentes de las extensiones SQLSRV y PDO_SQLSRV en la configuración de CLI utilizada por PIE. Mantén activadas las extensiones necesarias de PIE.

4. Actualiza ambos paquetes por separado. Estos comandos utilizan la instalación predeterminada de PHP de PIE:

   pie install microsoft/sqlsrv
   pie install microsoft/pdo_sqlsrv
   

5. Revisa todas las configuraciones activas de la instalación PHP que usa tu aplicación. Si una instalación manual anterior utiliza nombres de archivo de archivo como extension=SQLSRV_8.4_NTS.so y extension=PDO_SQLSRV_8.4_NTS.so, sustituye esas entradas por los nombres de archivo instalados en PIE:

   extension=sqlsrv.so
   extension=pdo_sqlsrv.so
   

   Reactiva ambas entradas de driver y elimina duplicados. Guarda PDO_SQLSRV en un archivo de configuración escaneado que se cargue después de PDO, como se describe en Cargar los controladores en Linux y macOS. Repite este cambio de configuración para la línea de comandos, PHP-FPM, el servidor web y las configuraciones de workers que utilice tu aplicación.

6. Actualiza el controlador Microsoft ODBC para SQL Server cuando la versión objetivo lo requiera.

7. Reinicia cada trabajador CLI, trabajador de cola, servidor web y servicio PHP-FPM que use la instalación actualizada de PHP.

Reinicia y verifica

Reemplazar un archivo de extensión no actualiza un proceso PHP que ya había cargado el binario antiguo. Reinicia el servidor web, PHP-FPM y cualquier proceso worker de PHP de larga ejecución antes de verificar la actualización.

1. Verifica el entorno de ejecución de línea de comandos:

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

   En Linux o macOS, sustituye el último comando por php -m | grep -E 'sqlsrv|pdo_sqlsrv'.

2. Para una aplicación web, restringe el acceso a la página de diagnóstico antes de crear una página temporal phpinfo(). Verifica el archivo de configuración cargado, el directorio de extensiones y ExtensionVer para ambos controladores. Confirma que ExtensionVer reporta la versión de destino y luego elimina la página.

3. Ejecuta una prueba de humo de aplicación existente que ejerce tanto SQLSRV como PDO_SQLSRV si tu aplicación usa ambos. Mantén la configuración de la conexión sin cambios durante esta comprobación para que una prueba de actualización no pruebe también un cambio de conexión no relacionado.

Si un controlador no se carga, compara la versión menor de PHP, la arquitectura, el modo de seguridad de hilos, el directorio de extensiones y la instalación ODBC con los valores registrados antes de la actualización.

Verifica tanto las APIs como las versiones

Guarda este programa como 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);

Ejecuta el programa con el ejecutable de la CLI y, temporalmente, en cada entorno de ejecución web. Confirma que ambas versiones reportadas coinciden con la versión que instalaste. Elimina la copia web después de verificarla.

Este programa verifica la capa de extensión PHP. Ejecuta la prueba de humo de la aplicación sin cambios después para verificar la carga ODBC, las opciones de conexión, la autenticación, el acceso a la base de datos, los tipos PHP devueltos y el comportamiento de limpieza.

Verifica el comportamiento de la base de datos antes y después de la actualización

Usa el mismo programa y configuración de conexión antes y después de la actualización. Mantener la prueba sin cambios separa los cambios de controladores de los cambios en la aplicación o configuración de conexión.

Establece las SQL_SERVER_NAMEvariables , SQL_DATABASE, SQL_UID, y SQL_PWD de entorno para una cuenta de prueba respondiendo a las preguntas. Introduce los valores en bruto, sin comillas de shell ni codificación del controlador. No incluyas credenciales en una línea de comandos ni en una sesión de terminal grabada.

En Windows PowerShell, introduce el nombre del servidor y el nombre de la base de datos, y luego utiliza el diálogo o el prompt de credenciales para la cuenta de prueba:

$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

En Linux o macOS, usa Bash. Desactiva el rastreo de comandos antes de leer cualquier valor. El mensaje de contraseña no muestra lo que escribes:

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

El entorno contiene la contraseña en texto plano para que PHP pueda leerla. Usa estas variables solo en la sesión de prueba, no las imprimas y elimínalas después de la prueba.

Guarda este programa como test-driver-upgrade.php. Mantén los valores del entorno sin cambios. El programa duplica las llaves de cierre y añade las llaves exteriores antes de pasar el nombre de la base de datos, nombre de usuario y contraseña al controlador. Esta codificación preserva las llaves literales y evita que los puntos y coma separen las opciones de conexión.

<?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);

Ejecuta el programa antes de la actualización y guarda la salida correcta. Ejecuta el archivo sin cambios de nuevo después de reiniciar todos los procesos PHP:

php test-driver-upgrade.php

Ambas ejecuciones deberían producir:

SQLSRV query: 1
PDO_SQLSRV query: 1

Si la ejecución posterior a la actualización falla, conserva exactamente SQLSTATE o la excepción. Luego compara el fallo con la línea base, las versiones de extension, la configuración activa, la versión ODBC y el estado de reinicio del proceso. Revierte ambas extensiones PHP juntas cuando no puedas corregir la discrepancia dentro de la ventana de despliegue.

Tras la verificación, elimina el archivo de prueba y borra las variables temporales del entorno. En PowerShell, ejecute:

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

En Linux o macOS, ejecute:

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

Revertir una actualización fallida

1. Detener los servidores web afectados, los grupos de PHP-FPM y los procesos worker de larga ejecución.

2. Si cambiaste la versión menor de PHP, restaura el entorno de ejecución anterior de PHP y apunta cada servidor web y worker de vuelta a esa instalación.

3. Restaura ambos archivos del controlador anterior. Restaura juntas las entradas de configuración anteriores de SQLSRV y PDO_SQLSRV.

4. Restaura el paquete ODBC anterior solo si la versión más reciente causó el fallo y el paquete anterior sigue soportado por la versión del controlador PHP que restauraste.

5. Reinicia los procesos y vuelve a ejecutar las comprobaciones de versión base y las pruebas de humo de la aplicación.

6. Guarda los registros de actualización fallida y el error exacto de inicio o conexión de PHP. Ayudan a identificar si el fallo se debe a la carga de PHP, al cargador del sistema operativo, a ODBC o a la conexión a la base de datos.

Solución de problemas de una actualización

Contenido relacionado

• Instala los controladores PHP para SQL Server en Windows
• Tutorial de instalación de Linux y macOS
• Carga de los controladores de Microsoft para PHP para SQL Server