概要

Database Projects とは

Database Projects（データベースプロジェクト）とは、Azure SQL ファミリーにおけるメタデータを宣言型で管理する機能である。Microsoft 社により提供されており、データ層アプリケーション(DAC)機能と Visual Studio のプロジェクト機能をベースに実装されている。

データ層アプリケーション(DAC)機能については、次のようにドキュメントに記載されている。メタデータだけでなくデータも含むファイルを dacpac ではなく、backpac と呼ぶ。

データ層アプリケーション (DAC) は、ユーザーのデータベースに関連付けられているすべてのSQL Server オブジェクト (テーブル、ビュー、ログインを含むインスタンスオブジェクトなど) を定義する論理データベースエンティティです。 DAC は、データベースモデル全体の自己完結型ユニットであり、DAC パッケージ ( .dacpac) と呼ばれる成果物で移植可能です。

引用元：データ層アプリケーション (DAC) - SQL Server | Microsoft Learn

BACPAC ファイルは、データベースのメタデータとデータを含む BACPAC の拡張子を持つ ZIP ファイルです。

引用元：BACPAC ファイルへのデータベースのエクスポート - Azure SQL Database & Azure SQL Managed Instance | Microsoft Learn

Visual Studio のプロジェクト機能については、次のようにドキュメントに記載されている。複数のプロジェクトをソリューションとして管理することが、ドキュメントに記載されている。

論理的には、実行可能ファイル、ライブラリ、または Web サイトにコンパイルされる、すべてのファイルがプロジェクトに含まれています。これらのファイルには、ソースコード、アイコン、画像、データファイルなどを含めることができます。また、プロジェクトには、プログラムが通信するさまざまなサービスまたはコンポーネントで必要になる可能性がある、コンパイラ設定とその他の構成ファイルも含まれています。

引用元：Visual Studio のソリューションおよびプロジェクト - Visual Studio (Windows) | Microsoft Learn

ソリューションは、1 つまたは複数の関連するコードプロジェクトを整理するためのコンテナーです。

引用元：プロジェクトとソリューションの概要 - Visual Studio (Windows) | Microsoft Learn

特徴

データベースプロジェクトを利用することで、次のようなことを実施できる。

ディレクトリにて DDL 文の管理ができること
既存のデータベースとの差分比較ができること
データベースへの増分デプロイができること

データベースプロジェクトの利用

データ層アプリケーション(DAC)機能の利用方法

データ層アプリケーション(DAC)機能を利用する方法としては、次の方法がある。既存のデータベースから定義情報を抽出することやデータベースプロジェクトから dacpac 、または、bacpac を作成することができる。

データベースプロジェクトを用いる方法
dacpac を用いる方法
bacpac を用いる方法

データベースプロジェクトを利用できるツール

次のツールにて、基本的な操作を GUI により実施できる。CLI で作業の自動化を実施する場合には、SqlPackageを利用する。

Azure Data Studio
- SQL Database プロジェクトの拡張機能 - Azure Data Studio | Microsoft Learn
- SQL Server dacpac の拡張機能 - Azure Data Studio | Microsoft Learn
- スキーマ比較の拡張機能 - Azure Data Studio | Microsoft Learn
Visual Studio Code
- SQL Server (mssql) - Visual Studio Marketplace
- SQL Database Projects - Visual Studio Marketplace
Visual Studio
- SQL Server Data Tools (SSDT) for Visual Studio

CLR が利用されているデータベースプロジェクトのビルド

SSMA により変換されたコードでは、CLR（共通言語ランタイム）機能が利用されているため、.NET framework テクノロジー（SSDT 等）によるビルドが必要となる。.NET Core がベースである Visual Studio Code や Azure Data Factory では、次のように記載があるように、ビルドを実施できない。ただし、CLR を利用している dacpac の配置はできることは確認できている。

プロジェクトの SQLCLR オブジェクトは、DacFx の .NET Core バージョンではサポートされていません。

引用元：制限事項 - Azure Data Studio | Microsoft Learn

SSMA からデータベースプロジェクトの出力

SQL Server Migration Assistant (SSSMA) には、変換後のコードをデータベースプロジェクトとして出力することができる。SSMA にて、変更後のスキーマを右クリック -> Save as SSDT projectを選択し、フォルダを指定後にデータベースプロジェクトとして出力される。SSMA から直接配置した Azure SQL Database の定義から、データベースプロジェクトを作成する場合には、アセンブリがdllファイルではなくsqlファイルとなってしまうことに注意が必要となる。

データベースプロジェクト出力後、次の手順を実施する必要がある。

SQL Server Migration Assistant for Oracle の場合
- Azure SQL Database でサポートされていないプロパティを削除するために、データベースプロジェクトのプロジェクト定義ファイル（例：SSMA-TEST-001.sqlproj）を XML として Visual Studio Code などで開き、SSMA4ORACLESQLSERVERCOLLECTIONS.NET.dllとSSMA4ORACLESQLSERVEREXTENSIONS.NET.dllに設定されているSqlPermissionSetプロパティ(<SqlPermissionSet>UNSAFE</SqlPermissionSet>)を削除する。
- .NET Framework のバージョンを最新化するために、データベースプロジェクトを Visual Studio で開き、プロジェクト 'SSMA-TEST' をビルドするには、ターゲット、参照、そしてシステムデータベース参照を更新する必要があります。...というメッセージが表示された場合には、はいを選択する。あるいは、TargetFrameworkVersionの値をサポートされている .NET Framework のバージョン（例：v4.7.2）に設定する。
- Visual Studio Code にて開き、表示されるThe targets, references, and system database references ...というメッセージにてYesと選択する。

Git で利用する際の注意事項

データベースプロジェクトの定義ファイル（sqlprj形式のファイル）にてプロジェクトに含まれるテーブル定義などのファイルへのパスが記載されているため、ファイルの追加を複数人で実施した場合に Git の競合が発生する場合がある。対応方法としては次の方法がある。データベースプロジェクトへのファイル追加する責任者が 1 の方法の実施を行い、開発者が SQL ファイルへの追記を行う方法が推奨。

空の SQL ファイルを事前に追加する方法
ファイル追記する箇所をコメントにより記載しておく方法
データベースプロジェクト上のファイルの項目を並び替える

参考リンク

SQL database project (SSDT) merge conflicts [RichardSwinbank.net]

データベースプロジェクトの利用方針

基本的な管理方針

データベースプロジェクトを、ソリューションで管理する。

データベースプロジェクトの作成方法

データベースプロジェクトで作成する場合には、Visual Studio で作成する場合と Azure Data Studio で作成する場合で、設定値が異なる可能性があることに留意する必要がある。

SSMA から出力されるデータベースプロジェクトを扱う場合には、次の方針にて Visual Studio で作成する。

空のデータベースプロジェクト作成後、ターゲットプラットフォームを最新の SQL Server 製品（例：SQL Server 2022 and Azure SQL Database Managed Instance）から Azure SQL Database （Microsoft Azure SQL Database）へ変更する。
データベースにスキーマなどのオブジェクトをデプロイ後、データベースのインポートにてデータベースから情報を抽出する。

データベースプロジェクトを作成後、Visual Studio Code にて開くことで次のようなメッセージが表示されるため、Yesと選択する。

The targets, references, and system database references need to be updated to build the project '{db_project_name}'. If the project was created in SSDT, it will continue to work in both tools. Do you want to update the project?

データベースプロジェクトのビルド

データベースをビルドする際には、Windows 上のディレクトリに配置することが推奨。

WSL 上に配置しているディレクトリ上にあるデータベースプロジェクトをビルドしようとすると次のようなエラーとなる場合がある。

\\WSL.LOCALHOST\ORACLE-DB\HOME\WSL_USER\SOURCE\MIGRATION_FROM_ORACLE_TO_AZURE_SQL_SAMPLE\SRC\DB_MIGRATIONS\00_UTILITIES\AZURE_SQL_DB\DB_PROJECT\MA_UTILITIES\OBJ\DEBUG\MA_UTILITIES.DLL は、壊れているか、無効です

エラーのデータベースオブジェクトが含まれる場合には、検証がエラーとなりビルドを実施できない。

すべてのデータベースオブジェクトがデータ層アプリケーション (DAC) でサポートされているかどうかを検証します。また、データベースオブジェクト間の依存関係を確認して、DAC に正常に含めることができるオブジェクトのセットを判断します。

1 つ以上のオブジェクトが DAC でサポートされていない場合は、 [次へ] ボタンは無効になり、抽出プロセスを続行できません。その場合は、サポートされていないオブジェクトを削除した後に、このウィザードを再度実行することをお勧めします。

引用元：データベースからの DAC の抽出 - SQL Server | Microsoft Learn

データベースプロジェクトのデプロイ

データベースプロジェクトをデプロイする方法には次の方法があり、運用設計に応じて選択する。データベースプロジェクトを発行する場合には、内部でビルドした dacpac を配置しているため、1 の方法となる。

dacpac をデプロイする方法
スキーマ比較機能により修正内容の DDL 文をデプロイする方法