Connect to Azure Database for PostgreSQL from your Mac

What you need

• The server name and admin login from the Azure portal, and the admin password (or a Microsoft Entra ID user, see below).
• A firewall rule for your IP address, if the server uses public access. A server created with private access (virtual network integration) has no public endpoint; reach it from inside the virtual network, for example through an SSH tunnel via a VM there.

Find your connection details

1. In the Azure portal, open the server and its Overview page.
2. Copy the Server name, which is the host: <server>.postgres.database.azure.com.
3. Copy the Administrator login: on a flexible server it’s the plain name you chose, such as myadmin.

The port is 5432, or 6432 for the built-in PgBouncer. Every server has a postgres database.

Firewall rules. With public access, no IP address is allowed until you add one. On the server’s Networking page, add your current client IP. Rules must be IPv4, and changes can take up to five minutes to apply. Allow public access from any Azure service lets in all of Azure, including other customers’ subscriptions, so it doesn’t help from your Mac and widens access.

Microsoft recommends always connecting with the server name, not an IP address: the IP can change.

PgBouncer. On General Purpose and Memory Optimized servers (not Burstable), you can turn on the built-in PgBouncer with the pgbouncer.enabled server parameter (Parameters pane; no restart needed). It listens on port 6432 on the same host name and pools in transaction mode by default.

Connection string

postgresql://<admin>:<password>@<server>.postgres.database.azure.com:5432/postgres?sslmode=verify-full

The portal and Microsoft’s quickstart use the key–value form:

host=<server>.postgres.database.azure.com port=5432 dbname=postgres user=<admin> password=<password> sslmode=require

Percent-encode special characters in the URL form; see special characters in passwords.

TLS

The server requires TLS by default (the require_secure_transport parameter is on) and accepts TLS 1.2 and 1.3 only. Microsoft asks you not to turn that off.

Server certificates chain to public root CAs. Microsoft lists DigiCert Global Root G2 and Microsoft RSA Root CA 2017 as the ones to trust (in China regions, DigiCert Global Root CA is still valid too). Both are among the roots macOS trusts (checked on macOS 26.2, which also has them in /etc/ssl/cert.pem). Use sslmode=verify-full: by default libpq clients use prefer and don’t check the certificate at all.

Connect with Inlet

1. Choose New Connection and enter the server name, port 5432, admin login and postgres, or paste a postgresql:// URL and Inlet fills in the form.
2. Under TLS, choose verify-full. Inlet checks the certificate against the certificates macOS trusts, so you don’t need a CA file.
3. For a private access server, turn on the SSH tunnel through a VM in the virtual network. Inlet runs the system ssh, so your ~/.ssh/config, the SSH agent and the 1Password SSH agent work.
4. Save the password in the Keychain or have Inlet ask every time.
5. Tag the environment. A production connection opens read-only: the server refuses writes until you unlock it, for ten minutes.

Use port 5432 for production. Inlet’s read-only mode is a session setting. Through PgBouncer on 6432 in transaction mode, each transaction can use a different server connection, and PgBouncer doesn’t reset session state in that mode, so the setting isn’t guaranteed to hold. To make a role read-only however it connects, set it on the server: ALTER ROLE <role> SET default_transaction_read_only = on. That’s a default a session can change, so for a hard limit give the role only SELECT.

Microsoft Entra ID. Get a token with az account get-access-token --resource-type oss-rdbms and use it as the password, with your Entra user principal name (for example user@tenant.onmicrosoft.com) as the user. Tokens last between 5 and 60 minutes, so choose to be asked for the password and paste a fresh one when you connect.

Connect from the command line

Microsoft’s example with certificate checks; on a Mac, point sslrootcert at the system roots:

psql "sslmode=verify-full sslrootcert=/etc/ssl/cert.pem host=<server>.postgres.database.azure.com dbname=postgres user=<admin>"

Through PgBouncer, change the port:

psql "host=<server>.postgres.database.azure.com port=6432 dbname=postgres user=<admin> sslmode=require"

With a Microsoft Entra ID token:

export PGPASSWORD=$(az account get-access-token --resource-type oss-rdbms --query "[accessToken]" -o tsv)
psql "host=<server>.postgres.database.azure.com user=<you@tenant.onmicrosoft.com> dbname=postgres sslmode=require"

Troubleshooting

• Connection timed out: Microsoft’s first suspect is the firewall. Add your current IP on the Networking page (or with az postgres flexible-server firewall-rule create), and allow a few minutes. If your IP changes often, ask your provider for its range. See connection refused.
• no pg_hba.conf entry for host: Microsoft shows this as the error when the firewall blocks a connection.
• TLS required: if your client sends sslmode=disable, the server refuses it. Use require or verify-full.
• password authentication failed: check the admin login and password; Entra user and group names are case-sensitive, and tokens expire.
• Too many connections: route your application through PgBouncer on 6432.