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

A program need not name a server in its code. Settings say where the servers are, as whom to connect, how, and what a server must be, and Settings.Connect connects as they say. They are read from layers, each setting taken from the first layer that has it: the program's own Options, or a turborel:// URI; then a section of the service file; then the environment's TURBOREL_ variables; then the defaults. Appendix C lists every setting.

uri := "turborel://ANN:ann%27s%20secret@127.0.0.1:17433/?tls_mode=verify-full" +
	"&tls_roots=" + dir + "/certs/ca.pem&server_name=localhost&application_name=payroll"
settings, err := turborel.SettingsFromURI(uri)
if err != nil {
	return err
}
fmt.Println(settings)
conn, err := settings.Connect(ctx)
if err != nil {
	return err
}
role, _ := conn.Role(ctx)
fmt.Println(conn.Authorization(), role)
// Settings{hosts: 127.0.0.1:17433, user: ANN, tls_mode: verify-full, target: any, ..}
// ANN read-write

A URI's user, password, hosts and values are percent-encoded, so a host %2Frun%2Fturborel.sock names a Unix socket, and an IPv6 address is written in brackets. Settings never show the password.

The service file and the password file

A service file holds sections, each [name] on a line of its own, then lines setting = value; a line beginning with # is a comment. The setting service names the section; service_file the file, else ~/.turborel_service.conf.

A password file, ~/.turborel_pass unless passfile names another, holds lines host:port:user:password, * matching anything and \ taking the character after it as it is. The password of the first line that matches the server and user is proved, unless the settings give one. The driver reads it only if it is a regular file; it should be readable by its owner alone.

services := dir + "/services.conf"
os.WriteFile(services, []byte("[payroll]\nhost = 127.0.0.1:1, 127.0.0.1:17433\ntls_mode = require\n"), 0o600)
passfile := dir + "/pass"
os.WriteFile(passfile, []byte("127.0.0.1:17433:ANN:ann's secret\n"), 0o600)
var options turborel.Options
options.Set(turborel.OptionService, "payroll")
options.Set(turborel.OptionServiceFile, services)
options.Set(turborel.OptionPassfile, passfile)
options.Set(turborel.OptionUser, "ANN")
settings, err = turborel.Resolve(options)
if err != nil {
	return err
}
fmt.Println(settings.Hosts)
conn, err = settings.Connect(ctx)
fmt.Println(err)
// [127.0.0.1:1 127.0.0.1:17433]
// <nil>

Several servers

The hosts are tried in the order given, or with load_balance=random in an order chosen at random for each connection, and each address a name resolves to in turn, each step within the connect timeout. A server that cannot be reached, refuses the user, or is not of the role target asks is passed for the next: read-write takes a server alone or its group's primary, read-only a replica following its group. With none kept, the failure names each address and why.

options.Set(turborel.OptionTarget, "read-only")
settings, _ = turborel.Resolve(options)
_, err = settings.Connect(ctx)
fmt.Println(err)
// SQLCODE -919 (SQLSTATE 08001): no server was kept: 127.0.0.1 (127.0.0.1:1): cannot connect: dial tcp 127.0.0.1:1: connect: connection refused; 127.0.0.1 (127.0.0.1:17433): the server is read-write, and read-only is asked

TLS and channel binding

tls_mode says how a connection over TCP uses TLS: disable, never; prefer, the default, TLS if the server takes it, else plain TCP; require, TLS or no connection; verify-ca, the server's certificate signed by an authority tls_roots or tls_system_roots trusts; verify-full, of the server's name too, server_name's if given. Under prefer and require the certificate is not checked, so they keep out an eavesdropper but not a server in the middle. A Unix socket or named pipe is private, and uses no TLS.

A password is proved by SCRAM-SHA-256, bound to the TLS channel unless channel_binding=disable; channel_binding=require refuses, before it proves anything, a connection that cannot bind. A password over plain TCP is refused before it is sent. With no password, a client certificate named by tls_certificate and tls_key proves the user, else trust. Every connection the same settings make shares one SCRAM key cache, so a connection again skips deriving the password's keys.