En/db resolver

[Umang01-hash]

Pull Request Template

Description:

What is DBResolver?

• Adds a DBResolver module to GoFr, which provides automatic read/write splitting for SQL databases.

• Read queries (e.g., SELECT) are routed to read replicas, and write queries (e.g., INSERT, UPDATE) are routed to the primary database.

• Seamlessly wraps the existing SQL datasource: does not require any application code changes for existing queries.

• Developers interact with c.SQL exactly as before; all routing and failover are fully transparent.

Motivation & Benefits

• Scalable horizontal read performance with multiple replicas
• Reduced load on primary database
• Fault-tolerant: automatic fallback to primary if all replicas fail
• Clean metrics and tracing support for operational visibility

Example Usage:

import (
    "gofr.dev/pkg/gofr"

    "gofr.dev/pkg/gofr/datasource/dbresolver"
)

func main() {
    a := gofr.New()

    // Enable DBResolver with round-robin strategy and fallback
    resolver := dbresolver.NewProvider("round-robin", true)
    a.AddDBResolver(resolver)

    // Continue as usual: all routes and SQL logic unchanged
    a.GET("/db/read", DBReadHandler)
    a.POST("/db/write", DBWriteHandler)
    a.Run()
}

Configuration Example:

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=rootpassword
DB_NAME=testdb
DB_PORT=3306
DB_DIALECT=mysql
DB_MAX_IDLE_CONNECTION=2
DB_MAX_OPEN_CONNECTION=0

# Replica hosts (comma-separated, e.g., on ports 3307 and 3308)
DB_REPLICA_HOSTS=localhost:3307,localhost:3308

Testing Strategy:

• Primary and Replicas launched with docker-compose (primary:3306, replicas:3307/3308)

• Replication automated by setup scripts; seed data from SQL dump and app endpoints

• Load Testing: Performed with Apache JMeter simulating high-concurrency API requests (both reads and writes)

Results:

• Zero error rate; throughput and latency showed no regression compared to the baseline.

• Read/write split is fully performant, and scaling is achieved without application change.

Checklist:

• I have formatted my code using goimport and golangci-lint.
• All new code is covered by unit tests.
• This PR does not decrease the overall code coverage.
• I have reviewed the code comments and documentation for clarity.

Thank you for your contribution!

[gizmo-rt]

@Umang01-hash Can you add more details on sequence of R(Read) and W(Write) cases under which read and write replicas would be selected ?

[Umang01-hash]

@Umang01-hash Can you add more details on sequence of R(Read) and W(Write) cases under which read and write replicas would be selected ?

Hey @gizmo-rt we first determine is a query is read/write and if it is a read query we check if healthyReplica is available or not. If the replica is available we select it and send the read query to it and if the replica is not available we send it to primary
database. Methods like QueryContext, Select have this logic. Methods like Exec , Prepare etc are directly using the primary db. Transaction methods (Begin, BeginTx) are always routed to the primary.

If all replicas are unhealthy at time of a read query and fallback is enabled, the read falls back to the primary. If fallback is disabled, the read fails with an error.

If a replica experiences multiple failures, it's circuit breaker opens and replica is temporarily skipped for queries. This timeout period is 30 seconds by default and we allow 5 failures for replica before cicuit breaker is opened.

For an example sequence like R,R,W,R:

1st R: Routed to replica

2nd R: Routed to next replica (depends on which strategy is choosen random or round-robin)

1st W: Routed to primary

3rd R: Routed to next replica

[ccoVeille]

I let the discussion going as I wasn't sure where it would land.

So functionally, I'm not sure whether it's OK.

But the code seems OK

[akshat-kumar-singhal]

@Umang01-hash Hope we are routing the reads within a transaction to the primary? I couldn't find any the corresponding code for it.

[Umang01-hash]

Hope we are routing the reads within a transaction to the primary? I couldn't find any the corresponding code for it.

Yes @akshat-kumar-singhal Reads within transactions are always routed to the primary database because the transaction itself is created on the primary connection. Since Begin() returns a transaction object from the primary database, all subsequent operations on this transaction (including reads) automatically use the primary connection.

// Begin always routes to primary (transactions).
func (r *Resolver) Begin() (*gofrSQL.Tx, error) {
    r.stats.totalQueries.Add(1)
    return r.primary.Begin()
}

[akshat-kumar-singhal]

Try to break the files into smaller logic groups - readability is a bit low right now.

[aryanmehrotra]

what if we use the existing Connect method?