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.

Connecting

A program connects to a Turborel server, turboreld, over TCP, a Unix socket, or on Windows a named pipe; or over TLS on the server's TCP port. It names the user it connects as, and a mechanism that proves it. This chapter connects with the low-level client, the module turborel.client; the standard API connects by settings, with turborel.connect (The turborel Module).

A first connection

A server trusts a client of its own machine as the user it names, when its operator sets SERVER.TRUST_LOCAL ON (Users and Authentication). The mechanism Trust asks for that.

from turborel.client import Trust, connect

conn = connect(("127.0.0.1", 7422), "ann", Trust())
print(conn.server, conn.authorization)
conn.terminate()
turborel 0.0.0 (alpha) ANN

A user name is read as an identifier, so ann connects as ANN. A host alone, connect("db.example", ...), is on port 7422. terminate ends the session, its transaction committed or rolled back as SESSION.COMMIT_AT_END says, ON by default.

Proving a password

A password is proved by SCRAM-SHA-256: the password never travels, and the server must prove it knows the user's verifier, or the connection is refused.

from turborel.client import Scram, connect_local

conn = connect_local("/run/turborel.sock", "ANN", Scram("ann's secret"))

An exchange overheard lets the password be guessed at leisure, so SCRAM goes only over TLS, a Unix socket or a named pipe. Over plain TCP the driver refuses before it connects, as it does Password, which sends the password whole:

from turborel.client import Password, connect

connect(("127.0.0.1", 7422), "ANN", Password("ann's secret"))
turborel.OperationalError: password is sent only over TLS, a Unix socket or a named pipe, never over plain TCP

Its SQLSTATE is 28000. Scram(password, in_the_clear=True) sends SCRAM over plain TCP all the same, to a server whose SERVER.SCRAM_WITHOUT_TLS is ON. A wrong password is refused by the server, with SQLCODE -919 and SQLSTATE 28000:

turborel.OperationalError: the user or the password is wrong

TLS

TLS begins on the server's TCP port. trusting makes a TLS context that trusts the authorities of one PEM file, and checks the server's certificate and name.

from turborel.client import Scram, connect_tls, trusting

context = trusting("/etc/turborel/ca.pem")
conn = connect_tls("db.example", context, "ANN", Scram("ann's secret"))

Over TLS, SCRAM is SCRAM-SHA-256-PLUS, bound to the connection by the certificate the server presented, so a server in the middle cannot relay it. roots(file, platform=True) trusts the platform's authorities too, or alone with no file; they are those of the files SSL_CERT_FILE and SSL_CERT_DIR name, where either is set. presenting(file, chain, key) presents a certificate chain and its key too, to log in by Certificate, as the user the certificate's common name names.

Timeouts

A connection waits 30 seconds to connect, begin TLS and take each step of the login, and as long as a statement runs after. connect_to takes a Timeouts of its own:

from turborel.client import Tcp, Timeouts, Trust, connect_to

conn = connect_to(Tcp("127.0.0.1", 7422), "ANN", Trust(), Timeouts(connect=5, read=60))
print(conn.read_timeout)
60

set_read_timeout changes the read timeout. A wait that runs out loses the connection, with SQLSTATE 08006, saying the server did not answer in time.

What the server tells

The server tells a session its settings as it begins, and again as a statement changes one. setting reads one, with no round trip:

conn = connect(("127.0.0.1", 7422), "ANN", Trust())
print(conn.setting("SESSION.TIME_ZONE"), conn.setting("SERVER_READ_ONLY"))
+00:00 NO

Cancelling and ending

canceller() gives what cancels the statement a connection runs, from another thread: its cancel opens a connection of its own and sends the session's key, and the statement fails with SQLCODE -920 and SQLSTATE TB920. ping asks whether the server and the connection are alive, with no statement run; terminate ends the session.

The API Reference's page Connections gives every function and method.