Azure SQL Developerコンテナーをローカル・CIで起動する方法|認証・Apple Silicon・DB作成まで

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 DeveloperAzure SQL Database向けアプリのローカル開発、統合テスト、CIAzure 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では、次の値が返ります。

項目期待値
EngineEdition5
EditionSQL 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 IDAzure SQL Databaseのクラウド接続や、必要に応じたローカル認証マネージドID、開発者ID、証明書

レジストリへログインするときのパスワードと、データベースへ接続するときのsaパスワードは別です。docker loginが成功しても、MSSQL_SA_PASSWORDが弱い場合はデータベースエンジンが正常に初期化されません。

必要な実行環境

公式の前提条件では、DockerなどのOCI互換ランタイムに加え、一定のCPU、メモリ、ディスク容量が必要です。

項目目安
コンテナーランタイムDocker 24以降、Podman 5.0以降、Rancher Desktop 1.13以降など
CPU2コア以上
メモリランタイムへ4GB以上を割り当て
ディスク10GB以上の空き容量
コンテナーポートTCP 1433
イメージアーキテクチャlinux/amd64
WindowsWindows 11、WSL2、Linuxコンテナーモード
macOSmacOS 14以降
Apple Siliconlinux/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_PASSWORDsaのパスワード
-p 1433:1433ホストの1433番をコンテナーの1433番へ割り当て
-v sqldb-data:/var/opt/mssqlデータを名前付きボリュームへ保存
-dバックグラウンドで実行
--platform linux/amd64x64イメージを非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ローカルの自己署名証明書を信頼
-bSQLエラーが起きたときにエラー終了させる
-l 2ログインタイムアウトを2秒に設定
IF DB_ID(...) IS NULLDBがない場合だけ作成し、再実行可能にする
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;
  "

次の値が確認できれば、基本的な準備は完了です。

項目期待値
EngineEdition5
EditionSQL Azure
DatabaseNameappdb

接続文字列はユーザーデータベースを指定する

アプリケーションでは、接続文字列を環境変数へ集約しておくと、ローカルと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
.NETMicrosoft.Data.SqlClient、Entity Framework Core
Node.jsmssql、Prisma、TypeORM
Pythonmssql-python、pyodbc、SQLAlchemy、Django
JavaMicrosoft 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_PASSWORDCI用の強力な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.jsnpm run test:integration
.NETdotnet test
Pythonpytest
Java・Mavenmvn test
Java・Gradle./gradlew test

この構成で重要なのは、ヘルスチェックがコンテナー内部のsqlcmdを使っている点です。CIランナー側へsqlcmdを追加インストールせず、データベースエンジンが実際にクエリを受け付けるまで待機できます。

その後、別ステップでappdbを作成し、マイグレーションや初期データ投入を行ってから統合テストを実行します。テストの接続先はmasterではなく、必ずユーザーデータベースのappdbにします。

CIで守るべき処理順序

GitHub Actions、Azure Pipelines、GitLab CIのいずれでも、基本的な処理順序は同じです。

  1. Secretからレジストリ認証情報を読み込む
  2. プライベートイメージを取得する
  3. ACCEPT_EULAとMSSQL_SA_PASSWORDを設定して起動する
  4. SQLクエリが成功するまで待機する
  5. master接続でユーザーデータベースを作成する
  6. ユーザーデータベースへマイグレーションを適用する
  7. 必要に応じて初期データを投入する
  8. Database=appdbを指定して統合テストを実行する

「コンテナーが起動中になったらテスト開始」ではなく、「ユーザーデータベースへのSQL接続が成功したらテスト開始」と判断するのがポイントです。

よくあるエラーと対処法

症状・エラー主な原因対処法
unauthorized: authentication requiredレジストリ未ログイン、認証情報の変更プレビューで案内された情報を確認し、docker loginをやり直す
no matching manifestARM64ホストでx64イメージを指定していない--platform linux/amd64を追加する
exec format errorアーキテクチャ不一致linux/amd64を明示する
コンテナーはUpだが接続できない弱いSAパスワード、メモリ不足、エンジン準備中docker logs sqldbを確認する
port is already allocated1433番ポートを別プロセスが使用中-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とパイプラインの差を最小限にできます。

この記事を書いた人

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows/Office(Teams・Excel)からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

コメント

コメントする

目次