Uppgradera PHP-drivrutinerna för SQL Server

Uppgradera SQLSRV och PDO_SQLSRV tillsammans så att båda tilläggen använder samma releasefamilj. PHP-drivrutinerna använder Microsoft ODBC-drivrutin för SQL Server, så kontrollera systemkraven innan du uppgraderar.

En uppgradering ändrar nativ kod som laddas in i PHP-processerna. En blandad driftsättning kan fortsätta köra föregående version, misslyckas vid PHP-start eller exponera olika drivrutinsversioner för CLI och webbapplikation. Inventera varje PHP-runtime och behåll tidigare filer och konfigurationer tills verifieringen är klar.

Välj uppgraderingsvägen

Nuvarande installation	Målinstallation	Procedure
PIE	PAJ	Kör PIE med samma PHP-exekverbara fil eller explicit `php-config`, och verifiera sedan varje SAPI
Windows extraherade ZIP	ZIP som släppts i Windows	Byt ut båda versionerade DLL:erna och uppdatera båda konfigurationsposterna samtidigt
Släppt ZIP-fil	PIE	Installera båda PIE-paketen, ersätt versionerade DLL-poster med PIE-poster och ta bort dubbletter
Linux- eller macOS-utgivet arkiv	PIE	Installera båda PIE-paketen, ersätt arkivfilnamnsposter med `sqlsrv.so` och `pdo_sqlsrv.so`, och bevara PDO-inläsningsordningen
Linux eller macOS PIE	Ny PHP-minorversion	Installera de nya PHP-utvecklingsverktygen, bygg båda tilläggen för den PHP-installationen och konfigurera varje SAPI separat

Skriv inte över de tidigare binärfilerna förrän du har en rollback-kopia. Uppgradera inte bara ett av tilläggen när applikationen använder båda API:erna.

Innan du uppgraderar

Registrera PHP-exekverbara filen, konfigurationsfilen, arkitekturen, trådsäkerhetsläget och aktuella drivrutinsversioner.
```
php --version
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv
```
Säkerhetskopiera php.ini filen och eventuella tilläggsspecifika .ini-filer som läser in sqlsrv eller pdo_sqlsrv.
Kontrollera supportmatrisen för den målinriktade PHP-versionen och operativsystemet.
Kontrollera ODBC:s kompatibilitetstabell under Systemkrav. Installera en stödd ODBC-version före eller under PHP-drivrutinsuppgraderingen när den aktuella drivrutinsversionen kräver det.
Planera en omstart av varje process som laddar PHP, inklusive webbservern, PHP FastCGI Process Manager (PHP-FPM), köarbetare och långvariga kommandoradsarbetare.
Spela in en baslinje från varje körning:
- Det ExtensionVer som visas av php --ri sqlsrv och php --ri pdo_sqlsrv.
- Läste in konfigurationsfilen och skannade .ini katalogen.
- Tilläggskatalogen och filnamnen på de aktiva drivrutinerna.
- Ett godkänt smoke test för applikationen som använder varje API som din applikation är beroende av.
Förbered en rollback:
- Behåll den tidigare PHP-runtimen tillgänglig om du ändrar PHP-minorversionen. Registrera den körbara filen konfigurerad för varje webbserver och workerprocess.
- Spara kopior av tidigare SQLSRV- och PDO_SQLSRV filer.
- Spara kopior av varje ändrad php.ini eller tilläggsspecifik .ini fil.
- Anteckna den tidigare ODBC-paketversionen om uppgraderingen ändrar den.
- Definiera hur begäranden eller arbetare ska stoppas medan nativer tilläggsfiler byts ut.

Uppgradera i Windows med PIE

Använd PHP Installer for Extensions (PIE) med den PHP-körbara filen som betjänar applikationen. Först, ladda ner och verifiera PIE. Innan du kör något av installationskommandona, dirigera bort applikationstrafiken och stoppa webbservern, FastCGI-processerna och arbetarna som använder denna PHP-installation. Förhindra att de startar om automatiskt förrän både tillägg och deras konfiguration är redo. Ha en separat kommandoradssession för PIE.

Kommentera tillfälligt ut befintliga SQLSRV- och PDO_SQLSRV-tilläggsposter i CLI-konfigurationen som används av PIE. Annars kan PHP-processen som kör PIE behålla de gamla DLL-filerna laddade och förhindra att DLL-filerna ersätts. Behåll PIE:s nödvändiga tillägg aktiverade.

Från katalogen som innehåller pie.phar, installera båda paketen separat:

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

PIE installerar php_sqlsrv.dll och php_pdo_sqlsrv.dll. I varje aktiv konfiguration, ersätt versionerade ZIP-poster som extension=php_sqlsrv_85_ts_x64.dll och extension=php_pdo_sqlsrv_85_ts_x64.dll med:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

Aktivera båda posterna och ta bort dubbletter av SQLSRV- och PDO_SQLSRV poster även om PIE rapporterar att automatisk aktivering lyckades. Om webbservern använder en annan PHP-installation, upprepa uppgraderingen och konfigurationsändringarna för den installationen.

Starta om varje PHP-process, kör php --ri sqlsrv sedan och php --ri pdo_sqlsrv med motsvarande exekverbar fil. Bekräfta att ExtensionVer rapporterar målversionen för båda drivrutinerna. För en webbapplikation, begränsa åtkomsten till diagnostiksidan innan du skapar en tillfällig phpinfo() sida. Verifiera båda värdena och ta sedan bort sidan.

Uppgradera en Windows ZIP-installation

Ladda ner målversionen av Windows ZIP från sidan Microsoft Drivers for PHP for SQL Server releases.
Bekräfta att de nya dynamiska länkbibliotekens (DLL) namn stämmer överens med PHP:s minorversion, arkitektur och trådsäkerhetsläge. Stoppa PHP-webbservern eller worker-processerna innan du byter filer.
Byt ut både php_sqlsrv_*.dll- och php_pdo_sqlsrv_*.dll-filerna i PHP-tilläggskatalogen. Behåll de befintliga extension= posterna om filnamnen fortfarande stämmer överens. Annars, uppdatera dem tillsammans.
Installera eller uppgradera Microsoft ODBC-drivrutinen för SQL Server om den avsedda PHP-drivrutinen kräver en nyare stödd version.
Starta om varje PHP-process som använder de utbytta DLL:erna. En körande process håller det gamla nativa tillägget laddat tills den avslutar.

Uppgradera på Linux eller macOS med PIE

Följ PIE-uppsättningen och plattformskraven om PIE inte är installerat. Kontrollera att PHP-utvecklingsverktygen och ODBC-utvecklingspaketet är installerade. I en interaktiv session kan PIE be om att installera saknade byggverktyg via plattformens pakethanterare. I en icke-interaktiv session, installera dem innan du kör PIE.
Välj PHP-installationen innan du uppgraderar. För en versionerad installation, lägg till PIE:s --with-php-config-alternativ till båda installationskommandona. Till exempel, använd pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv när det avsedda konfigurationsverktyget är /usr/bin/php-config8.4. Använd samma alternativ för microsoft/pdo_sqlsrv. För Alpines versionerade körbara filer, använd installationskommandona Alpine.
Avled applikationstrafiken och stoppa webbservern, PHP-FPM-processer och arbetare som använder denna PHP-installation. Förhindra att de startar om automatiskt förrän både tillägg och deras konfiguration är redo. Ha en separat kommandoradssession för PIE.

Kommentera tillfälligt ut befintliga SQLSRV- och PDO_SQLSRV-tilläggsposter i CLI-konfigurationen som används av PIE. Behåll PIE:s nödvändiga tillägg aktiverade.
Uppgradera båda paketen separat. Dessa kommandon använder PIE:s standardinstallation av PHP:
```
pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv
```
Kontrollera alla aktiva konfigurationer för PHP-installationen som används av din applikation. Om en tidigare manuell installation använder arkivfilnamn som extension=SQLSRV_8.4_NTS.so och extension=PDO_SQLSRV_8.4_NTS.so, ersätt dessa poster med de PIE-installerade filnamnen:
```
extension=sqlsrv.so
extension=pdo_sqlsrv.so
```
Aktivera båda drivrutinsposterna igen och ta bort dubbletter. Behåll PDO_SQLSRV i en skannad konfigurationsfil som laddas efter PDO, som beskrivs i Ladda drivrutinerna på Linux och macOS. Upprepa denna konfigurationsändring för kommandorads-, PHP-FPM-, webbserver- och arbetarkonfigurationer som din applikation använder.
Uppgradera Microsoft ODBC-drivrutinen för SQL Server när det krävs av målversionen.
Starta om varje CLI-arbetare, köarbetare, webbserver och PHP-FPM tjänst som använder den uppgraderade PHP-installationen.

Starta om och verifiera

Att ersätta en tilläggsfil uppdaterar inte en PHP-process som redan laddade den gamla binärfilen. Starta om webbservern, PHP-FPM och eventuella långvariga PHP-arbetare innan du verifierar uppgraderingen.

Verifiera kommandoradens körmiljö:
```
php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | findstr /I "sqlsrv pdo_sqlsrv"
```
På Linux eller macOS, ersätt det sista kommandot med php -m | grep -E 'sqlsrv|pdo_sqlsrv'.
För en webbapplikation, begränsa åtkomsten till diagnossidan innan du skapar en tillfällig phpinfo() sida. Verifiera den inlästa konfigurationsfilen, tilläggskatalogen och ExtensionVer för båda drivrutinerna. Bekräfta att ExtensionVer rapporterar målversionen, ta sedan bort sidan.
Kör ett smoketest för en befintlig applikation som testar både SQLSRV och PDO_SQLSRV om din applikation använder båda. Behåll anslutningskonfigurationen oförändrad under denna kontroll så att ett uppgraderingstest inte också testar en orelaterad anslutningsförändring.

Om en drivrutin inte laddar, jämför PHP-minorversionen, arkitekturen, trådsäkerhetsläget, tilläggskatalogen och ODBC-installationen med de värden som registrerats före uppgraderingen.

Verifiera både API:er och versioner

Spara detta program som 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);

Kör programmet med den körbara CLI-filen och, tillfälligt, i varje webbkörmiljö. Bekräfta att båda rapporterade versionerna stämmer överens med den version du installerade. Ta bort webbkopian efter verifiering.

Detta program verifierar PHP-tilläggslagret. Kör det oförändrade smoketestet för applikationen efteråt för att verifiera ODBC-laddning, anslutningsalternativ, autentisering, databasåtkomst, returnerade PHP-typer och rensningsbeteende.

Verifiera databasens beteende före och efter uppgraderingen

Använd samma program och anslutningsinställningar före och efter uppgraderingen. Att hålla testet oförändrat separerar drivrutinsändringar från applikations- eller anslutningskonfigurationsändringar.

Sätt miljövariablerna SQL_DATABASE, SQL_UID, SQL_PWD och SQL_SERVER_NAME för ett testkonto genom att svara på prompter. Ange råvärdena, utan citattecken i skalet eller drivrutinskodning. Inkludera inte inloggningsuppgifter i en kommandorad eller inspelad terminalsession.

På Windows PowerShell, ange servernamnet och databasnamnet, och använd sedan inloggningsdialogen eller prompten för testkontot:

$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

På Linux eller macOS, använd Bash. Inaktivera kommandospårning innan du läser några värden. Lösenordsprompten visar inte det du skriver:

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

Miljön innehåller klartextlösenordet så att PHP kan läsa det. Använd dessa variabler endast under testsessionen, skriv inte ut dem, och rensa dem efter testning.

Spara detta program som test-driver-upgrade.php. Behåll miljövärdena oförändrade. Programmet dubblerar avslutande klamrar och lägger till yttre klamrar innan databasnamnet, användarnamnet och lösenordet skickas till drivrutinen. Denna kodning bevarar bokstavliga klamrar och förhindrar semikolon från att separera anslutningsalternativ.

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

Kör programmet före uppgraderingen och spara utdata som genererades utan fel. Kör den oförändrade filen igen efter att ha startat om varje PHP-process:

php test-driver-upgrade.php

Båda körningarna bör ge:

SQLSRV query: 1
PDO_SQLSRV query: 1

Om post-upgrade-körningen misslyckas, behåll exakt SQLSTATE eller undantag. Jämför sedan orsaken till felet med baslinjen, tilläggsversioner, aktiv konfiguration, ODBC-version och processomstartsstatus. Rulla tillbaka båda PHP-tilläggen samtidigt när du inte kan rätta till mismatchen inom distributionsfönstret.

Efter verifiering, radera testfilen och rensa de tillfälliga miljövariablerna. Kör i 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

Kör i Linux eller macOS:

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

Rulla tillbaka en misslyckad uppgradering

Stoppa de berörda webbservrarna, PHP-FPM-poolerna och långkörande processerna.
Om du ändrade PHP-minorversionen, återställ den tidigare PHP-runtimen och peka varje webbserver och worker-process tillbaka till den installationen.
Återställ båda de tidigare drivrutinsfilerna. Återställ de tidigare SQLSRV- och PDO_SQLSRV konfigurationsposterna tillsammans.
Återställ det tidigare ODBC-paketet endast om den nyare versionen orsakade felet och det äldre paketet fortfarande stöds av PHP-drivrutinsversionen du återställde.
Starta om processerna och kör om basversionskontroller och smoketester för applikationen.
Behåll loggar över misslyckade uppgraderingar och det exakta PHP-start- eller anslutningsfelet. De hjälper till att identifiera om felet beror på PHP-laddning, operativsystemets laddare, ODBC eller databasanslutningen.

Felsöka en uppgradering

Symtom	Sannolik orsak	Korrigeringsåtgärder
PIE lyckas men `ExtensionVer` förblir oförändrad	En gammal versionshanterad post laddar fortfarande den föregående filen	Byt ut den gamla posten, ta bort dubbletter och starta om alla PHP-processer
SQLSRV och PDO_SQLSRV rapporterar olika versioner	Endast ett tillägg har bytts ut eller så har en SAPI en föråldrad konfiguration	Uppgradera och konfigurera båda tilläggen samtidigt i varje körmiljö
CLI rapporterar målversionen men webbplatsen gör det inte	Webb-SAPI:n använder en annan PHP-installation eller startades inte om	Jämför konfigurations- och tilläggskataloger, och starta sedan om rätt process
PHP-uppstart rapporterar ett arkitektur- eller symbolfel	Tillägget matchar inte PHP-bygget	Återställ de tidigare filerna, bygg sedan om eller välj filer för rätt PHP-minorversion, arkitektur och trådsäkerhetsläge
Tillägg laddas men anslutningar fallerar efter en ODBC-ändring	ODBC-konfiguration, certifikatbeteende, autentisering eller nätverksåtkomst har ändrats	Fånga SQLSTATE och det interna felet innan du rullar tillbaka eller ändrar anslutningsinställningar
Workerprocesser misslyckas medan nya webbförfrågningar lyckas	Långvariga workerprocesser behåller fortfarande det tidigare tillägget eller konfigurationen	Dränera och starta om varje arbetsprocess

Feedback

Var den här sidan till hjälp?

Uppdaterades senast 2026-11-05