Alpha

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

Connecting

A program reaches a server through a Turborel\Session\Connection, made to a target as a user, proved by a mechanism. This chapter tells how; Connections in the API Reference lists every method. The standard interface connects by a URI, as The Connection Class tells.

Where the server is

A Target says where the server is and how it is reached:

Target Reaches
Target::tcp('db.example') TCP, on port 7422 unless a second argument names another
Target::local('/run/turborel/socket') a Unix socket; on Windows, a named pipe, as \\.\pipe\turborel
Target::tls('db.example', $tls) TLS, begun on the TCP port, as $tls says

A Unix socket or a named pipe reaches the server's own machine alone, so a connection over one needs no TLS.

Who connects

Connection::connect takes the target, the user, and a mechanism that proves the user:

Mechanism Proves
new Trust() nothing: the server takes the user as it names itself, as it does only of a client of its own machine, and only where SERVER.TRUST_LOCAL is ON
new Scram($password) a password, by SCRAM-SHA-256: the password never travels, and the server must prove it knows the user's verifier; over TLS it is SCRAM-SHA-256-PLUS, bound to the connection
new Password($password) a password, sent whole
new Certificate() the user the TLS client certificate's common name names

A password, whether proved by SCRAM or sent whole, goes only over TLS, a Unix socket or a named pipe: over plain TCP it is refused before anything is sent, with SQLSTATE 28000. (new Scram($password))->inTheClear() sends SCRAM over plain TCP all the same, for a server whose SERVER.SCRAM_WITHOUT_TLS is ON.

use Turborel\Session\Connection;
use Turborel\Session\Target;
use Turborel\Session\Trust;

$connection = Connection::connect(Target::tcp('127.0.0.1'), 'ann', new Trust());
echo $connection->server(), ', as ', $connection->authorization(), PHP_EOL;
$connection->terminate();
turborel 0.0.0 (alpha), as ANN

The user is read as an identifier, so ann logs in as ANN. A login the server refuses, as a wrong password, fails with SQLSTATE 28000, and the connection is closed.

TLS

Tls::trusting($file) trusts the certificate authorities of a PEM file alone; Tls::roots($file, true) trusts the platform's too, and Tls::roots(null, true) the platform's alone, those of the files SSL_CERT_FILE and SSL_CERT_DIR name if either is set. Tls::presenting($roots, $chain, $key) presents a certificate chain and key as well, for the mechanism certificate. The server's certificate must be signed by an authority trusted and be of the host's name, or of the name forServerName gives; else the handshake fails with SQLSTATE 08006.

use Turborel\Session\Connection;
use Turborel\Session\Scram;
use Turborel\Session\Target;
use Turborel\Session\Tls;

$tls = Tls::trusting('/etc/turborel/ca.pem');
$connection = Connection::connect(Target::tls('localhost', $tls), 'bob', new Scram('bob-pass-2'));
echo $connection->authorization(), PHP_EOL;
$connection->terminate();
BOB

How long it waits

Timeouts says how long a connection waits on its server: connect, to connect, begin TLS and for each step of the login, 30 seconds by default; read, for each read or write after, with no limit by default, as a statement may run as long as it must. setReadTimeout changes a connection's read limit. A wait that runs out loses the connection with SQLSTATE 08006, saying the server did not answer in time. A named pipe is bounded only as it is opened.

$connection = Connection::connect(Target::tcp('127.0.0.1'), 'ann', new Trust(), new Timeouts(5.0, 60.0));

What a connection asks for

A connection asks the server for every capability but compression, and the server grants those it has. new Offer() is that offer; Offer::none() asks for none, ->compressed() adds compression, and ->attribute($name, $value) adds a connection attribute, which the server shows in INFORMATION_SCHEMA.CONNECTION_ATTRIBUTES. granted() gives what was granted, and a method that needs a capability not granted fails, before it sends anything, with SQLSTATE 08006.

The server tells the session's settings as it begins, and again as a statement changes one: setting($name) gives one with no round trip, settings() all of them.

$connection = Connection::connect(Target::tcp('127.0.0.1'), 'ann', new Trust());
echo $connection->setting('SESSION.TIME_ZONE'), ' ', $connection->setting('SERVER_READ_ONLY'), PHP_EOL;
$connection->query("SET SESSION.TIME_ZONE = '+02:00'");
echo $connection->setting('SESSION.TIME_ZONE'), PHP_EOL;
+00:00 NO
+02:00

Ending a connection

terminate ends the session, its transaction committed or rolled back as SESSION.COMMIT_AT_END says, ON by default, and waits for the server to close, at most the read timeout, else 60 seconds; on a stream the program opened, as the program bounded it. A commit that fails then, as of a deferred constraint not satisfied, gives its failure, SQLSTATE 40002, any notice before it read past.

canceller() gives what cancels the statement a connection runs: a new connection to the same server, made as the first was, which sends the session's cancel key and is closed. The statement fails with SQLCODE -920, SQLSTATE TB920, and the session goes on. A cancel gives up after 10 seconds, or the limit cancel takes. PHP runs one thread, so a program cancels from another process, or between sending a request and reading its reply.