Alpha

These pages are built from turborel-go’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Settings

NAME

Settings, Options, Settings.Connect: connecting as settings from outside the program say.

SYNOPSIS

type Options struct{ /* unexported */ }
func (o *Options) Set(key, value string) error
func (o Options) Get(key string) (string, bool)
func (o Options) Over(lower Options) Options
func (o Options) IsEmpty() bool
func OptionsFromURI(uri string) (Options, error)
func EnvironmentOptions(variable func(name string) (string, bool)) Options
func Service(file, name string) (Options, error)
func OptionKeys() []string
func EnvironmentVariables() [][2]string

type Host struct {
	Name string
	Port uint16
	Path string
}
type TLSFiles struct {
	Roots       string
	SystemRoots bool
	Certificate string
	Key         string
	ServerName  string
}
type Settings struct {
	Hosts           []Host
	User            string
	Password        string
	HasPassword     bool
	TLSMode         TLSMode
	ChannelBinding  ChannelBinding
	ApplicationName string
	ConnectTimeout  time.Duration
	Passfile        string
	Target          TargetRole
	LoadBalance     LoadBalance
	TLS             TLSFiles
	KeyCache        *KeyCache
}
func Resolve(explicit Options) (*Settings, error)
func ResolveIn(explicit Options, variable func(name string) (string, bool)) (*Settings, error)
func SettingsFromURI(uri string) (*Settings, error)
func (s *Settings) PasswordFor(host Host) (string, bool)
func (s *Settings) Connect(ctx context.Context) (*Conn, error)

type TLSMode uint8     // TLSPrefer, TLSDisable, TLSRequire, TLSVerifyCA, TLSVerifyFull
type TargetRole uint8  // TargetAny, TargetReadWrite, TargetReadOnly
type LoadBalance uint8 // LoadBalanceDisable, LoadBalanceRandom
type Role uint8        // RoleReadWrite, RoleReadOnly, RoleUnknown
func (c *Conn) Role(ctx context.Context) (Role, error)

DESCRIPTION

Resolve lays the program's Options over a service's section, the service named by them or by TURBOREL_SERVICE, over the environment, read by os.LookupEnv, over the defaults; ResolveIn reads the environment through the program's function. A variable set but empty gives nothing. Options.Set refuses a name no setting has. String and GoString of both never show the password.

Settings.Connect tries each host, in order or shuffled under LoadBalanceRandom, each address its name resolves to, a host whose Path is set being its Unix socket or named pipe. Over TCP it opens TLS as TLSMode says, under TLSPrefer connecting again over plain TCP to a server whose handshake fails. It proves a password, the settings' or PasswordFor's, by SCRAM with the settings' channel binding and key cache; with none, the certificate TLS.Certificate names, else trust. It asks for every capability but compression and, if named, the connection attribute application. It keeps a server of the role Target asks: Conn.Role reads SERVER_READ_ONLY, or of a server that does not tell it, runs RoleQuery as its own transaction, a server with no INFORMATION_SCHEMA.REPLICAS taking changes.

ERRORS

SQLSTATE When
08001 SQLCODE -919: a setting that cannot be read; a service file unread, malformed, or without the section; no user; no server kept, the message naming each address and why
28000 SQLCODE -919: channel binding required by a connection that cannot bind; a password over plain TCP; the last server tried refused the user
08006 SQLCODE -919: a TLS file that cannot be read; verify-ca or verify-full with no authority trusted; a client certificate with no key

Of one address tried, its own failure is given.

EXAMPLES

The examples of Settings.

STANDARD

[CLIENT Where settings come from], [CLIENT The connection URI], [CLIENT The service file], [CLIENT The password file], [CLIENT Several servers], [CLIENT TLS by mode] and [CLIENT The SCRAM key cache] of Settings, Pipelines and Pools.

SEE ALSO

Appendix C, Connections, Pools.