Azure SQL DeveloperコンテナーをローカルやCIで使うには、プライベートプレビューへの参加、専用レジストリへのログイン、Dockerでの起動、ユーザーデータベースの作成という順序で準備します。通常のSQL Serverコンテナーとは異なり、Azure SQL DeveloperはAzure SQL Databaseのエンジンを開発者PCやCI上で実行するための環境です。
特に注意したいのは、コンテナーを起動しただけではアプリケーション用データベースが作成されないことです。masterへ接続してCREATE DATABASEを実行し、その後、接続文字列のDatabaseで対象データベースを指定します。また、Apple Silicon Macではx64イメージを動かすため、--platform linux/amd64の指定が必要です。
2026年8月時点ではプライベートプレビューのため、レジストリの認証情報やイメージ名が変更される可能性があります。本記事では、現在の公式情報を基に、ローカルDocker環境からGitHub Actionsを使ったCIまでの実用的な構成を解説します。(Microsoft Developer Blogs)
Azure SQL Databaseエンジンをローカルで動かすAzure SQL Developer入門
Azure SQL Developerは、SQL ServerをAzure SQL Database風に設定したイメージではありません。Azure SQL Databaseで使用されるエンジンを、開発やテスト向けのコンテナーとしてローカル実行するものです。
そのため、Azure SQL Databaseと同じT-SQL、システムビュー、TDS接続、ドライバーを前提にアプリケーションを開発できます。ローカルで動かしたコードをAzure SQL Databaseへ移す際は、基本的に接続文字列を切り替える構成を目指します。
ただし、同じエンジンであっても、プライベートプレビュー版コンテナーとAzure上のマネージドサービスが、すべての動作や既定値まで完全に一致しているわけではありません。一部のPaaS制約や既定値には差が残っているため、本番公開前には実際のAzure SQL Databaseでも確認が必要です。(GitHub)
| 選択肢 | 主な用途 | エンジン・実行形態 |
|---|---|---|
| Azure SQL Developer | Azure SQL Database向けアプリのローカル開発、統合テスト、CI | Azure SQL Databaseエンジンをコンテナーで実行 |
| SQL Serverコンテナー | SQL Server向けアプリやSQL Server固有機能の検証 | SQL Serverエンジン |
| Azure SQL Database | 本番運用、バックアップ、高可用性、スケーリング | AzureのマネージドPaaS |
実際にAzure SQL Databaseエンジンが動いているかは、次のクエリで確認できます。
SELECT
SERVERPROPERTY('EngineEdition') AS EngineEdition,
SERVERPROPERTY('Edition') AS Edition;
Azure SQL Developerでは、次の値が返ります。
| 項目 | 期待値 |
|---|---|
EngineEdition | 5 |
Edition | SQL Azure |
異なる値が返る場合は、mcr.microsoft.com/mssql/serverなど、別のSQL Serverイメージを起動していないか確認してください。(GitHub)
最初に確認すること:現在はプライベートプレビュー
Azure SQL Developerのコンテナーイメージは、一般公開されたDocker HubやMicrosoft Container Registryから匿名で取得できる状態ではありません。
公式のプライベートプレビューへ参加し、案内されたユーザー名とパスワードを使って専用レジストリへログインします。レジストリの認証情報はイメージ取得専用で、プレビュー期間中に変更される可能性があります。ソースコードやDocker Composeファイルへ直接記載しないでください。
レジストリ認証とデータベース認証は別物
Azure SQL Developerでは、2種類の認証情報を区別する必要があります。
| 認証情報 | 用途 | 保存場所 |
|---|---|---|
| プレビュー用レジストリユーザー名 | コンテナーイメージの取得 | Dockerの資格情報ストア、CIのSecret |
| プレビュー用レジストリパスワード | コンテナーイメージの取得 | Dockerの資格情報ストア、CIのSecret |
MSSQL_SA_PASSWORD | 起動したデータベースへのsaログイン | 環境変数、CIのSecret |
| Microsoft Entra ID | Azure SQL Databaseのクラウド接続や、必要に応じたローカル認証 | マネージドID、開発者ID、証明書 |
レジストリへログインするときのパスワードと、データベースへ接続するときのsaパスワードは別です。docker loginが成功しても、MSSQL_SA_PASSWORDが弱い場合はデータベースエンジンが正常に初期化されません。
必要な実行環境
公式の前提条件では、DockerなどのOCI互換ランタイムに加え、一定のCPU、メモリ、ディスク容量が必要です。
| 項目 | 目安 |
|---|---|
| コンテナーランタイム | Docker 24以降、Podman 5.0以降、Rancher Desktop 1.13以降など |
| CPU | 2コア以上 |
| メモリ | ランタイムへ4GB以上を割り当て |
| ディスク | 10GB以上の空き容量 |
| コンテナーポート | TCP 1433 |
| イメージアーキテクチャ | linux/amd64 |
| Windows | Windows 11、WSL2、Linuxコンテナーモード |
| macOS | macOS 14以降 |
| Apple Silicon | linux/amd64をエミュレーション実行 |
Apple Silicon向けのネイティブARM64イメージは、現時点では提供されていません。エミュレーションのため、IntelやAMD64環境より起動や処理が遅くなる可能性があります。Apple Silicon環境は機能検証には利用できますが、データベース性能を比較する基準には向きません。
Dockerが正常に起動しているか、最初に確認しておきます。
docker info
Windowsでは、Docker DesktopがWindowsコンテナーモードになっていると起動できません。Linuxコンテナーモードへ切り替えてください。
Azure SQL DeveloperコンテナーをDockerでローカル起動する方法
以下のコマンドは、macOS、Linux、WindowsのWSLで使えるBashまたはzshを前提としています。
プライベートレジストリへログインする
プライベートプレビューで案内されたユーザー名を指定してログインします。パスワードはコマンドへ直接書かず、表示される入力欄へ入力してください。
docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io \
-u "<PREVIEW_USERNAME>"
ログイン後、コンテナーイメージを取得します。
docker pull \
sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
Apple Siliconなどの非x64環境では、プラットフォームを明示します。
docker pull \
--platform linux/amd64 \
sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
プライベートプレビューではlatestが更新されるため、既にローカルへイメージがある場合でも、修正を取り込むときは明示的にdocker pullを実行します。通常のdocker runは、ローカルにあるキャッシュ済みイメージを再利用するためです。
SAパスワードを環境変数へ設定する
MSSQL_SA_PASSWORDには、8文字以上かつ、大文字、小文字、数字、記号のうち3種類以上を含むパスワードが必要です。
export MSSQL_SA_PASSWORD='Change_This_Str0ng_Passw0rd!'
実際のプロジェクトでは、.envやシェルスクリプトをGitへコミットしないようにしてください。
x64環境でコンテナーを起動する
Intel Mac、AMD64 Linux、Windows 11のWSL2など、x64環境では次のコマンドを使用します。
docker run \
--name sqldb \
-e ACCEPT_EULA=Y \
-e MSSQL_SA_PASSWORD \
-p 1433:1433 \
-v sqldb-data:/var/opt/mssql \
-d \
sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
Apple Siliconでコンテナーを起動する
M1、M2、M3、M4などのApple Silicon Macでは、--platform linux/amd64を追加します。
docker run \
--platform linux/amd64 \
--name sqldb \
-e ACCEPT_EULA=Y \
-e MSSQL_SA_PASSWORD \
-p 1433:1433 \
-v sqldb-data:/var/opt/mssql \
-d \
sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
主なオプションの役割は次のとおりです。
| オプション | 役割 |
|---|---|
--name sqldb | コンテナー名をsqldbに固定 |
ACCEPT_EULA=Y | 使用許諾への同意。未設定では起動しない |
MSSQL_SA_PASSWORD | saのパスワード |
-p 1433:1433 | ホストの1433番をコンテナーの1433番へ割り当て |
-v sqldb-data:/var/opt/mssql | データを名前付きボリュームへ保存 |
-d | バックグラウンドで実行 |
--platform linux/amd64 | x64イメージを非x64ホストで実行 |
コンテナーの状態を確認します。
docker ps --filter "name=sqldb"
起動に失敗した場合は、最初にログを確認してください。
docker logs sqldb
パスワードポリシー違反、メモリ不足、ACCEPT_EULAの未設定などは、コンテナー一覧だけでは原因が分からないことがあります。
データベースを明示的に作成する
Azure SQL Developerでは、コンテナー起動時にアプリケーション用データベースは自動作成されません。
接続文字列へいきなりDatabase=appdbを指定しても、appdbが存在しなければ接続に失敗します。最初にmasterへ接続してデータベースを作成し、その後にappdbへ接続します。
起動待ちとDB作成を一つのループで行う
docker runが成功しても、内部のデータベースエンジンが即座に接続可能になるとは限りません。次の再試行ループで、起動確認とappdbの作成を同時に行えます。
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 "Azure SQL Developer and appdb are ready."
このコマンドには、次の意味があります。
| 指定 | 意味 |
|---|---|
-C | ローカルの自己署名証明書を信頼 |
-b | SQLエラーが起きたときにエラー終了させる |
-l 2 | ログインタイムアウトを2秒に設定 |
IF DB_ID(...) IS NULL | DBがない場合だけ作成し、再実行可能にする |
sleep 2 | エンジンが準備できるまで2秒ごとに再試行 |
コンテナーにはsqlcmdが含まれているため、ホスト側へSQLクライアントを追加インストールする必要はありません。
Azure SQL DatabaseエンジンとDB名を確認する
docker exec sqldb \
/opt/mssql-tools18/bin/sqlcmd \
-S localhost \
-U sa \
-P "$MSSQL_SA_PASSWORD" \
-C \
-d appdb \
-Q "
SELECT
SERVERPROPERTY('EngineEdition') AS EngineEdition,
SERVERPROPERTY('Edition') AS Edition,
DB_NAME() AS DatabaseName;
"
次の値が確認できれば、基本的な準備は完了です。
| 項目 | 期待値 |
|---|---|
EngineEdition | 5 |
Edition | SQL Azure |
DatabaseName | appdb |
接続文字列はユーザーデータベースを指定する
アプリケーションでは、接続文字列を環境変数へ集約しておくと、ローカルとAzureの切り替えが容易になります。
export SQL_CONNECTION_STRING="Server=localhost,1433;Database=appdb;User Id=sa;Password=${MSSQL_SA_PASSWORD};TrustServerCertificate=true"
重要なのは、Database=appdbを明示することです。
ユーザーデータベースのセッションでは、USE appdbによるDB切り替えはAzure SQL Databaseと同様にエラーになる場合があります。USEで切り替えるのではなく、接続文字列のDatabase、またはsqlcmdの-d appdbを使用してください。
また、PostgreSQLやMySQLで使われることのある/docker-entrypoint-initdb.dの自動実行は利用できません。初期データは、DB作成後にマイグレーションツールやsqlcmd -d appdb -i seed.sqlで投入します。
Docker Compose内から接続するときの違い
ホストPCから接続する場合は、次のサーバー名を使います。
Server=localhost,1433
同じDocker Composeネットワーク内のアプリケーションコンテナーから接続する場合は、localhostではなくサービス名を使います。
Server=sqldb,1433
アプリケーションコンテナー内のlocalhostは、Azure SQL Developerではなくアプリケーションコンテナー自身を指すためです。
Azure SQL Developerで利用できるドライバー
Azure SQL Developerは、Azure SQL Databaseへ接続できる一般的なドライバーやORMから利用できます。公式情報では、次のような構成が例示されています。(GitHub)
| 言語・環境 | ドライバー、ORM |
|---|---|
| .NET | Microsoft.Data.SqlClient、Entity Framework Core |
| Node.js | mssql、Prisma、TypeORM |
| Python | mssql-python、pyodbc、SQLAlchemy、Django |
| Java | Microsoft JDBC Driver、mssql-jdbc |
| コマンドライン | sqlcmd |
| エディター | Visual Studio Code MSSQL拡張機能 |
.NETでは、Azure SQL Databaseと同様にMicrosoft.Data.SqlClientを利用できます。Node.jsのmssqlは、環境変数に保存した接続文字列をそのまま読み込む構成にできます。
Pythonでは、Microsoftのmssql-pythonを使用できます。mssql-pythonは外部のODBCドライバーマネージャーを必要としない構成です。一方、pyodbcを利用する場合は、アプリケーションを実行するPCやコンテナーへMicrosoft ODBC Driver for SQL Serverをインストールする必要があります。新規構成ではODBC Driver 18系が候補になります。(Microsoft Learn)
Javaでは、次のようなJDBC URLを使用します。
jdbc:sqlserver://localhost:1433;databaseName=appdb;user=sa;password=Change_This_Str0ng_Passw0rd!;encrypt=true;trustServerCertificate=true
Microsoft JDBC Driverでは、encryptやtrustServerCertificateなどのTLS関連プロパティを設定できます。(Microsoft Learn)
TrustServerCertificateはローカル限定で使う
ローカルコンテナーでは自己署名証明書が使用されるため、接続文字列に次の設定を加えます。
TrustServerCertificate=true
この設定は証明書チェーンの検証を省略するため、信頼できるローカル開発環境向けです。Azure SQL Databaseへ接続するときに、そのまま流用しないでください。
クラウド側では、Microsoft Entra ID認証とTLS検証を利用する構成が基本です。
Server=your-server.database.windows.net,1433;Database=appdb;Authentication=Active Directory Default;Encrypt=true
アプリケーションコードを分岐させるのではなく、SQL_CONNECTION_STRINGの値だけを環境ごとに変更します。
SSMSやGUIでエラーになる場合
プライベートプレビュー段階では、SQL Server Management StudioやVisual Studio Code MSSQL拡張機能の一部GUIが完全には対応しておらず、画面操作時にエラーが出る可能性があります。
コンテナー自体の障害と決めつけず、まずは次の方法で接続を確認してください。
- コンテナー内の
sqlcmd - ホスト側の
sqlcmd - .NET、Node.js、Python、Javaのドライバー
- Visual Studio Code MSSQL拡張機能のGitHub Copilot連携
CLIやドライバーでは接続できるのにGUIだけでエラーになる場合は、プレビュー段階のツール互換性が原因である可能性があります。
GitHub ActionsでAzure SQL DeveloperをCI起動する方法
GitHub Actionsでは、Azure SQL Developerをサービスコンテナーとして起動できます。
リポジトリのSecretsへ、次の3項目を登録します。
| Secret名 | 内容 |
|---|---|
ACR_USERNAME | プライベートプレビューのレジストリユーザー名 |
ACR_PASSWORD | プライベートプレビューのレジストリパスワード |
MSSQL_SA_PASSWORD | CI用の強力なsaパスワード |
GitHubホストランナーのubuntu-latestはx64環境であるため、通常は--platform linux/amd64を追加する必要はありません。ARM64のセルフホストランナーを使う場合は、手動起動処理でプラットフォーム指定を追加します。
GitHub Actionsの設定例
name: integration
on:
push:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
services:
sqldb:
image: sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
credentials:
username: ${{ secrets.ACR_USERNAME }}
password: ${{ secrets.ACR_PASSWORD }}
env:
ACCEPT_EULA: "Y"
MSSQL_SA_PASSWORD: ${{ secrets.MSSQL_SA_PASSWORD }}
ports:
- 1433:1433
options: >-
--health-cmd "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P \"$MSSQL_SA_PASSWORD\" -C -b -l 2 -Q \"SELECT 1\""
--health-interval 5s
--health-timeout 3s
--health-retries 20
--health-start-period 30s
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Create appdb
env:
MSSQL_SA_PASSWORD: ${{ secrets.MSSQL_SA_PASSWORD }}
run: |
CID=$(docker ps \
--filter "ancestor=sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest" \
--format '{{.ID}}' | head -n 1)
docker exec "$CID" \
/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;"
- name: Run integration tests
env:
SQL_CONNECTION_STRING: >-
Server=localhost,1433;
Database=appdb;
User Id=sa;
Password=${{ secrets.MSSQL_SA_PASSWORD }};
TrustServerCertificate=true
run: |
npm ci
npm run test:integration
最後のテストコマンドは、利用している技術スタックに合わせて変更します。
| 技術スタック | コマンド例 |
|---|---|
| Node.js | npm run test:integration |
| .NET | dotnet test |
| Python | pytest |
| Java・Maven | mvn test |
| Java・Gradle | ./gradlew test |
この構成で重要なのは、ヘルスチェックがコンテナー内部のsqlcmdを使っている点です。CIランナー側へsqlcmdを追加インストールせず、データベースエンジンが実際にクエリを受け付けるまで待機できます。
その後、別ステップでappdbを作成し、マイグレーションや初期データ投入を行ってから統合テストを実行します。テストの接続先はmasterではなく、必ずユーザーデータベースのappdbにします。
CIで守るべき処理順序
GitHub Actions、Azure Pipelines、GitLab CIのいずれでも、基本的な処理順序は同じです。
- Secretからレジストリ認証情報を読み込む
- プライベートイメージを取得する
ACCEPT_EULAとMSSQL_SA_PASSWORDを設定して起動する- SQLクエリが成功するまで待機する
master接続でユーザーデータベースを作成する- ユーザーデータベースへマイグレーションを適用する
- 必要に応じて初期データを投入する
Database=appdbを指定して統合テストを実行する
「コンテナーが起動中になったらテスト開始」ではなく、「ユーザーデータベースへのSQL接続が成功したらテスト開始」と判断するのがポイントです。
よくあるエラーと対処法
| 症状・エラー | 主な原因 | 対処法 |
|---|---|---|
unauthorized: authentication required | レジストリ未ログイン、認証情報の変更 | プレビューで案内された情報を確認し、docker loginをやり直す |
no matching manifest | ARM64ホストでx64イメージを指定していない | --platform linux/amd64を追加する |
exec format error | アーキテクチャ不一致 | linux/amd64を明示する |
コンテナーはUpだが接続できない | 弱いSAパスワード、メモリ不足、エンジン準備中 | docker logs sqldbを確認する |
port is already allocated | 1433番ポートを別プロセスが使用中 | -p 1434:1433へ変更し、localhost,1434へ接続する |
| 起動直後だけ接続に失敗する | SQLエンジンの準備が完了していない | sqlcmdの再試行ループやヘルスチェックを使う |
Cannot open database "appdb" | appdbを作成していない | master接続でCREATE DATABASE appdbを実行する |
USE statement is not supported、Msg 40508 | ユーザーDBセッションでUSEを実行 | 接続文字列のDatabase=appdbまたは-d appdbを使う |
| 修正済みのはずの問題が残る | 古いlatestイメージをキャッシュしている | 明示的にdocker pullを実行する |
| SSMSやMSSQL拡張の画面でエラー | GUIのプレビュー互換性 | sqlcmdまたはアプリケーションドライバーで確認する |
プライベートプレビューでは、イメージや認証情報が更新されることがあります。CIで問題が発生したときに追跡しやすくするため、実行したイメージIDやコンテナーログをワークフローへ残しておくと原因を切り分けやすくなります。
Azure SQL Developerを本番データベースとして使わない
Azure SQL Developerコンテナーの用途は、開発、テスト、CI、デモです。本番データベースとして運用したり、コンテナー自体をAzure上へ本番配備したりするための製品ではありません。
また、コンテナーでは次のような制約があります。
BACKUP DATABASEとRESTORE DATABASEは利用できない- Azureの自動バックアップやポイントインタイムリストアはない
- 高可用性、スケーリング、SLAは提供されない
- Azureポータル、ARM、Bicepなどの管理機能は対象外
- 一部のAzure SQL Database制約や既定値が完全には一致しない
- SQL Server AgentやWindows認証など、Azure SQL DatabaseにないSQL Server機能は利用できない
ローカルデータをコンテナー削除後も残す場合は、/var/opt/mssqlへDockerの名前付きボリュームを割り当てます。
-v sqldb-data:/var/opt/mssql
完全に初期化したい場合は、コンテナーだけでなくボリュームも削除します。
docker rm -f sqldb
docker volume rm sqldb-data
本番へ移行する前には、実際のAzure SQL Databaseを対象に、マイグレーション、主要クエリ、認証、トランザクションを最低1回は検証してください。特にプライベートプレビュー中は、ローカルで成功したクエリがクラウド側のPaaS制約によって失敗する可能性があります。
ローカルとCIで同じ起動手順を使う
Azure SQL Developerコンテナーを安定運用するには、ローカル環境とCIで処理順序を統一することが重要です。
まずプライベートレジストリへログインし、必要に応じて最新イメージを取得します。Apple Siliconではlinux/amd64を指定してコンテナーを起動します。その後、SQLエンジンの準備完了を待ちながらappdbを明示的に作成し、アプリケーションはDatabase=appdbを含む接続文字列で接続します。
CIでも同じように、ヘルスチェック、DB作成、マイグレーション、統合テストの順に処理します。最初に実施すべきことは、プライベートプレビューへ参加してレジストリ認証情報を取得し、ローカルでEngineEdition=5、Edition=SQL Azure、DatabaseName=appdbを確認することです。その構成をそのままCIへ移すことで、開発者PCとパイプラインの差を最小限にできます。

コメント