Claude CodeのAzure SQL Developerプラグインでローカル開発する
Microsoftのプラグインを入れ、ローカルコンテナのAzure SQLに接続して開発する手順です。17個のスキルの役割、使えない機能、クラウドへの移し方まで扱います。
Claude CodeでAzure SQLのアプリを作るとき、AIが最初に選びがちなのは mcr.microsoft.com/mssql/server のSQL Serverイメージです。Azure SQL Databaseと同じ挙動を手元で試したいなら、これは別の製品です。
Microsoftが出している azure-sql-developer プラグインは、この取り違えを防ぐためのスキル集です。Azure SQL Databaseのエンジンをローカルのコンテナで動かし、接続、移行、RAG、CI、クラウドへの移行までをClaude Codeに任せられるようにします。
ただしコンテナのイメージはPrivate Previewで、サインアップしないと手に入りません。導入前に押さえる条件から順に説明します。
このプラグインが入れるのは17個のスキル
マーケットプレイスの説明では、Azure SQL Developerは「Azure SQL Databaseエンジンをコンテナでローカル実行するためのエージェントスキル」です。エンジンの起動、接続、移行、足場作り、RAG構築、CI設定、ローカルからクラウドへの移行をエージェントに教えます。SQL Serverのイメージではなく、Private Previewの実イメージを使う点が特徴です。
マーケットプレイスの掲載名は azure-sql-developer です。提供元リポジトリ側のプラグイン名は azure-sql-database-container で、中身はスキル17個のコレクションです。インストールコマンドに書くのは後者の名前です。
プラグインのバージョンは1.1.0です。各スキルは、公開のMicrosoft Learn MCPを通じて最新のドキュメントを引くこともできます。これは任意で、MCPなしでもスキルは動きます。
17個のスキルの役割
エンジンを動かす
azuresql-db-containerが起動とready待ちを担当します。azuresql-db-from-sql-serverはSQL Serverイメージからの切り替え、azuresql-db-sidecarはdocker composeやDev Containerへの組み込みです。スキーマとデータ
azuresql-db-schema-migration(EF Core、Prisma、Alembic、SqlPackage)、azuresql-db-import(.bacpac / .dacpacの読み込み)、azuresql-db-seed(外部キー順のテストデータ投入)があります。アプリを作る
azuresql-db-scaffoldは新規アプリの足場、azuresql-db-dabはData API BuilderによるREST / GraphQL、azuresql-db-functionsはAzure Functionsとの連携、azuresql-db-ragはベクトル検索です。品質と運用
azuresql-db-testing(Testcontainersで都度起動)、azuresql-db-ci(GitHub Actions)、azuresql-db-connections(プールとリトライ)、azuresql-db-auth(最小権限ユーザー)、azuresql-db-local-to-cloud(クラウド移行)が並びます。相談と報告
azuresql-db-faqは「このコンテナで何ができて何ができないか」に答えます。azuresql-db-feedbackは不具合報告の下書きを作り、ユーザーの確認なしには何も送りません。
各スキルは単独でも使えます。1つだけ入れる場合は --skill オプションでスキル名を指定します。スキル同士の受け渡しが効かなくなる点だけが、全部入れない場合の損失です。
導入前に確認する条件
コンテナの条件は、プラグインの導入より先に確認します。イメージの取得にはサインアップが要るため、ここを飛ばすと最初のpullで止まります。
動かすための前提
- コンテナのイメージは非公開レジストリにあり、Private Previewにサインアップして得たユーザー名とパスワードが必要です
- 認証情報は取得専用で、プレビュー期間中に更新されることがあります
- 対応OSはmacOS 14以降、Linux(Ubuntu、Debian、Fedora)、Windows 11(WSL2)で、x86_64とARM64のどちらも動きます
- コンテナランタイムはDocker 24以降、Podman 5.0以降、Rancher Desktop 1.13以降、containerd、WSLコンテナです
- ランタイムに割り当てるのは2コア、4GBのメモリ、10GBのディスクが最低ラインです
- 初回のpullにはネット接続が必要で、その後は完全にオフラインで動きます
Azureのサブスクリプションは、ローカル開発だけなら要りません。クラウドへ移す段階で初めて、Azure SQL Databaseサーバーと、App ServiceやContainer Appsなどのアプリ側リソースを作れる権限が必要になります。
もう1つ大事なのは用途の制限です。このコンテナは開発、テスト、CI、デモ向けで、本番のデータベースではありません。Private Previewのライセンスもその範囲に限られています。
プラグインを入れてスキルを確かめる
導入はClaude Code内で2コマンドです。
/plugin marketplace add microsoft/azure-sql-database-container
/plugin install azure-sql-database-container@azure-sql-database-container
/reload-plugins1行目でリポジトリをマーケットプレイスとして登録し、2行目でプラグインを入れます。/reload-plugins で現在のセッションに反映します。
プラグインを使わず、npx skills add でスキルだけを入れる方法もあります。Claude Code、Codex、Cursor、VS Code with GitHub Copilotで共通のコマンドです。
npx skills add microsoft/azure-sql-database-container \
-a claude-code-a claude-code を付けているのには理由があります。READMEによると、npx のインストーラーは成功と表示しながら、Claude Code用の場所に何も置かないことがあります。.agents/skills/ には入っているのに .claude/skills/ が空、という状態です。プラグイン経由の導入はこの問題の影響を受けません。
入ったかどうかは、スキルのフォルダーで確かめます。
ls .claude/skills/azuresql-db- で始まるディレクトリが並んでいれば成功です。
最初の起動はユーザー自身がログインする
エージェントに頼める作業と、頼めない作業があります。レジストリへのログインは後者です。パスワードは秘密情報で、ログインは対話式のため、エージェントには実行できません。先にユーザーが一度だけ実行します。
docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io \
-u <username>レジストリ名、イメージ名、ポート、接続文字列はスキルが知っています。ログインさえ済ませれば、あとは普通の言葉で頼めます。
このプロジェクトにローカルのAzure SQL Databaseを追加して、
スキーマ、マイグレーション、データアクセス層を今の技術スタックで作って。エージェントがこの依頼で動かす手順は、スキルの定義に書かれています。空いているホストポートを探し、イメージを docker run で起動し、エンジンが応答するまで待ち、appdb を作ります。
起動後、まず確かめるべきは接続先が本当にAzure SQLのエンジンかどうかです。
docker exec sqldb /opt/mssql-tools18/bin/sqlcmd \
-S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b \
-d appdb \
-Q "SELECT SERVERPROPERTY('EngineEdition') AS EngineEdition, \
SERVERPROPERTY('Edition') AS Edition;"正しいエンジンなら EngineEdition が5、Edition が SQL Azure になります。別の値が返るなら、SQL Serverのイメージを起動しています。
通しで確かめたいときは、スキルに同梱の scripts/verify.sh が使えます。ポート選択から起動、ready待ち、エンジンの識別、appdb の作成、後片付けまでを1回で検査し、失敗すると非ゼロで終了します。コンテナを残したいときは --keep を付けます。
初心者がつまずく接続の3つの決まり
スキルが繰り返し強調するのは、次の3点です。SQL Serverの経験者ほど逆の動きをしてしまいます。
接続で守ること
- 1
データベースは自動で作られない
接続前に、masterへの接続で
CREATE DATABASE appdbを実行します。appdbという名前は例で、実プロジェクトでは自分の名前に置き換えます。作る前にDatabase=appdbで接続すると失敗します。 - 2
切り替えに USE を使わない
ユーザーデータベースへの接続で
USEを実行すると、クラウドのAzure SQL Databaseと同じくMsg 40508が返ります。接続文字列のDatabase=で選びます。 - 3
master接続は作成専用
masterは、データベースやログインを作るための接続です。アプリの処理はすべてユーザーデータベースで行います。
シード用のSQLも同じ考え方です。このイメージは /docker-entrypoint-initdb.d のSQLを自動実行しません。PostgreSQLやMySQLの感覚で置いても動かないため、sqlcmd -d appdb -i で明示的に流します。
CLAUDE.mdに書いておく指示の例
プラグインはスキルの形で知識を渡しますが、スキルは毎回確実に呼ばれるとは限りません。プロジェクトの規約として最低限の線を引いておくと、取り違えを減らせます。以下はスキルの記述を元にした例です。
## データベース
- ローカルDBは Azure SQL Database コンテナ(azuresql-db-container スキル)を使う
- mcr.microsoft.com/mssql/server は使わない。SQL Server とは別製品
- 起動後に SERVERPROPERTY('EngineEdition') が 5 であることを確認する
- DB の切り替えに USE を使わず、接続文字列の Database= で指定する
- アプリは sa ではなく最小権限のログインで接続する
- レジストリのパスワードは扱わない。docker login は人が実行する最後の行は、設定でも強制できます。次の例は docker login をそもそも許可しない設定です。
{
"permissions": {
"deny": ["Bash(docker login:*)"]
}
}エージェントが対話式のログインに入り込むのを、設定の側でも止められます。
アプリ側の接続とマイグレーション
アプリは SQL_CONNECTION_STRING という1つの環境変数から接続文字列を読む、という規約をスキルが採っています。ローカルの文字列は次の形です。
Server=localhost,1433;Database=appdb;User Id=applogin;Password=<パスワード>;Encrypt=true;TrustServerCertificate=trueTrustServerCertificate=true は、コンテナの自己署名証明書を受け入れるための設定です。クラウドのAzure SQL Databaseに向けるときは付けません。クラウドの証明書は本物で、検証することに意味があるからです。
接続ユーザーも sa のままにしません。azuresql-db-auth スキルは、masterにログインを作り、ユーザーデータベースにそのログインのユーザーを対応づけ、必要なロールだけを付ける手順を示します。
-- masterへの接続で
CREATE LOGIN applogin WITH PASSWORD = '<強いパスワード>';
-- appdbへの接続で
CREATE USER appuser FOR LOGIN applogin;
ALTER ROLE db_datareader ADD MEMBER appuser;
ALTER ROLE db_datawriter ADD MEMBER appuser;db_owner は付けません。ここにはクラウドとの違いがあります。クラウドのAzure SQL Databaseでは、包含ユーザー(CREATE USER ... WITH PASSWORD)が普通です。ところがこのコンテナでは、Msg 33233で拒否され、有効にもできません。スキルの記述では、ローカルはログインにひもづくユーザーを使います。
マイグレーションはEF Core、Prisma、Alembic、SqlPackageのどれでも、先に appdb を作ってから、ユーザーデータベースに対して流します。この順序を飛ばす、あるいはmasterに流すと、スキーマが意図しない場所にできます。
コンテナで動くものと動かないもの
クラウドと同じに見えても、同じではありません。Microsoftの制限事項のページに書かれた差分のうち、開発に響くものを挙げます。
| 項目 | コンテナでの扱い |
|---|---|
| BACKUP / RESTORE | コンテナでの扱い使えない(Msg 40510)。クラウドも同じ |
| データの保持 | コンテナでの扱いDockerのnamed volumeに保存する |
| PaaSの制約 | コンテナでの扱い一部がコンテナでは未適用。ローカルで通ったクエリがクラウドで失敗しうる |
| 既定値(照合順序など) | コンテナでの扱いクラウドと完全には一致しない |
| 2段階のプロビジョニング | コンテナでの扱いmaster接続でDBを作ってから再接続する |
| SSMSとVS CodeのMSSQL拡張 | コンテナでの扱いUIエラーが出ることがある。sqlcmdやドライバーは問題なし |
| DTU / vCoreの上限 | コンテナでの扱いコンテナでは強制されない |
PaaSの制約が未適用という点は見落としやすい箇所です。ローカルで通ったクエリでも、クラウドで一度も流さないまま出荷すると、未適用の制約に本番で初めて当たります。提供元は、準備ができたと言う前に、Azure SQL Databaseの実インスタンスで一度流すことを回避策に挙げています。azuresql-db-local-to-cloud スキルが、確認用のデータベースの用意を手伝います。
ベクトル検索はルールが多い
RAG用に azuresql-db-rag を使うなら、制限事項の記述を先に読んでください。ネイティブの vector 型と VECTOR_DISTANCE が使え、CREATE VECTOR INDEX(DiskANN)も動きます。ただし条件があります。
- セッションで
SET QUOTED_IDENTIFIER ONが必要です。sqlcmdでは既定でオフです - ベクトルが入った行が100行未満だと、Msg 42266で失敗します
- インデックスがあるテーブルは
TRUNCATE TABLEできません(Msg 42232) - セキュリティポリシーとベクトルインデックスは同じテーブルに同居できません
もう1点、インデックスを読むのは VECTOR_SEARCH を使う TOP (N) WITH APPROXIMATE の形だけです。VECTOR_DISTANCE のクエリは常に厳密計算で、インデックスがあっても使いません。小さいテーブルでは結果が同じなので、警告も出ません。インデックスを作ったのに古いクエリのままだと、全件走査が続きます。
提供元は、インデックスの測定が数百行の低次元データに限られているとも書いています。768次元や1536次元の本番規模のデータでは、自分のデータで測る必要があります。
範囲外になるもの
SQL Server由来の機能は意図的に入っていません。SQL Agent、FILESTREAM、完全なService Broker、Windows認証、複数サーバーをまたぐ分散トランザクションなどです。エラスティックプールやHyperscaleのようなPaaSの階層機能も、エンジンではなくクラウドサービスの特性なので対象外です。
クラウドへ移すときに変わるもの
コードは変えず、接続文字列だけを変えるのが基本方針です。変わる点は認証方式に集中します。
接続の違い
ローカルのコンテナ
SQL認証で、最小権限のログインを使います。Encrypt=true に加えて TrustServerCertificate=true を付けます。
Azure SQL Database
パスワードではなくトークン方式を選びます。本番では Active Directory Default より Active Directory Managed Identity のほうが、資格情報の探索が省けます。TrustServerCertificate は付けません。
Entra IDの認証はコンテナでも使えますが、エンジン側で有効にしておく必要があります。設定なしで CREATE USER ... FROM EXTERNAL PROVIDER を実行すると、Msg 33134で拒否されます。文が壊れているのではなく、設定が足りていない状態です。
クラウド側のリソースを作るところから先は、AzureプラグインでClaude Codeにデプロイさせる流れが使えます。手順はAzureプラグインでazure-prepareからデプロイまで進める記事にまとめています。同じAzureのデータベースでも、NoSQLのAzure Cosmos DBプラグインは別の仕組みです。
他のデータベースプラグインとの違い
Claude Codeのデータベース系プラグインの多くは、すでにあるクラウドのインスタンスに接続して操作します。たとえばAlloyDBプラグインやCloud SQL for PostgreSQLプラグインは、そうした構成です。
このプラグインは向きが逆です。接続する先を、手元のコンテナとして作るところから始めます。課金されるクラウドのインスタンスを持たずに、スキーマ変更やテストを何度でもやり直せます。代わりに、そこで通ったものが本番でも通るという保証は、前節の差分の分だけ弱くなります。
まとめ
このプラグインの価値は、Azure SQL向けの開発環境を作る手順をエージェントに持たせる点にあります。イメージの取得がPrivate Previewのサインアップに依存することと、ログインだけは人が実行することを先に理解しておけば、導入時の詰まりどころはこの2点に集中します。
使い方の判断は2つです。ローカルで通ったクエリをクラウドで一度試すこと、ベクトルインデックスを使うなら自分のデータの規模で測ることです。この2つを飛ばすと、ローカルの快適さがそのまま本番の不具合になります。