En/db resolver

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

@@ -239,3 +239,134 @@ 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 automatically routes requests to the **primary database** or **read replicas** based on:
+
+- **HTTP Method**: Write operations (`POST`, `PUT`, `PATCH`, `DELETE`) → Primary | Read operations (`GET`, `HEAD`, `OPTIONS`) → Replicas
+- **Route Configuration**: Force specific routes to always use the primary database for strong consistency
+
+#### Installation
+
+Import the GoFr's dbresolver for MySQL:
+
+```shell
+go get gofr.dev/pkg/gofr/datasource/dbresolver@latest
+```
+
+#### Configuration
+
+**1. Environment Variables**
+
+Add replica connection details to your .env file:
+
+```editorconfig
+# Primary database
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=root123
+DB_NAME=test_db
+DB_DIALECT=mysql
+
+# Replica configuration
+DB_REPLICA_HOSTS=localhost,replica1,replica2
+DB_REPLICA_PORTS=3307,3308,3309
+DB_REPLICA_USERS=readonly1,readonly2,readonly3
+DB_REPLICA_PASSWORDS=pass1,pass2,pass3
+```
+
+**2. Initialize DBResolver**
+
+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
+package main
+
+import (
+	"gofr.dev/pkg/gofr"
+	"gofr.dev/pkg/gofr/datasource/dbresolver"
+)
+
+type Customer struct {
+	ID   int    `db:"id"`
+	Name string `db:"name"`
+}
+
+func main() {
+	a := gofr.New()
+
+	// Initialize DB resolver with default settings
+	err := dbresolver.InitDBResolver(a, dbresolver.Config{
+		Strategy:      dbresolver.StrategyRoundRobin, // use round-robin strategy or random strategy
+		ReadFallback:  true, // allow reads on primary if all replicas are down
+		MaxFailures:   3, 			  // number of allowed failures before marking a replica as down
+		TimeoutSec:    30, // timeout for marking a replica as down
+		PrimaryRoutes: []string{"/admin", "/api/payments/*"}, // routes that should go to primary
+	})
+	if err != nil {
+		a.Logger().Errorf("failed to initialize db resolver: %v", err)
+	}
+
+	// Read endpoint - goes to replica
+	a.GET("/customers", func(c *gofr.Context) (interface{}, error) {
+		var customers []Customer
+
+		c.SQL.Select(c, &customers, "SELECT id, name FROM customers")
+
+		return customers, err
+	})
+
+	// Write endpoint - goes to primary
+	a.POST("/customers", func(c *gofr.Context) (interface{}, error) {
+		var customer Customer
+
+		c.Bind(&customer)
+
+		_, err := c.SQL.Exec("INSERT INTO customers (name) VALUES (?)", customer.Name)
+
+		return customer, err
+	})
+
+	// Admin endpoint - forced to primary
+	a.GET("/admin/customers", func(c *gofr.Context) (interface{}, error) {
+		var customers []Customer
+
+		c.SQL.Select(c, &customers, "SELECT id, name FROM customers")
+
+		return customers, err
+	})
+
+	a.Run()
+}
+```
+
+**3. Connection Pool Tuning (Optional)**
+
+By default, replica pools are auto-scaled based on primary settings:
+
+```
+# Defaults (automatically calculated)
+DB_MAX_IDLE_CONNECTION=2    → Replicas: 8 (2 × 4)
+DB_MAX_OPEN_CONNECTION=20   → Replicas: 40 (20 × 2)
+```
+
+Override with:
+
+```
+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.mod

@@ -48,7 +48,7 @@ require (
 )
 
 require (
-	cloud.google.com/go v0.120.0 // indirect
+	cloud.google.com/go v0.121.1 // indirect
 	cloud.google.com/go/auth v0.17.0 // indirect
 	cloud.google.com/go/auth/oauth2adapt v0.2.8 // indirect
 	cloud.google.com/go/compute/metadata v0.9.0 // indirect

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.17.0 h1:74yCm7hCj2rUyyAocqnFzsAYXgJhrG26XCFimrc/Kz4=
 cloud.google.com/go/auth v0.17.0/go.mod h1:6wv/t5/6rOPAX4fJiRjKkJCvswLwdet7G8+UGXt7nCQ=
 cloud.google.com/go/auth/oauth2adapt v0.2.8 h1:keo8NaayQZ6wimpNSmW5OPc283g65QNIiLpZnkHRbnc=

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

@@ -786,6 +786,13 @@ type CouchbaseProvider interface {
 	provider
 }
 
+// DBResolverProvider defines an interface for SQL read/write splitting providers.
+type DBResolverProvider interface {
+	GetResolver() DB
+
+	provider
+}
+
 // InfluxDB defines the operations required to interact with an InfluxDB instance.
 type InfluxDB interface {
 	// CreateOrganization create new bucket in the influxdb