Alpha

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

Settings

A program can connect by settings rather than by a target and a mechanism of its own: ConnectionSettings says where the servers are, as whom to connect, how, and what a server must be, and ConnectAsync connects as it says. A password the settings give, or the password file, is proved by SCRAM-SHA-256; with none, the client's certificate if one is named, else the user is trusted as a local client.

Where settings come from

Each setting has one name, the same in the program's options, in a turborel:// URI and in a service file (Appendix C). They come in layers, and each is taken from the first layer that has it: the program's own, a ConnectionOptions or a URI; the section of the service file the program or the environment names; the environment's TURBOREL_ variables, a variable set but empty giving nothing; then the defaults. A setting that cannot be read, a service that cannot be read, and settings that name no user are refused, SQLSTATE 08001.

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

A URI's parts are percent-encoded, so %2Frun%2Fturborel.sock is a Unix socket; an IPv6 address is written in brackets. A service file holds sections, [name], of lines setting = value; # begins a comment. A password file holds lines host:port:user:password, * matching anything and \ escaping the character after it; it is read only if it is a regular file, or a link to one.

Several servers, and TLS

host may name several servers, tried in the order given or, with load_balance=random, in a random order for each connection; a name is tried at each address it resolves to. A server that cannot be reached, refuses the user, or is not of the role target asks is passed for the next; with none kept, the failure names each and why. read-write keeps a server alone or its group's primary, read-only a replica; the role is read from SERVER_READ_ONLY, which the server tells every session.

tls_mode says how a connection over TCP uses TLS: disable; prefer, TLS if the server takes it, else plain TCP; require; verify-ca, the server's certificate issued by an authority trusted; verify-full, and of server_name, else the host's name. A Unix socket or named pipe uses none. channel_binding=require refuses settings whose connection SCRAM cannot bind, SQLSTATE 28000. One key cache keeps the SCRAM keys of every connection the same settings make.

using Turborel.Data;
using Turborel.Data.Configuration;
using Turborel.Data.Session;

ConnectionSettings byUri = ConnectionSettings.FromUri(
    "turborel://ann@127.0.0.1:1,127.0.0.1:17435/?tls_mode=require&application_name=ledger&connect_timeout=5");
await using (NativeConnection connection = await byUri.ConnectAsync())
{
    Console.WriteLine($"{connection.Server}, as {connection.Authorization}, over {connection.Target}");
    Console.WriteLine($"the server is {ServerRole.Describe(await ServerRole.OfAsync(connection))}");
}

File.WriteAllText("services.conf", "# services\n[ledger]\nhost = localhost:17435\nuser = ann\ntls_mode = verify-full\ntls_roots = ca.pem\n");
File.WriteAllText("passwords", "*:17435:ann:ann's password\n");
ConnectionOptions options = new ConnectionOptions()
    .Set(ConnectionOptions.Service, "ledger")
    .Set(ConnectionOptions.ServiceFile, "services.conf")
    .Set(ConnectionOptions.Passfile, "passwords");
ConnectionSettings byService = ConnectionSettings.Resolve(options);
Console.WriteLine(byService);
for (int i = 0; i < 2; i++)
{
    await using NativeConnection connection = await byService.ConnectAsync();
    Console.WriteLine($"{connection.Authorization} over {connection.Target}");
}

Console.WriteLine($"key cache hits and misses: {byService.KeyCache.Lookups}");
try
{
    ConnectionSettings.FromUri("turborel://ann@db/?tls_mode=always");
}
catch (TurborelException e)
{
    Console.WriteLine($"SQLSTATE {e.SqlState}: {e.Message}");
}
turborel 0.0.0 (alpha), as ANN, over Tls(127.0.0.1:17435)
the server is read-write
ConnectionSettings(TcpHost { Name = localhost, Port = 17435 }, ann, VerifyFull, Any)
ANN over Tls(127.0.0.1:17435)
ANN over Tls(127.0.0.1:17435)
key cache hits and misses: (1, 1)
SQLSTATE 08001: [DESIGN] tls_mode is always, not one of disable, prefer, require, verify-ca, verify-full

The example's server listens on 127.0.0.1 alone, so localhost's first address, ::1, is passed when it has one.

Connection strings

The standard API takes the same settings as a connection string, key=value pairs separated by semicolons, by the names a URI's query gives them, with the pool's own keys, pooling and pool_max among them; or a whole turborel:// URI. host=localhost:17435;user=ann and turborel://ann@localhost:17435 name the same connection. A key that names no setting is refused, SQLSTATE 08001, so a misspelt one is not dropped. TurborelConnectionStringBuilder reads and writes one (TurborelFactory).

See also

Settings in the API Reference; Appendix C: Settings.