SQL Server용 PHP 드라이버를 업그레이드하세요

SQLSRV와 PDO_SQLSRV 함께 업그레이드하여 두 확장 모두 동일한 릴리스 계열을 사용하도록 하세요. PHP 드라이버는 Microsoft ODBC Driver for SQL Server를 사용하므로, 업그레이드 전에 시스템 요구사항을 확인하세요.

업그레이드는 PHP 프로세스에 로드된 네이티브 코드를 변경합니다. 혼합 배포는 이전 릴리스를 계속 실행하거나, PHP 시작 시 실패하거나, CLI 및 웹 애플리케이션에 서로 다른 드라이버 버전을 노출할 수 있습니다. 모든 PHP 런타임을 목록화하고, 검증이 끝날 때까지 이전 파일과 설정을 유지하세요.

업그레이드 경로를 선택하세요

현재 설치	대상 설치	Procedure
파이	파이	동일한 PHP 실행 파일이나 명시적 php-config로 PIE를 실행한 다음 모든 SAPI를 검증합니다
Windows에서 압축 해제한 ZIP	Windows에서 압축 해제된 ZIP	버전이 지정된 DLL 두 개 모두를 교체하고 두 구성 항목을 함께 업데이트하세요
Windows에서 릴리스된 ZIP	파이	두 PIE 패키지를 모두 설치하고, 버전이 있는 DLL 항목을 PIE 항목으로 교체하며, 중복 항목을 제거하세요
리눅스 또는 macOS용 릴리스 아카이브	파이	두 PIE 패키지를 모두 설치하고, 아카이브 파일명 항목을 sqlsrv.so 와 pdo_sqlsrv.so로 교체하며, PDO 로드 순서를 유지하세요
리눅스 또는 macOS PIE	새로운 PHP 마이너 버전	새로운 PHP 개발 도구를 설치하고, 해당 PHP 설치에 맞는 두 확장 기능을 모두 빌드한 뒤, 각 SAPI를 따로 설정하세요

롤백 복사본이 생기기 전까지는 이전 바이너리를 덮어쓰지 마세요. 애플리케이션이 두 API를 모두 사용할 때 하나의 확장 프로그램만 업그레이드하지 마세요.

업그레이드하기 전에

1. PHP 실행 파일, 구성 파일, 아키텍처, 스레드 세이프티 모드, 현재 드라이버 버전을 기록하세요.

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

2. .ini 파일과 pdo_sqlsrv 또는 php.ini를 로드하는 확장자별 sqlsrv 파일을 백업하세요.

3. 대상 PHP 버전과 운영체제의 지원 매트릭스를 확인하세요.

4. 시스템 요구사항의 ODBC 호환성 표를 확인해 보세요. 대상 드라이버 릴리스가 요구할 경우 PHP 드라이버 업그레이드 전이나 중에 지원되는 ODBC 버전을 설치하세요.

5. 웹 서버, PHP FastCGI 프로세스 관리자(PHP-FPM), 큐 작업자, 장기 실행 명령줄 작업 등 PHP를 로드하는 모든 프로세스의 재시작을 계획하세요.

6. 각 런타임의 기준선을 기록하세요:

   • php --ri pdo_sqlsrv 및 php --ri sqlsrv에 의해 표시된 ExtensionVer.
   • 로드된 구성 파일 및 스캔된 .ini 디렉터리.
   • 확장 디렉터리와 활성 드라이버 파일명.
   • 애플리케이션이 의존하는 각 API를 사용하는 성공한 애플리케이션 스모크 테스트입니다.

7. 롤백 준비하기:

   • PHP 마이너 버전을 변경할 때는 이전 PHP 런타임을 유지하세요. 각 웹 서버와 작업자별로 설정된 실행 파일을 기록하세요.
   • 이전 SQLSRV와 PDO_SQLSRV 파일 복사본을 보관하세요.
   • 변경된 php.ini 파일이나 확장자 전용 .ini 파일은 모두 복사본을 보관하세요.
   • 업그레이드로 인해 이전 ODBC 패키지 버전이 변경되면 기록해 두세요.
   • 네이티브 확장 파일이 교체되는 동안 트래픽이나 워커를 중지하는 방법을 정의하세요.

Windows에서 PIE로 업그레이드하기

애플리케이션을 실행하는 PHP 실행 파일과 함께 PHP 확장 설치 프로그램(PIE)을 사용하세요. 먼저, PIE를 다운로드하고 검증하세요. 설치 명령을 실행하기 전에 애플리케이션 트래픽을 다른 곳으로 우회하고 웹 서버, FastCGI 프로세스, 그리고 이 PHP 설치를 사용하는 작업자를 중지하세요. 확장 프로그램과 구성 모두 준비될 때까지 자동으로 재시작하지 못하게 하세요. 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을 설치합니다. 모든 활성 구성에서 extension=php_pdo_sqlsrv_85_ts_x64.dll 및 extension=php_sqlsrv_85_ts_x64.dll 같은 버전화된 ZIP 항목을 다음과 같이 교체하세요:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

두 항목을 모두 활성화하고, PIE가 자동 활성화 성공을 보고하더라도 중복된 SQLSRV와 PDO_SQLSRV 항목을 제거하세요. 웹 서버가 다른 PHP 설치를 사용한다면, 해당 설치에 대해 업그레이드와 설정 변경을 반복하세요.

각 PHP 프로세스를 재시작한 후, php --ri sqlsrv 및 php --ri pdo_sqlsrv을 해당 실행 파일로 실행하세요. 두 드라이버 모두 ExtensionVer 대상 버전을 보고하는지 확인하세요. 웹 애플리케이션의 경우, 임시 페이지를 만들기 전에 phpinfo()하세요. 두 값을 모두 확인한 후 페이지를 삭제하세요.

Windows ZIP 설치를 업그레이드

1. Microsoft Drivers for PHP for SQL Server 릴리스 페이지에서 대상 릴리스의 Windows ZIP을 다운로드하세요.

2. 새로운 동적 링크 라이브러리(DLL) 이름이 PHP 마이너 버전, 아키텍처, 스레드 세이프티 모드와 일치하는지 확인하세요. 파일을 교체하기 전에 PHP 웹 서버나 워커 프로세스를 중단하세요.

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-FPM 프로세스, 그리고 이 PHP 설치를 사용하는 작업자를 멈추세요. 확장 프로그램과 구성 모두 준비될 때까지 자동으로 재시작하지 못하게 하세요. PIE용으로 별도의 명령줄 세션을 유지하세요.

   PIE가 사용하는 CLI 구성에서 기존 SQLSRV와 PDO_SQLSRV 확장 항목을 임시로 주석 처리하세요. PIE의 필수 확장 기능을 계속 활성화하세요.

4. 두 패키지를 별도로 업그레이드하세요. 이 명령어들은 PIE의 기본 PHP 설치를 사용합니다:

   pie install microsoft/sqlsrv
   pie install microsoft/pdo_sqlsrv
   

5. 애플리케이션에서 사용하는 PHP 설치의 모든 활성 구성을 확인하세요. 이전 수동 설치에서 extension=PDO_SQLSRV_8.4_NTS.so 및 extension=SQLSRV_8.4_NTS.so 같은 아카이브 파일명을 사용했다면, 해당 항목들을 PIE에 설치된 파일명으로 교체하세요:

   extension=sqlsrv.so
   extension=pdo_sqlsrv.so
   

   두 드라이버 항목을 모두 다시 활성화하고 중복 항목을 제거하세요. Linux 및 macOS에서 드라이버 로드에 설명된 대로, PDO_SQLSRV를 PDO 이후에 로드되는 스캔된 설정 파일에 보관하세요. 이 설정 변경을 애플리케이션이 사용하는 명령줄, PHP-FPM, 웹 서버, 워커 구성에 대해 반복하세요.

6. 목표 릴리스에 따라 Microsoft ODBC 드라이버 for SQL Server를 업그레이드하세요.

7. 업그레이드된 PHP 설치 환경을 사용하는 각 CLI 작업자, 큐 작업자, 웹 서버, PHP-FPM 서비스를 재시작하세요.

재시작하고 확인하세요

확장 파일을 교체한다고 해서 이미 오래된 바이너리를 로드한 PHP 프로세스가 업데이트되지 않습니다. 업그레이드를 확인하기 전에 웹 서버, PHP-FPM, 그리고 오래 작동하는 PHP 작업자들을 재시작하세요.

1. 명령줄 런타임을 확인하세요:

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

   리눅스나 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 실행 파일과, 임시로 각 웹 런타임을 통해 프로그램을 실행하세요. 보고된 두 버전이 설치한 버전과 일치하는지 확인하세요. 검증 후 웹 사본을 삭제하세요.

이 프로그램은 PHP 확장 계층을 검증합니다. 변경 없는 애플리케이션 스모크 테스트를 실행하여 ODBC 로딩, 연결 옵션, 인증, 데이터베이스 접근, 반환된 PHP 타입, 정리 동작을 확인하세요.

업그레이드 전후로 데이터베이스 동작을 확인하세요

업그레이드 전후로 같은 프로그램과 연결 설정을 사용하세요. 테스트를 변경하지 않은 상태로 유지하면 드라이버 변경과 애플리케이션 또는 연결 설정 변경을 분리합니다.

프롬프트에 응답하여 테스트 계정의 SQL_DATABASE, SQL_UID, SQL_PWD, 및 SQL_SERVER_NAME 환경 변수를 설정하세요. 쉘 인용 표기나 드라이버 인코딩 없이 원시 값을 입력하세요. 명령줄이나 녹화된 터미널 세션에 자격증명을 포함하지 마세요.

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

리눅스나 맥OS에서는 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 런타임을 복원하고 각 웹 서버와 작업자를 해당 설치로 돌려주세요.

3. 이전 드라이버 파일 두 개를 모두 복원하세요. 이전 SQLSRV와 PDO_SQLSRV 구성 항목을 함께 복원하세요.

4. 이전 ODBC 패키지는 새 버전이 해당 실패의 원인인 경우이고, 복원한 PHP 드라이버 버전에서 여전히 지원되는 경우에만 복원하세요.

5. 프로세스를 재시작하고 기본 버전 검사와 애플리케이션 스모크 테스트를 다시 실행하세요.

6. 실패한 업그레이드 로그와 정확한 PHP 시작 또는 연결 오류를 보관하세요. 이들은 실패가 PHP 로딩, 운영 시스템 로더, ODBC, 또는 데이터베이스 연결 중 어느 것인지 식별하는 데 도움을 줍니다.

업그레이드 문제 해결

증상	가능한 원인	정정 작업
PIE는 성공하지만 ExtensionVer은 변경되지 않았습니다	버전 관리된 항목은 여전히 이전 파일을 불러옵니다	이전 항목을 교체하고, 중복 항목을 제거한 뒤 모든 PHP 프로세스를 재시작하세요
SQLSRV와 PDO_SQLSRV는 서로 다른 버전을 보고합니다	확장 기능이 하나만 교체되었거나 SAPI 구성이 오래된 상태였습니다	각 런타임마다 두 확장 프로그램을 함께 업그레이드하고 구성하세요
CLI는 대상 버전을 표시하지만 웹사이트는 그렇지 않습니다	웹 SAPI는 다른 PHP 설치를 사용하거나 재시작되지 않았습니다	구성 디렉터리와 확장 디렉터리를 비교한 후 올바른 프로세스를 다시 시작하세요
PHP 시작 시 아키텍처 또는 심볼 오류가 보고됨	확장 기능이 PHP 빌드와 일치하지 않습니다	이전 파일을 복원한 후, 올바른 PHP 마이너 버전, 아키텍처 및 스레드 세이프티 모드에 맞게 파일을 다시 빌드하거나 선택합니다
확장은 로드되지만 ODBC 변경 후에는 연결이 실패합니다	ODBC 설정, 인증서 동작, 인증 또는 네트워크 접근이 변경되었습니다	롤백하거나 연결 설정을 변경하기 전에 SQLSTATE와 네이티브 오류를 캡처하세요
워커 프로세스에서의 처리는 실패하지만 새로운 웹 요청은 성공합니다	장시간 실행되는 워커 프로세스는 여전히 이전 확장 프로그램이나 구성을 유지하고 있습니다	모든 작업자 프로세스를 드레인한 후 재시작하세요

관련 콘텐츠

• Windows에서 SQL Server용 PHP 드라이버를 설치하세요
• 리눅스 및 macOS 설치 튜토리얼
• 마이크로소프트 드라이버를 PHP용 SQL Server에 로드하기