Azure SQL Database 開発者に向けたデータベースプロジェクトを用いた開発論入門

## 概要

### Database Projects とは

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

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

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

引用元：[データ層アプリケーション (DAC) - SQL Server | Microsoft Learn](https://learn.microsoft.com/ja-jp/sql/relational-databases/data-tier-applications/data-tier-applications?view=sql-server-ver16&viewFallbackFrom=azuresqldb-current)

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

引用元：[BACPAC ファイルへのデータベースのエクスポート - Azure SQL Database & Azure SQL Managed Instance | Microsoft Learn](https://learn.microsoft.com/ja-jp/azure/azure-sql/database/database-export?view=azuresql)

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

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

引用元：[Visual Studio のソリューションおよびプロジェクト - Visual Studio (Windows) | Microsoft Learn](https://learn.microsoft.com/ja-jp/visualstudio/ide/solutions-and-projects-in-visual-studio?view=vs-2022)

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

引用元：[プロジェクトとソリューションの概要 - Visual Studio (Windows) | Microsoft Learn](https://learn.microsoft.com/ja-jp/visualstudio/get-started/tutorial-projects-solutions?view=vs-2022)

### 特徴

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

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

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

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

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

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

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

次のツールにて、基本的な操作を GUI により実施できる。CLI で作業の自動化を実施する場合には、[SqlPackage](https://learn.microsoft.com/ja-jp/sql/tools/sqlpackage/sqlpackage?view=sql-server-ver16)を利用する。

- Azure Data Studio
    - [SQL Database プロジェクトの拡張機能 - Azure Data Studio | Microsoft Learn](https://learn.microsoft.com/ja-jp/sql/azure-data-studio/extensions/sql-database-project-extension?view=sql-server-ver16)
    - [SQL Server dacpac の拡張機能 - Azure Data Studio | Microsoft Learn](https://learn.microsoft.com/ja-jp/sql/azure-data-studio/extensions/sql-server-dacpac-extension?view=sql-server-ver16)
    - [スキーマ比較の拡張機能 - Azure Data Studio | Microsoft Learn](https://learn.microsoft.com/ja-jp/sql/azure-data-studio/extensions/schema-compare-extension?view=sql-server-ver16)
- Visual Studio Code
    - [SQL Server (mssql) - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-mssql.mssql)
    - [SQL Database Projects - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-mssql.sql-database-projects-vscode)
- 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](https://learn.microsoft.com/ja-jp/sql/azure-data-studio/extensions/sql-database-project-extension?view=sql-server-ver16#limitations)

### 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 ファイルへの追記を行う方法が推奨。

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

参考リンク

- [SQL database project (SSDT) merge conflicts [RichardSwinbank.net]](https://richardswinbank.net/ssdt/ssdt_merge_conflicts)

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

### 基本的な管理方針

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

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

データベースプロジェクトで作成する場合には、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`と選択する。

```text
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 上に配置しているディレクトリ上にあるデータベースプロジェクトをビルドしようとすると次のようなエラーとなる場合がある。

```text
\\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](https://learn.microsoft.com/ja-jp/sql/relational-databases/data-tier-applications/extract-a-dac-from-a-database?view=sql-server-ver16#ValidateSummary)

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

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

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