config

type Config struct {
	// Reader is the replica (read-only) datasource pool.
	Reader *Pool `yaml:"reader,omitempty" json:"reader,omitempty" toml:"reader,omitempty" validate:"omitempty"`

	// Writer is the primary (read-write) datasource pool.
	Writer *Pool `yaml:"writer,omitempty" json:"writer,omitempty" toml:"writer,omitempty" validate:"omitempty"`
}

type DSN struct {
	// URL is a go-service "source string" for the datasource name/connection string.
	//
	// It is resolved via [os.FS.ReadSource], so it can be:
	//   - "env:NAME" to read from an environment variable,
	//   - "file:/path/to/dsn" to read from a file, or
	//   - any other value treated as a literal connection string.
	URL string `yaml:"url,omitempty" json:"url,omitempty" toml:"url,omitempty"`
}

type Pool struct {
	// Settings configures connection pool behavior for this role.
	Settings *PoolSettings `yaml:"settings,omitempty" json:"settings,omitempty" toml:"settings,omitempty" validate:"required"`

	// DSNs is the set of datasource names for this role.
	//
	// Each DSN URL is a "source string" resolved via [os.FS.ReadSource], so it can be:
	//   - "env:NAME" to read the DSN from an environment variable,
	//   - "file:/path/to/dsn" to read the DSN from a file, or
	//   - any other value treated as a literal DSN string.
	DSNs []DSN `yaml:"dsns,omitempty" json:"dsns,omitempty" toml:"dsns,omitempty"`
}

type PoolSettings struct {
	// ConnMaxLifetime is the maximum amount of time a connection may be reused.
	//
	// In config files it is encoded as a Go duration string (for example "30s", "5m", "1h").
	ConnMaxLifetime time.Duration `yaml:"conn_max_lifetime,omitempty" json:"conn_max_lifetime,omitempty" toml:"conn_max_lifetime,omitempty" validate:"gte=0"`

	// ConnMaxIdleTime is the maximum amount of time a connection may remain idle.
	//
	// In config files it is encoded as a Go duration string (for example "30s", "5m", "1h").
	ConnMaxIdleTime time.Duration `yaml:"conn_max_idle_time,omitempty" json:"conn_max_idle_time,omitempty" toml:"conn_max_idle_time,omitempty" validate:"gte=0"`

	// MaxOpenConns is the maximum number of open connections to the database.
	MaxOpenConns int `yaml:"max_open_conns" json:"max_open_conns" toml:"max_open_conns" validate:"gt=0"`

	// MaxIdleConns is the maximum number of connections in the idle connection pool.
	MaxIdleConns int `yaml:"max_idle_conns" json:"max_idle_conns" toml:"max_idle_conns" validate:"gt=0,ltefield=MaxOpenConns"`
}