Alpha

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

Settings

Options

NAME

trl_options, trl_options_new, trl_options_set, trl_options_get, trl_options_from_uri, trl_options_failure, trl_options_free: a layer of connection settings, as text.

SYNOPSIS

#include <turborel/turborel.h>

#define TRL_SETTING_HOST "host"
/* and TRL_SETTING_PORT, _USER, _PASSWORD, _TLS_MODE, _CHANNEL_BINDING,
   _APPLICATION_NAME, _CONNECT_TIMEOUT, _SERVICE, _SERVICE_FILE, _PASSFILE,
   _TARGET, _LOAD_BALANCE, _TLS_ROOTS, _TLS_SYSTEM_ROOTS, _TLS_CERTIFICATE,
   _TLS_KEY, _SERVER_NAME */
#define TRL_DEFAULT_PORT 7422
#define TRL_DEFAULT_HOST "localhost"
#define TRL_URI_SCHEME "turborel://"

trl_status trl_options_new(trl_options **out);
trl_status trl_options_set(trl_options *options, const char *key, const char *value);
const char *trl_options_get(const trl_options *options, const char *key);
trl_status trl_options_from_uri(const char *uri, trl_options **out);
const trl_failure *trl_options_failure(const trl_options *options);
void trl_options_free(trl_options *options);

DESCRIPTION

A layer holds settings by name, each a setting of Appendix C, its value text, copied [CLIENT Where settings come from]. trl_options_from_uri reads a connection URI into one [CLIENT The connection URI]:

turborel://[user[:password]@][host[:port][,host[:port]]...][/][?setting=value[&setting=value]...]

Its user, password, hosts and values are percent-encoded, so p%40ss is the password p@ss and %2Frun%2Fturborel.sock a Unix socket; an IPv6 address is written in brackets. A server serves one database, so the URI names none, and has no path but /.

ERRORS

TRL_INVALID_ARGUMENT of a null pointer; TRL_NO_MEMORY. TRL_FAILED, SQLSTATE 08001, the layer's failure: a key that names no setting; of a URI, another scheme, a path, a pair without =, a % not followed by two hexadecimal digits, or octets not UTF-8 once decoded.

Settings

NAME

trl_settings, trl_variable, trl_settings_resolve, trl_settings_resolve_in, trl_settings_from_uri, trl_settings_failure, trl_settings_host_count, trl_settings_host, trl_settings_user, trl_settings_get, trl_settings_tls_mode, trl_settings_channel_binding, trl_settings_connect_timeout, trl_settings_target, trl_settings_load_balance, trl_settings_tls_system_roots, trl_settings_password_for, trl_settings_key_cache, trl_settings_free: settings laid.

SYNOPSIS

typedef const char *(*trl_variable)(void *context, const char *name);

typedef enum trl_tls_mode { TRL_TLS_DISABLE = 0, TRL_TLS_PREFER, TRL_TLS_REQUIRE, TRL_TLS_VERIFY_CA,
                            TRL_TLS_VERIFY_FULL } trl_tls_mode;
typedef enum trl_target_role { TRL_TARGET_ANY = 0, TRL_TARGET_READ_WRITE, TRL_TARGET_READ_ONLY } trl_target_role;
typedef enum trl_load_balance { TRL_LOAD_BALANCE_DISABLE = 0, TRL_LOAD_BALANCE_RANDOM } trl_load_balance;

trl_status trl_settings_resolve(const trl_options *options, trl_settings **out);
trl_status trl_settings_resolve_in(const trl_options *options, trl_variable variable, void *context,
                                   trl_settings **out);
trl_status trl_settings_from_uri(const char *uri, trl_settings **out);
const trl_failure *trl_settings_failure(const trl_settings *settings);
size_t trl_settings_host_count(const trl_settings *settings);
const char *trl_settings_host(const trl_settings *settings, size_t host, uint16_t *port, bool *local);
const char *trl_settings_user(const trl_settings *settings);
const char *trl_settings_get(const trl_settings *settings, const char *key);
trl_tls_mode trl_settings_tls_mode(const trl_settings *settings);
trl_channel_binding trl_settings_channel_binding(const trl_settings *settings);
uint32_t trl_settings_connect_timeout(const trl_settings *settings);
trl_target_role trl_settings_target(const trl_settings *settings);
trl_load_balance trl_settings_load_balance(const trl_settings *settings);
bool trl_settings_tls_system_roots(const trl_settings *settings);
bool trl_settings_password_for(const trl_settings *settings, size_t host, char *out, size_t capacity,
                               size_t *length);
trl_key_cache *trl_settings_key_cache(const trl_settings *settings);
void trl_settings_free(trl_settings *settings);

DESCRIPTION

trl_settings_resolve lays the program's layer, null for none, over the section of the service file it or the environment names, over the environment's variables, over the defaults, each setting taken from the first layer that has it [CLIENT Where settings come from]; the process's environment is read once, as the settings are laid. trl_settings_resolve_in reads it through variable instead. trl_settings_from_uri lays a URI's layer. The settings are made even when they cannot be laid, holding why.

The service file is service_file, else ~/.turborel_service.conf: sections, each [name] on a line of its own, then lines setting = value; a line beginning with # a comment, blank lines skipped. A section cannot set service or service_file [CLIENT The service file].

host names the servers, comma-separated, each its own port as name:port, an IPv6 address as [address]:port, a path a Unix socket (on Windows, a named pipe); a host of no port takes the port of the same place of port, or the one port it gives, or 7422. trl_settings_host gives each, its port 0 and local true of a socket. trl_settings_get gives a setting as laid, but password, which it never gives. trl_settings_connect_timeout gives milliseconds, 30 000 unless told, 0 for no limit, at most about 49 days.

trl_settings_password_for gives the password to prove at a server: the settings', else the password file's for the server, its port and the user [CLIENT The password file]. The password file is passfile, else ~/.turborel_pass: lines host:port:user:password, a field * matching anything, \ taking the character after it as it is, # beginning a comment; the first line that matches is taken, a Unix socket matched by its path and port 7422. It is read only if it is a regular file, or a link to one; its owner answers for keeping it private.

trl_settings_key_cache gives the SCRAM key cache every connection the settings make shares [CLIENT The SCRAM key cache].

ERRORS

TRL_INVALID_ARGUMENT of a null pointer; TRL_NO_MEMORY, nothing made. TRL_FAILED, SQLSTATE 08001, the settings' failure: a setting that cannot be read, as a word no setting takes ("tls_mode is always, not one of disable, prefer, require, verify-ca, verify-full"), a port that is no number, a host empty or an IPv6 address unclosed; a service file that cannot be read, a malformed line of it, naming its file and line, or no section of the name; no user ("no user is named: by the program, a service, or TURBOREL_USER"). The accessors give their defaults of null settings.

EXAMPLES

Settings lays each layer.

Connecting by settings

NAME

trl_settings_connect, trl_connect_uri, trl_server_role, trl_conn_role: a connection made as settings, or a URI, say, and the role of its server.

SYNOPSIS

typedef enum trl_server_role { TRL_SERVER_READ_WRITE = 0, TRL_SERVER_READ_ONLY, TRL_SERVER_UNKNOWN } trl_server_role;

trl_status trl_settings_connect(const trl_settings *settings, trl_conn **out);
trl_status trl_connect_uri(const char *uri, trl_conn **out);
trl_status trl_conn_role(trl_conn *conn, trl_server_role *out);

DESCRIPTION

trl_settings_connect tries each host in the order given, or with load_balance=random in an order drawn at random for each connection, and each address a host's name resolves to, every step within the connect timeout [CLIENT Several servers]. A server reached, logged in to and of the role target asks is kept; one that cannot be reached, refuses the user, or is of another role is left, and the next tried. A password is proved by SCRAM-SHA-256, its channel bound as channel_binding says, its keys kept in the settings' cache; with none, the certificate tls_certificate names is presented; else the user is trusted. A secret mechanism is refused over plain TCP before anything is sent. The connection asks for every capability but compression, and gives application_name as the connection attribute application.

TLS is used as tls_mode says [CLIENT TLS by mode]: disable never; prefer if the server takes it, else plain TCP, a server reached whose handshake fails connected to again over plain TCP; require always; and these three do not check the server's certificate but that the server holds its key. verify-ca checks the certificate against the authorities tls_roots and tls_system_roots trust, verify-full its name too, server_name's, else the host's. A Unix socket or a named pipe uses none. channel_binding=require refuses, before anything is sent, a connection not over TLS or a password not proved by SCRAM.

Settings may connect from several threads at once; their connections share their key cache, which takes every thread (RULES.md D11).

trl_connect_uri is the standard API's way to a connection: the URI laid with the rest of the settings, as trl_settings_from_uri lays it, then connected by trl_settings_connect. Its connection is made on TRL_FAILED too, holding why, a URI that cannot be read among the reasons.

trl_conn_role gives the role of a connection's server as its session sees it: as SERVER_READ_ONLY last told it; of a server that does not tell it, as INFORMATION_SCHEMA.REPLICAS shows it, asked as a statement that is its own transaction. A server alone, which has no REPLICAS, takes changes; a replica's role is shown to the database's owner alone, so another session finds it unknown.

ERRORS

TRL_INVALID_ARGUMENT of a null pointer, or settings not laid; TRL_NO_MEMORY, nothing made. TRL_FAILED, the connection made and holding why: of one server tried, its own failure; of several, SQLSTATE 08001 naming each address and why, as "no server was kept: 127.0.0.1 (127.0.0.1:1): cannot connect: ...", or 28000 where the last refused the user; SQLSTATE 08006 of TLS that cannot be made, as "no certificate authority is trusted: name a file of them, or the platform's" or "a client certificate is presented with its key, and none is named"; SQLSTATE 28000 of a secret over plain TCP, or of channel binding required that cannot bind ("channel binding is required: SCRAM over TLS alone binds one"); SQLSTATE 08001 of a server of another role ("the server is read-write, and read-only is asked").

trl_conn_role: TRL_INVALID_ARGUMENT of a null pointer; TRL_FAILED with the connection's failure, the query's, but of a server alone.

EXAMPLES

Settings connects to several servers, and checks a role.