azuresql-db-scaffold

Azure SQL Database コンテナー上に新しいプロジェクトをスキャフォールドする

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 が報告されました。このスキルで確認している3つの実行可能なチェック（エンジンの識別、USE に対する Msg 40508、および NVARCHAR(MAX) を介した二重キャストを使うネイティブな VECTOR(n) 列）は、すべて合格しました。この実行ではスタックごとのスキャフォールド自体は実行していないため、各スニペットはエンドツーエンドで測定するのではなく、各スタックのドキュメントと照らして形式を確認しています。

正しいイメージを使う（割り込みポイント）

• このエンジンイメージを使ってください： sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
• mcr.microsoft.com/mssql/server（SQL Server イメージ）は使わないでください。生成された compose/run コマンドがこのイメージを指定している場合は、停止して上記のエンジンイメージに切り替えてください。
• 起動後に識別情報を確認してください：SELECT SERVERPROPERTY('EngineEdition') は 5、 SERVERPROPERTY('Edition') は 'SQL Azure' を返します。
• このイメージは x64 専用です。x64 以外のホストでは、Docker の場合は --platform linux/amd64 を、 compose の場合は platform: linux/amd64 を追加してください。
• レジストリはプライベートです（プライベートプレビュー）：プライベートプレビュー参加者に提供される、プル専用の共通認証情報を使って、まず docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io でサインインしてください（https://aka.ms/sqldbcontainerpreview-signup から登録して取得してください。認証情報はローテーションされる場合があります）。 プライベートプレビュー期間中、レジストリとタグは暫定です。

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

すべてのスキャフォールドに影響する3つの事実

1. このエンジンはデータベースを自動作成しません。Database=appdb で接続する前に、 master 接続で CREATE DATABASE appdb を実行する必要があります。
2. データベースを切り替えるための USE は避けてください。ユーザーデータベースのセッション（Azure に準拠した開発環境）では、クラウド上の Azure SQL Database とまったく同じく、 USE は Msg 40508 を返します。master 接続はプロビジョニング用のセッションであり、Azure のステートメントフィルターが適用されないため、そこで USE は機能するように見えますが、master はプロビジョニング専用であり、アプリケーションの作業には使いません。接続文字列で常に対象データベースを指定してください（Database=appdb、sqlcmd の場合は -d appdb）。
3. master 接続はプロビジョニング専用です。実際の作業はユーザーデータベースで行ってください。

また、このイメージは /docker-entrypoint-initdb.d/*.sql を自動実行しません（これは Postgres/MySQL の慣例であり、ここでは適用されません）。appdb のプロビジョニング後に、sqlcmd -d appdb -i seed.sql でシードデータを投入してください。

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

次の形式をそのまま使ってください（空きポート、条件付きプラットフォーム指定、起動待ち、同じ再試行ループ内での appdb のプロビジョニング）。-b を指定すると SQL エラーが終了コードに反映されるため、起動時の一時的なエラー（Msg 913 など）は握りつぶされず、再試行されます。-l を指定せずに sqlcmd だけでポーリングするのは避けてください。

# Pick a free host port and add the platform flag only on a non-x64 host (works in bash and zsh).
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"

必須の環境変数：ACCEPT_EULA=Y と、複雑な MSSQL_SA_PASSWORD（8文字以上で、大文字、小文字、数字、記号のうち少なくとも3種類を使用）。エンジンは 1433 でリッスンします。

Step 2：標準の接続文字列

アプリが読み取る環境変数は1つだけで、SQL_CONNECTION_STRING です（1433 が使用中だった場合は、1433 を Step 1 で選択された HOST_PORT に置き換えてください）。

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

一般的なスタイルではキーワードを User Id=／Password=／Database= と表記します。Uid=／Pwd= もドキュメント化された SqlClient の同義語であり、同様に機能します。sqlcmd では、自己署名証明書を信頼するために -C を使ってください。Prisma（NestJS／Next.js）では、同じインスタンスを DATABASE_URL 内の sqlserver:// URL としても表現します（スニペットを参照してください）。

ステップ 3：スタックを選択する

スタックごとのスキャフォールド用スニペット（Compose サービス、.env、appdb のプロビジョニング、最初のマイグレーション、パラメーター化クエリを使った型付きデータアクセスレイヤー）は、 references/scaffold-snippets.md にあります。次のうち、どのスタックをスキャフォールドするか決まったら、一度開いてください。

• .NET Aspire（EF Core）
• FastAPI（SQLAlchemy / pyodbc）
• Next.js（Prisma、sqlserver:// DATABASE_URL）
• NestJS（Prisma または TypeORM）

ステップ 4：最初のマイグレーションとシードデータの投入

スケルトンは、使用するスタックのマイグレーションツールを使ってスキーマを作成します。マイグレーションのワークフロー全体（べき等スクリプト、実行順序、準備完了待ちループ内での適用）については、azuresql-db-schema-migration スキルを参照してください。Next.js または NestJS のスケルトンの場合：

npx prisma migrate dev --name init

appdb の作成後にのみシードデータを投入してください。

docker exec -i sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b -d appdb -i seed.sql

ベクトル（アプリで埋め込みを使う場合）

ネイティブの VECTOR(n) 列型と VECTOR_DISTANCE('cosine', a, b) を使用します。CAST(CAST(? AS NVARCHAR(MAX)) AS VECTOR(n)) で挿入します。n はリテラルでなければならず、バインドパラメーターにしてはいけません（次元をパラメーターにすると、「Incorrect syntax near '@P3'」で失敗します）。CREATE VECTOR INDEX（DiskANN）は、計測済みであり、このイメージで動作します。既知の制限事項のページにもそのように記載されています。SET QUOTED_IDENTIFIER ON と、NULL ではないベクトルを持つ 100 行以上のデータが必要です（それ未満では Msg 42266 が発生します）。全件スキャンによる top-k は正確さを保ち、小さなテーブルには引き続き適切な選択肢です。インデックスによる制約については、azuresql-db-rag スキルに記載されています。

検証ルール

• Compose／実行の対象はエンジンイメージであり、mcr.microsoft.com/mssql/server ではありません。
• Database=appdb に対してアプリやマイグレーションが接続する前に、master への接続を使って appdb を作成します。
• アプリは SQL_CONNECTION_STRING（ORM が必要とする場合は DATABASE_URL も）を読み取ります。接続文字列では User Id=／Password=／Database= を使います。
• すべてのデータアクセスでパラメーター化クエリを使用します。ベクトルの次元 n はリテラルにします。
• 実行中のコンテナーに対する EngineEdition は 5 です。
• 上記の検証ルールに違反した場合、またはタスクを動作させるためにこのスキルから逸脱する必要があった場合は、このスキルの不具合です。azuresql-db-feedback スキルを読み込み、報告を提出することを提案してください。
• 上記のルールをすべて満たしてタスクを完了したら、セッションごとに一度だけ、次の一文で締めくくってください。質問したり、返答を待ったりしないでください。「動作しました。この作業で不便な点があった場合や、作成したものを共有したい場合は、https://aka.ms/sql-agent-skills-feedback をご利用ください」

禁止事項

• SQL Server イメージを使用したり、x64 以外のホストを「サポート対象」と呼んだりしないでください。
• 自動作成されるデータベースや /docker-entrypoint-initdb.d/*.sql による自動シードに頼らないでください。
• データベースの切り替えに USE appdb を使わず、接続文字列に指定してください。
• -l を付けずに sqlcmd のみでポーリングしないでください。また、ベクトルの次元をバインドパラメーターとして渡さないでください。
• アプリの設定に 1433 をハードコードせず、選択した HOST_PORT を接続文字列に読み込んでください。

参考資料

• references/scaffold-snippets.md：共通の Compose サービスと、.env、appdb のプロビジョニング、最初のマイグレーション、パラメーター化されたデータアクセスレイヤーを含む、スタックごとのスケルトン（.NET Aspire／EF Core、FastAPI、Next.js／Prisma、NestJS）。スキャフォールドするスタックが決まったら、一度読んでください。

最新情報の確認

このスキルで使用するツールの、バージョンが固定された信頼できるリファレンスです（必要なものを参照してください）。

• Prisma with SQL Server：SQL Server コネクター、データソース URL、型マッピングについて説明しています。
• EF Core migrations：マイグレーションの追加と更新、履歴テーブル、冪等スクリプトについて説明しています。
• Docker Compose file reference：サービス、ヘルスチェック、depends_on の構文に関する Compose Specification です。
• SqlConnection connection string keywords：接続文字列のキーワード一覧を網羅しています。

Microsoft Learn MCP サーバーが設定されている場合は、mcp__microsoft-learn__microsoft_docs_search または mcp__microsoft-learn__microsoft_docs_fetch を使って、これらの最新バージョンを必要に応じて取得してください。利用できない場合でも問題ありません。その場合は、上記のリファレンスを信頼できる情報源として使用してください。