[antoinetoussaint-byte]

Follow-up to #205, and the thing that makes it adoptable.

The problem #205 did not solve

#205 put the external-identity declaration and the pinned trust anchor in this library, where they belong. But every constructor here is opinionated:

• Open splits a service across a reader and a writer and installs the scoped RLS factory;
• OpenMaintenance selects an application role and refuses a privileged login.

A service with one runtime principal, which owns its own tenancy model rather than delegating it to transaction-local RLS settings, fits neither. So it called pgxpool.New itself — and in doing so re-decided the transport, the trust anchor and the credential, each of which this package already decides.

Four services in this fleet did exactly that. That is not four call sites; it is four copies of three decisions, which is precisely why a managed-database or passwordless posture cannot be rolled out by changing one thing.

Classification

Fix. OpenPool is the primitive the other two constructors already build on (parse, install credential, create, ping) — exposed rather than reimplemented. It is not a second mechanism: every refusal the opinionated constructors make about a capability's transport and credential holds here too, so it is the same decision by a shorter route, not a weaker one.

What it is

pool, close, err := postgres.OpenPool(ctx, connection, profile, options...)

The profile decides the transport and the pinned authority, the options decide the credential, the caller gets a pool. It grants no role, installs no session policy and judges no privilege — a caller wanting those wants Open or OpenMaintenance.

It pings before returning. pgxpool connects lazily, so a pool handed back before its first connection succeeded moves a wrong credential, an unverifiable server or an unreachable address from boot to the first query, where it reads as a runtime fault rather than the deployment fault it is.

The legacy zero profile stays accepted, so a service adopts the library in one call and changes its TLS posture as a separate, visible step rather than as a side effect of adoption.

Reuse

Reused wholesale: ParseConnection as the single judge of a connection, resolveExternalIdentity and installAccessTokenProvider for the credential, profileConnectionError so an explicit profile still reports a capability as unavailable rather than leaking the driver's text, configured for the option surface.

Deliberately not done: refactoring Open and OpenMaintenance onto this primitive. They would read better for it, but that is a change to two working, heavily-tested constructors with no behavioural need, and it does not belong in the change that introduces the primitive.

Tests

The refusal set is asserted through OpenPool itself rather than trusted to be inherited — two credentials for one pool, a password beside a provider, a pinned transport with no anchor, an anchor on a transport that verifies nothing, an undeclared issuer, verify-full on a pinned transport — plus a nil context and an empty connection, the eager ping against a name that does not resolve, and the zero profile not being rejected as a profile error.

Not verified

The success path needs a reachable Postgres and is not exercised here; it is covered only by the refusals and the eager-ping behaviour. No connection was opened to a managed instance by this PR.

Size

~70 hand-written non-test lines, ~110 test lines, one new file plus a README section.