Создание, сборка и проверка проектов базы данных SQL

Прежде чем автоматизировать развертывание, выполнить тесты или обнаружить смещение схемы, вам потребуется что-то, что конвейер может фактически построить. Это проект базы данных SQL.

Общие сведения о проектах базы данных SQL

Подумайте о проекте базы данных SQL как о вашей базе данных в формате файла. Каждая таблица, хранимая процедура, представление и функция находятся в собственном .sql файле. Вы объявляете каждый объект один раз, и когда необходимо добавить столбец или изменить тип данных, измените этот один файл.

Если вы работали с скриптами миграции раньше, разница имеет значительное значение. Сценарии миграции являются последовательными. Вы пишете ALTER заявление, надеетесь, что он работает в правильном порядке, и накапливает растущую цепочку изменений с течением времени. Проект базы данных SQL принимает противоположный подход: вы сохраняете требуемое конечное состояние каждого объекта, а средство вычисляет разницу между проектом и целевой базой данных во время развертывания.

При сборке проекта выходным файлом будет .dacpac, скомпилированная модель вашей полной схемы базы данных. Вы публикуете эту .dacpac базу данных, чтобы создать новую базу данных или обновить существующую. Процесс сборки предоставляет две вещи, которые имеют значение для CI/CD:

• Проверка: ссылки на объекты и синтаксис T-SQL проверяются на определенную версию SQL, прежде чем все будет развернуто.
• Развертываемый артефакт: .dacpac становится единым пакетом, который проходит через вашу платформу в каждую среду.

Выбор между исходными проектами и проектами в стиле SDK

Проекты базы данных SQL доступны в двух форматах. Исходный формат основан на MSBuild (.NET Framework) и поставляется с SQL Server Data Tools (SSDT) в Visual Studio. Формат SDK основан на Microsoft.Build.Sql проекте SDK и используется расширением "Проекты баз данных SQL" для Visual Studio Code.

Для новых проектов используйте стиль SDK. Он предоставляет возможности, которые недоступны в исходном формате:

• Поддержка .NET 8+ позволяет создавать кроссплатформенные платформы в Windows, Linux и macOS. Эта поддержка имеет значение, если ваши средства выполнения CI не являются компьютерами с Windows.
• Ссылки на пакеты NuGet для баз данных обеспечивают управление зависимостями по тем же принципам, что и в остальной части экосистемы .NET.
• Globbing по умолчанию для .sql файлов. Переместите файл в папку проекта, и он автоматически добавится в сборку. Никаких записей вручную не требуется.

Если у вас есть исходный проект, его можно преобразовать в стиль ПАКЕТА SDK, изменив .sqlproj файл. Перед преобразованием проекта создайте резервную копию файла проекта и заархивируйте текущий .dacpac проекта. Сравните "до" и "после" .dacpac, чтобы подтвердить, что преобразование сохранило всё.

Создание и заполнение проекта

Проект базы данных SQL можно создать из Visual Studio Code, Visual Studio или командной строки. Командная строка особенно удобно подходит для сценариев CI/CD, где графические среды недоступны.

Чтобы создать новый проект в стиле SDK: Следуйте этим шагам:

dotnet new sqlproj -n MyDatabaseProject

📝 Это создает .sqlproj файл в формате SDK. Здесь вы добавляете объекты базы данных, помещая .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), сборка перехватывает ее.

Чтобы выполнить сборку из командной строки, выполните следующие действия.

dotnet build MyDatabaseProject.sqlproj

📝 Сборка создает .dacpac файл в папке bin/Debug по умолчанию.

В результаты сборки входят ошибки, блокирующие сборку, и предупреждения (например, несоответствие регистра в именах объектов). Предупреждения не останавливают сборку, но на них стоит обратить внимание. Вы также можете включить правила анализа кода SQL для выявления нарушений лучших практик во время сборки, обнаруживая такие проблемы, как устаревший синтаксис соединения, SELECT * в представлениях или неиндексированные столбцы в предикатах IN.

Целевая платформа устанавливается в .sqlproj файле и управляет тем, какие функции T-SQL проходят проверку. Задайте для него соответствие целевому объекту развертывания, будь то SQL Server 2025 или База данных SQL Azure.

Развертывание проекта

После создания .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 с обоими дополнениями. Процесс идемпотентен. Разверните один и тот же .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 создает xml-сводку по каждому CREATE, ALTERа также DROP. Просмотрите любой из них перед отправкой изменений в рабочую среду.

Основные выводы

Проект базы данных SQL сохраняет каждый объект базы данных в виде декларативного .sql файла, а сборка компилирует их в один .dacpac артефакт. Проекты в стиле SDK (Microsoft.Build.Sql) поддерживают кроссплатформенные сборки .NET 8+, ссылки на пакеты NuGet и globbing по умолчанию для .sql файлов. Процесс сборки проверяет ссылки на объекты и синтаксис T-SQL на целевой платформе, прежде чем что-либо попадет в базу данных. SqlPackage вычисляет разницу между .dacpac базой данных и целевой базой данных, создавая только инструкции, необходимые для закрытия пробела. Используйте действия Script и DeployReport для предварительного просмотра запланированных изменений перед развертыванием в рабочей среде. Проект базы данных SQL, его .dacpac артефакт и SqlPackage формируют основу для всего последующего, включая контроль версий, конвейеры CI/CD, обнаружение изменений схемы и тестирование.