getSession

(No version information available, might only be in Git)

getSession — Baut eine Verbindung zu einem MySQL-Server auf

Beschreibung

mysql_xdevapi\getSession(string $uri): mysql_xdevapi\Session

Baut eine Verbindung zum MySQL-Server auf.

Parameter-Liste

uri

Der URI des MySQL-Servers, z. B. mysqlx://user:password@host.

URI-Format:

scheme://[user[:[password]]@]target[:port][?attribute1=value1&attribute2=value2...

scheme: erforderlich; das Verbindungsprotokoll

In mysql_xdevapi ist es immer 'mysqlx' (für das X-Protokoll)
user: optional; das MySQL-Benutzerkonto für die Authentifizierung
password: optional; das Passwort des MySQL-Benutzers für die Authentifizierung
target: erforderlich; die Serverinstanz, auf die sich die Verbindung bezieht:

* TCP-Verbindung (Hostname, IPv4-Adresse oder IPv6-Adresse)

* Pfad des Unix-Sockets (lokaler Dateipfad)

* Windows Named-Pipe (lokaler Dateipfad)
port: optional; der Netzwerk-Port des MySQL-Servers

der Standard-Port für das X-Protokoll ist 33060
?attribute=value: Dieses Element ist optional und gibt ein Datenwörterbuch an, das verschiedene Optionen enthält, unter anderem:
- Das Attribut auth (Authentifizierungsmechanismus), das für verschlüsselte Verbindungen benötigt wird. Für weitere Informationen siehe » Command Options for Encrypted Connections. Die folgenden 'auth'-Werte werden unterstützt: plain, mysql41, external und sha256_mem.
- Das Attribut connect-timeout betrifft die Verbindung selbst, aber nicht die nachfolgenden Operationen. Es wird pro Verbindung gesetzt, unabhängig davon, ob die Verbindung zu einem oder mehreren Hosts besteht.
  
  Das Zeitlimit für die Verbindung wird mit einer positiven Ganzzahl in Sekunden angegeben. Wenn 0 (Null) angegeben wird, ist das Zeitlimit deaktiviert (unendlich). Wird kein Zeitlimit angegeben, wird der Standardwert 10 verwendet.
  
  In diesem Zusammenhang können die Umgebungsvariablen MYSQLX_CONNECTION_TIMEOUT (Zeitlimit in Sekunden) und MYSQLX_TEST_CONNECTION_TIMEOUT (wird bei Tests verwendet) gesetzt und im URI anstelle von connect-timeout verwendet werden. Die URI-Option connect-timeout hat gegenüber diesen Umgebungsvariablen Vorrang.
- Das optionale Attribut compression akzeptiert diese Werte: preferred (der Client verhandelt mit dem Server, um einen unterstützten Algorithmus zu finden; wenn kein von beiden Seiten unterstützter Algorithmus gefunden wird, bleibt die Verbindung unkomprimiert), required (wie "preferred", aber die Verbindung wird abgebrochen, wenn kein von beiden Seiten unterstützter Algorithmus gefunden wird) oder disabled (die Verbindung bleibt unkomprimiert). Der Standardwert ist preferred.
  
  Diese Option wurde in Version 8.0.20 hinzugefügt.
- Das optionale Attribut compression-algorithms definiert die gewünschten Kompressionsalgorithmen (und die bevorzugte Reihenfolge ihrer Verwendung): zstd_stream (alias: zstd), lz4_message (alias: lz4) oder deflate_stream (alias: deflate oder zlib). Standardmäßig wird (je nach Verfügbarkeit des Systems) die Reihenfolge lz4_message, zstd_stream und dann deflate_stream verwendet. Wenn zum Beispiel compression-algorithms=[lz4,zstd_stream] übergeben wird, wird lz4 verwendet, wenn es verfügbar ist, andernfalls wird zstd_stream verwendet. Wenn beide nicht verfügbar sind, hängt das Verhalten vom compression-Wert ab, so wird z. B. bei compression=required eine Fehlermeldung ausgegeben.
  
  Diese Option wurde in Version 8.0.22 hinzugefügt.

Beispiel #1 Beispiele für URIs

mysqlx://foobar
mysqlx://root@localhost?socket=%2Ftmp%2Fmysqld.sock%2F
mysqlx://foo:bar@localhost:33060
mysqlx://foo:bar@localhost:33160?ssl-mode=disabled
mysqlx://foo:bar@localhost:33260?ssl-mode=required
mysqlx://foo:bar@localhost:33360?ssl-mode=required&auth=mysql41
mysqlx://foo:bar@(/path/to/socket)
mysqlx://foo:bar@(/path/to/socket)?auth=sha256_mem
mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]
mysqlx://foobar?ssl-ca=(/path/to/ca.pem)&ssl-crl=(/path/to/crl.pem)
mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]?ssl-mode=disabled
mysqlx://foo:bar@localhost:33160/?connect-timeout=0
mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required
mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required&compression-algorithms=[lz4,zstd_stream]

Für weitere Informationen siehe den Abschnitt » Connecting using a URI String zur MySQL Shell.

Rückgabewerte

Gibt ein Session-Objekt zurück.

Fehler/Exceptions

Ein Verbindungsfehler löst eine Exception aus.

Beispiele

Beispiel #2 mysql_xdevapi\getSession()-Beispiel

<?php
try {
    $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
} catch(Exception $e) {
    die("Die Verbindung konnte nicht aufgebaut werden: " . $e->getMessage());
}

$schemas = $session->getSchemas();
print_r($schemas);

$mysql_version = $session->getServerVersion();
print_r($mysql_version);

var_dump($collection->find("name = 'Alfred'")->execute()->fetchOne());
?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Array
(
    [0] => mysql_xdevapi\Schema Object
        (
            [name] => helloworld
        )
    [1] => mysql_xdevapi\Schema Object
        (
            [name] => information_schema
        )
    [2] => mysql_xdevapi\Schema Object
        (
            [name] => mysql
        )
    [3] => mysql_xdevapi\Schema Object
        (
            [name] => performance_schema
        )
    [4] => mysql_xdevapi\Schema Object
        (
            [name] => sys
        )
)

80012

array(4) {
  ["_id"]=>
  string(28) "00005ad66abf0001000400000003"
  ["age"]=>
  int(42)
  ["job"]=>
  string(7) "Butler"
  ["name"]=>
  string(4) "Alfred"
}