azuresql-db-schema-migration

Azure SQL Database コンテナーでのスキーマ移行

クラウドに対して実行するのと同じ方法で、ローカルの Azure SQL Database コンテナーにスキーマ移行を適用し、開発環境と本番環境を同一に保ちます。これは Azure SQL Database エンジンです（SELECT SERVERPROPERTY('EngineEdition') は 5 を返し、Edition は 'SQL Azure' を返します）。SQL Server イメージの mcr.microsoft.com/mssql/server ではありません。ツールやテンプレートが SQL Server イメージを指定している場合は、そこで止めて、代わりに以下のイメージを使用してください。

2026-09-05 に、コンテナーイメージ sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest に対して検証済みです。EngineEdition は 5、Edition は SQL Azure、ビルドは 12.0.2000.8 でした。このスキルの6つの実行可能なチェックはすべて合格しました。エンジンの識別、USE に対する Msg 40508、移行 DDL 内の VECTOR(n) 列、SqlPackage 170.4.83.3 自身のヘルプに記載されている3つの Publish パラメーターと /TargetTrustServerCertificate、および Entity Framework Core .NET コマンドラインツール 9.0.19 での dotnet ef database update です。

あらゆる移行ツールで問題となる唯一のルール

このエンジンは、接続時にデータベースを自動作成しません。すべての移行ツールは、接続先のデータベースがすでに存在することを前提としています。そのため、次の手順を実行してください。

1. まず、master 接続で appdb をプロビジョニングします。
2. その後、移行ツールの接続先をユーザーデータベース（Database=appdb）に指定します。

データベースの切り替えに USE を使用しないでください。ユーザーデータベースのセッション（開発時に使用する Azure に準拠したコンテキスト）では、クラウドの Azure SQL Database と同様に、USE は Msg 40508 を返します。master 接続は Azure のステートメントフィルターが適用されないプロビジョニング用のセッションなので、そこで USE は機能するように見えます。しかし、master はプロビジョニング専用であり、アプリケーションの作業には使用しません。接続文字列で必ず接続先データベースを選択してください（Database=appdb、または sqlcmd の場合は -d appdb）。master 接続はプロビジョニング専用です。移行は appdb に対して実行してください。

コンテナーを起動して appdb をプロビジョニングする（標準手順）

docker run が戻った時点では、エンジンの準備ができていない場合があります。再試行ループで待機し、同じループ内で appdb を作成します。イメージは x64 専用です。x64 以外のホストでは、この手順により --platform linux/amd64 が自動的に追加されます。Private Preview 期間中、レジストリはプライベートなので、先にサインインしてください。

docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io   # pull-only creds by signing up at https://aka.ms/sqldbcontainerpreview-signup

# 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"

-C は自己署名証明書を信頼します。-b は SQL エラー時に終了コードを設定するため、（Msg 913 などの）一時的な起動エラーがマスクされず、再試行されます。-l を指定せずに sqlcmd のみでポーリングしないでください。ライフサイクルの詳細については、azuresql-db-container スキルを参照してください。

接続文字列の管理

形式を1つに統一し、単一の SQL_CONNECTION_STRING 環境変数から読み取るようにします。

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

• ハウススタイルとして、キーワードは User Id= / Password= / Database= と表記します。Uid= / Pwd= は、ドキュメントに記載されている SqlClient の同義語で、こちらも使用できます。
• 移行およびアプリケーションの作業では、master ではなく Database=appdb を指定します。
• ローカルの自己署名証明書には TrustServerCertificate=true を指定します。
• 上記でデフォルト以外の HOST_PORT を選択した場合は、Server=localhost,<HOST_PORT> を使用します。

移行を適用する（ツール別）

以下のツールを使う前に、上記の手順で appdb をプロビジョニングしてください。各ツールのすべてのオプション、環境変数の設定、トラブルシューティングについては、references/migration-tools.md を参照してください。

EF Core（.NET）

export SQL_CONNECTION_STRING="Server=localhost,1433;Database=appdb;User Id=sa;Password=${MSSQL_SA_PASSWORD};TrustServerCertificate=true"
dotnet ef database update

EF Core の EnsureCreated / Migrate は、アカウントにデータベースの作成権限がある場合に限り、appdb を作成します。まず master でプロビジョニングする方法が確実です。デザイン時ファクトリーと CI（migrations bundle）形式については、リファレンスを参照してください。

Prisma（Node）

Prisma では、DATABASE_URL に sqlserver:// 形式の URL が必要です。

npm install -D prisma@6
npm install @prisma/client@6
export DATABASE_URL="sqlserver://localhost:1433;database=appdb;user=sa;password=${MSSQL_SA_PASSWORD};trustServerCertificate=true"
npx prisma migrate deploy          # apply committed migrations (CI / prod-like)
npx prisma migrate dev --name init # author + apply a new migration (local dev)

@6 のままにしてください。Prisma 7 が現在の安定版（7.10.0）ですが、以下の url = env("DATABASE_URL") データソースブロックは拒否されます。prisma migrate は検証時に「スキーマファイルでは datasource プロパティ url はサポートされなくなりました」というエラーで停止します。Prisma 7 では接続 URL を prisma.config.ts に移し、クライアントにドライバーアダプター（@prisma/adapter-mssql）を使用するため、これはバージョンの引き上げではなく設定の変更です。npm に選ばせず、メジャーバージョンを明示して固定してください。prisma の latest ディストタグには、8.x のプレリリースが含まれていたことがあります。Prisma 7 の設定方法については、参考資料を参照してください。

Alembic（Python）

export SQL_CONNECTION_STRING="mssql+pyodbc://sa:${MSSQL_SA_PASSWORD}@localhost,1433/appdb?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes"
alembic upgrade head

SqlPackage / DACPAC

sqlpackage /Action:Publish /SourceFile:./app.dacpac \
  /TargetServerName:"localhost,1433" /TargetDatabaseName:appdb \
  /TargetUser:sa /TargetPassword:"$MSSQL_SA_PASSWORD" \
  /TargetTrustServerCertificate:true

マイグレーションでのベクトル

このエンジンには、ネイティブの VECTOR(n) 列型と VECTOR_DISTANCE('cosine', a, b) があります。マイグレーションでは、次元 n は DDL 内でリテラルにする必要があります（embedding VECTOR(1536)）。CAST(CAST(? AS NVARCHAR(MAX)) AS VECTOR(n)) を介して挿入する場合、n はリテラルでなければならず、バインドパラメーターにはできません（次元をパラメーターにすると「Incorrect syntax near '@P3'」で失敗します）。内側の NVARCHAR(MAX) キャストにより、実際の埋め込みの JSON が ntext として送信されるのを防ぎます。エンジンは ntext を拒否します（エラー 529）。CREATE VECTOR INDEX（DiskANN）はこのイメージで動作することを実測で確認しており、既知の制限に関するページにも記載されています。マイグレーションでは、次の 3 点が重要です。

• DDL を実行するセッションで SET QUOTED_IDENTIFIER ON が必要です。また、null ではないベクトルを含む行が 100 件未満の場合、作成は拒否されます（Msg 42266）。そのため、インデックスは CREATE TABLE と同時ではなく、コーパスの読み込み後に実行するマイグレーション手順に含めます。
• インデックスが存在する間は TRUNCATE TABLE が拒否されます（Msg 42232）。テーブルを再読み込みするマイグレーションでは、まずインデックスを削除する必要があります。また、DROP VECTOR INDEX はステートメントではないため、DROP INDEX name ON dbo.table を使用します。
• Microsoft Learn のドキュメントによると、データ階層パッケージのインポートでは、インポート時に行の読み込みより先にスキーマが作成され、インデックスが 100 行の最小要件に抵触するため、ベクトルインデックスを引き継ぐことはできません。エクスポート前にベクトルインデックスを削除し、インポート後に再作成してください。

小さなテーブルでは、フルスキャンによる top-k が引き続き正確で、適切な選択肢です。

マイグレーション後のシード投入

このイメージは /docker-entrypoint-initdb.d/*.sql を自動実行しません（これは Postgres/MySQL の慣習であり、ここでは適用されません）。マイグレーション後に明示的にシードを投入してください。

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

検証ルール

• マイグレーションツールの実行前に、master 上に appdb が存在します。
• マイグレーションツールの接続先は master ではなく Database=appdb です。
• 接続文字列では User Id=／Password=／Database= を使用し、TrustServerCertificate=true を指定します。
• USE appdb はどこにも使用しません。接続文字列でデータベースを選択してください。ユーザーデータベースのセッションで USE を実行すると、クラウド上の Azure SQL Database と同様に Msg 40508 が返されます。プロビジョニング専用の master セッションでのみ動作するように見えます。
• -b -l を指定して準備完了を待つループを実行し、マイグレーション前にコンテナーが「ready」と報告しました。
• 上記の検証ルールに違反した場合、またはタスクを完了するためにこのスキルから逸脱する必要があった場合は、このスキルのバグです。azuresql-db-feedback スキルを読み込み、レポートの提出を提案してください。
• 上記のすべてのルールを満たし、タスクが完了したら、セッションごとに 1 回だけ、1 行で締めくくってください。質問したり、返答を待ったりしないでください。「うまくいきました。この作業で何か大変だった点があったり、作成したものを共有したい場合は、こちらをご利用ください：https://aka.ms/sql-agent-skills-feedback」

禁止事項

• SQL Server イメージ mcr.microsoft.com/mssql/server は使用しないでください。
• 接続時にデータベースが自動作成されることを期待しないでください。
• データベースの切り替えに USE <db> を使用しないでください。
• /docker-entrypoint-initdb.d/ による自動シード投入に依存しないでください。
• x64 以外のホストを「サポート対象」と呼ばないでください。x64 以外のホストでは --platform linux/amd64 を追加してください。
• ベクトルの次元をバインドパラメーターとして渡さないでください。
• master への接続でマイグレーションを実行しないでください。

参考資料

• references/migration-tools.md：ツールごとの詳細な接続設定（EF Core、Prisma、Alembic、SqlPackage）、環境変数の設定、よくあるマイグレーションの失敗について記載しています。上記のコマンドだけでは不十分な場合や、マイグレーションが失敗した場合に参照してください。

最新情報の確認

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

• EF Core のマイグレーション：マイグレーションの追加／更新、履歴テーブル、冪等性のあるスクリプトについて説明しています。
• SQL Server での Prisma：SQL Server コネクター、データソース URL、型マッピングについて説明しています。
• Alembic：SQLAlchemy のマイグレーション、env.py、自動生成、アップグレード／ダウングレードについて説明しています。
• SqlPackage のインポート：.bacpac/.dacpac のインポートおよび発行のパラメーターについて説明しています。

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