SQL Database プロジェクトの作成、ビルド、検証

完了済み

デプロイを自動化したり、テストを実行したり、スキーマの誤差を検出したりする前に、パイプラインで実際に構築できるものが必要です。 これは SQL データベース プロジェクトです。

SQL データベース プロジェクトについて

SQL データベース プロジェクトは、ファイル形式のデータベースと考えてください。 すべてのテーブル、ストアド プロシージャ、ビュー、および関数は、独自の .sql ファイル内に存在します。 各オブジェクトは 1 回宣言し、列を追加したりデータ型を変更したりする必要がある場合は、その 1 つのファイルを編集します。

以前に移行スクリプトを使用していた場合、その違いは大きくなります。 移行スクリプトはシーケンシャルです。 ALTERステートメントを記述し、正しい順序で実行し、徐々に変化の連鎖を蓄積することを望みます。 SQL データベース プロジェクトでは、対照的なアプローチを取ります。各オブジェクトの理想的な終了状態を維持し、その状態をターゲット データベースと比較して、配置時に、プロジェクトとターゲットデータベースの差をツールが計算します。

プロジェクトをビルドすると、出力は .dacpac ファイルであり、データベース スキーマ全体のコンパイル済みモデルです。 その .dacpac を発行して、新しいデータベースを作成するか、既存のデータベースを更新します。 ビルド プロセスでは、CI/CD にとって重要な 2 つのことが提供されます。

  • 検証: オブジェクト参照と T-SQL 構文は、何かをデプロイする前に、特定のバージョンの SQL に対してチェックされます。
  • デプロイ可能な成果物: .dacpac は、パイプラインを通ってすべての環境に流れる単一のパッケージになります。

元のプロジェクトと SDK スタイルのプロジェクトを選択する

SQL データベース プロジェクトには、2 つの形式があります。 元の形式は MSBuild (.NET Framework) 上に構築され、Visual Studio の SQL Server Data Tools (SSDT) に付属しています。 SDK スタイルの形式は、Microsoft.Build.Sql プロジェクト SDK 上に構築され、Visual Studio Code 用の SQL Database Projects 拡張機能で使用される形式です。

新しいプロジェクトの場合は、SDK スタイルを使用します。 元の形式にはない機能が提供されます。

  • .NET 8 以降のサポートにより、Windows、Linux、macOS でクロスプラットフォームを構築できます。 このサポートは、CI ランナーが Windows マシンでない場合に重要です。
  • NuGet パッケージ参照はデータベース参照にも使用されるため、依存関係の管理は.NET エコシステム全体の他の部分と同様のパターンに従います。
  • .sql ファイルに対する既定のグロビング プロジェクト フォルダーにファイルをドロップすると、自動的にビルドに含まれます。 手動のファイル エントリは必要ありません。

既存の元のプロジェクトがある場合は、 .sqlproj ファイルを変更して SDK スタイルに変換できます。 プロジェクトを変換する前に、プロジェクト ファイルをバックアップし、現在のプロジェクトから .dacpac をアーカイブします。 "before" と "after" の .dacpac を比較して、変換がすべて保持されていることを確認します。

注

SDK スタイルの SQL プロジェクトは、Visual Studio Code および Visual Studio 2022 のプレビューで一般提供されています。 Visual Studio 2026 では、元の SQL プロジェクト形式のみがサポートされます。

プロジェクトを作成してデータを入力する

SQL データベース プロジェクトは、Visual Studio Code、Visual Studio、またはコマンド ラインから作成できます。 コマンド ラインは、グラフィカル環境が使用できない CI/CD シナリオに特に便利です。

新しい SDK スタイルのプロジェクトを作成するには:

dotnet new sqlproj -n MyDatabaseProject

📝 これにより、SDK 形式の .sqlproj ファイルが生成されます。 ここから、プロジェクト フォルダーに .sql ファイルをドロップして、データベース オブジェクトを追加します。 既定の globbing パターンは、それらを自動的に取得します。

たとえば、テーブルを定義するには、次の 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 でも 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 ステートメントのみが生成されます。 列が2つ欠けていませんか? 両方の追加で 1 つの ALTER TABLE を取得します。 このプロセスは冪等性を持っています。 同じ .dacpac を 5 回デプロイすると、5 回目の実行では何も変更されません。 複数のテナントをアップグレードする際には、1 つの .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 概要を生成します。 運用環境に変更をプッシュする前に、いずれか 1 つを確認してください。

重要なポイント

SQL データベース プロジェクトでは、すべてのデータベース オブジェクトが宣言型の .sql ファイルとして格納され、ビルドによって 1 つの .dacpac 成果物にコンパイルされます。 SDK スタイルのプロジェクト (Microsoft.Build.Sql) では、.NET 8 以降、クロスプラットフォーム ビルド、NuGet パッケージ参照、および .sql ファイルの既定の globbing がサポートされます。 ビルド プロセスでは、データベースに到達する前に、ターゲット プラットフォームに対するオブジェクト参照と T-SQL 構文が検証されます。 SqlPackage では、 .dacpac とターゲット データベースの差が計算され、ギャップを埋めるために必要なステートメントのみが生成されます。 ScriptアクションとDeployReportアクションを使用して、運用環境にデプロイする前に計画された変更をプレビューします。 SQL データベース プロジェクト、その .dacpac 成果物、SqlPackage は、ソース管理、CI/CD パイプライン、スキーマ ドリフト検出、テストなど、今後のすべての基盤を形成します。