LocalDB 지원

PHP 드라이버 다운로드

SQL Server Express LocalDB는 SQL Server Express의 가벼운 사용자 인스턴스 모드로, Windows에서만 사용할 수 있습니다. 두 드라이버 모두 (localdb)\<instance-name> 서버 이름 형식을 사용하여 임의의 명명된 인스턴스에 연결하는 것과 같은 방식으로 LocalDB 인스턴스에 연결합니다.

설명

LocalDB는 Windows 사용자 계정으로 실행됩니다. 이 프로그램들은 Microsoft Entra 인증이 아닌 Windows 통합 인증을 사용합니다. 사용자 단위 데이터베이스 인스턴스가 워크플로우에 맞을 때 로컬 Windows 개발에 사용하세요. 컨테이너 이미지나 Azure 서비스가 아닙니다.

Note

LocalDB는 리눅스나 macOS에서 사용할 수 없습니다. 대신 지원되는 호스트에서 SQL Server 인스턴스에 연결하세요. 컨테이너의 경우, 지원되는 SQL Server on Linux 플랫폼을 확인하세요; 모든 macOS나 리눅스 아키텍처가 SQL Server 컨테이너 이미지를 실행할 수 있다고 가정하지 마세요.

LocalDB 인스턴스에 연결하세요

지원되는 SQL Server Express LocalDB 릴리스와 ODBC 전제 조건, 선택한 PHP 확장 기능을 모두 설치하세요. LocalDB 설치 시 PHP 확장 프로그램이 로드되지 않습니다.

Windows 터미널에서 sqllocaldb.exe i를 실행해서 인스턴스를 나열하세요.
MSSQLLocalDB이(가) 없으면 sqllocaldb.exe create MSSQLLocalDB을(를) 실행하세요.
sqllocaldb.exe start MSSQLLocalDB를 실행한 다음 sqllocaldb.exe info MSSQLLocalDB를 실행하여 인스턴스를 검사합니다. 이 단계들은 PHP 프로그램을 실행하는 Windows 계정으로 수행하세요.
명령줄 PHP로 프로그램 중 하나를 저장하고 실행하세요. 각각은 master에 기본적으로 연결되며 대상이 실제로 LocalDB인지 확인합니다. 샘플 데이터베이스도 SQL 비밀번호도 필요하지 않습니다.

인스턴스 이름은 Windows 머신과 소유 계정에 로컬로 한정됩니다. DNS 호스트 이름도, TCP 포트도, 다른 컴퓨터와의 연결도 아닙니다.

SQLSRV

이 프로그램을 connect-localdb-sqlsrv.php로 저장하고 php connect-localdb-sqlsrv.php를 실행하세요.

<?php
$instance = getenv('LOCALDB_INSTANCE') ?: 'MSSQLLocalDB';
$database = getenv('LOCALDB_DATABASE');
if ($database === false || $database === '') {
    $database = 'master';
}
$file = getenv('LOCALDB_MDF');
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';
$options = ['Database' => $databaseValue, 'LoginTimeout' => 30, 'CharacterSet' => 'UTF-8'];
if ($file !== false && $file !== '') {
    if ($database === 'master' || !is_file($file)) {
        throw new RuntimeException('Set a non-master database name and an accessible MDF path.');
    }
    $options['AttachDBFileName'] = '{' . str_replace('}', '}}', $file) . '}';
}
$conn = sqlsrv_connect('(localdb)\\' . $instance, $options);
if ($conn === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
$stmt = null;
try {
    $stmt = sqlsrv_query(
        $conn,
        "SELECT DB_NAME() AS DatabaseName, CAST(SERVERPROPERTY('IsLocalDB') AS int) AS IsLocalDB"
    );
    if ($stmt === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    $row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    if ($row !== ['DatabaseName' => $database, 'IsLocalDB' => 1]) {
        throw new RuntimeException('Expected the selected LocalDB database.');
    }
    echo 'LocalDB database: ', $row['DatabaseName'], PHP_EOL;
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

PDO_SQLSRV

이 별도의 프로그램을 connect-localdb-pdo.php로 저장하고 php connect-localdb-pdo.php실행하세요.

<?php
$instance = getenv('LOCALDB_INSTANCE') ?: 'MSSQLLocalDB';
$database = getenv('LOCALDB_DATABASE');
if ($database === false || $database === '') {
    $database = 'master';
}
$file = getenv('LOCALDB_MDF');
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';
$dsn = "sqlsrv:Server=(localdb)\\$instance;Database=$databaseValue;LoginTimeout=30";
if ($file !== false && $file !== '') {
    if ($database === 'master' || !is_file($file)) {
        throw new RuntimeException('Set a non-master database name and an accessible MDF path.');
    }
    $dsn .= ';AttachDBFileName={' . str_replace('}', '}}', $file) . '}';
}
$pdo = new PDO($dsn, null, null, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE => true,
    PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
]);
$stmt = null;
try {
    $stmt = $pdo->query(
        "SELECT DB_NAME() AS DatabaseName, CAST(SERVERPROPERTY('IsLocalDB') AS int) AS IsLocalDB"
    );
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row !== ['DatabaseName' => $database, 'IsLocalDB' => 1]) {
        throw new RuntimeException('Expected the selected LocalDB database.');
    }
    echo 'LocalDB database: ', $row['DatabaseName'], PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

기본 구성에서의 예상 출력:

LocalDB database: master

SQLSRV는 연결 리소스를 반환하고 연결 실패를 false로 보고합니다. PDO는 객체를 반환하고, 구성이 실패하면 PDOException 예외를 발생시킵니다. PDO 프로그램은 명시적으로 숫자형으로 가져오기를 활성화하여 int 값이 SQLSRV 결과와 일치하는 PHP int가 되도록 합니다. 두 경우 모두 문자 데이터에 UTF-8을 사용하며, 쿼리가 실패하더라도 릴리스 문과 연결 핸들을 해제합니다.

기존 데이터베이스를 선택하거나 파일을 첨부하세요

프로그램은 다음과 같은 선택적 프로세스 변수를 수용합니다:

변수	Meaning
`LOCALDB_INSTANCE`	`(localdb)\` 접두사 없는 인스턴스 이름. 기본값은 `MSSQLLocalDB`입니다.
`LOCALDB_DATABASE`	기존 데이터베이스 이름이거나, 첨부된 데이터베이스에 부여할 이름입니다. 기본값은 `master`입니다.
`LOCALDB_MDF`	첨부할 수 있는 기존 접근 가능한 `.mdf` 파일로 가는 절대 경로. 이미 등록된 데이터베이스에 연결할 때는 이 부분을 생략하세요.

인스턴스에 이미 등록된 데이터베이스를 사용하려면 LOCALDB_DATABASE을 설정하고 LOCALDB_MDF은 설정하지 않은 상태로 두세요. 기존 데이터베이스 파일을 첨부하려면 둘 다 설정하세요. 예를 들어 PowerShell에서 다음을 수행합니다.

$env:LOCALDB_DATABASE = 'myData'
$env:LOCALDB_MDF = 'C:\Data\myData.mdf'

이 목적을 위해 준비된 데이터베이스 파일을 사용하세요. 다른 실행 중인 인스턴스에 연결된 파일이 아니라요. Windows 계정에 데이터베이스 파일과 해당 파일이 있는 디렉터리에 대한 접근 권한을 부여하세요. AttachDBFileName 누락된 MDF 파일을 생성하지 않으며, 데이터베이스를 마이그레이션하거나, 호환되지 않는 데이터베이스 파일 버전을 해결하지 않습니다. 첨부는 데이터베이스를 인스턴스에 등록합니다; PHP를 닫아도 데이터베이스가 분리되거나 삭제되지 않습니다. 둘 다 독립적으로 검증해야 한다면 분리된 상태에서 각 API의 첨부 경로를 테스트하세요.

서버 문자열의 백슬래시는 PHP 단일 따옴표 문자열에서 \\로 이스케이프됩니다. PHP 이중 인용 문자열은 백슬래시와 변수도 해석하기 때문에 PDO 프로그램은 인스턴스 문자열을 의도적으로 구성합니다. 두 프로그램 모두 연결을 위해 데이터베이스 이름을 이스케이프 처리하면서도 검증 및 결과 검사를 위해 원래 이름을 유지합니다. 또한 첨부 값에 이스케이프 처리를 하기 전에 실제 파일 시스템 경로를 확인합니다. 각 연결 값에 대해 닫는 브레이스를 두 배로 하고 값을 브레이스로 감쌉니다. SQLSRV는 연결 배열에 포함된 문자열 옵션조차도 이스케이프를 요구합니다. LOCALDB_DATABASE 및 LOCALDB_MDF를 실제 이름과 경로로 설정하되, 브레이스를 직접 추가하거나 중복해서 입력하지 마세요.

이 연결들은 원격 서버가 아닌 로컬 인스턴스를 사용합니다. 원격 SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, Fabric 내 SQL 데이터베이스, 또는 Fabric 내 Warehouse의 경우, 실제 서비스 엔드포인트를 사용하세요. 인증, 암호화, 인증서 검증을 명시적으로 설정하세요. 자세한 내용은 서버에 연결하기를 참조하세요.

계정 및 인스턴스 문제 진단

sqlcmd -S "(localdb)\MSSQLLocalDB"를 사용해 명령줄에서 LocalDB 인스턴스의 데이터베이스를 관리할 수도 있습니다. 예를 들어 . 당신의 인터랙티브 Windows 계정이 소유한 LocalDB 인스턴스가 인터넷 정보 서비스(IIS) 애플리케이션 풀 ID에 자동으로 접근 권한을 부여하지는 않습니다. PHP를 실행하는 계정을 변경할 때 인스턴스 소유권과 파일 권한을 확인하세요. 자세한 내용은 SQL Server Express LocalDB를 참조하세요.

증상	수표
`sqllocaldb.exe` 찾을 수 없음	LocalDB가 설치되어 있고 해당 유틸리티를 터미널에서 사용할 수 있는지 확인하세요. PHP 드라이버 설치만으로는 충분하지 않습니다.
인스턴스가 발견되지 않습니다	PHP를 실행하는 동일한 Windows 계정으로 인스턴스 목록을 확인하고 `LOCALDB_INSTANCE`를 확인해 보세요.
초기 연결은 너무 오래 걸립니다	인스턴스를 명시적으로 시작하고 문서화된 로그인 타임아웃을 사용해 다시 시도하세요. 무기한 재시도하기보다는 인스턴스 시작 실패를 조사하세요.
`master` 작동하지만 `myData`은 작동하지 않습니다	해당 인스턴스에 데이터베이스가 존재하는지 확인하거나, 액세스 가능한 연결 파일과 데이터베이스 이름을 구성하세요.
파일 첨부에 실패합니다	정확한 경로, 파일 소유권, 디렉터리 권한, 파일이 이미 사용 중인지, LocalDB 버전 호환성을 확인하세요.
터미널 PHP는 작동하지만 IIS는 그렇지 않습니다	계정, 인스턴스 소유권, 파일 접근, 런타임 설정, 확장 프로그램 로딩 등을 비교해 보세요. 상호작용 테스트가 웹 호스팅 액세스를 증명한다고 가정하지 마세요.

LocalDB 시작 및 사용자별 소유권은 SQL Server LocalDB 및 Windows에 속합니다. PHP 확장 프로그램은 ODBC를 통한 연결 옵션을 제공합니다. 인스턴스 소유권 문제를 보완하기 위해 SQL 자격 증명이나 Microsoft Entra 옵션을 추가하지 마세요.

피드백

이 페이지가 도움이 되었나요?

2026-10-28 에 마지막으로 업데이트됨