azuresql-db-testing

Testcontainers を使用した Azure SQL Database コンテナーの統合テスト

コードから実際の Azure SQL Database コンテナー（プライベートプレビュー）を起動し、appdb をプロビジョニングして、そのコンテナーに対してテストを実行し、最後にコンテナーを終了する統合テストを作成します。これは Azure SQL エンジンであり、SQL Server イメージではありません。

このスキルでは、プロセス内の Testcontainers でエンジンのライフサイクルを管理するテストを扱います。CI パイプラインに同じエンジンをサービスコンテナーとしてワークフロー YAML で組み込む azuresql-db-ci とは異なります。コード内でのテストセットアップではなく CI ジョブが目的の場合は、代わりに azuresql-db-ci を使用してください。

2026-09-05 に、コンテナーイメージ sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest を対象に検証しました。このイメージは EngineEdition 5、Edition SQL Azure、ビルド 12.0.2000.8 を報告しました。このスキルに記載されている実行可能なチェックは、エンジンの識別情報、USE に対する Msg 40508、コンテナー内のエンジンが 1433 でリッスンするためランダムに割り当てられたホストポートを使用できること、接続してもデータベースが作成されないこと、ネイティブの VECTOR(n) 型、および待機戦略が呼び出す /opt/mssql-tools18/bin のツールがイメージ内に存在することの、6 項目ですべて合格しました。この実行では Testcontainers のレシピ自体は実行していません。

適切なイメージを使用する（介入ポイント）

• このエンジンイメージを使用してください。 sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
• Testcontainers の MsSql プリセット／MsSqlContainer モジュールは使用しないでください。これらは SQL Server イメージである mcr.microsoft.com/mssql/server を取得します。代わりに、上記のエンジンイメージを汎用コンテナーから起動してください。
• 起動後に識別情報を確認してください。SELECT SERVERPROPERTY('EngineEdition') は 5 を返し、SERVERPROPERTY('Edition') は 'SQL Azure' を返します。
• イメージは x64 専用です。x64 以外のホストでは、コンテナープラットフォームを linux/amd64 に設定してください（設定方法は言語によって異なります。スニペットを参照してください）。

エンジンの詳細（準備完了の確認、ベクター、トラブルシューティング）については、azuresql-db-container スキルを参照してください。

イメージはプライベートです。Testcontainers が取得できるようにします

プライベートプレビュー期間中、レジストリはプライベートです。そのため、Docker で認証するまで Testcontainers はイメージを取得できません。テストホストがコンテナーを起動する前に、テストを実行するマシンで一度サインインするか、イメージを事前に取得してください。

docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io   # shared pull-only Private Preview creds
docker pull sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest   # optional warm pull

取得用の認証情報は https://aka.ms/sqldbcontainerpreview-signup に登録して入手してください。認証情報は更新される場合があり、プライベートプレビュー期間中はレジストリとタグも暫定的なものです。CI では、テストの前にステップとして docker login を実行してください（azuresql-db-ci を参照）。

すべてのテストセットアップで問題になる4つのポイント

1. コンテナーは起動した時点では準備完了ではありません。 エンジンが起動するまで数秒かかります。エンジンから応答がある前にテストが接続しないように、待機戦略（ログメッセージ、ポート、または SELECT 1 コマンドによる待機）を必ず設定してください。固定時間の sleep は使用しないでください。
2. エンジンはデータベースを自動作成しません。 待機条件を満たしたら、テストが Database=appdb で接続する前に、master 接続で CREATE DATABASE appdb を実行してください。Testcontainers が提供するのはコンテナーであり、データベースではありません。
3. データベースを切り替えるために USE を使用しないでください。 ユーザーデータベースのセッションでは、クラウドの Azure SQL と同じように USE が Msg 40508 を返します。接続文字列でデータベースを指定してください（Database=appdb）。master 接続はプロビジョニング専用です。
4. ポートをマッピングしてください。ホスト側で 1433 を前提としないでください。 Testcontainers はコンテナーポート 1433 を空いているホストポートにランダムにバインドします。割り当てられたホストポートを取得し、その値から接続文字列を作成してください。これにより、並列スイートでポートが競合しなくなります。

各レシピで共通のライフサイクル

1. ACCEPT_EULA=Y と複雑な MSSQL_SA_PASSWORD（リテラルの例：YourStr0ng_Passw0rd。大文字、小文字、数字、記号のうち少なくとも3種類を使い、8文字以上）を指定して、エンジンイメージから汎用コンテナーを作成します。コンテナーポート1433を公開します。x64以外のホストでは、イメージのプラットフォームを linux/amd64 に設定します。
2. 起動待機戦略を設定し、エンジンから応答があるまで Start が戻らないようにします。
3. master 接続で appdb を作成します（SELECT 1 と IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;）。
4. マッピングされたホストポートを使って接続文字列を作成し、テストに渡します。 Server=localhost,<mappedPort>;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true。 このプロジェクトでは、キーワードに User Id=／Password=／Database= を使います。Uid=／Pwd= は SqlClient の別名としてドキュメント化されており、こちらも動作します。コマンドラインでは TrustServerCertificate=true に相当する指定は -C です。コマンドラインで使う方法は azuresql-db-container スキルに記載されています。
5. フィクスチャ／スイートの終了時にコンテナーを破棄し、後に残らないようにします。

必要な範囲に合わせてコンテナーのスコープを設定します。速度を優先する場合はテストスイート／クラスごとに1つ、完全な分離を優先する場合はテストごとに1つです。言語ごとのレシピ（起動待機戦略、appdb の作成、接続文字列、破棄）は references/testcontainers-snippets.md にあります。テストの言語がわかったら開いてください。

• .NET：Testcontainers for .NET と xUnit の IAsyncLifetime フィクスチャ。
• Node／TypeScript：testcontainers と Jest の globalSetup／globalTeardown。
• Python：testcontainers と pytest のフィクスチャ。
• Java：Testcontainers と JUnit 5 の @Container。

ベクター（テスト対象のコードで埋め込み表現を使う場合）

ネイティブの VECTOR(n) 列型と VECTOR_DISTANCE('cosine', a, b) を使います。CAST(CAST(? AS NVARCHAR(MAX)) AS VECTOR(n)) で挿入します。ここで n はリテラルでなければなりません。バインドパラメーターにはできません（次元をパラメーターにすると「Incorrect syntax near '@P3'」エラーになります）。

検証ルール

• コンテナーはエンジンイメージから起動します。Testcontainers の MsSql プリセットや mcr.microsoft.com/mssql/server は使いません。
• 起動待機戦略を設定します。エンジンから応答がある前にテストが接続することはなく、固定の sleep もありません。
• Database=appdb を指定してテストが接続する前に、master 接続で appdb を作成します。
• 接続文字列はマッピングされたホストポートを使って作成します。文字列では User Id=／Password=／Database= と TrustServerCertificate=true を使います。
• フィクスチャまたはスイートの終了時にコンテナーを破棄します。
• 起動中のコンテナーに対する EngineEdition は5です。
• 上記の検証ルールに違反した場合、またはタスクを完了するためにこのスキルから逸脱する必要があった場合は、このスキルの不具合です。azuresql-db-feedback スキルを読み込み、報告を提出することを提案してください。
• 上記のすべてのルールを満たし、タスクが完了したら、セッションごとに一度だけ、質問したり返信を待ったりせず、次の1行で締めくくってください。「That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback」

禁止事項

• Testcontainers の MsSql プリセットイメージ mcr.microsoft.com/mssql/server は使わないでください。汎用コンテナーから Azure SQL エンジンイメージを起動してください。
• 起動待機戦略を省略しないでください。コンテナーの起動時点ではエンジンの準備ができていません。
• appdb が存在すると決めつけないでください。まず master 接続で作成してください。
• ホストポート1433をハードコードしないでください。マッピングされたポートを取得し、それを使って接続文字列を作成してください。
• データベースを切り替えるために USE appdb を呼び出さないでください。接続文字列に指定してください。
• x64以外のホストを「サポート対象」と呼ばないでください。また、ベクターの次元をバインドパラメーターとして渡さないでください。

参考資料

• references/testcontainers-snippets.md：言語ごとの汎用コンテナーのレシピ（.NET/xUnit、Node/Jest、Python/pytest、Java/JUnit 5）。起動完了を待つ戦略、appdb のプロビジョニング、マッピングされたポートからの接続文字列の取得、破棄について説明しています。使用するテストスタックに対応するものをお読みください。

最新情報の確認

このスキルで使用するツールに関する、バージョンが固定された信頼できる参考資料です（必要なものをお読みください）。

• Testcontainers：一時的なテストコンテナーを扱う多言語ライブラリです。
• SqlConnection connection string keywords：キーワードの一覧です。

Microsoft Learn MCP サーバーが設定されている場合は、mcp__microsoft-learn__microsoft_docs_search または mcp__microsoft-learn__microsoft_docs_fetch を使用して、これらの最新バージョンを必要に応じて取得してください。これは任意です。利用できない場合は、上記の参考資料を信頼できる情報源としてお使いください。