mcpField
A
azuresql-db-connections

azuresql-db-connections

github.com/microsoftデータ・データベース2262 回インストール1 週間前に更新
リポジトリ

azuresql-db-connections について

Azure SQL Database コンテナーへの接続に、コネクションプーリングと一時的な障害へのリトライを設定するスキルです。.NET、Node、Python 向けの手順を含み、プールの上限と安全な再試行を重視します。

主な機能

  1. 01プーリングによる接続の再利用
  2. 02一時的な障害のみを再試行
  3. 03上限付き指数バックオフ
  4. 04.NET、Node、Python の設定例

活用シーン

  1. 01データベース接続を繰り返し開く負荷の軽減
  2. 02一時的なデータベース停止や接続切断への対応
  3. 03非冪等な書き込みの重複実行防止

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/microsoft/azure-sql-database-container --skill azuresql-db-connections

インストール後、Claude Code で/azuresql-db-connectionsを入力して読み込まれたか確認します。

同梱ファイルreferences/retry-snippets.mdskill.spec.jsonc

詳細

Azure SQL Database コンテナーでの信頼性の高い接続（プーリング＋リトライ）

コネクションプーリングとリトライ／一時的な障害への対応によって、アプリのデータベース接続の信頼性を高めます。これはAzure SQL エンジン（プライベートプレビュー）であり、SQL Server イメージではありません。

2026-09-05 に、コンテナーイメージ sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest に対して検証済みです。EngineEdition 5、Edition SQL Azure、ビルド 12.0.2000.8 が報告されました。このスキルに含まれる実行可能なチェックは5つすべて合格しました。エンジンの識別情報、USE に対する Msg 40508、マッピングされたポート上の TCP セッション、そして2つのリソースガバナンス動的管理ビューがローカルでは何も返さないことです。以下のリトライリストにある10個の一時的なエラー番号のうち、このビルドの sys.messages に含まれているのは9個で、Msg 10929 は含まれていません。コンテナーで発生する理由のないクラウドのリソースガバナンスエラーであり、実行結果ではなく Microsoft Learn を出典としているため、リストに残しています。

ローカルで行う理由（ローカルとクラウドの同等性）

ローカルコンテナーでは接続が切断されることはほとんどないため、プーリングとリトライを省略したくなるかもしれません。しかし、省略しないでください。クラウドの Azure SQL Database は、フェールオーバー、スケーリング、負荷の発生時に接続をスロットリングし、切断します。リトライのないクライアントでは、それらが致命的なエラーとして表面化します。ローカルコンテナーを使って、今のうちにプーリングとリトライを実装すれば、同じコードをクラウドでも書き換えずに使えます。クラウドへの移行について詳しくは、azuresql-db-local-to-cloud スキルをご覧ください。

起動後に識別情報を確認します。SELECT SERVERPROPERTY('EngineEdition') は 5 を返し、SERVERPROPERTY('Edition') は 'SQL Azure' を返します。エンジンについて詳しくは、azuresql-db-container スキルをご覧ください。

コンテナーにはクラウドのスロットリングテレメトリが含まれていないため、コンテナーに対するローカル診断は作成しないでください。sys.dm_db_resource_stats と sys.dm_user_db_resource_governance はこのエンジンには存在しません。どちらも OBJECT_ID は NULL を返し、どちらに対するクエリもここでは実行できません。これらが存在しないからといって、クラウドでスロットリングが発生しないという証拠にはなりません。ローカルで障害を発生させられない状態で、以下のリトライポリシーを構築する必要があるのはそのためです。

エンジンと接続の仕様

  • イメージ：sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest（x64 / linux/amd64、プライベートプレビューのレジストリ）。まずサインインしてください。 https://aka.ms/sqldbcontainerpreview-signup にある共有のプル専用認証情報を使って docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io を実行します（認証情報は変更される場合があります）。x64 以外のホストでは、--platform linux/amd64（Docker）または platform: linux/amd64（compose）を追加します。
  • mcr.microsoft.com/mssql/server（SQL Server イメージ）は使用しないでください。
  • 必須の環境変数：ACCEPT_EULA=Y と、複雑な MSSQL_SA_PASSWORD（値の例： YourStr0ng_Passw0rd）。エンジンは1433でリッスンします。
  • エンジンはデータベースを自動作成しません。まず master 接続で CREATE DATABASE appdb を実行してください。データベースの切り替えに USE を使わないでください。ユーザーデータベースへのセッションでは Msg 40508 が返されます。接続文字列でデータベースを選択してください（Database=appdb）。
  • アプリが読み取る環境変数は1つだけです。SQL_CONNECTION_STRING を使います。接続文字列には User Id=／Password=／Database= と TrustServerCertificate=true を使います。sqlcmd では -C を使います。

コンテナーを起動して appdb をプロビジョニングする

HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done
MSSQL_SA_PASSWORD="${MSSQL_SA_PASSWORD:-Aa1%$(openssl rand -hex 16)}"
PLATFORM=(); case "$(docker info -f '{{.Architecture}}' 2>/dev/null)" in x86_64|amd64) ;; *) PLATFORM=(--platform linux/amd64);; esac
docker rm -f sqldb 2>/dev/null
docker run -d --name sqldb "${PLATFORM[@]}" -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=$MSSQL_SA_PASSWORD" \
  -p "127.0.0.1:$HOST_PORT:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
until docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b -l 2 \
  -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" >/dev/null 2>&1; do sleep 2; done
echo "ready on localhost,$HOST_PORT"

アプリが使用する標準の接続文字列（1433が使用中の場合は、1433 を選択した HOST_PORT に置き換えてください）：

Server=localhost,1433;Database=appdb;User Id=sa;Password=$MSSQL_SA_PASSWORD;TrustServerCertificate=true

プーリング：クエリごとに接続を開き直さず、再利用する

  • プーリングは有効のままにします（ほとんどのドライバーではデフォルトで有効です）。アプリでは1つのプールを使用します。
  • 上限のある Max Pool Size（.NET ではデフォルトで 100）を設定し、急増時に接続が無制限に開かれないようにします。推測ではなく、実際の同時実行数に合わせて設定してください。
  • Min Pool Size を小さく設定すると、少数の接続がウォーム状態に保たれ、コールドスタートの遅延を減らせます。
  • 1つの接続文字列につき、プールは1つです。リクエストごとに文字列を動的に生成しないでください（異なる文字列ごとに別のプールが作成されます）。また、呼び出しごとにプールされていない新しい接続を開かないでください。
  • 接続は必ず閉じるか破棄します（または using / with / コンテキストマネージャーを使用します）。これにより、接続のリークを防ぎ、プールに戻せます。

再試行：一時的な障害に限り、バックオフを使用する

再試行するのは、一時的な障害に限ります。スロットリング、一時的なフェイルオーバー、アイドル状態の接続切断などです。Azure SQL では、これらは特定のエラー番号で発生します：40501（スロットリング）、40613（データベースを利用できない）、49918/49919/49920（ビジー）、4060、10928、10929、40197、233、および接続タイムアウトやパイプ切断のソケットエラーです。

  • 再試行するのは、一時的なエラーのみです。一時的でないエラー（ログイン失敗 18456、構文エラー、制約違反、権限拒否）を再試行しても、失敗が遅くなるだけで、実際のバグが見えにくくなります。
  • 上限と少量のジッターを設けた指数バックオフを使用し、試行回数にも上限を設定します（例：5回）。スロットリング中のサーバーに過剰なリクエストを送らないでください。
  • 冪等でない書き込み：接続が切断される前にコミットされた INSERT を再試行すると、二重に適用される可能性があります。クライアント生成キー、MERGE、または処理全体を再実行するトランザクションを使用してください。処理が Execute / トランザクション API を経由する場合、EF Core の実行戦略がこれに対応します。
  • フレームワークに再試行ポリシーがある場合は、自作のループよりもそちらを優先してください（.NET の EF Core EnableRetryOnFailure など）。自作するのは、低レベルのドライバーを使用する場合に限ります。

スタック別

これらのスタックのいずれかを設定する場合は、references/retry-snippets.md を開いてください。各スタックでコピーして使えるプーリング設定と、一時的なエラーに限った再試行が記載されています。

  • .NET（Microsoft.Data.SqlClient）：プーリングキーワード（Max Pool Size、Min Pool Size、Pooling=true）と接続文字列の再試行キーワード（ConnectRetryCount、ConnectRetryInterval）、および EF Core の EnableRetryOnFailure（SqlServer 実行戦略）。
  • Node（mssql / tedious）：プール設定（max / min / idleTimeoutMillis）と、一時的なエラーに限って再試行するラッパー。
  • Python（pyodbc）：接続の再利用と、一時的な ODBC エラーに限って再試行する tenacity 再試行デコレーター。

単一の SQL_CONNECTION_STRING という契約を維持してください。プーリングと再試行はコードおよびドライバー固有のキーワードで調整し、新しい環境変数を勝手に追加しないでください。

検証ルール

  • 再試行が実行されるのは一時的なエラーのみです。一時的でないエラー（認証、構文、制約）は直ちに表面化します。
  • 再試行には指数バックオフを使用し、試行回数に上限を設けます。また、冪等でない書き込みは安全に再実行できるようにします（キー、MERGE、または再試行可能なトランザクション）。
  • プーリングは有効で、Max Pool Size には上限を設定します。接続は破棄されてプールに戻され、クエリごとに開かれることはありません。
  • 接続文字列1つにつきプールは1つです。アプリが読み取る SQL_CONNECTION_STRING は1つのままです。
  • EngineEdition が 5 のエンジンイメージに対して実行します。アプリが接続する前に、master 接続を使って appdb が作成されています。
  • 上記の検証ルールを満たせない場合、またはタスクを完了するためにこのスキルから逸脱する必要があった場合は、このスキルのバグです。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"

禁止事項

  • 一時的なエラーではないエラー（認証、構文、制約）に対して再試行しないでください。再試行しても、失敗するまでの時間が長くなるだけです。
  • 冪等性を保証する手段（キー、MERGE、または再試行可能なトランザクション）なしに、冪等でない書き込みを再試行しないでください。
  • 上限のないプールを設定しないでください。プールを使わず、クエリごとに新しい接続を開かないでください。
  • 余分な環境変数を作らないでください。SQL_CONNECTION_STRING だけを使う契約を維持してください。
  • sys.dm_db_resource_stats または sys.dm_user_db_resource_governance に対するローカルのスロットリング診断を記述しないでください。このエンジンには、どちらのビューも存在しません。
  • mcr.microsoft.com/mssql/server の SQL Server イメージを使用しないでください。また、x64 以外のホストを「サポート対象」と呼ばないでください。

参考資料

  • references/retry-snippets.md：.NET（Microsoft.Data.SqlClient と EF Core の EnableRetryOnFailure）、Node（mssql/tedious のプールと再試行ラッパー）、Python（pyodbc の再利用と tenacity デコレーター）向けの、コピーして使えるプーリング設定と一時的なエラーのみを対象とする再試行の例です。使用するスタックのセクションをお読みください。

最新情報の確認

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

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

コメント

Markdown 対応