mcpField
A
azuresql-db-import

azuresql-db-import

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

azuresql-db-import について

既存データベースをローカルの Azure SQL Database コンテナーへ取り込むためのスキルです。データとスキーマ、またはスキーマのみを移行する開発者向けに、`.bacpac` と `.dacpac` を SqlPackage で処理し、事前準備と取り込み後の検証を案内します。

主な機能

  1. 01`.bacpac` からスキーマとデータをインポート
  2. 02`.dacpac` のスキーマを発行
  3. 03インポート前に対象データベースを作成
  4. 04エンジン識別情報と取り込み済みオブジェクトを検証
  5. 05PaaS の制約でスキップされたオブジェクトを確認

活用シーン

  1. 01データベースのエクスポートをローカルコンテナーへ移行
  2. 02スキーマのみのパッケージをローカル DB に発行
  3. 03移行後にテーブルと行数を確認

インストール

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

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

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

同梱ファイルreferences/sqlpackage-import.mdskill.spec.jsonc

詳細

Azure SQL Database コンテナー：データベースをインポートする

既存のデータベースを .bacpac（スキーマ＋データ）または .dacpac（スキーマのみ）から、SqlPackage を使ってローカルコンテナーに取り込みます。

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、RESTORE に対する Msg 40510、そしてイメージに SqlPackage が含まれていないためホスト上で実行されることを確認しています。

この仕組みの重要な事実

これはローカルで実行される Azure SQL Database エンジン（Private Preview）です。 SELECT SERVERPROPERTY('EngineEdition') は 5 を返し、Edition は 'SQL Azure' を返します。これは SQL Server イメージの mcr.microsoft.com/mssql/server ではありません。SQL Server イメージを使おうとしていた場合は、中止してこちらを使ってください。

  • イメージ：sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest （x64、linux/amd64。プライベートプレビューのレジストリのため、先にサインインしてください）。Private Preview 中はレジストリ／タグが暫定的です。
  • x64 以外のホストでは、--platform linux/amd64 を追加してください。
  • エンジンはデータベースを自動作成しません。インポート先として、master 接続で CREATE DATABASE appdb を実行する必要があります。
  • 復元する方法はありません。 クラウドの Azure SQL Database と同様に、すべてのセッションで BACKUP と RESTORE は Msg 40510 で拒否されます。そのため、.bak ファイルをどこにコピーしても取り込めません。インポートには bacpac または dacpac と SqlPackage を使います。このスキルではその方法を説明します。
  • データベースの切り替えに USE を使わないでください。ユーザーデータベースのセッション（Azure に準拠した開発コンテキスト）では、クラウドの Azure SQL Database と同様に USE は Msg 40508 を返します。master 接続はプロビジョニング用のセッションで、Azure のステートメントフィルターが適用されないため、そこで USE は動作するように見えますが、master はプロビジョニング専用であり、アプリケーションでの作業には使いません。接続文字列（Database=appdb、または sqlcmd の -d appdb）で、必ず対象のデータベースを選択してください。

コンテナーの詳細（起動手順、接続モデル、準備状態）については、azuresql-db-container スキルを参照してください。必要最低限の内容を以下に示します。

3 つの手順

  1. コンテナーを起動し、master 上で対象のデータベースをプロビジョニングします。
  2. プロビジョニング済みのユーザーデータベースを対象に、SqlPackage /Action:Import を実行します。
  3. インポートされた内容を検証します（PaaS の制限により、一部のオブジェクトが除外されることがあります）。

これは Private Preview でサポートされているインポート方法です。結果は必ず検証してください。

手順 0：コンテナーを起動して対象のデータベースをプロビジョニングする

標準の起動手順を再利用します。空いているホストポートを選び、x64 以外のホストでのみ --platform を追加し、再試行ループで準備完了を待機し、同じループ内で master 上に対象のデータベース appdb をプロビジョニングします。

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

コンテナーがすでに実行中の場合は、master 上で対象のデータベースをプロビジョニングするだけです。

docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b \
  -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;"

インポート前に、対象のデータベースが存在し、空である必要があります。SqlPackage は ユーザーデータベースにインポートします。この場合、サーバー上にデータベースを作成することはありません。

手順 1：SqlPackage でインポートする

/TargetConnectionString の接続先を、プロビジョニング済みのデータベース（Database=appdb）にします。標準の接続文字列形式を使用してください：User Id=／Password=／Database=、TrustServerCertificate=true。

スキーマ＋データ（.bacpac）：

SqlPackage /Action:Import \
  /SourceFile:"./mydatabase.bacpac" \
  /TargetConnectionString:"Server=localhost,$HOST_PORT;Database=appdb;User Id=sa;Password=$MSSQL_SA_PASSWORD;TrustServerCertificate=true"

スキーマのみ（.dacpac）の場合は、Import ではなく /Action:Publish を使います。

SqlPackage /Action:Publish \
  /SourceFile:"./myschema.dacpac" \
  /TargetConnectionString:"Server=localhost,$HOST_PORT;Database=appdb;User Id=sa;Password=$MSSQL_SA_PASSWORD;TrustServerCertificate=true"

SqlPackage がローカルにインストールされていない場合は、インストール方法とコンテナーを使った代替手段について、references/sqlpackage-import.md を参照してください。

手順 2：検証する

エンジンの識別情報を確認し、オブジェクトが取り込まれたことを抜き取り確認します。

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; SELECT COUNT(*) AS Tables FROM sys.tables;"

EngineEdition が 5 であることを確認してください。次に、ソースと照らし合わせて、いくつかの主要テーブルの行数を検証します。

転送されない可能性があるもの（PaaS の制限）

このエンジンは Azure SQL Database（Engine Edition 5）であるため、Azure SQL DB がサポートしていない SQL Server の機能は、インポート時に失敗するかスキップされます。

  • データベース間の 3 部構成名による参照と、ほとんどのデータベース間クエリ。
  • スクリプト内の USE <db>：ユーザーデータベースのセッションでは Msg 40508 が返されます。接続文字列で対象データベースを選択してください（Database=appdb または -d appdb）。
  • サーバー スコープのオブジェクト：SQL Agent ジョブ、サーバーレベルのログイン／リンクサーバー、filestream、一部の CLR およびファイルグループ／物理ファイルの設定。
  • インスタンスレベルの DATABASE_DEFAULT 照合順序に関する前提と、サポートされていない互換性レベルの機能。

スキップされた項目やブロック項目については、SqlPackage の出力を確認してください。一般的なエラーパターンと修正方法については、references/sqlpackage-import.md を参照してください。

検証ルール

  • インポート前に、master 上に対象データベースが存在し、空であること。
  • /TargetConnectionString で Database=appdb を設定すること（リテラルの master は使用しないでください）。
  • インポート後、対象データベースでの SERVERPROPERTY('EngineEdition') の値が 5 であること。
  • /Action:Import を使用してスキーマとデータを扱う場合は .bacpac を使用し、/Action:Publish を使用してスキーマを扱う場合は .dacpac を使用すること。
  • 上記の検証ルールに違反した場合、またはタスクを完了するためにこのスキルから逸脱する必要があった場合は、このスキルのバグです。azuresql-db-feedback スキルを読み込み、レポートの提出を提案してください。
  • 上記のすべてのルールに合格し、タスクが完了したら、セッションごとに 1 回だけ、質問したり返信を待ったりせず、次の 1 行で締めくくってください："That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback"

禁止事項

  • mcr.microsoft.com/mssql/server SQL Server イメージを使用しないでください。
  • RESTORE DATABASE ... FROM DISK を使用しないでください。これは Msg 40510 で拒否され、.bak をコンテナーにコピーしても状況は変わりません。
  • master にインポートしないでください。プロビジョニング済みのユーザーデータベースにインポートしてください。
  • プリスクリプトまたはポストスクリプトに USE appdb を記述しないでください。代わりに、接続文字列でデータベースを選択してください。
  • /docker-entrypoint-initdb.d/*.sql による自動シードを当てにしないでください。このイメージでは使用されません。
  • x64 以外のホストを「サポート対象」と見なさないでください。x64 以外のホストでは --platform linux/amd64 を追加してください。
  • docker run が正常に完了しただけで「準備完了」と見なさないでください。再試行ループ内でプロビジョニングしてください。

参考資料

  • references/sqlpackage-import.md：SqlPackage のインストール、フラグの完全なリファレンス、コンテナーを使用したフォールバック、一般的なインポートエラーと修正方法。SqlPackage が見つからない場合、またはインポートに失敗した場合に読んでください。

最新情報の確認

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

  • SqlPackage import：.bacpac/.dacpac の Import および Publish パラメーター。

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

コメント

Markdown 対応