50 lines
1.8 KiB
Go
50 lines
1.8 KiB
Go
// 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
|