Werk de PHP-stuurprogramma's voor SQL Server bij

Upgrade SQLSRV en PDO_SQLSRV samen zodat beide extensies dezelfde releasefamilie gebruiken. De PHP-drivers gebruiken de Microsoft ODBC Driver voor SQL Server, dus controleer de systeemvereisten voordat je upgradet.

Een upgrade verandert native code die in PHP-processen wordt geladen. Een gemengde implementatie kan de vorige release blijven draaien, falen bij het opstarten van PHP, of verschillende driverversies beschikbaar stellen aan de CLI en webapplicatie. Inventariseer elke PHP-runtime en bewaar de vorige bestanden en configuraties totdat de verificatie is afgerond.

Kies het upgradepad

Huidige installatie Doelinstallatiepad Procedure
PIE PIE Voer PIE uit met hetzelfde PHP-uitvoerbare bestand of expliciet php-config, en verifieer vervolgens elke SAPI
Windows heeft ZIP uitgebracht Door Windows gemaakte ZIP Vervang beide DLL's met versienummer en werk beide configuratie-items tegelijk bij
Windows Released ZIP PIE Installeer beide PIE-pakketten, vervang DLL-vermeldingen met versienummer door PIE-vermeldingen en verwijder duplicaten
archief voor Linux of macOS PIE Installeer beide PIE-pakketten, vervang archiefbestandsnaam-entries door sqlsrv.so en pdo_sqlsrv.so, en behoud de PDO-laadvolgorde
Linux of macOS PIE Nieuwe PHP minor versie Installeer de nieuwe PHP-ontwikkeltools, bouw beide extensies voor die PHP-installatie en configureer elke SAPI afzonderlijk

Overschrijf de vorige binaries niet totdat je een rollback-kopie hebt. Upgrade niet slechts één extensie als de applicatie beide API's gebruikt.

Voordat u een upgrade uitvoert

  1. Noteer het PHP-uitvoerbare bestand, configuratiebestand, architectuur, thread-safety-modus en huidige driverversies.

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

  2. Maak een back-up van het php.ini bestand en eventuele extensie-specifieke .ini bestanden die sqlsrv of pdo_sqlsrv laden.

  3. Controleer de ondersteuningsmatrix voor de beoogde PHP-versie en het besturingssysteem.

  4. Bekijk de ODBC-compatibiliteitstabel in Systeemvereisten. Installeer een ondersteunde ODBC-versie vóór of tijdens de PHP-driver-upgrade wanneer de beoogde driverrelease dat vereist.

  5. Plan een herstart van elk proces dat PHP laadt, inclusief de webserver, PHP FastCGI Process Manager (PHP-FPM), wachtrijwerkers en langlopende commandoregelwerkers.

  6. Noteer een baseline van elke runtime:

    • De ExtensionVer die wordt getoond door php --ri sqlsrv en php --ri pdo_sqlsrv.
    • Het configuratiebestand en de map .ini zijn geladen en gescand.
    • De extensiedirectory en de bestandsnamen van actieve stuurprogramma's.
    • Een geslaagde applicatie-rooktest die elke API gebruikt waarvan jouw applicatie afhankelijk is.

  7. Bereid een rollback voor:

    • Houd de vorige PHP-runtime beschikbaar als je de PHP-minor versie verandert. Noteer het uitvoerbare bestand dat voor elke webserver en worker is geconfigureerd.
    • Bewaar kopieën van de vorige SQLSRV- en PDO_SQLSRV bestanden.
    • Bewaar kopieën van elk gewijzigd php.ini of extensie-specifiek .ini bestand.
    • Noteer de vorige ODBC-pakketversie als de upgrade deze verandert.
    • Definieer hoe u verkeer of workers kunt stoppen terwijl native extensiebestanden worden vervangen.

Upgrade in Windows met PIE

Gebruik de PHP Installer for Extensions (PIE) met het PHP-uitvoerbare bestand dat de applicatie bedient. Eerst download en verifieer PIE. Voordat je een van beide installatiecommando's uitvoert, leid je het applicatieverkeer om en stop je de webserver, FastCGI-processen en workers die deze PHP-installatie gebruiken. Voorkom dat ze automatisch opnieuw opstarten totdat zowel extensies als hun configuratie klaar zijn. Houd een aparte commandoregelsessie voor PIE.

Schakel de bestaande SQLSRV- en PDO_SQLSRV-extensie-entries in de CLI-configuratie die door PIE wordt gebruikt tijdelijk uit door ze uit te commentariëren. Anders kan het PHP-proces waarin PIE draait de oude DLL's geladen houden en vervanging voorkomen. Houd de vereiste extensies van PIE ingeschakeld.

Vanuit de map met pie.phar installeer je beide pakketten apart:

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

PIE installeert php_sqlsrv.dll en php_pdo_sqlsrv.dll. In elke actieve configuratie vervang ZIP-items met versie zoals extension=php_sqlsrv_85_ts_x64.dll en extension=php_pdo_sqlsrv_85_ts_x64.dll door:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

Schakel beide vermeldingen in en verwijder dubbele SQLSRV- en PDO_SQLSRV-items, zelfs als PIE meldt dat automatische inschakeling is geslaagd. Als de webserver een andere PHP-installatie gebruikt, herhaal dan de upgrade en configuratiewijzigingen voor die installatie.

Start elk PHP-proces opnieuw op en voer vervolgens php --ri sqlsrv en php --ri pdo_sqlsrv uit met het bijbehorende uitvoerbare bestand. Bevestig dat ExtensionVer de beoogde versie voor beide stuurprogramma’s rapporteert. Voor een webapplicatie, beperk de toegang tot diagnostische pagina's voordat een tijdelijke phpinfo() pagina wordt aangemaakt. Controleer beide waarden en verwijder dan de pagina.

Upgrade een Windows ZIP-installatie

  1. Download de Windows ZIP van de beoogde release vanaf de pagina Microsoft Drivers for PHP for SQL Server releases.

  2. Bevestig dat de nieuwe namen van de dynamic-link library (DLL) overeenkomen met de PHP-minorversie, architectuur en thread-safety-modus. Stop de PHP-webserver of workerprocessen voordat je bestanden vervangt.

  3. Vervang de bestanden php_sqlsrv_*.dll en php_pdo_sqlsrv_*.dll in de PHP-extensiemap. Behoud de bestaande extension= vermeldingen als de bestandsnamen nog overeenkomen. Anders, update ze samen.

  4. Installeer of upgrade de Microsoft ODBC-driver voor SQL Server als de doel-PHP-driver een nieuwere ondersteunde versie vereist.

  5. Herstart elk PHP-proces dat de vervangen DLL's gebruikt opnieuw. Een lopend proces houdt de oude native extensie geladen totdat deze afsluit.

Upgrade op Linux of macOS met PIE

  1. Volg de PIE-setup en platformvereisten als PIE niet geïnstalleerd is. Bevestig dat de PHP-ontwikkeltools en het ODBC-ontwikkelpakket zijn geïnstalleerd. In een interactieve sessie kan PIE via de platformpakketbeheerder vragen om ontbrekende buildtools te installeren. In een niet-interactieve sessie installeer je ze voordat je PIE uitvoert.

  2. Selecteer de PHP-installatie voordat je upgradet. Voor een geversioneerde installatie voeg je PIE's --with-php-config optie toe aan beide installatiecommando's. Gebruik bijvoorbeeld pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv wanneer /usr/bin/php-config8.4 het bedoelde configuratiehulpmiddel is. Pas dezelfde optie toe op microsoft/pdo_sqlsrv. Voor de geversioneerde uitvoerbare bestanden van Alpine gebruik je de installatiecommando's van Alpine.

  3. Leid het applicatieverkeer weg en stop de webserver, PHP-FPM processen en workers die deze PHP-installatie gebruiken. Voorkom dat ze automatisch opnieuw opstarten totdat zowel extensies als hun configuratie klaar zijn. Houd een aparte commandoregelsessie voor PIE.

    Schakel de bestaande SQLSRV- en PDO_SQLSRV-extensie-entries in de CLI-configuratie die door PIE wordt gebruikt tijdelijk uit door ze uit te commentariëren. Houd de vereiste extensies van PIE ingeschakeld.

  4. Werk beide pakketten apart bij. Deze commando's gebruiken de standaard PHP-installatie van PIE:

    pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

  5. Controleer elke actieve configuratie van de PHP-installatie die door jouw applicatie wordt gebruikt. Als een eerdere handmatige installatie archiefbestandsnamen zoals extension=SQLSRV_8.4_NTS.so en extension=PDO_SQLSRV_8.4_NTS.sogebruikt, vervang dan die vermeldingen door de door PIE geïnstalleerde bestandsnamen:

    extension=sqlsrv.so
extension=pdo_sqlsrv.so

    Activeer beide driververmeldingen opnieuw en verwijder duplicaten. Bewaar PDO_SQLSRV in een gescand configuratiebestand dat na PDO wordt geladen, zoals beschreven in Load the drivers on Linux en macOS. Herhaal deze configuratiewijziging voor de commandoregel-, PHP-FPM-, webserver- en workerconfiguraties die je applicatie gebruikt.

  6. Upgrade de Microsoft ODBC-driver voor SQL Server wanneer vereist door de doelrelease.

  7. Herstart elke CLI-worker, queue-worker, webserver en PHP-FPM-service die de geüpgradede PHP-installatie gebruiken.

Herstart en controleer

Het vervangen van een extensiebestand werkt een PHP-proces dat al de oude binary heeft geladen niet bij. Herstart de webserver, PHP-FPM en eventuele langlopende PHP-workers voordat je de upgrade verifieert.

  1. Controleer de runtime van de commandoregel:

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

    Op Linux of macOS vervang je het laatste commando door php -m | grep -E 'sqlsrv|pdo_sqlsrv'.

  2. Voor een webapplicatie, beperk de toegang tot diagnostische pagina's voordat een tijdelijke phpinfo() pagina wordt aangemaakt. Controleer het geladen configuratiebestand, de extensiemap en ExtensionVer voor beide drivers. Bevestig dat dat ExtensionVer de doelversie rapporteert en verwijder dan de pagina.

  3. Voer een bestaande applicatie-rooktest uit die zowel SQLSRV als PDO_SQLSRV gebruikt als je applicatie beide gebruikt. Laat de verbindingsconfiguratie ongewijzigd tijdens deze controle, zodat een upgradetest niet ook een niet-gerelateerde verbindingswijziging test.

Als een driver niet laadt, vergelijk dan de PHP minor-versie, architectuur, thread-safety-modus, extensiemap en ODBC-installatie met de waarden die vóór de upgrade zijn geregistreerd.

Controleer zowel API's als versies

Sla dit programma op als 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);

Voer het programma uit met het CLI-uitvoerbare bestand en, tijdelijk, via elke webruntime. Bevestig dat beide gerapporteerde versies overeenkomen met de release die je hebt geïnstalleerd. Verwijder de webkopie na verificatie.

Dit programma verifieert de PHP-extensielaag. Voer daarna de rooktest van de ongewijzigde applicatie uit om ODBC-laden, verbindingsopties, authenticatie, databasetoegang, teruggegeven PHP-types en opruimgedrag te verifiëren.

Controleer het gedrag van de database vóór en na de upgrade

Gebruik hetzelfde programma en dezelfde verbindingsinstellingen voor en na de upgrade. Het ongewijzigd houden van de test scheidt stuurprogrammawijzigingen van applicatie- of verbindingsconfiguratiewijzigingen.

Stel de omgevingsvariabelen SQL_SERVER_NAME, SQL_DATABASE, SQL_UID en SQL_PWD in voor een testaccount door prompts te beantwoorden. Voer de ruwe waarden in, zonder shell-quotes of drivercodering. Voeg geen inloggegevens toe in een commandoregel of opgenomen terminalsessie.

Voer in Windows PowerShell de servernaam en databasenaam in, en gebruik vervolgens het inloggegevensvenster of de prompt voor het testaccount:

$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

Gebruik Bash op Linux of macOS. Schakel command tracing uit voordat u eventuele waarden leest. De wachtwoordprompt toont je invoer niet:

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

De omgeving bevat het platte tekstwachtwoord zodat PHP het kan lezen. Gebruik deze variabelen alleen tijdens de testsessie, print ze niet uit en maak ze na het testen schoon.

Sla dit programma op als test-driver-upgrade.php. Houd de omgevingswaarden ongewijzigd. Het programma verdubbelt sluitaccolades en voegt buitenste beugels toe voordat de databasenaam, gebruikersnaam en wachtwoord aan het stuurprogramma worden doorgegeven. Deze codering behoudt letterlijke accolades en voorkomt dat puntkomma's verbindingsopties scheiden.

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

Voer het programma uit vóór de upgrade en sla de succesvolle output op. Voer het ongewijzigde bestand opnieuw uit nadat je elk PHP-proces hebt herstart:

php test-driver-upgrade.php

Beide uitvoeringen moeten opleveren:

SQLSRV query: 1
PDO_SQLSRV query: 1

Als de post-upgrade uitvoering mislukt, behoud dan de exacte SQLSTATE of uitzondering. Vergelijk vervolgens de fout met de basislijn, extensieversies, actieve configuratie, ODBC-versie en de status van het herstarten van het proces. Rol beide PHP-extensies tegelijk terug als je de mismatch binnen het deploymentvenster niet kunt corrigeren.

Na verificatie verwijder je het testbestand en wis je de tijdelijke omgevingsvariabelen. Voer in PowerShell het volgende uit:

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

Voer in Linux of macOS het volgende uit:

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

Draai een mislukte upgrade terug

  1. Stop de getroffen webservers, PHP-FPM-pools en langlopende workerprocessen.

  2. Als je de PHP-minorversie hebt veranderd, herstel dan de vorige PHP-runtime en wijs elke webserver en worker terug naar die installatie.

  3. Herstel beide eerdere driverbestanden. Herstel samen de vorige SQLSRV- en PDO_SQLSRV configuratie-items.

  4. Herstel het vorige ODBC-pakket alleen als de nieuwere versie de fout heeft veroorzaakt en het oudere pakket nog steeds wordt ondersteund door de PHP-driverversie die je hebt hersteld.

  5. Herstart de processen en voer de basisversiecontroles en applicatie-smoketests opnieuw uit.

  6. Houd de mislukte upgradelogs en de exacte PHP-opstart- of verbindingsfout bij. Ze helpen bepalen of de storing ligt bij het laden van PHP, de besturingssysteemloader, ODBC of de databaseverbinding.

Problemen met een upgrade oplossen

Symptom Waarschijnlijke oorzaak Corrigerende actie
PIE slaagt, maar ExtensionVer blijft ongewijzigd Een oude geversioneerde invoer laadt nog steeds het vorige bestand Vervang de oude post, verwijder duplicaten en start alle PHP-processen opnieuw
SQLSRV en PDO_SQLSRV rapporteren verschillende versies Slechts één extensie is vervangen of één SAPI heeft een verouderde configuratie Upgrade en configureer beide extensies samen in elke runtime
De CLI rapporteert de doelversie, maar de website doet dat niet De web-SAPI gebruikt een andere PHP-installatie of is niet opnieuw opgestart Vergelijk configuratie- en extensiemappen en start dan het juiste proces opnieuw
PHP-opstart meldt een architectuur- of symboolfout De extensie komt niet overeen met de PHP-build Herstel de vorige bestanden, bouw vervolgens bestanden opnieuw op of selecteer ze voor de juiste PHP-minorversie, architectuur en thread-veiligheidsmodus
Extensies laden maar verbindingen mislukken na een ODBC-wijziging ODBC-configuratie, certificaatgedrag, authenticatie of netwerktoegang is gewijzigd Leg de SQLSTATE en de native fout vast voordat je terugrolt of de verbindingsinstellingen verandert
Workerprocessen falen terwijl nieuwe webverzoeken slagen Langlopende workers behouden nog steeds de vorige extensie of configuratie Laat elk werkproces leeglopen en start het opnieuw

Verwante onderwerpen

  • Laatst bijgewerkt om