SQL Database 프로젝트 만들기, 빌드 및 유효성 검사

배포를 자동화하거나, 테스트를 실행하거나, 스키마 드리프트를 검색하려면 파이프라인이 실제로 빌드할 수 있는 항목이 필요합니다. SQL 데이터베이스 프로젝트입니다.

SQL 데이터베이스 프로젝트 이해

SQL 데이터베이스 프로젝트를 파일 형식의 데이터베이스로 간주합니다. 모든 테이블, 저장 프로시저, 뷰 및 함수는 자체 .sql 파일에 있습니다. 각 개체를 한 번 선언하고 열을 추가하거나 데이터 형식을 변경해야 하는 경우 해당 단일 파일을 편집합니다.

이전에 마이그레이션 스크립트를 사용한 경우 차이가 중요합니다. 마이그레이션 스크립트는 순차적입니다. 당신은 ALTER 문을 작성하여 올바른 순서로 실행되기를 바라고, 시간이 지남에 따라 변화의 연쇄가 쌓이기를 바랍니다. SQL 데이터베이스 프로젝트는 반대 방식을 사용합니다. 즉, 각 개체의 원하는 끝 상태를 유지하고 도구는 배포 시 프로젝트와 대상 데이터베이스 간의 차이를 계산합니다.

프로젝트를 빌드할 때 출력은 전체 데이터베이스 스키마의 컴파일된 모델인 파일입니다 .dacpac . 새 .dacpac 데이터베이스를 만들거나 기존 데이터베이스를 업데이트하기 위해 게시합니다. 빌드 프로세스는 CI/CD에 중요한 두 가지 사항을 제공합니다.

• 유효성 검사: 개체 참조 및 T-SQL 구문은 배포되기 전에 특정 버전의 SQL에 대해 검사됩니다.
• 배포 가능한 아티팩트: .dacpac 파이프라인을 통해 모든 환경으로 이동하는 단일 패키지가 됩니다.

원래 프로젝트와 SDK 스타일 프로젝트 중에서 선택

SQL 데이터베이스 프로젝트는 두 가지 형식으로 제공됩니다. 원래 형식은 MSBuild(.NET Framework)를 기반으로 하며 Visual Studio의 SSDT(SQL Server Data Tools)와 함께 제공됩니다. SDK 스타일 형식은 프로젝트 SDK를 기반으로 Microsoft.Build.Sql 하며 Visual Studio Code용 SQL Database 프로젝트 확장에서 사용하는 형식입니다.

새 프로젝트의 경우 SDK 스타일로 이동합니다. 원래 형식에 없는 기능을 제공합니다.

• .NET 8+ 지원을 통해 Windows, Linux 및 macOS에서 플랫폼 간을 빌드할 수 있습니다. 이 지원은 CI 실행기에서 Windows 컴퓨터가 아닌 경우에 중요합니다.
• 데이터베이스 참조에 대한 NuGet 패키지 참조 이므로 종속성 관리는 .NET 에코시스템의 나머지 부분과 동일한 패턴을 따릅니다.
• .sql 파일에 대한 기본 글로빙 입니다. 프로젝트 폴더에 파일을 놓으면 자동으로 빌드에 포함됩니다. 수동 파일 항목이 필요하지 않습니다.

기존 원래 프로젝트가 있는 경우 파일을 수정 .sqlproj 하여 SDK 스타일로 변환할 수 있습니다. 프로젝트를 변환하기 전에 프로젝트 파일을 백업하고 현재 프로젝트에서 .dacpac을(를) 아카이브하십시오. "before" 및 "after" .dacpac 를 비교하여 변환이 모든 것을 유지했는지 확인합니다.

프로젝트 만들기 및 채우기

Visual Studio Code, Visual Studio 또는 명령줄에서 SQL Database 프로젝트를 만들 수 있습니다. 명령줄은 그래픽 환경을 사용할 수 없는 CI/CD 시나리오에 특히 유용합니다.

새 SDK 스타일 프로젝트를 만들려면 다음을 수행합니다.

dotnet new sqlproj -n MyDatabaseProject

📝 그러면 SDK 스타일 형식의 파일이 생성 .sqlproj 됩니다. 여기에서 파일을 .sql 프로젝트 폴더에 드롭하여 데이터베이스 개체를 추가합니다. 파일 검색을 위해 기본 글로빙 패턴이 자동으로 적용됩니다.

예를 들어 테이블을 정의하려면 다음을 만듭니다 Tables/Customers.sql.

CREATE TABLE [dbo].[Customers]
(
    [CustomerID] INT NOT NULL PRIMARY KEY,
    [FirstName] NVARCHAR(50) NOT NULL,
    [LastName] NVARCHAR(50) NOT NULL,
    [Email] NVARCHAR(100) NULL
);

기존 데이터베이스부터 시작하시겠습니까? 스키마 비교 도구를 사용하면 라이브 데이터베이스를 빈 프로젝트와 비교하고 차이점을 가져올 수 있으므로 모든 개체를 직접 다시 만들 필요가 없습니다.

프로젝트 빌드 및 유효성 검사

건물은 안전망이 작동하기 시작하는 곳입니다. 빌드 프로세스는 모든 개체 참조의 유효성을 검사하고 대상 플랫폼에 대해 T-SQL 구문을 확인합니다. 뷰가 존재하지 않는 열을 참조하는 경우 빌드가 실패합니다. SQL Server 2025에 추가된 벡터 함수를 사용하지만 프로젝트가 SQL Server 2017(Sql140)을 대상으로 하는 경우 빌드에서 이를 catch합니다.

명령줄에서 빌드하려면 다음을 수행합니다.

dotnet build MyDatabaseProject.sqlproj

📝빌드는 기본적으로 폴더에 .dacpac 파일을 생성합니다bin/Debug.

빌드 출력에는 오류 (빌드를 차단하는 오류) 및 경고 (예: 개체 이름의 일치하지 않는 대/소문자)가 포함됩니다. 경고는 빌드를 멈추지 않지만 주의해야 합니다. 더불어 SQL 코드 분석 규칙을 적용하면 빌드 과정에서 권장 사항 위반 사례를 감지할 수 있으며, 특히 사용되지 않는 조인 문법이나 SELECT * 뷰 구문, 인덱스가 누락된 조건절 컬럼 IN 등의 잠재적 문제를 식별할 수 있습니다.

.sqlproj 파일에서 대상 플랫폼이 설정되며, 유효성 검사를 통과하도록 T-SQL 기능을 제어합니다. SQL Server 2025 또는 Azure SQL Database와 관계없이 배포 대상과 일치하도록 설정합니다.

프로젝트 배포

.dacpac을(를) 가질 때, SqlPackage는 배포를 처리합니다. .NET 글로벌 도구로 설치합니다.

dotnet tool install --global microsoft.sqlpackage

그런 다음 대상 데이터베이스에 게시합니다.

sqlpackage /Action:Publish /SourceFile:bin/Debug/MyDatabaseProject.dacpac /TargetConnectionString:"Server=myserver.database.windows.net;Database=mydb;Authentication=Active Directory Default"

📝 SqlPackage는 플랫폼 간이며 Windows, Linux 및 macOS에서 실행됩니다.

배포 중에 발생하는 작업은 대상에 따라 달라집니다. 새 데이터베이스의 경우 SqlPackage는 개체 종속성 그래프를 탐색하고 외세 키 앞에 참조된 테이블과 같은 올바른 순서로 각 개체를 만듭니다. 기존 데이터베이스의 경우 .dacpac와 라이브 스키마 간의 차이를 계산한 후 간격을 좁히는 데 필요한 ALTER 문만 생성합니다. 두 개의 열이 누락되었나요? 두 가지 추가와 함께 하나의 ALTER TABLE을 얻을 수 있습니다. 프로세스는 idempotent입니다. 동일한 .dacpac 다섯 번 배포하고 다섯 번째 실행은 아무것도 변경하지 않습니다. 여러 테넌트를 업그레이드할 때 여러 데이터베이스에 걸쳐 단일 .dacpac를 확산할 수도 있습니다.

직접 배포하기 전에 계획된 변경 내용을 미리 볼 수 있습니다.

sqlpackage /Action:Script /SourceFile:bin/Debug/MyDatabaseProject.dacpac /TargetConnectionString:"..." /OutputPath:deploy-script.sql
sqlpackage /Action:DeployReport /SourceFile:bin/Debug/MyDatabaseProject.dacpac /TargetConnectionString:"..." /OutputPath:report.xml

이 Script 작업은 실행할 정확한 T-SQL을 생성합니다. 이 DeployReport 작업은 모든 CREATE, ALTER, 및 DROP에 대한 XML 요약을 생성합니다. 프로덕션에 변경 내용을 푸시하기 전에 둘 중 하나를 검토합니다.

주요 내용

SQL 데이터베이스 프로젝트는 모든 데이터베이스 개체를 선언적 .sql 파일로 저장하고 빌드는 이를 단일 .dacpac 아티팩트로 컴파일합니다. SDK 스타일 프로젝트(Microsoft.Build.Sql)는 .NET 8 이상, 플랫폼 간 빌드, NuGet 패키지 참조 및 파일에 대한 .sql 기본 글로빙을 지원합니다. 빌드 프로세스는 데이터베이스에 도달하기 전에 대상 플랫폼에 대한 개체 참조 및 T-SQL 구문의 유효성을 검사합니다. SqlPackage는 .dacpac와 대상 데이터베이스 간의 차이를 계산하여 차이를 해소하는 데 필요한 문만 생성합니다. 프로덕션에 배포하기 전에 계획된 변경 사항을 미리 보기 위해 Script 및 DeployReport 액션을 사용하세요. SQL Database 프로젝트, 해당 .dacpac 아티팩트 및 SqlPackage는 소스 제어, CI/CD 파이프라인, 스키마 드리프트 검색 및 테스트를 포함하여 모든 것을 위한 토대를 형성합니다.