Azure SQL documentation updateとして確認すべき今回の変更は、az postgres flexible-server配下の複数コマンドで、--nameと--server-nameの使い分けを統一する破壊的変更です。結論から言うと、これまで一部の子リソース操作で--nameが「サーバー名」を指していたケースが見直され、今後は--nameを「操作対象の名前」、--server-nameを「PostgreSQL Flexible Serverのサーバー名」として扱う方向に変わります。
影響を受けるのは、Azure SQL Database本体のaz sqlコマンドではなく、Azure Database for PostgreSQL Flexible ServerをAzure CLIで操作している管理者・開発者です。特に、バックアップ、データベース作成、ファイアウォール規則、長期保持、移行、レプリカ作成をCI/CDや運用スクリプトで自動化している環境では、旧パラメーターのままだとコマンドが失敗する可能性があります。Azure/azure-cliのPR #33343は2026年5月20日にマージされ、対象コマンドと--name/--server-nameの整理方針が示されています。 (GitHub)
Azure SQL documentation updateの対象は何か
今回の「Azure SQL documentation update: [POSTGRESQL] BREAKING CHANGE」は、名前だけを見るとAzure SQL全般の変更に見えますが、実際の対象はaz postgres flexible-serverコマンド群です。
つまり、次のような運用をしているチームが主な対象です。
- Azure Database for PostgreSQL Flexible Serverを利用している
- Azure CLIでバックアップ、DB、ファイアウォール、移行、レプリカを操作している
- Azure DevOps、GitHub Actions、Cloud Shell、Runbook、シェルスクリプト、PowerShellで
az postgres flexible-serverを実行している - 手順書や社内Runbookに古いCLI構文を記載している
一方で、az sql db、az sql server、az sql miなど、Azure SQL DatabaseやAzure SQL Managed Instance向けのコマンドを使っているだけなら、この変更の直接対象ではありません。ただし、同じAzure環境でSQL DatabaseとPostgreSQL Flexible Serverを併用している場合は、運用スクリプトの棚卸しが必要です。
変更の中心は「–nameは操作対象、–server-nameはサーバー名」
今回の変更で最も重要なのは、--nameの意味がコマンドごとに揺れていた点を整理することです。
従来は、たとえばファイアウォール規則やデータベースを操作するコマンドでも、--nameがサーバー名を指すケースがありました。これだと、スクリプトを読む人が「この--nameはサーバー名なのか、DB名なのか、ルール名なのか」を毎回文脈で判断する必要があります。
新しい考え方では、--nameはコマンドが直接操作するオブジェクトの名前です。サーバー名が必要な場合は、--server-nameまたは短縮形の-sを使います。Microsoft Learnの今後の破壊的変更ページでも、firewall-rule、migration、db、backup、long-term-retentionでこの方針が案内されています。 (Microsoft Learn)
| 対象コマンド群 | これまで問題になりやすかった指定 | 変更後の考え方 | 確認すべきポイント |
|---|---|---|---|
az postgres flexible-server backup | --nameがサーバー名、--backup-nameがバックアップ名 | --server-nameがサーバー名、--nameがバックアップ名 | backup createではバックアップ名引数が不要になる案内もあるため、実行環境の--helpで必須項目を確認する |
az postgres flexible-server db | --nameがサーバー名、--database-nameがDB名 | --server-nameがサーバー名、--nameがDB名 | DB作成・削除・参照の自動化スクリプトを優先確認する |
az postgres flexible-server firewall-rule | --nameがサーバー名、--rule-nameが規則名 | --server-nameがサーバー名、--nameが規則名 | -nをサーバー名として使っているスクリプトは特に危険 |
az postgres flexible-server long-term-retention | --nameがサーバー名、--backup-nameがバックアップ名 | --server-nameがサーバー名、--nameがバックアップ名 | コマンドグループ自体の非推奨・削除予定も確認する |
az postgres flexible-server migration | --nameがサーバー名、--migration-nameが移行名 | --server-nameがサーバー名、--nameが移行名 | 移行ジョブの作成・確認・更新スクリプトを確認する |
az postgres flexible-server replica create | --replica-nameでレプリカ名を指定 | --nameでレプリカ名を指定 | レプリカ作成時の名前指定だけでなく、ネットワーク関連の変更案内も合わせて確認する |
旧構文と新構文の具体例
実務で最も壊れやすいのは、短縮オプション-nを何となくサーバー名として使っているスクリプトです。今後は、子リソースを操作するコマンドでは-nの意味が変わるため、移行時は短縮形ではなくフルオプションで書くほうが安全です。
データベース作成コマンドの例
変更前の例では、--nameがサーバー名、--database-nameがデータベース名でした。
az postgres flexible-server db create \
--resource-group rg-prod \
--name pg-prod-01 \
--database-name appdb変更後の考え方では、サーバー名を--server-name、データベース名を--nameで指定します。
az postgres flexible-server db create \
--resource-group rg-prod \
--server-name pg-prod-01 \
--name appdbaz postgres flexible-server dbでは、--database-name/-dが非推奨となり、--name/-nがデータベース名を指す方向の変更が案内されています。 (Microsoft Learn)
ファイアウォール規則作成コマンドの例
ファイアウォール規則では、旧構文の-nがサーバー名、--rule-nameが規則名として使われていたケースが多いはずです。
az postgres flexible-server firewall-rule create \
--resource-group rg-prod \
--name pg-prod-01 \
--rule-name allow-office \
--start-ip-address 203.0.113.10 \
--end-ip-address 203.0.113.10変更後は、サーバー名と規則名を明確に分けます。
az postgres flexible-server firewall-rule create \
--resource-group rg-prod \
--server-name pg-prod-01 \
--name allow-office \
--start-ip-address 203.0.113.10 \
--end-ip-address 203.0.113.10firewall-ruleでは、--rule-name/-rが非推奨となり、--name/-nがファイアウォール規則名を指す方向で案内されています。 (Microsoft Learn)
バックアップ参照コマンドの例
バックアップ関連も混乱しやすい領域です。バックアップ名とサーバー名の両方が登場するため、--nameをサーバー名として使っているスクリプトは見直しが必要です。
# 変更前の例
az postgres flexible-server backup show \
--resource-group rg-prod \
--name pg-prod-01 \
--backup-name pre-change-backup# 変更後の考え方
az postgres flexible-server backup show \
--resource-group rg-prod \
--server-name pg-prod-01 \
--name pre-change-backupMicrosoft Learnのバックアップコマンド説明では、--name/-nがバックアップ名を指すように再利用され、サーバー名には--server-name/-sを導入する案内が掲載されています。 (Microsoft Learn)
レプリカ作成コマンドの例
レプリカ作成では、レプリカ名の指定が--replica-nameから--nameへ寄せられます。
# 変更前の例
az postgres flexible-server replica create \
--resource-group rg-prod \
--source-server pg-primary-01 \
--replica-name pg-replica-01# 変更後の考え方
az postgres flexible-server replica create \
--resource-group rg-prod \
--source-server pg-primary-01 \
--name pg-replica-01ここで注意したいのは、replica createでは「作成するレプリカの名前」が--nameです。既存のプライマリサーバーを指す引数まで機械的に--server-nameへ置換しないようにしてください。
影響範囲はCLIスクリプトと運用手順が中心
この変更は、PostgreSQLのデータ形式やアプリケーションのSQL文を変えるものではありません。アプリケーションの接続文字列、テーブル定義、クエリ、PostgreSQLのバージョンが直接変わるわけではありません。
ただし、Azure CLIを使った運用自動化には大きく影響します。特に次のような場所に旧構文が残りやすいです。
| 確認対象 | 影響の出方 | 優先度 |
|---|---|---|
| Azure DevOps / GitHub Actions | デプロイ中にDB作成、FW規則追加、バックアップ取得が失敗する | 高 |
| Cloud Shell用の手順書 | 担当者が手順通りに実行してもエラーになる | 高 |
| 運用Runbook / Automation Account | 定期バックアップ確認や移行確認のジョブが失敗する | 高 |
Terraformのlocal-execや外部スクリプト | Terraform自体ではなく、内部で呼ぶazコマンドが失敗する | 中 |
| 社内Wiki・障害対応手順 | 緊急時に古いコマンドを実行して復旧が遅れる | 中 |
| 開発者のローカルスクリプト | 個人環境では動くがCIで失敗する、またはその逆が起きる | 中 |
Bicep、ARMテンプレート、Terraform ProviderでAzure Resource Manager APIを直接使っている部分は、基本的にはこのCLIパラメーター変更の直接対象ではありません。ただし、デプロイ前後の補助処理でAzure CLIを呼び出している場合は対象になります。
管理者と開発者がまず確認すべきこと
本番環境に影響を出さないために、最初にやるべきことは「Azure CLIの更新」ではなく「旧構文の棚卸し」です。CLIだけ先に更新すると、どのスクリプトが壊れたのかを本番デプロイ時に初めて知ることになります。
| 手順 | 実施内容 | 判断基準 |
|---|---|---|
| CLIバージョンを確認する | az versionまたはaz --versionを実行する | チーム内、CI、Cloud Shell、自己ホストランナーで差がないか確認する |
| 対象コマンドを検索する | リポジトリ、Runbook、Wikiからaz postgres flexible-serverを検索する | backup、db、firewall-rule、long-term-retention、migration、replica createを含むものを抽出する |
| 旧パラメーターを分類する | --name、-n、--backup-name、--database-name、--rule-name、--migration-name、--replica-nameを確認する | --nameがサーバー名なのか、子リソース名なのかを1行ずつ判断する |
| 新構文に置き換える | サーバー名は--server-name、操作対象は--nameへ寄せる | 文字列置換ではなく、コマンド単位で意味を確認する |
| 検証環境で実行する | 参照系、作成系、削除系の順にテストする | listやshowで構文を確認してから、createやdeleteを試す |
| 手順書を更新する | 社内Wiki、Runbook、障害対応手順を修正する | -nの意味が誤解されないよう、重要手順ではフルオプションを使う |
Azure CLIのインストール案内では、インストール済みバージョン確認のためにaz versionを実行するよう案内されています。環境ごとにAzure CLIの反映タイミングが異なるため、ローカルPC、Cloud Shell、CIランナーを同じ前提で扱わないことが重要です。 (Microsoft Learn)
旧構文を探すためのコマンド例
Linux、macOS、WSL、Cloud Shellでは、次のように対象コマンドを検索できます。
grep -RInE "az postgres flexible-server (backup|db|firewall-rule|long-term-retention|migration|replica create)" .PowerShellでは、次のように検索できます。
Get-ChildItem -Recurse -File |
Select-String -Pattern "az postgres flexible-server (backup|db|firewall-rule|long-term-retention|migration|replica create)"見つかった行に-nが含まれている場合は、特に注意してください。旧構文では-nがサーバー名を意味していたとしても、新しい構文ではバックアップ名、DB名、ファイアウォール規則名、移行名などを指す可能性があります。
置き換え時の判断基準
移行では、単純な一括置換を避ける必要があります。--nameは他のAzure CLIコマンドでも広く使われるため、すべての--nameを--server-nameに変えると、別のコマンドを壊します。
| 旧パラメーター | 新しい指定の目安 | 対象 |
|---|---|---|
--nameまたは-nでサーバー名を指定していた | --server-nameまたは-sへ変更 | backup、db、firewall-rule、long-term-retention、migration |
--backup-nameでバックアップ名を指定していた | --nameへ変更。ただしbackup createは必須性を--helpで確認 | backup、long-term-retention |
--database-nameまたは-dでDB名を指定していた | --nameへ変更 | db |
--rule-nameまたは-rでFW規則名を指定していた | --nameへ変更 | firewall-rule |
--migration-nameで移行名を指定していた | --nameへ変更 | migration |
--replica-nameでレプリカ名を指定していた | --nameへ変更 | replica create |
移行コマンドでは、--migration-nameが非推奨となり、--name/-nが移行名を指定する方向の変更が案内されています。移行処理は本番データに関わることが多いため、ジョブ作成、状態確認、更新、名前可用性チェックをまとめて検証してください。 (Microsoft Learn)
長期保持コマンドはパラメーター変更だけで見ない
az postgres flexible-server long-term-retentionについては、--nameと--server-nameの整理だけでなく、コマンドグループ自体が非推奨で、将来的に削除される案内がある点に注意が必要です。Microsoft Learnでも、長期保持コマンドグループの削除予定と、--backup-name、--name、--server-nameに関する変更が掲載されています。 (Microsoft Learn)
そのため、長期保持を使っている場合は、単にスクリプトを書き換えるだけでは不十分です。次の観点で運用設計を見直してください。
| 確認項目 | 見るべきポイント |
|---|---|
| 現在の用途 | 監査対応、災害復旧、手動バックアップ保管など、何のために使っているか |
| 実行頻度 | 定期ジョブなのか、障害時だけの手順なのか |
| 代替手段 | Azure Portal、サポート案内、バックアップ設計の見直しが必要か |
| 手順書 | 古いlong-term-retentionコマンドを緊急時手順に残していないか |
| 権限 | サポート問い合わせやバックアップ確認を実施できる担当者が明確か |
長期保持は、障害発生時や監査対応時に初めて使うケースもあります。普段動かさない手順ほど古い構文が残りやすいため、今回の変更をきっかけに復旧手順も確認しておくべきです。
失敗しやすいポイント
-nをサーバー名として使い続ける
最も多い失敗は、-nをサーバー名の短縮形として使い続けることです。
az postgres flexible-server firewall-rule create -g rg-prod -n pg-prod-01 --rule-name allow-officeこのようなコマンドは、見た目だけでは-nが何を指すのか分かりにくくなります。移行後は、少なくとも運用手順やCIでは次のように明示するのが安全です。
az postgres flexible-server firewall-rule create \
--resource-group rg-prod \
--server-name pg-prod-01 \
--name allow-office短縮形は便利ですが、破壊的変更の直後は誤読を招きます。チーム全体が新しいルールに慣れるまでは、--server-nameと--nameを明示する運用に切り替えるのがおすすめです。
すべての--nameを機械的に置換する
az postgres flexible-server showやaz postgres flexible-server updateのように、サーバー自体を操作するコマンドでは、--nameがサーバー名を指す文脈もあります。今回問題になるのは、主に子リソースを操作するコマンドです。
そのため、次のような一括置換は避けてください。
--name → --server-name正しい進め方は、コマンドグループごとに--nameが何を指しているかを判断することです。特に、db、firewall-rule、backup、migrationは、同じ--nameでも意味が大きく変わります。
CLIバージョン差を見落とす
開発者のローカルPCでは旧構文が動くのに、CIランナーでは失敗することがあります。逆に、CIだけAzure CLIが古く、ローカルでは新構文が通るケースもあります。
確認すべき場所は少なくとも次の4つです。
- 開発者のローカル環境
- Azure Cloud Shell
- GitHub ActionsやAzure DevOpsのMicrosoft-hosted runner
- 自己ホストランナー、Automation Account、踏み台サーバー
移行期間中は、az versionの出力をジョブログに残しておくと、障害時の切り分けが速くなります。
パラメーター永続化を見落とす
Azure CLIでは、環境によってパラメーター永続化の設定が使われている場合があります。PR内でも、データベース削除コマンドのエラーメッセージにおいて、--resource-group、--server-name、--nameの明示や、az config param-persist showによる確認に触れる修正が入っています。 (GitHub)
過去に永続化されたnameがサーバー名として残っていると、新構文では意図しない値として解釈される可能性があります。自動化環境では、必要な値をコマンドラインで明示し、暗黙の既定値に依存しない設計にするほうが安全です。
本番反映前のチェックリスト
本番環境で変更を反映する前に、次のチェックを済ませてください。
| チェック項目 | 合格条件 |
|---|---|
| 対象コマンドの棚卸し | backup、db、firewall-rule、long-term-retention、migration、replica createを含むスクリプトを洗い出している |
-nの意味確認 | -nがサーバー名なのか、操作対象名なのかをすべて確認している |
| 新構文への修正 | サーバー名は--server-name、操作対象は--nameとして書き分けている |
| 検証環境での実行 | 少なくともlist、show、代表的なcreateを検証している |
| CI/CDのログ確認 | az versionと対象コマンドの実行結果をログで確認できる |
| 手順書更新 | 社内Wiki、Runbook、障害対応手順の古い構文を修正している |
| ロールバック方針 | CLIバージョン固定で一時回避する場合の期限と担当者を決めている |
CLIバージョンを一時的に固定することは、移行時間を確保する手段にはなります。ただし、破壊的変更そのものを避け続ける対策にはなりません。最終的には、新しいパラメーター設計に合わせてスクリプトを更新する必要があります。
まずやるべき対応
今回のAzure SQL documentation updateで確認すべきポイントは明確です。az postgres flexible-serverの子リソース操作では、--nameを「操作対象の名前」、--server-nameを「サーバー名」として使う前提に移行してください。
最初にやるべきことは、Azure CLIを更新することではなく、旧構文の検索です。リポジトリ、CI/CD、Runbook、社内Wikiから対象コマンドを洗い出し、-nや--nameが何を指しているかを確認します。そのうえで、検証環境で新構文を実行し、問題がなければ本番用のスクリプトと手順書を更新します。
Azure Database for PostgreSQL Flexible ServerをCLIで管理しているチームにとって、この変更は小さな表記変更ではなく、運用自動化の前提が変わる変更です。特にバックアップ、ファイアウォール、移行、レプリカ作成は本番影響が出やすいため、早めに棚卸ししておくことが安全です。
コメント