Alpha

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

Connections

NAME

turborel.client: connecting to a server, and the connection a program then holds.

SYNOPSIS

connect(address, user, mechanism) -> Connection
connect_local(path, user, mechanism) -> Connection
connect_tls(address, context, user, mechanism, server_name=None) -> Connection
connect_to(target, user, mechanism, timeouts=None, offer=None) -> Connection
Connection.open(socket_or_file, user, mechanism, offer=None) -> Connection
Connection.open_within(sock, user, mechanism, timeouts, offer=None) -> Connection

Tcp(host, port=7422) | Local(path) | Tls(host, context, port=7422, server_name=None)
Trust() | Password(password) | Certificate()
Scram(password, *, in_the_clear=False, channel_binding=ChannelBinding.PREFER, cache=None)
Timeouts(connect=30.0, read=None)
Offer(capabilities=..., attributes=(), compress_from=1024)
trusting(file) | roots(file=None, *, platform=False) | presenting(file, chain, key)
KeyCache()

DESCRIPTION

Connecting. connect connects over TCP to address, a host on port 7422 or a (host, port) pair; connect_local over a Unix socket, or on Windows the named pipe \\.\pipe\turborel or another; connect_tls over TLS, the server's certificate checked by the ssl.SSLContext given and its name by server_name, the host's by default; connect_to to a Target, with timeouts and an offer of the program's. Connection.open logs in over a stream the program opened, which bounds its own waits; over a TLS socket the program binds SCRAM to it first, mechanism.bind(tls_channel(sock)). Connection.open_within logs in over a socket the program opened, bounded as timeouts say: each step of the login by connect, each wait after it by read, which set_read_timeout then changes.

Mechanisms. Trust asks the server to trust the user as it names itself, which it does of a client of its own machine where SERVER.TRUST_LOCAL is ON. Password sends the password whole, and Scram proves it by SCRAM-SHA-256, or SCRAM-SHA-256-PLUS over TLS, bound by the certificate the server presented; both are refused over plain TCP before connecting, unless Scram is made in_the_clear. Certificate proves the user by the TLS client certificate presenting presents. channel_binding says whether SCRAM binds the TLS channel: DISABLE, PREFER where the connection has a binding, or REQUIRE, which refuses an exchange not bound.

TLS. trusting(file) trusts the authorities of a PEM file alone; roots(file, platform=True) the platform's too, or alone with no file, read from SSL_CERT_FILE and SSL_CERT_DIR where either is set; presenting(file, chain, key) presents a certificate chain and its key. Each offers TLS 1.2 and 1.3 and checks the server's certificate and name.

The SCRAM key cache. A KeyCache given to Scram keeps the keys a password derived by PBKDF2, so a later login of the same salt and iterations skips the derivation. An entry is found by the salt, the iterations and a tag of the password under a random secret of the cache's own; it holds at most 64 (KEY_CACHE_ENTRIES), the oldest dropped first, drops an entry when a login that used it fails, and lives in the process's memory alone. lookups() gives its hits and misses.

Timeouts. Timeouts.connect bounds connecting, beginning TLS and each step of the login, 30 seconds by default; Timeouts.read each read or write after, no limit by default. A wait that runs out loses the connection. A named pipe is bounded only as it is opened.

What a connection asks for. By default every capability but compression. Offer.none() asks for none, compressed() adds compression, and attribute(name, value) a connection attribute, which the server shows in INFORMATION_SCHEMA.CONNECTION_ATTRIBUTES.

The connection.

Member What
authorization, server the session's user and the server's product, as Ready told them
target where it reached its server, or None for open
granted the capabilities granted, in Ready's order
setting(name), settings() a session setting, or all, as the server last told them
set_notice_handler(handler), take_notices() notices handed to a handler as they come, or the last 64 kept and taken
in_transaction whether the session's transaction is active
autocommit whether each statement is its own transaction
read_timeout, set_read_timeout(seconds) the read timeout, changed
set_max_body(bytes) the longest reply's body taken, 16 MiB by default
canceller() what cancels its statements from another thread
ping() whether the server and the connection are alive
reset() the session as it was at login, its user kept
change_user(user, mechanism) the connection authenticated again as user
query(sql) and the rest statements, prepared statements and cursors (Statements and Cursors)
terminate() the session ended, its transaction as SESSION.COMMIT_AT_END says; a notice or status before a failing commit's failure read past, that failure raised; waiting for the close at most the read timeout, else 60 seconds, or over a stream given to open as its maker set it
close() the connection closed, the session not ended first
is_lost whether it is lost, every call then giving its failure

Canceller.cancel(within=10.0) sends the session's cancel key on a connection of its own and waits for the server to close it.

ERRORS

Condition SQLCODE, SQLSTATE
A password, or SCRAM, over plain TCP, before connecting -919, 28000
A wrong user or password, or SCRAM's proof refused either way -919, 28000
A server that cannot be reached, a TLS handshake that fails, a wait that runs out, a reply malformed or too long -919, 08006
A method needing a capability the server did not grant, before it sends anything -919, 08006
A statement cancelled -920, TB920

A failure of class 08 but 08003, or of class 28 at login, loses the connection; so does any failure of its stream.

EXAMPLES

from turborel.client import KeyCache, Scram, connect_local

cache = KeyCache()
connect_local(
    "/tmp/trl-doc.sock", "ANN", Scram("ann's secret", cache=cache)
).terminate()
connect_local(
    "/tmp/trl-doc.sock", "ANN", Scram("ann's secret", cache=cache)
).terminate()
print(cache.lookups())
(1, 1)
from turborel.client import Offer, Tcp, Trust, connect_to

conn = connect_to(Tcp("127.0.0.1", 17431), "ANN", Trust(), offer=Offer.none())
print(conn.granted)
()

SEE ALSO

Connecting, the chapter; The Native Protocol; The Client Library, turborel-client's.