Microsoft Drivers for PHP for SQL Server에 대한 시스템 요구 사항

PHP 드라이버 다운로드

이 글에서는 SQLSRV 또는 PDO_SQLSRV 드라이버를 사용하여 SQL Server 또는 Azure SQL Database 데이터를 접근하기 위해 시스템에 설치해야 하는 구성 요소를 나열합니다.

PHP 드라이버의 지원 수명 주기와 요구사항에 대한 자세한 정보는 지원 매트릭스를 참조하세요. 각 릴리스의 SQLSRV와 PDO_SQLSRV 드라이버는 동일한 PHP, 운영체제, 아키텍처, 스레드 세이프티, ODBC 요구사항을 가지고 있습니다.

드라이버 스택이 어떻게 맞물리는지

PHP 애플리케이션은 데이터베이스 서버에 직접 연결되지 않습니다. 각 층은 그 옆 층과 호환되어야 합니다:

계층	사용자가 선택하거나 구성하는 항목	불일치의 예
Application	SQLSRV 함수 또는 PDO_SQLSRV 클래스 및 속성	정의되지 않은 함수, 사용할 수 없는 PDO 드라이버, 또는 애플리케이션 수준의 오류
PHP 확장	PHP 마이너 버전, 아키텍처 및 스레드 안전 모드에 맞게 빌드된 SQLSRV 및 PDO_SQLSRV 파일	PHP 시작 경고, 모듈 로드 실패, 프로세스 크래시
PHP 런타임	명령줄 인터페이스(CLI), Apache 모듈, PHP-FPM, 또는 IIS FastCGI 구성	CLI는 드라이버를 로드하지만 웹 애플리케이션은 그렇지 않습니다
Microsoft ODBC 드라이버	선택한 PHP 드라이버 릴리스에서 지원하는 버전	연결 실패 또는 누락된 ODBC 라이브러리
운영 체제	필요한 런타임 및 빌드 패키지를 포함한 지원되는 릴리스 및 아키텍처	호환되는 패키지, 해결되지 않은 공유 라이브러리 또는 소스 빌드 실패가 없음
데이터베이스 제품	지원되는 SQL Server 또는 Azure SQL 대상	연결 설정 후 서버 버전 또는 기능별 오류

SQLSRV와 PDO_SQLSRV는 동일한 ODBC 드라이버 위에서 서로 다른 PHP API를 제공합니다. 애플리케이션이 두 API를 모두 사용할 때 두 API를 모두 설치하세요. 한 확장 프로그램을 설치한다고 해서 다른 확장 프로그램이 자동으로 설치되거나 활성화되는 것은 아닙니다.

API	프로그래밍 모델	설치별 확인
SQLSRV	절차적 sqlsrv_* 함수와 SQLSRV 상수	extension_loaded('sqlsrv') 및 function_exists('sqlsrv_connect')
PDO_SQLSRV	PHP 데이터 객체(PDO) 클래스, 속성 및 예외	extension_loaded('pdo_sqlsrv'), sqlsrv 및 PDO::getAvailableDrivers()

확장 프로그램은 독립적으로 설치할 수 있습니다. PDO_SQLSRV 또한 PDO_SQLSRV보다 먼저 PDO를 로드해야 합니다.

호환 가능한 집합을 선택하세요

드라이버를 다운로드하거나 빌드하기 전에 다음 점검을 완료하세요:

1. 애플리케이션을 제공하는 모든 PHP 런타임을 식별하세요. 예약된 작업, 명령줄 작업자, IIS 사이트, Apache 모듈, PHP-FPM 풀은 서로 다른 PHP 실행 파일과 구성 파일을 사용할 수 있습니다.

2. 각 PHP 실행 파일마다 다음 명령어를 실행하세요:

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

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

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

   file 명령은 실행 파일의 아키텍처를 보고합니다. 만약 보편적인 macOS 실행 파일로 식별되면, 의도된 아키텍처(예: arch -arm64 php --version 또는 arch -x86_64 php --version)를 명시적으로 선택하세요. 확장을 빌드, 로딩, 테스트할 때 동일한 아키텍처 선택을 사용하세요.

3. PHP 마이너 버전, 운영체제, 데이터베이스 대상 버전을 지원하는 PHP 드라이버 릴리스를 선택하세요.

4. 이 글의 호환성 표에서 지원되는 Microsoft ODBC 드라이버 버전을 선택하세요.

5. 확장 파일 또는 PIE 빌드를 PHP 아키텍처와 스레드 세이프티 모드에 맞추세요. 이 모든 값이 일치하지 않는 한 다른 PHP 설치에서 확장 프로그램을 복사하지 마세요.

6. CLI와 웹 서버 런타임을 별도로 구성하고 검증하세요. 성공적인 php -m 명령어는 CLI 런타임이 확장 기능을 로드했음을 증명할 뿐입니다.

PHP

PHP 웹사이트에서 PHP 바이너리를 다운로드하세요. PHP 버전 지원에 명시된 PHP 버전을 선택하세요.

• PHP 버전과 일치하는 드라이버 파일을 활성화하세요. 파일 이름은 드라이버 버전을 참조하세요. PHP용 SQL Server용 Microsoft Drivers 다운로드에서 파일을 다운로드하세요. 구성 지침은 SQL Server용 PHP용 Microsoft 드라이버 설치를 참조하세요.

• PHP와 애플리케이션 프레임워크가 지원하는 웹 서버와 PHP 통합 방식을 선택하세요. PHP 설치 문서와 프레임워크의 배포 지침을 따라 웹 서버가 PHP를 실행하도록 구성하세요. 확장 로딩은 CLI와 별도로 웹 서버 런타임에서 검증하세요.

스레드 안전성과 아키텍처

PHP 빌드와 확장 파일의 두 값이 서로 일치해야 합니다.

PHP 값	필수 드라이버 선택
Thread Safety => enabled	스레드 안전 (ts 또는 TS) 드라이버 파일
Thread Safety => disabled	스레드로부터 안전하지 않은 (nts 또는 NTS) 드라이버 파일
Architecture => x64	64비트 드라이버 파일 및 64비트 ODBC 구성 요소
Architecture => x86	32비트 Windows 드라이버 파일 및 32비트 ODBC 구성 요소

CLI는 스레드 안전 또는 비스레드 안전 PHP 빌드에서 사용할 수 있습니다. 모든 CLI 빌드가 스레드 안전하지 않다고 가정하지 말고, 보고된 값에 따라 확장을 선택하세요.

ODBC 드라이버

PHP가 실행되는 컴퓨터에 지원되는 Microsoft ODBC Driver for SQL Server를 설치하세요. SQL Server용 ODBC 드라이버 다운로드에서 드라이버를 다운로드하세요.

64비트 버전의 Windows에서 Windows 버전의 드라이버를 다운로드하는 경우 ODBC 64비트 설치 프로그램은 32비트 및 64비트 ODBC 드라이버를 모두 설치합니다. 32비트 버전의 Windows를 사용하는 경우 ODBC x86 설치 관리자를 사용합니다. 비 Windows 플랫폼에서는 64비트 버전의 드라이버만 사용할 수 있습니다.

표에는 업그레이드 계획을 위한 과거 조합이 포함되어 있습니다. 새 설치를 위해 현재 PHP 드라이버 릴리스와 해당 릴리스에 명시된 ODBC 버전을 사용하세요. 구버전 버전과의 호환성이 지원 수명 주기를 연장하지는 않습니다. PHP 드라이버 지원 수명주기와 지원되는 PHP 버전 모두를 확인하세요.

빈 셀이라고 해서 PHP 드라이버가 반드시 그 ODBC 버전을 거부한다는 뜻은 아닙니다. 개별 기능은 기본 조합보다 더 새로운 ODBC 버전이 필요할 수 있습니다.

PHP 드라이버 버전 → ↓ ODBC 드라이버 버전	5.13	5.12	5.11	5.10	5.9	5.8	5.6	5.3	5.2	4.3	4.0	3.2
ODBC 드라이버 18	예	예	예	예
ODBC 드라이버 17	예	예	예	예	예	예	예	예	예
ODBC 드라이버 13.1		예	예	예	예	예	예	예	예	예	예
ODBC 드라이버 13											예
ODBC 드라이버 11						예	예	예	예	예	예	예

SQLSRV 드라이버를 사용하는 경우 sqlsrv_client_info는 Microsoft Drivers for PHP for SQL Server가 사용하는 SQL Server Microsoft ODBC Driver for SQL Server 버전에 대한 정보를 반환합니다. PDO_SQLSRV 드라이버를 사용하는 경우 PDO::getAttribute를 사용해서 버전을 검색할 수 있습니다.

SQL Server

지원되는 SQL Server 버전에 대해서는 지원되는 SQL Server 버전을(를) 참조하세요.

SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, Microsoft Fabric의 SQL 데이터베이스, Microsoft Fabric의 Warehouse에 대한 타겟 지원을 별도로 평가하세요. 설치 요구사항은 클라이언트 측 요구사항이며, 모든 인증 방법, 연결 옵션, Transact-SQL(T-SQL) 기능 또는 데이터 유형을 모든 대상 시스템에서 사용할 수 있음을 의미하지는 않습니다. 애플리케이션에서 사용하는 시나리오에 대해 지원 매트릭스와 대상 제품의 문서를 활용하세요.

운영 체제

지원되는 운영체제에 대해서는 지원 운영체제를 참조하세요.

드라이버 버전

Microsoft PHP for SQL Server 드라이버의 각 릴리스는 SQLSRV와 PDO_SQLSRV 드라이버 파일을 스레드 안전 및 비스레드 안전 변형으로 포함한다. Windows에서는 각 변형 버전이 32비트 및 64비트 PHP용으로도 빌드됩니다. 드라이버 파일을 PHP 버전, 스레드 세이프티 모드, 아키텍처에 맞게 맞추세요. 드라이버 파일을 다운로드한 후 활성화하려면 SQL Server용 PHP용 Microsoft 드라이버 로딩을 참조하세요.

리눅스와 macOS에서는 리눅스와 macOS 설치 지침에 설명된 대로 PIE(확장 기능 PHP 설치 프로그램)로 드라이버를 설치하세요. PIE는 더 이상 지원되지 않는 PHP 확장 커뮤니티 라이브러리(PECL) 패키지 시스템을 대체하며, 설치된 확장 프로그램을 sqlsrv.so 또는 pdo_sqlsrv.so라고 명명합니다. 다음 표는 Microsoft Drivers for PHP for SQL Server 릴리스 페이지에서 수동으로 다운로드하는 미리 구축된 바이너리 패키지의 파일명을 나열한 것입니다.

다음 표는 5.13 릴리스 패키지의 파일들을 나열합니다. 파일명에서 ts 및 TS는 스레드 안전을 의미하며, nts 및 NTS는 스레드 비안전을 의미합니다.

Windows 드라이버 파일

Windows_5.13.xRTW.zip 패키지에는 이 파일들이 포함되어 있습니다.

SQLSRV 파일	PDO_SQLSRV 파일	PHP 버전	스레드 세이프?	Architecture
php_sqlsrv_83_nts_x86.dll	php_pdo_sqlsrv_83_nts_x86.dll	8.3	아니요	32-bit
php_sqlsrv_83_ts_x86.dll	php_pdo_sqlsrv_83_ts_x86.dll	8.3	예	32-bit
php_sqlsrv_83_nts_x64.dll	php_pdo_sqlsrv_83_nts_x64.dll	8.3	아니요	64비트
php_sqlsrv_83_ts_x64.dll	php_pdo_sqlsrv_83_ts_x64.dll	8.3	예	64비트
php_sqlsrv_84_nts_x86.dll	php_pdo_sqlsrv_84_nts_x86.dll	8.4	아니요	32-bit
php_sqlsrv_84_ts_x86.dll	php_pdo_sqlsrv_84_ts_x86.dll	8.4	예	32-bit
php_sqlsrv_84_nts_x64.dll	php_pdo_sqlsrv_84_nts_x64.dll	8.4	아니요	64비트
php_sqlsrv_84_ts_x64.dll	php_pdo_sqlsrv_84_ts_x64.dll	8.4	예	64비트
php_sqlsrv_85_nts_x86.dll	php_pdo_sqlsrv_85_nts_x86.dll	8.5	아니요	32-bit
php_sqlsrv_85_ts_x86.dll	php_pdo_sqlsrv_85_ts_x86.dll	8.5	예	32-bit
php_sqlsrv_85_nts_x64.dll	php_pdo_sqlsrv_85_nts_x64.dll	8.5	아니요	64비트
php_sqlsrv_85_ts_x64.dll	php_pdo_sqlsrv_85_ts_x64.dll	8.5	예	64비트

비스레드 안전 드라이버 파일은 비스레드 안전 PHP 빌드와 함께 사용하고, 스레드 안전 드라이버 파일은 스레드 안전 PHP 빌드와 함께 사용하세요. 두 빌드 모두 명령줄 인터페이스(CLI)를 사용할 수 있습니다. 어떤 빌드인지 확인하려면 을(를) 실행하고 php -i 값을 확인해 보세요.

리눅스 및 macOS 드라이버 파일

Mac_5.13.xRTW.tar.gz 및 Linux_5.13.xRTW.tar.gz 패키지에는 이러한 파일이 포함됩니다. 리눅스 아카이브에는 x64 바이너리가 있고, macOS 아카이브에는 Arm64 바이너리가 포함되어 있습니다.

프리빌드 파일도 운영체제의 기본 라이브러리와 일치해야 합니다. Linux 5.13.3 바이너리는 glibc 2.38 및 이후 버전과 GLIBCXX_3.4.32를 제공하는 C++ 런타임이 필요합니다. macOS 5.13.3 바이너리는 macOS 26을 최소 배포 목표로 선언합니다. 이러한 이진 요구사항은 소스 빌드에 대한 운영 시스템 지원과는 별개입니다.

아카이브의 아키텍처나 네이티브 라이브러리 요구사항이 PHP 설치와 맞지 않을 때는 PIE를 사용하세요. 설치된 PHP 및 네이티브 라이브러리용 PIE 빌드입니다. 시스템 라이브러리를 수동으로 교체해서 미리 구축된 확장 프로그램을 불러오지 마세요.

SQLSRV 파일	PDO_SQLSRV 파일	PHP 버전	스레드 세이프?
SQLSRV_8.3_NTS.so	PDO_SQLSRV_8.3_NTS.so	8.3	아니요
SQLSRV_8.3_TS.so	PDO_SQLSRV_8.3_TS.so	8.3	예
SQLSRV_8.4_NTS.so	PDO_SQLSRV_8.4_NTS.so	8.4	아니요
SQLSRV_8.4_TS.so	PDO_SQLSRV_8.4_TS.so	8.4	예
SQLSRV_8.5_NTS.so	PDO_SQLSRV_8.5_NTS.so	8.5	아니요
SQLSRV_8.5_TS.so	PDO_SQLSRV_8.5_TS.so	8.5	예

필요한 파일을 PHP 확장 디렉터리에 복사하세요. 패키지 파일 이름을 유지하고 extension=SQLSRV_8.4_NTS.so를 작성하거나, 파일 이름을 sqlsrv.so로 바꾸고 짧은 형식인 extension=sqlsrv를 작성할 수 있습니다. 같은 명명 선택을 PDO_SQLSRV에도 적용하세요. 확장 프로그램 디렉터리를 찾으려면 php -i | grep extension_dir를 실행하세요. Linux 및 macOS에서 드라이버 로드의 지침을 따라 올바른 구성 파일에서 확장 기능을 활성화하고 PDO_SQLSRV 전에 PHP 데이터 오브젝트(PDO)를 로드하세요.

이전 릴리스

5.13 이전 릴리스에 포함된 드라이버 파일의 경우 Microsoft Drivers for PHP for SQL Server 릴리스 페이지에서 해당 릴리스의 패키지를 다운로드하고 그 내용을 나열하세요. 5.12 이전 릴리스는 각 운영체제와 PHP 버전별로 별도의 패키지를 배포하며, 플랫폼별로 단일 패키지를 배포하지 않습니다.

선택한 환경을 검증하세요

PHP 확장과 ODBC 드라이버를 설치한 후, 웹 서버를 구성하기 전에 다음 검사를 실행하세요:

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

마지막 두 명령어는 별도의 모듈 정보 섹션을 표시해야 합니다. 두 명령어 중 하나라도 확장 프로그램이 없다고 보고하면, 데이터베이스 연결을 테스트하기 전에 플랫폼 설치 및 로딩 절차를 완료하세요.

verify-php-drivers.php를 생성하여 자격 증명 없이 두 PHP API를 모두 확인하세요:

<?php
$failures = [];

if (!extension_loaded('sqlsrv') || !function_exists('sqlsrv_connect')) {
    $failures[] = 'SQLSRV is not loaded.';
}

if (!extension_loaded('pdo_sqlsrv') || !in_array('sqlsrv', PDO::getAvailableDrivers(), true)) {
    $failures[] = 'PDO_SQLSRV is not loaded.';
}

echo $failures === []
    ? "SQLSRV and PDO_SQLSRV are loaded." . PHP_EOL
    : implode(PHP_EOL, $failures) . PHP_EOL;

exit($failures === [] ? 0 : 1);

애플리케이션을 제공하는 PHP 실행 파일로 실행하세요:

php verify-php-drivers.php

예상 출력:

SQLSRV and PDO_SQLSRV are loaded.

이 검사는 확장 로드를 검증합니다. ODBC 연결성, 인증, 인증서 신뢰, 네트워크 접근, 데이터베이스 권한 등을 검증하지 않습니다.

결과를 기록한 후 삭제하세요 verify-php-drivers.php .

요구 사항 실패를 진단

증상	가능한 소유자	수표
PHP Startup: Unable to load dynamic library	PHP 런타임 또는 확장 선택	PHP 마이너 버전, 아키텍처, 스레드 세이프티 모드, extension_dir그리고 정확한 파일명
Call to undefined function sqlsrv_connect()	SQLSRV 확장 구성	php --ri sqlsrv, 활성 php.ini파일 , 스캔된 .ini 파일들
PDOException: could not find driver	PDO_SQLSRV 확장 또는 PDO 로드 순서	php --ri pdo_sqlsrv, PDO::getAvailableDrivers(), 그리고 PDO가 먼저 로드되는지 여부
누락된 msodbcsql 또는 libodbc 라이브러리	ODBC 설치 또는 운영 시스템 로더	설치된 ODBC 패키지, 아키텍처 및 공유 라이브러리 의존성
CLI는 성공하지만 웹사이트는 작동하지 않습니다	SAPI 전용 PHP 구성	를 임시 phpinfo() 페이지와 php --ini 비교해 보세요
확장 프로그램이 로드되지만 연결에 실패합니다	ODBC, 네트워크, 인증, 인증서 또는 데이터베이스 대상	SQLSRV 오류 컬렉션 또는 PDO 예외를 캡처하고 보고된 SQLSTATE 문제를 해결하세요

관련 콘텐츠

• SQL Server용 Microsoft Drivers for PHP 시작하기
• SQL Server용 PHP용 Microsoft 드라이버 프로그래밍 가이드
• SQLSRV 드라이버 API 참조
• PDO_SQLSRV 드라이버 참조