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

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 を作成することができる。

1. データベースプロジェクトを用いる方法
2. dacpac を用いる方法
3. 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 ファイルへの追記を行う方法が推奨。

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

参考リンク

• 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 の方法となる。

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