En/db resolver

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

@@ -239,3 +239,42 @@ 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
+Add replica hosts to your `.env` file using the `DB_REPLICA_HOSTS` variable:
+
+```env
+DB_REPLICA_HOSTS=localhost:3307,localhost:3308
+```
+
+These hosts will be treated as **read replicas**.
+
+**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,12 @@ 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_CHARSET
 - The character set for database connection
 - utf8

go.sum

@@ -1,6 +1,6 @@
 cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
-cloud.google.com/go v0.120.0 h1:wc6bgG9DHyKqF5/vQvX1CiZrtHnxJjBlKUyF9nP6meA=
-cloud.google.com/go v0.120.0/go.mod h1:/beW32s8/pGRuj4IILWQNd4uuebeT4dkOhKmkfit64Q=
+cloud.google.com/go v0.121.1 h1:S3kTQSydxmu1JfLRLpKtxRPA7rSrYPRPEUmL/PavVUw=
+cloud.google.com/go v0.121.1/go.mod h1:nRFlrHq39MNVWu+zESP2PosMWA0ryJw8KUBZ2iZpxbw=
 cloud.google.com/go/auth v0.16.3 h1:kabzoQ9/bobUmnseYnBO6qQG7q4a/CffFRlJSxv2wCc=
 cloud.google.com/go/auth v0.16.3/go.mod h1:NucRGjaXfzP1ltpcQ7On/VTZ0H4kWB5Jy+Y9Dnm76fA=
 cloud.google.com/go/auth/oauth2adapt v0.2.8 h1:keo8NaayQZ6wimpNSmW5OPc283g65QNIiLpZnkHRbnc=

go.work

@@ -1,6 +1,4 @@
-go 1.24.0
-
-toolchain go1.24.0
+go 1.24.5
 
 use (
 	.
@@ -22,4 +20,5 @@ use (
 	./pkg/gofr/datasource/scylladb
 	./pkg/gofr/datasource/solr
 	./pkg/gofr/datasource/surrealdb
+	pkg/gofr/datasource/dbresolver
 )

pkg/gofr/container/datasources.go

@@ -721,3 +721,11 @@
 
 	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/dbresolver_wrapper.go

@@ -0,0 +1,81 @@
+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
+	strategyName string
+	readFallback bool
+}
+
+// NewProvider creates a new ResolverWrapper with strategy and fallback config.
+func NewProvider(strategy string, readFallback bool) *ResolverWrapper {
+	return &ResolverWrapper{
+		strategyName: 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
+	}
+
+	// Create options slice
+	var opts []Option
+
+	var strategy Strategy
+	if r.strategyName == "random" {
+		strategy = NewRandomStrategy()
+	} else {
+		// Default to round-robin for any other value including "round-robin"
+		strategy = NewRoundRobinStrategy(len(replicas))
+	}
+
+	// Add options.
+	opts = append(opts, WithStrategy(strategy), WithFallback(r.readFallback))
+
+	// Create and return the resolver.
+	return NewResolver(primary, replicas, r.logger, r.metrics, opts...), nil
+}