Alpha

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

Settings

NAME

Turborel::Client::Settings, Options, Host, TlsFiles and Role: connection settings from outside the program, and connecting by them to one of several servers.

SYNOPSIS

Turborel::Client::Settings.from_uri(uri) { |variable| ... }       # => Settings
Turborel::Client::Settings.resolve(options = Options.new) { |variable| ... } # => Settings
Turborel::Client::Settings.service(file, name)                    # => Options
settings.connect                                                  # => Connection
settings.password_for(host)                                       # => String, or nil
settings.hosts  settings.user  settings.password  settings.tls_mode  settings.channel_binding
settings.application_name  settings.connect_timeout  settings.passfile  settings.target
settings.load_balance  settings.tls  settings.key_cache

Turborel::Client::Options.new(hash = {})   options.set(name, value)   options[name]   options.over(lower)
Turborel::Client::Options.environment { |variable| ... }          # => Options
Turborel::Client::Host.tcp(name, port) | .local(path)             # name, port, path, local?
Turborel::Client::TlsFiles                 # roots, system_roots, certificate, key, server_name
Turborel::Client::Role.of(connection)      # => :read_write, :read_only or :unknown

DESCRIPTION

resolve lays the program's Options over the section of the service file they or the environment name, over the environment's variables, read from ENV or by the block, over the defaults; from_uri reads the program's from a turborel:// URI. Settings are read into Ruby values: tls_mode as :disable, :prefer, :require, :verify_ca or :verify_full; channel_binding as :disable, :prefer or :require; target as :any, :read_write or :read_only; load_balance as :disable or :random; connect_timeout in whole seconds, nil for no limit; hosts as Hosts, each of its port, or of the port of its place in port, or of the one port given, or 7422. inspect never shows the password.

connect tries each host in order, or in a random order under load_balance=random, at each address its name resolves to, over TLS as tls_mode says, the user proved by SCRAM-SHA-256 of the password the settings or the password file give, else by the certificate named, else trusted, and keeps the first server of the role target asks; its connections share the settings' key_cache. password_for gives the password proved at a host. Role.of gives the role a connection's session sees: from its status SERVER_READ_ONLY, else from INFORMATION_SCHEMA.REPLICAS, asked as its own transaction.

ERRORS

SQLSTATE SQLCODE When
08001 -919 A setting that cannot be read; a URI that is not one; a service file that cannot be read, has a malformed line, or no section of the name; no user named; a server not of the role asked; several servers, none kept, each named with why
28000 -919 A password over plain TCP, before it is sent; channel binding required by settings that cannot bind, before any proof; the last of several servers refusing the user
08006 -919 One server, that cannot be reached or whose TLS handshake fails; a verifying TLS mode with no authority trusted; a client certificate named without its key

EXAMPLES

options = Turborel::Client::Options.new("user" => "ann", "host" => "[::1]:7001,/run/turborel.sock")
settings = Turborel::Client::Settings.resolve(options) { nil }
p settings.hosts.map { |host| host.local? ? host.path : [host.name, host.port] }
p settings
[["::1", 7001], "/run/turborel.sock"]
#<Turborel::Client::Settings hosts=[#<data Turborel::Client::Host name="::1", port=7001, path=nil>, #<data Turborel::Client::Host name=nil, port=nil, path="/run/turborel.sock">] user="ann" tls_mode=prefer target=any>

STANDARD

[CLIENT Connecting by settings], [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

Settings, Appendix C, Connections