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.

Connections

NAME

Turborel\Session\Connection: a connection to a server, and its session.

SYNOPSIS

final class Connection
{
    public static function connect(Target $target, string $user, Mechanism $mechanism, ?Timeouts $timeouts = null, ?Offer $offer = null): self;
    public static function open(mixed $stream, string $user, Mechanism $mechanism, ?Offer $offer = null, ?Timeouts $timeouts = null): self;
    public function authorization(): string;
    public function server(): string;
    public function target(): ?Target;
    public function granted(): array;
    public function has(string $capability): bool;
    public function setting(string $name): ?string;
    public function settings(): array;
    public function inTransaction(): bool;
    public function autocommit(): bool;
    public function setAutocommit(bool $on): void;
    public function readTimeout(): ?float;
    public function setReadTimeout(?float $within): void;
    public function setMaxBody(int $bytes): void;
    public function isLost(): bool;
    public function canceller(): ?Canceller;
    public function query(string $sql): Outcome;
    public function ping(): void;
    public function reset(): void;
    public function changeUser(string $user, Mechanism $mechanism): void;
    public function terminate(): void;
}

DESCRIPTION

connect connects to a Target, TCP, a Unix socket or named pipe, or TLS, as the user, proved by a Mechanism: Trust, Password, Certificate or Scram. Over plain TCP a mechanism that sends a secret is refused before anything is sent. It waits as its Timeouts say, 30 seconds to connect and log in and no limit after by default, and asks for what its Offer asks, every capability but compression by default.

open logs in over a stream the program opened. Its maker answers for its privacy and bounds its waits, Terminate's too, unless $timeouts are given: then the driver bounds the login's by connect and each after by read, and setReadTimeout changes it. Of a TLS stream opened with the ssl option capture_peer_cert, $scram->bind(TlsChannel::of($stream)) binds SCRAM-SHA-256-PLUS first. Such a connection has no target, so no canceller.

authorization and server give what Ready told: the session's authorization identifier and the server's product. granted lists the capabilities granted, in the spec's order; setting and settings give the session's settings as the server last told them. ping asks whether the server and the connection are alive, reset puts the session back as it was at login, and changeUser authenticates the connection again as another user, each only where granted.

query runs one statement; Statements and Cursors describes it with the rest of a session's statements. setReadTimeout bounds each read and write from then on, setMaxBody the longest reply taken, 16 MiB by default. A connection lost, isLost, takes no more requests.

Scram takes inTheClear(), channelBinding(ChannelBinding) and withCache(KeyCache): a KeyCache keeps the keys a password derives, 64 at most, so a later login of the same salt and iterations skips their slow derivation; lookups() counts its hits and misses.

ERRORS

SQLSTATE SQLCODE When
28000 -919 A secret over plain TCP; the server refusing the user, the password or the certificate; SCRAM's exchange refused
08004 -919 The server refusing the connection, as of a protocol version it does not speak
08006 -919 The server not reached, TLS failing, a wait run out, a reply that cannot be read, a capability not granted, or the connection lost
40002 -913 Terminate's commit failing
TB920 -920 The statement cancelled

EXAMPLES

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 implode(' ', array_slice($connection->granted(), 0, 3)), PHP_EOL;
$connection->ping();
$connection->terminate();
notices status diagnostics

STANDARD

[PROTOCOL Opening a connection], [PROTOCOL Mechanisms], [PROTOCOL Capabilities], [PROTOCOL Status 'T'], [PROTOCOL Cancel 'Z'], [PROTOCOL Terminate 'X'], [CLIENT Connecting], [CLIENT Timeouts], [CLIENT What a connection asks for], [CLIENT What the server tells], [CLIENT Controlling the session], [CLIENT The SCRAM key cache].

SEE ALSO

Errors, Values.