feat(pgdb): add DATABASE_URI environment variable support

Add support for PostgreSQL connection URIs via DATABASE_URI env var.
When set, it takes precedence over config files and PoolOptions are
ignored (pool settings can be specified in URI query string).

database/pgdb/CLAUDE.md

@@ -93,8 +93,34 @@ sslmode: prefer
 
 ## Environment Variables
 
+- `DATABASE_URI` - PostgreSQL connection URI (takes precedence over config files)
 - `DATABASE_CONFIG_FILE` - Override config file location
 
+### URI Format
+
+Standard PostgreSQL URI format:
+```
+postgresql://user:password@host:port/database?sslmode=require&pool_max_conns=10
+```
+
+Pool settings can be included in the URI query string:
+- `pool_max_conns`, `pool_min_conns`
+- `pool_max_conn_lifetime`, `pool_max_conn_idle_time`
+- `pool_health_check_period`
+
+When using `DATABASE_URI`, `PoolOptions` are ignored and all settings come from the URI.
+
+Example with CloudNativePG:
+```yaml
+# Mount the secret's 'uri' key as DATABASE_URI
+env:
+  - name: DATABASE_URI
+    valueFrom:
+      secretKeyRef:
+        name: mydb-app
+        key: uri
+```
+
 ## When to Use
 
 **Use `pgdb.OpenPool()`** (this package) when:

database/pgdb/pool.go

@@ -51,25 +51,45 @@ func DefaultPoolOptions() PoolOptions {
 
 // OpenPool opens a native pgx connection pool with the specified configuration
 // This is the primary and recommended way to connect to PostgreSQL
+//
+// Configuration precedence (highest to lowest):
+// 1. DATABASE_URI environment variable (pool settings can be included in URI)
+// 2. DATABASE_CONFIG_FILE environment variable (YAML)
+// 3. Default config files (database.yaml, /vault/secrets/database.yaml)
+//
+// When using DATABASE_URI, pool settings (pool_max_conns, pool_min_conns, etc.)
+// can be specified in the URI query string and PoolOptions are ignored.
+// When using config files, PoolOptions are applied.
 func OpenPool(ctx context.Context, options PoolOptions) (*pgxpool.Pool, error) {
-	// Find and read config file
+	var poolConfig *pgxpool.Config
-	pgCfg, err := findAndParseConfig(options.ConfigFiles)
+	var err error
-	if err != nil {
-		return nil, err
-	}
 
-	// Create pool config from PostgreSQL config
+	// Check DATABASE_URI environment variable first (highest priority)
-	poolConfig, err := CreatePoolConfig(pgCfg)
+	if uri := os.Getenv("DATABASE_URI"); uri != "" {
-	if err != nil {
+		poolConfig, err = pgxpool.ParseConfig(uri)
-		return nil, err
+		if err != nil {
-	}
+			return nil, fmt.Errorf("failed to parse DATABASE_URI: %w", err)
+		}
+		// Pool settings from URI are used; PoolOptions ignored
+	} else {
+		// Fall back to config file approach
+		pgCfg, err := findAndParseConfig(options.ConfigFiles)
+		if err != nil {
+			return nil, err
+		}
 
-	// Apply pool-specific settings
+		poolConfig, err = CreatePoolConfig(pgCfg)
-	poolConfig.MinConns = options.MinConns
+		if err != nil {
-	poolConfig.MaxConns = options.MaxConns
+			return nil, err
-	poolConfig.MaxConnLifetime = options.MaxConnLifetime
+		}
-	poolConfig.MaxConnIdleTime = options.MaxConnIdleTime
+
-	poolConfig.HealthCheckPeriod = options.HealthCheckPeriod
+		// Apply pool-specific settings from PoolOptions (config files don't support these)
+		poolConfig.MinConns = options.MinConns
+		poolConfig.MaxConns = options.MaxConns
+		poolConfig.MaxConnLifetime = options.MaxConnLifetime
+		poolConfig.MaxConnIdleTime = options.MaxConnIdleTime
+		poolConfig.HealthCheckPeriod = options.HealthCheckPeriod
+	}
 
 	// Create the pool
 	pool, err := pgxpool.NewWithConfig(ctx, poolConfig)

database/pgdb/pool_test.go

@@ -1,6 +1,9 @@
 package pgdb
 
 import (
+	"context"
+	"os"
+	"strings"
 	"testing"
 	"time"
 
@@ -149,3 +152,63 @@ func TestCreatePoolConfigDefaults(t *testing.T) {
 		t.Errorf("Expected default Port=5432, got %d", poolCfg.ConnConfig.Port)
 	}
 }
+
+func TestOpenPoolWithDatabaseURI(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test")
+	}
+
+	// This test requires a running PostgreSQL instance
+	uri := os.Getenv("TEST_DATABASE_URI")
+	if uri == "" {
+		t.Skip("TEST_DATABASE_URI not set")
+	}
+
+	ctx := context.Background()
+	t.Setenv("DATABASE_URI", uri)
+
+	pool, err := OpenPool(ctx, DefaultPoolOptions())
+	if err != nil {
+		t.Fatalf("OpenPool failed: %v", err)
+	}
+	defer pool.Close()
+
+	// Verify connection works
+	var result int
+	err = pool.QueryRow(ctx, "SELECT 1").Scan(&result)
+	if err != nil {
+		t.Fatalf("query failed: %v", err)
+	}
+	if result != 1 {
+		t.Errorf("expected 1, got %d", result)
+	}
+}
+
+func TestDatabaseURIPrecedence(t *testing.T) {
+	// Test that DATABASE_URI takes precedence over config files
+	// We use localhost with a port that's unlikely to have postgres running
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+
+	// Set DATABASE_URI to a parseable URI pointing to a non-listening port
+	t.Setenv("DATABASE_URI", "postgres://testuser:testpass@127.0.0.1:59999/testdb?connect_timeout=1")
+
+	// Set config files to a nonexistent path - if this were used, we'd get
+	// "config file not found" error instead of connection refused
+	opts := DefaultPoolOptions()
+	opts.ConfigFiles = []string{"/nonexistent/path/database.yaml"}
+
+	_, err := OpenPool(ctx, opts)
+
+	// Should fail with connection error (not config file error)
+	// This proves DATABASE_URI was used instead of config files
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+
+	// The error should be about connection failure, not about missing config file
+	errStr := err.Error()
+	if strings.Contains(errStr, "config file") || strings.Contains(errStr, "no such file") {
+		t.Errorf("expected connection error, got config file error: %v", err)
+	}
+}

metricsserver/metrics.go

@@ -3,6 +3,24 @@
 // This package implements a dedicated metrics server that exposes application metrics
 // via HTTP. It uses a custom Prometheus registry to avoid conflicts with other metric
 // collectors and provides graceful shutdown capabilities.
+//
+// # Usage
+//
+// Create a new metrics server and register your metrics with its Registry():
+//
+//	m := metricsserver.New()
+//	myCounter := prometheus.NewCounter(...)
+//	m.Registry().MustRegister(myCounter)
+//
+// When you need a Gatherer (for example, to pass to other libraries), use the Gatherer() method
+// instead of prometheus.DefaultGatherer to ensure your custom metrics are collected:
+//
+//	gatherer := m.Gatherer()  // Returns the custom registry as a Gatherer
+//
+// To use the default Prometheus gatherer alongside your custom registry:
+//
+//	m := metricsserver.NewWithDefaultGatherer()
+//	m.Gatherer()  // Returns prometheus.DefaultGatherer
 package metricsserver
 
 import (
@@ -21,15 +39,32 @@ import (
 // Metrics provides a custom Prometheus registry and HTTP handlers for metrics exposure.
 // It isolates application metrics from the default global registry.
 type Metrics struct {
-	r *prometheus.Registry
+	r                  *prometheus.Registry
+	useDefaultGatherer bool
 }
 
 // New creates a new Metrics instance with a custom Prometheus registry.
+// Use this when you want isolated metrics that don't interfere with the default registry.
 func New() *Metrics {
 	r := prometheus.NewRegistry()
 
 	m := &Metrics{
-		r: r,
+		r:                  r,
+		useDefaultGatherer: false,
+	}
+
+	return m
+}
+
+// NewWithDefaultGatherer creates a new Metrics instance that uses the default Prometheus gatherer.
+// This is useful when you want to expose metrics from the default registry alongside your custom metrics.
+// The custom registry will still be available via Registry() but Gatherer() will return prometheus.DefaultGatherer.
+func NewWithDefaultGatherer() *Metrics {
+	r := prometheus.NewRegistry()
+
+	m := &Metrics{
+		r:                  r,
+		useDefaultGatherer: true,
 	}
 
 	return m
@@ -41,6 +76,23 @@ func (m *Metrics) Registry() *prometheus.Registry {
 	return m.r
 }
 
+// Gatherer returns the Prometheus gatherer to use for collecting metrics.
+// This returns the custom registry's Gatherer by default, ensuring your registered
+// metrics are collected. If the instance was created with NewWithDefaultGatherer(),
+// this returns prometheus.DefaultGatherer instead.
+//
+// Use this method when you need a prometheus.Gatherer interface, for example when
+// configuring other libraries that need to collect metrics.
+//
+// IMPORTANT: Do not use prometheus.DefaultGatherer directly if you want to collect
+// metrics registered with this instance's Registry(). Always use this Gatherer() method.
+func (m *Metrics) Gatherer() prometheus.Gatherer {
+	if m.useDefaultGatherer {
+		return prometheus.DefaultGatherer
+	}
+	return m.r
+}
+
 // Handler returns an HTTP handler for the /metrics endpoint with OpenMetrics support.
 func (m *Metrics) Handler() http.Handler {
 	log := logger.NewStdLog("prom http", false, nil)

metricsserver/metrics_test.go

@@ -67,6 +67,47 @@ func TestRegistry(t *testing.T) {
 	}
 }
 
+func TestGatherer(t *testing.T) {
+	metrics := New()
+
+	gatherer := metrics.Gatherer()
+	if gatherer == nil {
+		t.Fatal("Gatherer() returned nil")
+	}
+
+	// Register a test metric
+	counter := prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "test_gatherer_counter",
+		Help: "A test counter for gatherer",
+	})
+
+	metrics.Registry().MustRegister(counter)
+	counter.Inc()
+
+	// Test that the gatherer collects our custom metric
+	metricFamilies, err := gatherer.Gather()
+	if err != nil {
+		t.Errorf("failed to gather metrics: %v", err)
+	}
+
+	found := false
+	for _, mf := range metricFamilies {
+		if mf.GetName() == "test_gatherer_counter" {
+			found = true
+			break
+		}
+	}
+
+	if !found {
+		t.Error("registered metric not found via Gatherer()")
+	}
+
+	// Verify gatherer is the same as registry
+	if gatherer != metrics.r {
+		t.Error("Gatherer() should return the same object as the registry for custom registry mode")
+	}
+}
+
 func TestHandler(t *testing.T) {
 	metrics := New()
 
@@ -212,6 +253,45 @@ func TestListenAndServeContextCancellation(t *testing.T) {
 	}
 }
 
+func TestNewWithDefaultGatherer(t *testing.T) {
+	metrics := NewWithDefaultGatherer()
+
+	if metrics == nil {
+		t.Fatal("NewWithDefaultGatherer returned nil")
+	}
+
+	if !metrics.useDefaultGatherer {
+		t.Error("useDefaultGatherer should be true")
+	}
+
+	gatherer := metrics.Gatherer()
+	if gatherer == nil {
+		t.Fatal("Gatherer() returned nil")
+	}
+
+	// Verify it returns the default gatherer
+	if gatherer != prometheus.DefaultGatherer {
+		t.Error("Gatherer() should return prometheus.DefaultGatherer when useDefaultGatherer is true")
+	}
+
+	// Verify the custom registry is still available and separate
+	if metrics.Registry() == nil {
+		t.Error("Registry() should still return a custom registry")
+	}
+
+	// Test that registering in custom registry doesn't affect default gatherer check
+	counter := prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "test_default_gatherer_counter",
+		Help: "A test counter",
+	})
+	metrics.Registry().MustRegister(counter)
+
+	// The gatherer should still be the default one, not our custom registry
+	if metrics.Gatherer() != prometheus.DefaultGatherer {
+		t.Error("Gatherer() should continue to return prometheus.DefaultGatherer")
+	}
+}
+
 // Benchmark the metrics handler response time
 func BenchmarkMetricsHandler(b *testing.B) {
 	metrics := New()