Add non-blocking asyncpg support to SQLAlchemy Entra authentication

[pabloacan]

Is your feature request related to a problem? Please describe.
enable_entra_authentication_async configures an asynchronous SQLAlchemy engine,
but its do_connect event listener is synchronous and requires a synchronous
TokenCredential. As a result, applications using
postgresql+asyncpg and azure.identity.aio.DefaultAzureCredential cannot obtain
Microsoft Entra tokens without introducing custom token caching and connection-event
workarounds. Calling the synchronous credential path from an async application can
also block the event loop.

Describe the solution you'd like
Add a SQLAlchemy integration path for postgresql+asyncpg that accepts an
AsyncTokenCredential and acquires Entra connection information through the
existing get_entra_conninfo_async API.

Because SQLAlchemy's do_connect listener cannot await a coroutine, the integration
should use SQLAlchemy's asynchronous connection-creation hook (async_creator) to:

• acquire the token and PostgreSQL principal asynchronously;
• open an asyncpg connection with the Entra token as its password;
• return the driver connection to SQLAlchemy's async pool.

The existing enable_entra_authentication_async API must remain compatible with
synchronous TokenCredential implementations and async engines backed by drivers
that use the synchronous event hook.

The package should provide:

• a documented public helper or factory for the asyncpg integration;
• an optional dependency extra for asyncpg, if required;
• unit tests covering async credential validation, token injection, failures, and
  concurrent connection creation;
• a live test and a README example using azure.identity.aio.DefaultAzureCredential.

Describe alternatives you've considered
Applications can manually cache tokens, inject them into asyncpg connection
parameters, and refresh them before creating connections. This duplicates
azure-postgresql-auth behavior, risks stale tokens and secret exposure in URLs,
and does not provide a reusable solution for SQLAlchemy users.

Using enable_entra_authentication_async with a synchronous
DefaultAzureCredential works for supported drivers, but token acquisition still
runs synchronously in the connection event and is unsuitable when the application
requires an end-to-end asynchronous credential flow.

Additional context
The package already exposes get_entra_conninfo_async and supports
AsyncTokenCredential in psycopg3.AsyncEntraConnection; this feature would extend
that capability to SQLAlchemy applications using asyncpg.

The change must not attempt to make SQLAlchemy's do_connect listener awaitable:
SQLAlchemy invokes that listener synchronously.

[github-actions]

🎯 Agentic Issue Triage

Summary: The author requests native async SQLAlchemy support for azure-postgresql-auth using asyncpg, so applications can acquire Entra tokens with AsyncTokenCredential (e.g., azure.identity.aio.DefaultAzureCredential) without blocking the event loop.

📋 Issue Details

Package: azure-postgresql-auth
Affected API: enable_entra_authentication_async, get_entra_conninfo_async
Scenarios:

• Using postgresql+asyncpg SQLAlchemy dialect with AsyncTokenCredential — currently unsupported because do_connect is synchronous
• Applications with fully async credential flows that cannot use the synchronous DefaultAzureCredential path without risking event-loop blocking

Root ask: Add a new integration path (e.g., via SQLAlchemy's async_creator hook) that accepts an AsyncTokenCredential, acquires the Entra token asynchronously, and returns an asyncpg driver connection to SQLAlchemy's async pool; with tests, docs, and README example.

🔎 Debugging / Reproduction Notes

The existing enable_entra_authentication_async function attaches a synchronous do_connect event handler. When paired with asyncpg and an async credential, the credential's get_token coroutine cannot be awaited inside that handler, forcing callers to use manual token caching workarounds.

Suggested investigation steps:

1. Review current enable_entra_authentication_async implementation and confirm it uses a synchronous do_connect listener incompatible with asyncpg.
2. Evaluate SQLAlchemy's async_creator parameter as the integration point for fully async connection creation.
3. Determine whether asyncpg should be an optional dependency extra or already in scope.
4. Design the public API (helper/factory function) and assess backward-compatibility impact on existing synchronous TokenCredential users.
5. Add unit tests for async credential validation, token injection, failure paths, and concurrent connection creation, plus a live test and README example.

🏷️ Label Confidence

• Category: Client — azure-postgresql-auth is a data-plane authentication library (not an azure-mgmt-* package).
• Service: PostgreSQL Auth — the issue explicitly targets azure-postgresql-auth and its Entra authentication APIs.
• Confidence: High — package name is unambiguous and maps directly to the PostgreSQL Auth service label (color #e99695) found in CODEOWNERS and the label registry.

👥 Owner Routing

• Matched CODEOWNERS entry: # ServiceLabel: %PostgreSQL Auth (line 365) — service label matches exactly.
• AzureSdkOwners: none listed in this entry's block.
• ServiceOwners: none listed in this entry's block.
• Routing action: Applied needs-team-triage — matched entry has no AzureSdkOwners or ServiceOwners; manual assignment required.
• Scan notes: Bottom-to-top scan also encountered # ServiceLabel: %PostgreSQL %Service Attention (line 689) and a second # ServiceLabel: %PostgreSQL Auth (line 692); the first match from the bottom that equals the predicted service label "PostgreSQL Auth" is line 365 per first-match-wins semantics. The %PostgreSQL entry was skipped as it does not equal "PostgreSQL Auth".

Generated by Agentic Triage for issue #48365 · 28.4 AIC · ⌖ 7.48 AIC · ⊞ 9.6K · ◷