// Package dbx provides a production-ready PostgreSQL helper library built on top of pgx/v5.
//
// It manages connection pools, master/replica routing, automatic retries with
// exponential backoff, load balancing across replicas, background health checking,
// and transaction helpers.
//
// # Quick Start
//
//	cluster, err := dbx.NewCluster(ctx, dbx.Config{
//	    Master: dbx.NodeConfig{
//	        Name: "master",
//	        DSN:  "postgres://user:pass@master:5432/mydb",
//	        Pool: dbx.PoolConfig{MaxConns: 20, MinConns: 5},
//	    },
//	    Replicas: []dbx.NodeConfig{
//	        {Name: "replica-1", DSN: "postgres://...@replica1:5432/mydb"},
//	    },
//	})
//	if err != nil {
//	    log.Fatal(err)
//	}
//	defer cluster.Close()
//
//	// Write → master
//	cluster.Exec(ctx, "INSERT INTO users (name) VALUES ($1)", "alice")
//
//	// Read → replica with fallback to master
//	rows, _ := cluster.ReadQuery(ctx, "SELECT * FROM users WHERE active = $1", true)
//
//	// Transaction → master, panic-safe
//	cluster.RunTx(ctx, func(ctx context.Context, tx pgx.Tx) error {
//	    _, _ = tx.Exec(ctx, "UPDATE accounts SET balance = balance - $1 WHERE id = $2", 100, fromID)
//	    _, _ = tx.Exec(ctx, "UPDATE accounts SET balance = balance + $1 WHERE id = $2", 100, toID)
//	    return nil
//	})
//
// # Routing
//
// The library uses explicit method-based routing (no SQL parsing):
//   - Exec, Query, QueryRow, Begin, BeginTx, CopyFrom, SendBatch → master
//   - ReadQuery, ReadQueryRow → replicas with master fallback
//   - Master(), Replica() → direct access to specific nodes
//
// # Retry
//
// Retryable errors include connection errors (PG class 08), serialization failures (40001),
// deadlocks (40P01), and too_many_connections (53300). A custom classifier can be provided
// via RetryConfig.RetryableErrors.
package dbx