postgres

Overview ¶

Package postgres provides a shared PostgreSQL connection layer for the ToolHive ecosystem. It wraps github.com/jackc/pgx/v5/pgxpool with a single Config type, a NewPool factory, and a dynamic-authentication dispatcher. Schema management — migrations, queries, and per-application type codecs — remains the caller's responsibility.

Quick Start ¶

cfg := &postgres.Config{
    Host:     "db.example.com",
    Port:     5432,
    User:     "appuser",
    Password: "s3cret",
    Database: "appdb",
}

pool, err := postgres.NewPool(ctx, cfg)
if err != nil {
    return err
}
defer pool.Close()

Dynamic Authentication ¶

Setting Config.DynamicAuth causes NewPool to install a BeforeConnect hook that resolves a fresh credential before every connection attempt.

Currently supported backends:

• AWS RDS IAM — short-lived tokens signed with the workload's ambient AWS credentials (env vars, EC2 instance profile, EKS web identity, …). Region "detect" auto-discovers the region via IMDS.

Example:

cfg.DynamicAuth = &postgres.DynamicAuthConfig{
    AWSRDSIAM: &postgres.DynamicAuthAWSRDSIAM{Region: "us-east-1"},
}

For short-lived connections that cannot use a pool hook (for example golang-migrate's one-shot migration connection), call NewAuthToken to materialize a single token, then embed it via BuildConnectionStringWithAuth:

token, _ := postgres.NewAuthToken(ctx, cfg, cfg.GetMigrationUser())
connStr := cfg.BuildConnectionStringWithAuth(cfg.GetMigrationUser(), token)

Hooks ¶

WithAfterConnect installs an AfterConnect callback — the canonical place to register application-specific type codecs (for example, codecs for PostgreSQL enum array types defined in the caller's schema):

pool, err := postgres.NewPool(ctx, cfg,
    postgres.WithAfterConnect(func(ctx context.Context, conn *pgx.Conn) error {
        return registerMyEnumCodecs(ctx, conn)
    }),
)

WithBeforeConnect installs a BeforeConnect hook directly. It is mutually exclusive with Config.DynamicAuth — NewPool refuses both, because silently dropping one would leave production tokens to expire ~15 minutes after deploy. Callers that genuinely need both should call NewDynamicAuthFunc, compose with their hook, and pass the composition via WithBeforeConnect with Config.DynamicAuth left nil.

TLS and SSL Mode ¶

DefaultSSLMode is "require", which mandates an encrypted connection but does not verify the server certificate against a CA. This defends against passive eavesdropping; it does not defend against an active attacker that can present a forged certificate. For production deployments against cloud Postgres services that publish a CA bundle (for example AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL), set SSLMode to "verify-full" and configure pgx with the appropriate CA roots — typically by placing the bundle on disk and setting PGSSLROOTCERT, or by attaching a *tls.Config via WithAfterConnect. "require" is kept as the package default because tighter modes break self-signed and dev environments out of the box; production callers should opt up explicitly.

Logging ¶

NewPool emits a single info-level message on success, redacting password fields via Config's slog.LogValuer implementation. StartPoolStatsLogger is an opt-in helper that periodically logs connection-pool statistics at debug level until its context is cancelled.

Secrets Handling ¶

This package treats Password and MigrationPassword as already-resolved strings. File-based secret loading, environment-variable overrides, and pgpass fallback all live in the caller's configuration layer. Config implements slog.LogValuer to redact credentials when logged.