SQL Server Express LocalDB는 로컬 Windows 개발을 위한 경량 SQL Server 엔진입니다. Windows 사용자 계정으로 실행되며 필요할 때 시작됩니다. LocalDB는 원격 데이터베이스 서비스가 아니며 리눅스나 macOS에서 실행되지 않습니다.
크로스 플랫폼 개발을 위해서는 지원되는 SQL Server 컨테이너나 원격 SQL 엔드포인트를 사용하세요. NuGet 패키지를 Microsoft.Data.SqlClient 설치하면 클라이언트 드라이버가 설치되지, LocalDB가 설치되지 않습니다.
LocalDB 설치
SQL Server Express 설정이나 Visual Studio 설치 프로그램을 통해 LocalDB를 설치하세요. Visual Studio에서 적절한 데이터 개발 워크로드 또는 SQL Server Express LocalDB 개별 컴포넌트를 선택하세요. 현재 다운로드와 설치 옵션은 SQL Server Express LocalDB 설치를 참조하세요.
LocalDB 설치는 엔진과 SQLUserInstance.dll관리 SqlLocalDB.exe 유틸리티를 제공합니다.
SqlLocalDB에 PATH이(가) 없으면 설치된 SQL Server 도구 디렉터리에서 실행하세요.
설치된 버전과 인스턴스를 나열하세요:
SqlLocalDB versions
SqlLocalDB info
자동 인스턴스에 연결
자동 인스턴스의 이름은 MSSQLLocalDB이며 현재 Windows 사용자에게 속합니다. Windows 통합 인증을 사용하세요. LocalDB는 Microsoft Entra 인증을 지원하지 않습니다.
Microsoft.Data.SqlClient이(가) 설치된 .NET 콘솔 애플리케이션의 경우:
using Microsoft.Data.SqlClient;
string connectionString =
@"Server=(localdb)\MSSQLLocalDB;Database=master;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;";
using var connection = new SqlConnection(connectionString);
await connection.OpenAsync();
using var command = new SqlCommand("SELECT DB_NAME();", connection);
Console.WriteLine(await command.ExecuteScalarAsync());
쿼리는 master를 출력합니다. 첫 번째 연결은 LocalDB가 인스턴스를 생성하거나 시작하기 때문에 시간이 더 걸릴 수 있습니다. 시작에 연결 시간 초과보다 더 오래 걸리면 인스턴스 상태를 확인하고 시작이 완료될 때까지 기다린 후 다시 시도하세요.
이 예시는 를 포함한 TrustServerCertificate=true지역 개발 증명서를 허용합니다. 이 예외는 지역 개발에 한정하세요. 원격 SQL 엔드포인트의 경우, 검증 가능한 인증서를 사용하고; TrustServerCertificate=false암호화 및 인증서 검증을 참조하세요.
연결 문자열의 백슬래시
connection-string 값은 인스턴스 이름 와 (localdb) 사이에 백슬래시 하나를 포함합니다. 이스케이핑은 값을 어디에 쓰느냐에 따라 다릅니다:
| Location | 서버 값 |
|---|---|
| 일반 텍스트, 확장 가능한 마크업 언어(XML) 구성, 또는 PowerShell 단일 인용 문자열 중 하나일 수 있습니다. | (localdb)\MSSQLLocalDB |
| C# 축자 문자열. | @"(localdb)\MSSQLLocalDB" |
| C# 일반 문자열 또는 JavaScript 객체 표기법(JSON) 문자열을 사용할 수 있습니다. | "(localdb)\\MSSQLLocalDB" |
C#의 이중 백슬래시를 일반 텍스트 연결 문자열에 복사하지 마세요.
이름 붙여진 인스턴스 및 공유 인스턴스
애플리케이션에 별도의 로컬 엔진 인스턴스를 만들고 싶을 때는 이름 있는 인스턴스를 사용하세요. 연결 전에 생성하세요:
SqlLocalDB create SqlClientDev
SqlLocalDB start SqlClientDev
SqlLocalDB info SqlClientDev
다음 일반 텍스트 연결 문자열을 사용하여 연결하세요:
Server=(localdb)\SqlClientDev;Database=master;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;
서로 다른 Windows 사용자가 같은 이름의 개인 인스턴스를 가질 수 있습니다. 이름만으로는 다른 사용자의 인스턴스를 식별할 수 없습니다.
공유 인스턴스는 같은 컴퓨터의 다른 사용자에게도 보이는 별칭을 가집니다. 관리자는 공유를 설정해야 하며, 다른 사용자는 적절한 Windows 또는 SQL 로그인이 필요합니다. 공유가 데이터베이스 권한을 자동으로 부여하지 않습니다. 공유 네임스페이스 사용:
Server=(localdb)\.\<shared_instance>;Database=<database>;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;
개발 인스턴스만 의도적으로 공유하세요. 로컬 파일 접근 및 데이터베이스 권한을 검토하세요. LocalDB의 공유 인스턴스를 참조하세요.
설명
인스턴스 소유자가 접근할 수 있는 기존 데이터베이스 파일을 첨부하는 데 사용 AttachDBFilename 하세요. 또한, 데이터베이스 이름을 지정하세요:
Server=(localdb)\MSSQLLocalDB;Database=<database>;AttachDBFilename=C:\Data\<database>.mdf;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;
절대 파일 경로나 적절하게 설정된 |DataDirectory| 값을 사용하세요.
AttachDBFilename 누락된 데이터베이스 파일을 생성하지 않습니다. 엔진은 데이터베이스 파일의 버전을 지원해야 하며, 다른 인스턴스가 이미 파일을 열어둘 수 없습니다.
파일을 첨부할 때 생략 Database 하면, 애플리케이션이 종료될 때 데이터베이스가 LocalDB 인스턴스에서 제거됩니다. 영구 데이터베이스 등록을 언제 원하는지 명시 Database 하세요.
User Instance=true LocalDB에는 해당되지 않습니다. LocalDB에서는 MultiSubnetFailover=true를 사용하지 마세요. 해당 로컬 네임드 파이프 연결은 TCP 장애 조치 엔드포인트가 아닙니다.
데이터베이스와 로그 파일을 Windows 파일 권한으로 보호하세요. 보호받지 않은 데이터베이스 파일을 복사할 수 있는 사람은 자신이 제어하는 인스턴스에 첨부할 수 있습니다. SQL 권한이 파일 시스템 보호를 대체하지 않습니다.
프로그래밍 방식으로 명명된 인스턴스 만들기
적용 대상: .NET Framework
.NET 프레임워크 애플리케이션의 경우, . 섹션에 system.data.localdbapp.config이름 있는 인스턴스와 설치된 LocalDB 엔진 버전을 선언하세요.
Microsoft.Data.LocalDBConfigurationSection 어셈블리의 Microsoft.Data.SqlClient configuration-section 형식을 등록한 다음, 해당 인스턴스를 localdbinstances 아래에 추가합니다.
인스턴스 이름을 Server=(localdb)\<instance> 설정 항목에 맞추고, 컴퓨터에 설치된 LocalDB 엔진 버전을 사용하세요. 오래된 드라이버 어셈블리 버전이나 엔진 버전을 새 애플리케이션에 복사하지 마세요.
현대 .NET는 인스턴스를 생성할 때 이 구성 섹션을 사용하지 않습니다. 개발자 설정 시 또는 애플리케이션이 인스턴스를 관리해야 할 때 LocalDB 관리 API를 사용할 SqlLocalDB 수 있습니다.
Limitations
LocalDB는 인스턴스 소유자의 권한으로 실행됩니다. 이 서비스는 지역 개발을 위한 것이지, 공유 제작 서비스가 아닙니다.
- LocalDB는 Windows 전용입니다. Windows가 아닌 플랫폼에서 관리형 네트워킹 LocalDB 연결은
PlatformNotSupportedException예외를 발생시킵니다. - 원격 관리는 지원되지 않습니다.
- FILESTREAM과 머지-복제 구독자 사용은 지원되지 않습니다.
- 서비스 브로커는 로컬 대기열만 지원합니다.
- 데이터베이스 크기와 리소스 제한은 SqlClient 패키지 버전이 아니라 설치된 SQL Server Express 엔진을 따릅니다.
| Engine | 인스턴스당 최대 연산 | 최대 버퍼 풀(메가바이트 단위) | 최대 관계형 데이터베이스 크기 (GB) |
|---|---|---|---|
| SQL Server 2022 Express LocalDB. | 1개의 소켓과 4개의 코어 중 더 적은 쪽을 선택하세요. | 1,410 MB. | 10GB. |
| SQL Server 2025 Express LocalDB. | 1개의 소켓과 4개의 코어 중 더 적은 쪽을 선택하세요. | 1,410 MB. | 50GB입니다. |
SQL Server 2022와 SQL Server 2025의 에디션 제한을 참조하세요. LocalDB 테스트는 Microsoft Entra 인증, 원격 전송층 보안(TLS) 인증서 검증, 가용성 그룹 장애 조치, 클라우드 서비스 제한을 적용하지 않습니다. 해당 명령들은 계획된 배치에 대해 별도로 적용하세요.