SQL Server용 PHP용 Microsoft 드라이버를 로드하세요

SQLSRV와 PDO_SQLSRV 드라이버는 PHP 확장입니다. PHP는 PHP 프로세스가 시작될 때 .ini 및 추가 php.ini 파일을 읽고 이를 로드합니다.

로딩은 설치와 별개입니다. 확장 프로그램을 복사하거나 빌드하면 파일이 디스크에 저장됩니다. PHP는 활성 구성에 올바른 항목이 포함되어 있고 PHP 프로세스가 재시작되기 전까지는 SQLSRV나 PDO_SQLSRV를 사용할 수 없습니다.

웹 진단 페이지 보호

임시 phpinfo() 페이지를 만들기 전에 웹 서버가 localhost의 요청이나 인증된 관리자만 허용하도록 설정하세요. 페이지를 삭제할 때까지 그 제한을 유지하세요. phpinfo() 환경 변수, 자격 증명, 서버 구성을 노출할 수 있습니다. 인증 후 즉시 페이지를 삭제하세요.

PHP 구성 범위 이해하기

각 PHP 서버 애플리케이션 프로그래밍 인터페이스(SAPI)는 서로 다른 실행 파일과 구성을 사용할 수 있습니다:

Runtime 일반적인 구성 원본 식별 방법
CLI(명령줄 인터페이스) php --ini에서 보고한 php.ini 및 스캔 디렉터리 정확히 해당 실행 파일로 실행하세요 php --ini
IIS FastCGI IIS FastCGI 애플리케이션에서 구성된 PHP 실행 파일 임시 phpinfo() 페이지를 사용하세요
Apache 모듈 Apache의 PHP 모듈 구성 phpinfo() 임시 페이지 사용
PHP-FPM FPM 실행 파일, 풀, php.ini 및 스캔 디렉터리 버전이 지정된 FPM 바이너리 -i를 실행하거나 임시 phpinfo() 페이지를 사용하세요
장시간 실행 워커 작업자를 시작한 실행 파일과 환경 작업자 서비스를 점검하고 변경 후 재시작하세요

CLI 구성을 변경해도 IIS, Apache 또는 PHP-FPM이 다른 PHP 설치 또는 스캔 디렉터리를 사용하는 경우에는 변경되지 않습니다.

PHP 구성 찾기

애플리케이션에서 사용하는 PHP 실행 파일로 다음 명령어를 실행하세요:

php --ini
php -i | findstr /I "PHP Version Thread Safety Architecture extension_dir"

리눅스나 macOS에서는 grep를 findstr로 대체하세요:

php -i | grep -E "PHP Version|Thread Safety|extension_dir"
file "$(php -r 'echo PHP_BINARY;')"

file 명령은 선택한 실행 파일의 아키텍처를 식별합니다. 범용 macOS 실행 파일의 경우 명시적 아키텍처 선택을 따르세요.

로드된 구성 파일 값과 추가 .ini 파일 검색 위치 값은 명령줄 프로세스에서 사용하는 구성을 식별합니다. 웹 서버나 PHP FastCGI 프로세스 관리자(PHP-FPM) 프로세스는 다른 PHP 실행 파일이나 구성 파일을 사용할 수 있습니다. 임시 phpinfo() 페이지를 사용해 해당 프로세스의 값을 식별하세요.

파일을 편집하기 전에 다음을 기록하세요:

  • PHP 실행 파일 경로와 버전.
  • 로드된 항목 php.ini.
  • 추가 스캔 디렉터리.ini
  • 확장 프로그램 디렉터리.
  • 스레드 세이프티 모드와 아키텍처.
  • 다시 시작해야 하는 모든 프로세스

변경한 각 설정 파일을 백업하세요.

Windows에서 드라이버를 로드하세요

PHP 확장 설치 프로그램(PIE)로 설치하는 경우, 먼저 PIE를 다운로드하고 검증하세요. pie.phar이(가) 포함된 디렉터리에서 드라이버를 로드해야 하는 PHP 실행 파일을 사용해 다음 명령어를 실행하세요:

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

PIE는 php_sqlsrv.dll 및 php_pdo_sqlsrv.dll을 설치합니다. PIE가 확장 기능을 자동으로 활성화하지 못한다면, 활성 상태인 php.ini에서 기존 SQLSRV 및 PDO_SQLSRV 항목을 제거한 후 다음을 추가하세요:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

각 운전자에 대해 항목은 하나만 사용하세요. 설정 변경 후 PHP 프로세스를 재시작하세요.

ZIP 설치의 경우, PHP 마이너 버전, 아키텍처, 스레드 세이프티 모드에 맞는 동적 링크 라이브러리(DLL)를 extension_dir 디렉터리에 복사합니다. PHP 8.5 x64 스레드 안전 런타임은 다음과 같은 파일명을 사용합니다:

php_sqlsrv_85_ts_x64.dll
php_pdo_sqlsrv_85_ts_x64.dll

PHP 프로세스에서 사용하는 php.ini에 두 파일 이름을 모두 추가하세요:

extension=php_sqlsrv_85_ts_x64.dll
extension=php_pdo_sqlsrv_85_ts_x64.dll

ts, x64, 및 85를 PHP 런타임 값으로 대체하세요. 스레드 안전과 비스레드 안전 파일, 32비트와 64비트 파일, 또는 다른 PHP 마이너 버전을 위해 만들어진 파일을 섞지 마세요.

Linux 및 macOS에 드라이버를 로드하세요

PIE를 사용해 드라이버를 설치하세요. 자세한 내용은 리눅스 및 macOS 설치 튜토리얼을 참고하세요. PIE는 확장 파일을 설치하고, 플랫폼의 PHP 구성 도구를 사용하거나 추가 php.ini 파일 또는 표준 extension=에 .ini 항목을 추가하여 이를 활성화하려고 시도합니다. PIE가 확장 기능을 활성화할 수 없다고 보고하면, 직접 항목을 추가하고 활성 구성을 확인하세요.

수동 설치를 위해서는 PHP 버전, 아키텍처, 스레드 세이프티 모드, 운영 체제 기본 라이브러리에 맞는 미리 구축 .so 된 파일을 선택하세요. 리눅스와 macOS의 사전 구축 요구사항을 확인하세요; 환경과 맞지 않으면 PIE를 사용하세요.

예를 들어, PHP 8.4 스레드 비안전 파일들은 SQLSRV_8.4_NTS.so 및 PDO_SQLSRV_8.4_NTS.so로 명명됩니다. 해당 항목을 php -i | grep extension_dir에서 반환한 디렉터리에 배치하세요. 이름을 sqlsrv.so 및 pdo_sqlsrv.so(으)로 바꿔 다음 항목을 사용하거나, 대신 항목에 정확한 패키지 파일 이름을 사용하세요. 이 섹션에서 설명하는 로드 순서에 따라 활성 PHP 구성에 항목들을 추가하세요:

extension=sqlsrv.so
extension=pdo_sqlsrv.so

PHP 데이터 객체(PDO)는 PDO_SQLSRV보다 먼저 로드되어야 합니다. PHP는 .ini를 읽은 후 추가 php.ini 파일을 알파벳 순서로 스캔합니다. 배포판이 스캔된 파일에서 pdo.so을 로드하는 경우, PDO_SQLSRV 항목을 나중에 스캔되는 파일(예: PDO가 10-pdo.ini를 사용하는 경우 30-pdo_sqlsrv.ini)에 넣으세요. 그럴 경우 PDO_SQLSRV 항목을 php.ini에 넣지 마세요.

확장 항목을 선택하세요

드라이버가 설치된 방식과 일치하는 항목을 사용하세요:

플랫폼과 방법 SQLSRV 항목 PDO_SQLSRV 항목
PIE 지원 Windows extension=php_sqlsrv.dll extension=php_pdo_sqlsrv.dll
Windows 압축 해제된 ZIP 정확한 버전 지정 DLL 이름, 예를 들어 extension=php_sqlsrv_85_ts_x64.dll 정확한 버전 지정 DLL 이름, 예를 들어 extension=php_pdo_sqlsrv_85_ts_x64.dll
PIE를 지원하는 Linux 또는 macOS extension=sqlsrv.so extension=pdo_sqlsrv.so
Linux 또는 macOS 압축 해제된 아카이브, 이름이 변경된 파일 extension=sqlsrv.so extension=pdo_sqlsrv.so
Linux 또는 macOS용 아카이브, 원본 파일 extension=SQLSRV_8.4_NTS.so와 같은 정확한 아카이브 파일 이름 정확한 아카이브 파일명, 예를 들어 extension=PDO_SQLSRV_8.4_NTS.so

같은 확장 프로그램에 대해 짧은 이름과 버전명을 모두 설정하지 마세요. PHP는 모듈이 이미 로드되었음을 보고할 수 있고, 업그레이드 후에도 이전 파일을 계속 로드할 수 있습니다.

드라이버를 로드하려면 PHP를 재시작하세요

확장 파일이나 설정 파일을 변경한 후 프로세스를 재시작하세요. 웹 서버, PHP-FPM, 큐 워커 및 드라이버를 로드하는 기타 장기 실행 PHP 프로세스를 재시작하세요.

SQLSRV와 PDO_SQLSRV 확장 기능은 각각 별도로 로드할 수 있지만, 애플리케이션이 두 드라이버를 모두 사용할 때는 두 가지 모두 설치하고 검증하세요. PDO는 많은 PHP 패키지에 내장되어 있습니다. 만약 PDO가 내장되어 있지 않다면, PDO_SQLSRV를 활성화하기 전에 PDO 확장 기능을 활성화하세요.

로드된 드라이버를 검증하세요

명령줄 런타임의 경우 다음을 실행하세요:

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

리눅스나 macOS에서는 다음을 사용하세요:

php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | grep -E "sqlsrv|pdo_sqlsrv"

웹 서버의 경우, <?php phpinfo(); ?>한 후 가 포함된 임시 페이지를 생성하세요. 로드된 구성 파일, extension_dir, 그리고 별도의 sqlsrv 및 pdo_sqlsrv 섹션을 확인하세요. 인증 후 페이지를 삭제하세요.

또한 PHP 수준 검사를 실행해서 검증 범위가 모듈 이름뿐만 아니라 두 API 모두를 포함하도록 하세요. 이 프로그램을 다음과 같이 verify-php-drivers.php저장하세요:

<?php
$checks = [
    'SQLSRV extension' => extension_loaded('sqlsrv'),
    'SQLSRV API' => function_exists('sqlsrv_connect'),
    'PDO_SQLSRV extension' => extension_loaded('pdo_sqlsrv'),
    'PDO_SQLSRV API' => class_exists('PDO')
        && in_array('sqlsrv', PDO::getAvailableDrivers(), true),
];

$failed = false;
foreach ($checks as $name => $passed) {
    echo $name . ': ' . ($passed ? 'loaded' : 'missing') . PHP_EOL;
    $failed = $failed || !$passed;
}

exit($failed ? 1 : 0);

애플리케이션이 사용하는 각 PHP 실행 파일로 프로그램을 실행하세요:

php verify-php-drivers.php

예상 출력:

SQLSRV extension: loaded
SQLSRV API: loaded
PDO_SQLSRV extension: loaded
PDO_SQLSRV API: loaded

웹 런타임의 경우, 파일을 일시적으로 문서 루트에 두고 브라우저에서 해당 파일을 요청하세요. 검증 후 삭제하세요. 이 프로그램은 데이터베이스 연결을 열거나 설정 값을 출력하지 않습니다.

CLI와 웹 런타임 검사를 마친 후 삭제하세요 verify-php-drivers.php .

드라이버 로드 문제 해결

증상 확인하게 함 정정 작업
Unable to load dynamic library 잘못된 파일명, extension_dirPHP 마이너 버전, 아키텍처, 또는 스레드 세이프티 모드 php -i를 선택한 드라이버 파일과 비교하고 임시로 절대 경로를 사용하여 경로 오류를 식별하세요
Windows The specified module could not be found 드라이버 DLL이나 그 종속성 중 하나를 사용할 수 없습니다 DLL이 extension_dir에 있는지 확인하고, 해당 Visual C++ 런타임을 설치한 뒤, 남아 있는 DLL 의존성을 점검하세요
undefined symbol 또는 리눅스나 macOS에서 공유 라이브러리 오류 확장 기능과 PHP 빌드의 불일치, 또는 ODBC 의존성 누락 의도한 php-config대로 다시 빌드한 후 보고된 누락된 라이브러리를 점검하세요
Module "sqlsrv" is already loaded 중복 항목 또는 스캔된 두 개의 파일 로드된 php.ini 및 스캔 디렉터리를 검색한 후 한 항목을 유지하세요
could not find driver PDO에서 PDO_SQLSRV가 로드되지 않았거나 PDO가 그 후에 로드됩니다 php --ri pdo_sqlsrv를 확인하고 PDO 뒤로 PDO_SQLSRV 항목을 이동하세요
CLI는 작동하지만 웹 요청이 실패합니다 다른 SAPI 구성 또는 다시 시작되지 않은 프로세스 CLI 및 phpinfo() 구성 값을 비교하고, 웹 설정을 수정한 후 웹 프로세스를 재시작하세요
업그레이드 후에도 오래된 ExtensionVer이 남아 있습니다 설정에는 여전히 이전 버전 파일 이름이 지정되어 있습니다 이전 항목을 선택한 메서드가 설치한 파일로 교체하고, 중복을 제거하며, 모든 PHP 프로세스를 재시작하세요

PHP는 확장 탐색과 로드 순서를 제어합니다. PIE 또는 수동 복사가 확장 파일을 제공합니다. 운영체제 로더는 네이티브 의존성을 해결합니다. 확장 프로그램이 로드된 후 Microsoft ODBC 드라이버가 데이터베이스 프로토콜을 처리합니다.

관련 콘텐츠

  • 에 마지막으로 업데이트됨