database: close pgxpool on db.Close and apply pool defaults to pgxpool

database/database.go

@@ -36,11 +36,15 @@ func New(ctx context.Context, logger log.Logger, config DatabaseConfig) (*sql.DB
 		}
 		return db, nil
 	} else if config.Postgres != nil {
+		// Pool settings are applied to pgxpool inside postgresConnection.
+		// Do not call ApplyConnectionsConfig on the returned *sql.DB:
+		// OpenDBFromPool requires MaxIdleConns=0, and sql.DB setters do not
+		// configure the underlying pgxpool.
 		db, err := postgresConnection(ctx, logger, *config.Postgres, config.DatabaseName)
 		if err != nil {
 			return nil, fmt.Errorf("connecting to postgres: %w", err)
 		}
-		return ApplyConnectionsConfig(db, &config.Postgres.Connections, logger), nil
+		return db, nil
 	}
 
 	return nil, ErrMissingConfig
@@ -112,3 +116,17 @@ func ApplyConnectionsConfig(db *sql.DB, connections *ConnectionsConfig, logger l
 
 	return db
 }
+
+// ApplyPostgresConnectionsConfig applies connection pool settings with safe defaults
+// onto a *sql.DB.
+//
+// Deprecated: Postgres connections from New use pgxpool under the hood. Pool
+// settings are applied via ApplyPostgresPoolConfig inside postgresConnection.
+// Calling this on a Postgres *sql.DB from New is incorrect: SetMaxIdleConns
+// with a non-zero value breaks OpenDBFromPool, and the other setters do not
+// configure the underlying pgxpool. Prefer ConnectionsConfig on PostgresConfig
+// (applied automatically) or ApplyPostgresPoolConfig when building a pool.
+func ApplyPostgresConnectionsConfig(db *sql.DB, connections *ConnectionsConfig, logger log.Logger) *sql.DB {
+	applied := ResolvePostgresConnectionsConfig(*connections)
+	return ApplyConnectionsConfig(db, &applied, logger)
+}

database/database_test.go

@@ -8,6 +8,7 @@ import (
 	"errors"
 	"os"
 	"testing"
+	"time"
 
 	gomysql "github.com/go-sql-driver/mysql"
 	"github.com/jackc/pgx/v5/pgconn"
@@ -121,6 +122,33 @@ func TestDataTooLong(t *testing.T) {
 	}
 }
 
+func TestResolvePostgresConnectionsConfig_Defaults(t *testing.T) {
+	defaults := database.DefaultPostgresConnectionsConfig()
+	got := database.ResolvePostgresConnectionsConfig(database.ConnectionsConfig{})
+	require.Equal(t, defaults, got)
+}
+
+func TestResolvePostgresConnectionsConfig_Overrides(t *testing.T) {
+	in := database.ConnectionsConfig{
+		MaxOpen:     10,
+		MaxIdle:     3,
+		MaxLifetime: time.Minute,
+		MaxIdleTime: time.Second * 15,
+	}
+	got := database.ResolvePostgresConnectionsConfig(in)
+	require.Equal(t, in, got)
+}
+
+func TestDefaultPostgresConnectionsConfig(t *testing.T) {
+	defaults := database.DefaultPostgresConnectionsConfig()
+	require.Greater(t, defaults.MaxOpen, 0)
+	require.Greater(t, defaults.MaxIdle, 0)
+	require.Greater(t, defaults.MaxLifetime, time.Duration(0))
+	require.Greater(t, defaults.MaxIdleTime, time.Duration(0))
+	// MaxIdleTime should be shorter than MaxLifetime
+	require.Less(t, defaults.MaxIdleTime, defaults.MaxLifetime)
+}
+
 func TestConnectionsConfigOrder(t *testing.T) {
 	bs, err := os.ReadFile("database.go")
 	require.NoError(t, err)

database/model_config.go

@@ -99,6 +99,28 @@ type ConnectionsConfig struct {
 	MaxIdleTime time.Duration
 }
 
+// DefaultPostgresConnectionsConfig returns connection pool defaults tuned for
+// database failover recovery (e.g. AlloyDB maintenance switchovers).
+//
+// These are applied by ResolvePostgresConnectionsConfig / ApplyPostgresPoolConfig
+// whenever a field on ConnectionsConfig is zero. pgxpool always uses a finite
+// MaxConns (unlike database/sql, where MaxOpen=0 means unlimited), so leaving
+// MaxOpen unset would otherwise silently fall back to max(4, NumCPU()).
+// Explicit defaults keep pool size and eviction policy predictable across
+// services that never set Connections.
+//
+// Short MaxLifetime / MaxIdleTime help the background reaper drop stale
+// connections after a primary change; acquire-time liveness is separate
+// (pgxpool ShouldPing / PingTimeout).
+func DefaultPostgresConnectionsConfig() ConnectionsConfig {
+	return ConnectionsConfig{
+		MaxOpen:     25,
+		MaxIdle:     5,
+		MaxLifetime: 5 * time.Minute,
+		MaxIdleTime: 30 * time.Second,
+	}
+}
+
 type RetryConfig struct {
 	MaxAttempts int
 	MinDuration time.Duration