En/db resolver

docs/quick-start/connecting-mysql/page.md

@@ -239,3 +239,73 @@ Now when we access {% new-tab-link title="http://localhost:9000/customer" href="
 ```
 
 **Note:** When using PostgreSQL or Supabase, you may need to use `$1` instead of `?` in SQL queries, depending on your driver configuration.
+
+### Enabling Read/Write Splitting in MySQL (DBResolver)
+GoFr provides built-in support for read/write splitting using its `DBRESOLVER` module for **MySQL**. 
+This feature allows applications to route write queries (e.g., `INSERT`, `UPDATE`) to the **primary database**, and 
+distribute read queries (`SELECT`) across **one or more replicas**, boosting performance, scalability, and reliability.
+
+Import the GoFr's dbresolver for MySQL:
+
+```shell
+go get gofr.dev/pkg/gofr/datasource/dbresolver@latest
+```
+
+After importing the package, you can configure the DBResolver in your GoFr application using the `AddDBResolver` method. 
+You can choose the load balancing strategy and enable fallback to primary:
+
+```go
+// Add DB resolver with round-robin strategy and fallback enabled
+resolver := dbresolver.NewProvider("round-robin", true)
+a.AddDBResolver(resolver)
+```
+
+- The first argument specifies the **load balancing strategy** for read queries. Supported values:
+   - `round-robin`: Distributes reads evenly across replicas.
+   - `random`: Selects a replica at random for each read.
+- The second argument enables **fallback** to the primary if all replicas are unavailable.
+
+###  Configuration
+
+#### 1. Replica Hosts
+Add replica hosts, ports,users, passwords to your `.env` file using the following configs:
+
+```env
+DB_REPLICA_HOSTS=localhost,replica1,replica2
+DB_REPLICA_PORTS=3307,3308,3309
+DB_REPLICA_USERS=readonly1,readonly2,readonly3
+DB_REPLICA_PASSWORDS=pass1,pass2,pass3
+
+```
+
+These hosts will be treated as **read replicas**.
+
+#### 2. Replica Connection Pool Tuning
+By default, GoFr automatically scales connection pools for replicas based on your primary database settings:
+
+`DB_MAX_IDLE_CONNECTION` → multiplied by 4
+`DB_MAX_OPEN_CONNECTION` → multiplied by 2
+
+This ensures replicas can handle higher read concurrency without impacting the primary.
+GoFr also applies min/max caps to keep values safe. These can be customized:
+
+```go
+# Primary DB pool settings
+DB_MAX_IDLE_CONNECTION=2
+DB_MAX_OPEN_CONNECTION=20
+
+# Replica pool overrides (optional)
+DB_REPLICA_MAX_IDLE_CAP=100
+DB_REPLICA_MIN_IDLE=5
+DB_REPLICA_DEFAULT_IDLE=15
+
+DB_REPLICA_MAX_OPEN_CAP=500
+DB_REPLICA_MIN_OPEN=20
+DB_REPLICA_DEFAULT_OPEN=150
+
+```
+
+**Benefits**
+- Performance: Offloads read traffic from the primary, reducing latency.
+- Scalability: Easily scale reads by adding more replicas.
+- Resilience: Ensures high availability through automatic fallback.

docs/references/configs/page.md

@@ -195,6 +195,67 @@ This document lists all the configuration options supported by the GoFr framewor
 
 ---
 
+- DB_REPLICA_HOSTS
+- Comma-separated list of replica database hosts. Used for read replicas.
+- None
+
+---
+
+- DB_REPLICA_PORTS
+- Comma-separated list of replica database ports. Used for read replicas.
+- None
+
+---
+
+- DB_REPLICA_USERS
+- Comma-separated list of replica database users. Used for read replicas.
+- None
+
+---
+
+- DB_REPLICA_PASSWORDS_
+- Comma-separated list of replica database passwords. Used for read replicas.
+- None
+
+---
+
+- DB_REPLICA_MAX_IDLE_CONNECTIONS
+- Maximum idle connections allowed for a replica
+- 50
+
+---
+
+- DB_REPLICA_MIN_IDLE_CONNECTIONS
+- Minimum idle connections for a replica
+- 10
+
+---
+
+- DB_REPLICA_DEFAULT_IDLE_CONNECTIONS
+- Idle connections used if no primary setting is provided
+- 10
+
+---
+
+- DB_REPLICA_MAX_OPEN_CONNECTIONS
+- Maximum open connections allowed for a replica
+- 200
+
+---
+
+- DB_REPLICA_MIN_OPEN_CONNECTIONS
+- Minimum open connections for a replica
+- 50
+
+---
+
+- DB_REPLICA_DEFAULT_OPEN_CONNECTIONS
+- Open connections used if no primary setting is provided
+- 100
+
+---
+
+
 - DB_CHARSET
 - The character set for database connection
 - utf8

go.work

@@ -7,6 +7,7 @@ use (
 	./pkg/gofr/datasource/cassandra
 	./pkg/gofr/datasource/clickhouse
 	./pkg/gofr/datasource/couchbase
+	./pkg/gofr/datasource/dbresolver
 	./pkg/gofr/datasource/dgraph
 	./pkg/gofr/datasource/elasticsearch
 	./pkg/gofr/datasource/file/ftp

pkg/gofr/container/datasources.go

@@ -776,3 +776,11 @@ type CouchbaseProvider interface {
 
 	provider
 }
+
+// DBResolverProvider defines an interface for SQL read/write splitting providers.
+type DBResolverProvider interface {
+	// Build creates a resolver with the given primary and replicas.
+	Build(primary DB, replicas []DB) (DB, error)
+
+	provider
+}

pkg/gofr/datasource/dbresolver/circuit_breaker.go

@@ -0,0 +1,55 @@
+package dbresolver
+
+import (
+	"sync/atomic"
+	"time"
+)
+
+// Circuit breaker for replica health with atomic operations.
+type circuitBreaker struct {
+	failures    atomic.Int32
+	lastFailure atomic.Int64
+	state       atomic.Int32 // 0=closed, 1=open, 2=half-open.
+	maxFailures int32
+	timeout     time.Duration
+}
+
+func newCircuitBreaker(maxFailures int32, timeout time.Duration) *circuitBreaker {
+	return &circuitBreaker{
+		maxFailures: maxFailures,
+		timeout:     timeout,
+	}
+}
+
+func (cb *circuitBreaker) allowRequest() bool {
+	state := cb.state.Load()
+
+	switch state {
+	case circuitStateClosed:
+		return true
+	case circuitStateOpen:
+		if time.Since(time.Unix(0, cb.lastFailure.Load())) > cb.timeout {
+			return cb.state.CompareAndSwap(circuitStateOpen, circuitStateHalfOpen)
+		}
+
+		return false
+	case circuitStateHalfOpen:
+		return true
+	default:
+		return true
+	}
+}
+
+func (cb *circuitBreaker) recordSuccess() {
+	cb.failures.Store(0)
+	cb.state.Store(0)
+}
+
+func (cb *circuitBreaker) recordFailure() {
+	failures := cb.failures.Add(1)
+	cb.lastFailure.Store(time.Now().UnixNano())
+
+	if failures >= cb.maxFailures {
+		cb.state.Store(1)
+	}
+}

pkg/gofr/datasource/dbresolver/dbresolver_wrapper.go

@@ -0,0 +1,78 @@
+package dbresolver
+
+import (
+	"errors"
+
+	"go.opentelemetry.io/otel/trace"
+	"gofr.dev/pkg/gofr/container"
+)
+
+var (
+	errPrimaryNil              = errors.New("primary database cannot be nil")
+	errReplicaFailedNoFallback = errors.New("replica query failed and fallback disabled")
+)
+
+// ResolverWrapper implements container.DBResolverProvider interface
+// It acts as a factory that creates a Resolver with given config.
+type ResolverWrapper struct {
+	logger       Logger
+	metrics      Metrics
+	tracer       trace.Tracer
+	strategy     Strategy
+	readFallback bool
+}
+
+// NewProvider creates a new ResolverWrapper with strategy and fallback config.
+func NewProvider(strategy Strategy, readFallback bool) *ResolverWrapper {
+	return &ResolverWrapper{
+		strategy:     strategy,
+		readFallback: readFallback,
+	}
+}
+
+// UseLogger sets the logger instance.
+func (r *ResolverWrapper) UseLogger(logger any) {
+	if l, ok := logger.(Logger); ok {
+		r.logger = l
+	}
+}
+
+// UseMetrics sets the metrics instance.
+func (r *ResolverWrapper) UseMetrics(metrics any) {
+	if m, ok := metrics.(Metrics); ok {
+		r.metrics = m
+	}
+}
+
+// UseTracer sets the tracer instance.
+func (r *ResolverWrapper) UseTracer(tracer any) {
+	if t, ok := tracer.(trace.Tracer); ok {
+		r.tracer = t
+	}
+}
+
+// Connect is no-op for wrapper as connections are created externally.
+func (*ResolverWrapper) Connect() {
+	// no-op
+}
+
+// Build creates a Resolver instance with primary and replica DBs.
+func (r *ResolverWrapper) Build(primary container.DB, replicas []container.DB) (container.DB, error) {
+	if primary == nil {
+		return nil, errPrimaryNil
+	}
+
+	// Update RoundRobinStrategy count if needed
+	if rr, ok := r.strategy.(*RoundRobinStrategy); ok {
+		rr.count = len(replicas)
+	}
+
+	// Create options slice
+	var opts []Option
+
+	// Add options.
+	opts = append(opts, WithStrategy(r.strategy), WithFallback(r.readFallback))
+
+	// Create and return the resolver.
+	return NewResolver(primary, replicas, r.logger, r.metrics, opts...), nil
+}