GORM DBResolver: Default Policy & Read/Write Splitting

When you're diving into GORM, a popular Go ORM, and setting up read-write splitting with its DBResolver feature, you might run into a rather tricky issue. It seems that the default configuration for DBResolver isn't quite what we'd expect, leading to read operations sometimes being directed to your primary sources instead of your intended replicas. This can be a real head-scratcher, especially when you've followed the official documentation meticulously. Let's unpack this and figure out why the dbresolver config might never seem to be nil, and what's really going on under the hood.

Understanding the DBResolver Configuration

The DBResolver in GORM is designed to help you manage read and write operations more efficiently. The idea is simple: direct write operations to your primary database (sources) and offload read operations to one or more replica databases. This is a fundamental strategy for scaling database performance and ensuring your application remains responsive under load. However, the implementation details matter, and that's where we encounter the snag. Let's look at the Config struct that governs this behavior:

type Config struct {
	Sources           []gorm.Dialector
	Replicas          []gorm.Dialector
	Policy            Policy
	datas             []interface{}
	TraceResolverMode bool
}

And here's how the Register function initializes a DBResolver:

func Register(config Config, datas ...interface{}) *DBResolver {
	return (&DBResolver{}).Register(config, datas...)
}

func (dr *DBResolver) Register(config Config, datas ...interface{}) *DBResolver {
	if dr.prepareStmtStore == nil {
		dr.prepareStmtStore = map[gorm.ConnPool]*gorm.PreparedStmtDB{}
	}

	if dr.resolvers == nil {
		dr.resolvers = map[string]*resolver{}
	}

	if config.Policy == nil {
		config.Policy = RandomPolicy{}
	}

	config.datas = datas
	dr.configs = append(dr.configs, config)
	if dr.DB != nil {
		dr.compileConfig(config)
	}
	return dr
}

Now, pay close attention to this line: if config.Policy == nil { config.Policy = RandomPolicy{} }. This is where the magic (or perhaps, the mischief) happens. If you don't explicitly provide a Policy when creating your Config, GORM helpfully assigns RandomPolicy{} to it. This means, from the perspective of the Register function, config.Policy will never be nil. It will either be the policy you've provided, or it will be the default RandomPolicy{}. So, while the intention might be to check if a policy is set, the code effectively ensures it always has a value.

The Consequence: Reads Go to Sources

This default behavior has a significant implication for read-write splitting. The DBResolver uses the configured Policy to decide which database to use for a given operation. If you haven't specified a custom policy, it defaults to RandomPolicy. The RandomPolicy itself is designed to distribute operations across the available connections, which include both sources and replicas. The problem arises because the default assignment doesn't inherently prioritize replicas for read operations when no explicit policy is given.

When the DBResolver needs to execute a read query, it consults the Policy. If the Policy is the default RandomPolicy and it hasn't been explicitly configured to favor replicas for reads, the random selection might very well pick one of the sources instead of a replica. This defeats the purpose of read-write splitting, which is to reduce the load on your primary database by directing reads elsewhere. In essence, your read operations are hitting the same servers that are handling your writes, potentially leading to performance bottlenecks and increased latency.

This behavior can be particularly misleading because the DBResolver is technically configured. The config.Policy field isn't nil; it holds a RandomPolicy. This can lead developers to believe that read-write splitting is correctly set up, only to discover later that their read traffic is not being distributed as intended.

Why the Default Might Be Misleading

The core issue lies in the interpretation of the default policy. While assigning a default policy like RandomPolicy{} prevents a nil pointer dereference and ensures the Register function completes without error, it doesn't automatically align with the common use case for read-write splitting: preferring replicas for reads. Many developers setting up read-write splitting expect that if they don't specify a policy, the system will intelligently route reads to replicas. However, the RandomPolicy doesn't have this inherent intelligence. It simply picks from the available connections without a specific read/write bias unless configured to do so.

Consider a scenario where you have one primary database (source) and two replica databases. If you don't explicitly set a policy, RandomPolicy could select any of the three connections at random. This means a read query has a 1 in 3 chance of hitting the source, which is not ideal. The goal of read-write splitting is to minimize reads on the source, not to distribute them randomly across all available connections.

The Pointer vs. Value Dilemma

One potential avenue for improvement that has been discussed is making the Policy field a pointer type, like *Policy. Let's explore why this might be a better approach. If Policy were a pointer, then a nil value for config.Policy would genuinely indicate that no policy has been explicitly provided by the user. In such a case, GORM could then implement a more sensible default behavior or perhaps even return an error, prompting the user to configure the policy explicitly.

// Hypothetical scenario if Policy were a pointer
type Config struct {
	Sources           []gorm.Dialector
	Replicas          []gorm.Dialector
	Policy            *Policy // Changed to a pointer
	datas             []interface{}
	TraceResolverMode bool
}

func (dr *DBResolver) Register(config Config, datas ...interface{}) *DBResolver {
    // ... other checks ...

    // If Policy is nil, it means the user didn't provide one.
    // Here, we could assign a default that favors reads to replicas,
    // or perhaps log a warning or error.
    if config.Policy == nil {
        // Option 1: Assign a replica-favoring default policy
        // config.Policy = &DefaultReadReplicaPolicy{}

        // Option 2: Prompt the user explicitly
        // log.Fatal("DBResolver Policy not set. Please configure a read/write splitting policy.")
    }

    // ... rest of the function ...
}

By using a pointer, the distinction between