azure-postgres

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure Database for PostgreSQL

Configure passwordless authentication with Microsoft Entra ID for existing Azure Database for PostgreSQL Flexible Server. This skill focuses on setting up Entra ID authentication, managing user access, and migrating from password-based authentication.

Primary use cases:

Migrating existing PostgreSQL databases from password to Entra ID authentication
Setting up developer access with Azure identities
Configuring managed identity access for Azure-hosted applications
Managing group-based access control and permissions

为现有Azure Database for PostgreSQL灵活服务器配置基于Microsoft Entra ID的无密码身份验证。本技能重点介绍如何设置Entra ID身份验证、管理用户访问权限，以及从基于密码的身份验证进行迁移。

主要使用场景：

将现有PostgreSQL数据库从密码身份验证迁移至Entra ID身份验证
使用Azure标识设置开发者访问权限
为Azure托管应用程序配置托管标识访问权限
管理基于组的访问控制与权限

MCP Tools (Preferred)

MCP工具（首选）

When Azure MCP is enabled, use these tools for PostgreSQL operations:

```
azure__postgres
```
with command
```
postgres_server_list
```
- List PostgreSQL servers
```
azure__postgres
```
with command
```
postgres_database_list
```
- List databases on a server
```
azure__postgres
```
with command
```
postgres_database_query
```
- Execute SQL queries

azure__postgres

with command

postgres_server_param_get

- Get server parameters

azure__postgres

with command

postgres_server_param_set

- Set server parameters

启用Azure MCP后，可使用以下工具执行PostgreSQL操作：

```
azure__postgres
```
搭配命令
```
postgres_server_list
```
- 列出PostgreSQL服务器
```
azure__postgres
```
搭配命令
```
postgres_database_list
```
- 列出服务器上的数据库
```
azure__postgres
```
搭配命令
```
postgres_database_query
```
- 执行SQL查询

azure__postgres

搭配命令

postgres_server_param_get

- 获取服务器参数

azure__postgres

搭配命令

postgres_server_param_set

- 设置服务器参数

CLI Commands (Fallback)

CLI命令（备选）

bash

az postgres flexible-server list --output table
az postgres flexible-server db list --server-name SERVER -g RG
az postgres flexible-server show --name SERVER -g RG
az postgres flexible-server create --name SERVER -g RG --location REGION --admin-user ADMIN --version 16

bash

az postgres flexible-server list --output table
az postgres flexible-server db list --server-name SERVER -g RG
az postgres flexible-server show --name SERVER -g RG
az postgres flexible-server create --name SERVER -g RG --location REGION --admin-user ADMIN --version 16

Quick Reference

快速参考

Property	Value
CLI prefix	`az postgres flexible-server`
MCP tools	`azure__postgres`
Best for	Relational data, PostgreSQL compatibility, PostGIS
Engine versions	PostgreSQL 11, 12, 13, 14, 15, 16 (recommended)

属性	值
CLI前缀	`az postgres flexible-server`
MCP工具	`azure__postgres`
适用场景	关系型数据、PostgreSQL兼容性、PostGIS
引擎版本	PostgreSQL 11、12、13、14、15、16（推荐）

Working with Existing PostgreSQL Servers

操作现有PostgreSQL服务器

This skill primarily focuses on configuring authentication for existing PostgreSQL servers. If you need to reference or create servers, use MCP tools or CLI commands, and provide Azure Portal links for easy access.

Portal Link Format:

https://portal.azure.com/#@{tenant-domain}/resource/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.DBforPostgreSQL/flexibleServers/{server-name}/overview

Example portal link:

View in Azure Portal:
https://portal.azure.com/#resource/subscriptions/abc123.../resourceGroups/myrg/providers/Microsoft.DBforPostgreSQL/flexibleServers/myserver/overview

本技能主要聚焦于为现有PostgreSQL服务器配置身份验证。若需引用或创建服务器，请使用MCP工具或CLI命令，并提供Azure门户链接以便快速访问。

门户链接格式：

https://portal.azure.com/#@{tenant-domain}/resource/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.DBforPostgreSQL/flexibleServers/{server-name}/overview

示例门户链接：

在Azure门户中查看：
https://portal.azure.com/#resource/subscriptions/abc123.../resourceGroups/myrg/providers/Microsoft.DBforPostgreSQL/flexibleServers/myserver/overview

Microsoft Entra ID Authentication (Critical)

Microsoft Entra ID身份验证（关键）

⚠️ ALWAYS use passwordless authentication with Entra ID for production workloads.

⚠️ 生产工作负载请始终使用基于Entra ID的无密码身份验证。

Complete Setup Guide

完整设置指南

→ Microsoft Entra ID Authentication Setup Guide

This guide covers:

Enabling Entra ID authentication on PostgreSQL servers
Creating PostgreSQL roles mapped to Azure identities
Granting database permissions
Connecting with access tokens instead of passwords

→ Microsoft Entra ID身份验证设置指南

本指南涵盖：

在PostgreSQL服务器上启用Entra ID身份验证
创建映射到Azure标识的PostgreSQL角色
授予数据库权限
使用访问令牌替代密码进行连接

Quick Setup Patterns

快速设置模式

Use these patterns based on your scenario:

Scenario	Guide Link	Use When
Developer Access	Pattern 1	Grant developers access with their Azure identity
App Authentication	Pattern 2	Passwordless access for Azure-hosted apps (Container Apps, App Service, Functions)
Team Access	Pattern 3	Manage permissions via Azure AD groups
Connection Issues	Troubleshooting	Diagnose authentication and connection failures
Migration	Pattern 5	Transition from password to Entra ID authentication

根据你的场景使用以下模式：

场景	指南链接	使用时机
开发者访问	模式1	为开发者授予其Azure标识的访问权限
应用程序身份验证	模式2	为Azure托管应用（容器应用、应用服务、函数）提供无密码访问权限
团队访问	模式3	通过Azure AD组管理权限
连接问题	故障排查	诊断身份验证与连接失败问题
迁移	模式5	从密码身份验证过渡到Entra ID身份验证

Service Tiers

服务层级

Tier	vCores	Memory	Use Case
Burstable	1-20	0.5-4 GB/vCore	Dev/test, low traffic
General Purpose	2-64	4 GB/vCore	Most production workloads
Memory Optimized	2-64	8 GB/vCore	High-memory workloads

Start with Burstable for dev/test, scale up as needed.

层级	vCPU核心数	内存	适用场景
突发型	1-20	0.5-4 GB/vCPU核心	开发/测试、低流量场景
通用型	2-64	4 GB/vCPU核心	大多数生产工作负载
内存优化型	2-64	8 GB/vCPU核心	高内存工作负载

开发/测试环境从突发型开始，按需扩容。

Common Issues

常见问题

Issue	Cause	Solution
`role does not exist`	Role not created in database	Run `pgaadauth_create_principal` - see guide
`password authentication failed`	Token expired (5-60 min validity)	Get fresh token: `az account get-access-token --resource-type oss-rdbms`
`permission denied`	Role lacks permissions	Run `GRANT` statements - see templates
Connection timeout	Firewall blocking access	Add firewall rule: `az postgres flexible-server firewall-rule create`
Guest user login fails	Wrong UPN format	Use full UPN with `#EXT#` tag from Azure AD

问题	原因	解决方案
`role does not exist`	数据库中未创建角色	运行 `pgaadauth_create_principal` - 查看指南
`password authentication failed`	令牌过期（有效期5-60分钟）	获取新令牌： `az account get-access-token --resource-type oss-rdbms`
`permission denied`	角色缺少权限	运行 `GRANT` 语句 - 查看模板
连接超时	防火墙阻止访问	添加防火墙规则： `az postgres flexible-server firewall-rule create`
来宾用户登录失败	UPN格式错误	使用包含 `#EXT#` 标签的完整UPN（来自Azure AD）

References

参考资料

Microsoft Entra ID Authentication Setup - Complete passwordless authentication guide
SQL Functions - Entra ID role management functions
Permission Templates - Common permission patterns
Troubleshooting - Connection and auth issues

Microsoft Entra ID身份验证设置 - 完整无密码身份验证指南
SQL函数 - Entra ID角色管理函数
权限模板 - 常见权限模式
故障排查 - 连接与身份验证问题