Tingkatkan driver PHP untuk SQL Server

Tingkatkan SQLSRV dan PDO_SQLSRV bersama-sama agar kedua ekstensi menggunakan keluarga rilis yang sama. Driver PHP menggunakan Microsoft ODBC Driver for SQL Server, jadi periksa persyaratan sistem sebelum melakukan pembaruan.

Upgrade mengubah kode asli yang dimuat dalam proses PHP. Penyebaran campuran dapat terus menjalankan rilis sebelumnya, gagal saat startup PHP, atau mengekspos versi driver yang berbeda ke CLI dan aplikasi web. Inventarisasi setiap runtime PHP dan pertahankan file serta konfigurasi sebelumnya hingga verifikasi selesai.

Pilih jalur peningkatan

Instalasi saat ini Instalasi target Procedure
PIE PIE Jalankan PIE dengan executable PHP yang sama atau php-config yang eksplisit, lalu verifikasi setiap SAPI
Windows ZIP yang diekstrak Windows merilis ZIP Ganti kedua DLL berversi dan perbarui kedua entri konfigurasi secara bersamaan
ZIP yang diekstrak Windows PIE Instal kedua paket PIE, ganti entri DLL versi dengan entri PIE, dan hapus duplikat
Arsip rilis untuk Linux atau macOS PIE Instal kedua paket PIE, ganti entri nama file arsip dengan sqlsrv.so dan pdo_sqlsrv.so, dan pertahankan urutan muat PDO
Linux atau macOS PIE Versi minor PHP baru Instal alat pengembangan PHP baru, bangun kedua ekstensi untuk instalasi PHP tersebut, dan konfigurasikan setiap SAPI secara terpisah

Jangan menimpa biner sebelumnya sampai Anda memiliki salinan rollback. Jangan hanya upgrade satu ekstensi jika aplikasi menggunakan kedua API.

Sebelum Anda memutakhirkan

  1. Catat file eksekusi PHP, file konfigurasi, arsitektur, mode keamanan thread, dan versi driver saat ini.

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

  2. Cadangkan file php.ini dan file .ini khusus ekstensi yang memuat sqlsrv atau pdo_sqlsrv.

  3. Periksa matriks dukungan untuk versi PHP target dan sistem operasi.

  4. Periksa tabel kompatibilitas ODBC di Persyaratan Sistem. Instal versi ODBC yang didukung sebelum atau selama upgrade driver PHP ketika rilis driver target memerlukannya.

  5. Rencanakan restart setiap proses yang memuat PHP, termasuk server web, PHP FastCGI Process Manager (PHP-FPM), pekerja antrean, dan pekerja baris perintah yang sudah lama berjalan.

  6. Catat baseline dari setiap runtime:

    • ExtensionVer ditampilkan oleh php --ri sqlsrv dan php --ri pdo_sqlsrv.
    • File konfigurasi dimuat dan direktori .ini dipindai.
    • Direktori ekstensi dan nama file driver aktif.
    • Smoke test aplikasi yang lolos menggunakan setiap API yang bergantung pada aplikasi Anda.

  7. Siapkan rollback:

    • Pertahankan runtime PHP sebelumnya tetap tersedia jika Anda mengubah versi minor PHP. Catat executable yang dikonfigurasi untuk setiap server web dan worker.
    • Simpan salinan file SQLSRV dan PDO_SQLSRV versi sebelumnya.
    • Simpan salinan setiap file yang diubah php.ini atau file khusus ekstensi .ini.
    • Catat versi paket ODBC sebelumnya jika pemutakhiran mengubahnya.
    • Tentukan cara menghentikan trafik atau proses worker saat file ekstensi native diganti.

Upgrade di Windows dengan PIE

Gunakan PHP Installer for Extensions (PIE) dengan file executable PHP yang melayani aplikasi. Pertama, unduh dan verifikasi PIE. Sebelum menjalankan salah satu perintah instalasi, alihkan trafik aplikasi dan hentikan server web, proses FastCGI, dan pekerja yang menggunakan instalasi PHP ini. Cegah mereka memulai ulang secara otomatis sampai kedua ekstensi dan konfigurasinya siap. Simpan sesi baris perintah terpisah untuk PIE.

Untuk sementara, komentari entri ekstensi SQLSRV dan PDO_SQLSRV yang ada dalam konfigurasi CLI yang digunakan oleh PIE. Jika tidak, proses PHP yang berjalan di PIE dapat menjaga DLL lama tetap termuat dan mencegah penggantian. Biarkan ekstensi prasyarat PIE tetap aktif.

Dari direktori yang berisi pie.phar, instal kedua paket secara terpisah:

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

PIE menginstal php_sqlsrv.dll dan php_pdo_sqlsrv.dll. Di setiap konfigurasi aktif, ganti entri ZIP berversi seperti extension=php_sqlsrv_85_ts_x64.dll dan extension=php_pdo_sqlsrv_85_ts_x64.dll dengan:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

Aktifkan kedua entri, dan hapus entri SQLSRV dan PDO_SQLSRV duplikat meskipun PIE melaporkan bahwa pengaktifan otomatis berhasil. Jika server web menggunakan instalasi PHP yang berbeda, ulangi upgrade dan perubahan konfigurasi untuk instalasi tersebut.

Mulai ulang setiap proses PHP, lalu jalankan php --ri sqlsrv dan php --ri pdo_sqlsrv dengan executable yang sesuai. Konfirmasi bahwa ExtensionVer melaporkan versi target untuk kedua driver tersebut. Untuk aplikasi web, batasi akses halaman diagnostik sebelum membuat halaman phpinfo() sementara. Verifikasi kedua nilai, lalu hapus halaman.

Memutakhirkan instalasi ZIP Windows

  1. Unduh Windows ZIP untuk rilis target dari halaman rilis Microsoft Drivers for PHP for SQL Server.

  2. Konfirmasi nama dynamic-link library (DLL) baru sesuai dengan versi minor PHP, arsitektur, dan mode keamanan thread. Hentikan server web PHP atau proses worker sebelum mengganti file.

  3. Ganti kedua php_sqlsrv_*.dll file dan php_pdo_sqlsrv_*.dll file di direktori ekstensi PHP. Pertahankan entri yang ada extension= jika nama file masih cocok. Kalau tidak, perbarui keduanya sekaligus.

  4. Instal atau tingkatkan Microsoft ODBC Driver for SQL Server jika driver PHP target memerlukan versi yang lebih baru dan didukung.

  5. Mulai ulang setiap proses PHP yang menggunakan DLL yang telah diganti. Proses yang berjalan menjaga ekstensi native lama tetap dimuat hingga proses tersebut berhenti.

Upgrade di Linux atau macOS dengan PIE

  1. Ikuti pengaturan PIE dan prasyarat platform jika PIE belum terpasang. Pastikan alat pengembangan PHP dan paket pengembangan ODBC sudah terpasang. Dalam sesi interaktif, PIE dapat menampilkan prompt untuk menginstal alat build yang hilang melalui pengelola paket platform. Dalam sesi non-interaktif, instal semuanya sebelum menjalankan PIE.

  2. Pilih instalasi PHP sebelum melakukan pembaruan. Untuk instalasi berversi, tambahkan opsi PIE --with-php-config ke kedua perintah instalasi. Misalnya, gunakan pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv ketika alat konfigurasi yang dimaksud adalah /usr/bin/php-config8.4. Terapkan opsi yang sama ke microsoft/pdo_sqlsrv. Untuk executable versi Alpine, gunakan perintah instalasi Alpine.

  3. Mengalihkan lalu lintas aplikasi dan menghentikan server web, proses PHP-FPM, serta pekerja yang menggunakan instalasi PHP ini. Cegah mereka memulai ulang secara otomatis sampai kedua ekstensi dan konfigurasinya siap. Pertahankan sesi baris perintah terpisah untuk PIE.

    Untuk sementara, komentari entri ekstensi SQLSRV dan PDO_SQLSRV yang ada dalam konfigurasi CLI yang digunakan oleh PIE. Pastikan ekstensi prasyarat PIE tetap aktif.

  4. Upgrade kedua paket secara terpisah. Perintah-perintah ini menggunakan instalasi PHP default PIE:

    pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

  5. Periksa setiap konfigurasi aktif untuk instalasi PHP yang digunakan oleh aplikasi Anda. Jika instalasi manual sebelumnya menggunakan nama file arsip seperti extension=SQLSRV_8.4_NTS.so dan extension=PDO_SQLSRV_8.4_NTS.so, ganti entri tersebut dengan nama file yang diinstal PIE:

    extension=sqlsrv.so
extension=pdo_sqlsrv.so

    Aktifkan kembali kedua entri driver, dan hapus duplikatnya. Simpan PDO_SQLSRV dalam file konfigurasi yang dipindai yang dimuat setelah PDO, seperti yang dijelaskan dalam Memuat driver di Linux dan macOS. Ulangi perubahan konfigurasi ini untuk konfigurasi baris perintah, PHP-FPM, server web, dan worker yang digunakan aplikasi Anda.

  6. Tingkatkan Driver Microsoft ODBC untuk SQL Server saat diperlukan oleh rilis target.

  7. Restart setiap pekerja CLI, pekerja antrean, server web, dan layanan PHP-FPM yang menggunakan instalasi PHP yang telah ditingkatkan.

Mulai ulang dan verifikasi

Mengganti file ekstensi tidak memperbarui proses PHP yang sudah memuat biner lama. Restart web server, PHP-FPM, dan worker PHP yang berjalan lama sebelum memverifikasi upgrade.

  1. Verifikasi runtime baris perintah:

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

    Di Linux atau macOS, ganti perintah terakhir dengan php -m | grep -E 'sqlsrv|pdo_sqlsrv'.

  2. Untuk aplikasi web, batasi akses ke halaman diagnostik sebelum membuat phpinfo() halaman diagnostik sementara. Verifikasi file konfigurasi yang dimuat, direktori ekstensi, dan ExtensionVer untuk kedua driver. Konfirmasi bahwa ExtensionVer melaporkan versi target, lalu hapus halaman.

  3. Jalankan tes asap aplikasi yang sudah ada yang menguji baik SQLSRV maupun PDO_SQLSRV jika aplikasi Anda menggunakan keduanya. Jaga konfigurasi koneksi tetap tidak berubah selama pemeriksaan ini agar uji upgrade tidak juga menguji perubahan koneksi yang tidak terkait.

Jika driver gagal dimuat, bandingkan versi minor PHP, arsitektur, mode keselamatan thread, direktori ekstensi, dan instalasi ODBC dengan nilai yang tercatat sebelum upgrade.

Verifikasi baik API maupun versi

Simpan program ini sebagai 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);

Jalankan program dengan executable CLI dan, sementara, di setiap web runtime. Pastikan kedua versi yang dilaporkan sesuai dengan rilis yang Anda pasang. Hapus salinan web setelah verifikasi.

Program ini memverifikasi lapisan ekstensi PHP. Jalankan smoke test aplikasi yang tidak berubah setelahnya untuk memverifikasi pemuatan ODBC, opsi koneksi, autentikasi, akses database, tipe PHP yang dikembalikan, dan perilaku pembersihan.

Verifikasi perilaku basis data sebelum dan sesudah peningkatan

Gunakan program dan pengaturan koneksi yang sama sebelum dan sesudah pembaruan. Membiarkan pengujian tetap sama memisahkan perubahan driver dari perubahan konfigurasi aplikasi atau koneksi.

Atur SQL_SERVER_NAMEvariabel , SQL_DATABASE, SQL_UID, dan SQL_PWD lingkungan untuk akun uji dengan menjawab prompt. Masukkan nilai mentah, tanpa tanda kutip shell atau pengkodean driver. Jangan sertakan kredensial dalam baris perintah atau sesi terminal yang direkam.

Di Windows PowerShell, masukkan nama server dan nama database, lalu gunakan dialog kredensial atau prompt untuk akun pengujian:

$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

Di Linux atau macOS, gunakan Bash. Nonaktifkan pelacakan perintah sebelum membaca nilai apa pun. Prompt kata sandi tidak menampilkan karakter yang Anda ketik:

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

Lingkungan berisi kata sandi dalam teks biasa sehingga PHP dapat membacanya. Gunakan variabel ini hanya dalam sesi pengujian, jangan cetak variabel ini, dan hapus variabel ini setelah pengujian.

Simpan program ini sebagai test-driver-upgrade.php. Pertahankan nilai lingkungan tetap tidak berubah. Program ini menggandakan kurawal penutup dan menambahkan kurawal luar sebelum mengirimkan nama database, nama pengguna, dan kata sandi ke driver. Pengkodean ini mempertahankan kurung kurawal literal dan mencegah titik koma memisahkan opsi koneksi.

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

Jalankan program sebelum upgrade dan simpan output yang berhasil. Jalankan file yang sama lagi setelah memulai ulang setiap proses PHP:

php test-driver-upgrade.php

Kedua rangkaian tersebut harus menghasilkan:

SQLSRV query: 1
PDO_SQLSRV query: 1

Jika run pasca-upgrade gagal, pertahankan SQLSTATE atau pengecualian yang persis. Kemudian bandingkan kegagalan dengan baseline, versi ekstensi, konfigurasi aktif, versi ODBC, dan status restart proses. Kembalikan kedua ekstensi PHP tersebut ke versi sebelumnya secara bersamaan jika Anda tidak dapat memperbaiki ketidaksesuaian dalam jendela deployment.

Setelah verifikasi, hapus file uji dan hapus variabel lingkungan sementara. Pada PowerShell, jalankan:

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

Di Linux atau macOS, jalankan:

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

Batalkan peningkatan yang gagal

  1. Hentikan server web yang terdampak, pool PHP-FPM, dan proses worker yang berjalan lama.

  2. Jika Anda mengubah versi minor PHP, pulihkan runtime PHP sebelumnya dan arahkan setiap server web serta pekerja kembali ke instalasi tersebut.

  3. Pulihkan kedua file driver sebelumnya. Pulihkan entri konfigurasi SQLSRV dan PDO_SQLSRV sebelumnya secara bersamaan.

  4. Pulihkan paket ODBC sebelumnya hanya jika versi yang lebih baru menyebabkan kegagalan dan paket lama tetap didukung oleh versi driver PHP yang Anda pulihkan.

  5. Mulai ulang proses dan jalankan ulang pemeriksaan versi dasar serta uji smoke test aplikasi.

  6. Simpan log pembaruan yang gagal dan pesan galat startup atau koneksi PHP yang persis. Mereka membantu mengidentifikasi apakah kegagalan tersebut termasuk dalam pemuatan PHP, loader sistem operasi, ODBC, atau koneksi database.

Pemecahan masalah peningkatan

Gejala Kemungkinan penyebabnya Tindakan korektif
PIE berhasil tetapi ExtensionVer tidak berubah Entri berversi lama masih memuat file sebelumnya Ganti entri lama, hapus duplikat, dan restart semua proses PHP
SQLSRV dan PDO_SQLSRV melaporkan versi yang berbeda Hanya satu ekstensi yang diganti atau satu SAPI memiliki konfigurasi basi Tingkatkan dan konfigurasikan kedua ekstensi tersebut bersama-sama di setiap runtime
CLI melaporkan versi target tetapi situs web tidak Web SAPI menggunakan instalasi PHP lain atau tidak dimulai ulang Bandingkan direktori konfigurasi dan ekstensi, lalu restart proses yang tepat
Startup PHP melaporkan kesalahan arsitektur atau simbol Ekstensi ini tidak cocok dengan build PHP Pulihkan file sebelumnya, lalu bangun ulang atau pilih file untuk versi minor PHP, arsitektur, dan mode thread-safe yang benar
Ekstensi dimuat tetapi koneksi gagal setelah perubahan ODBC Konfigurasi ODBC, perilaku sertifikat, autentikasi, atau akses jaringan berubah Tangkap SQLSTATE dan kesalahan native sebelum melakukan rollback atau mengubah pengaturan koneksi
Proses pekerja gagal sementara permintaan web baru berhasil Pekerja yang berjalan lama masih memegang ekstensi atau konfigurasi sebelumnya Mengosongkan antrean dan memulai ulang setiap proses pekerja

Konten terkait

  • Terakhir diperbarui pada