|
getSession
Connect to a MySQL server
Description
mysql_xdevapi\Session mysql_xdevapi\getSession(string $uri )
Parameters
-
uri
-
The URI to the MySQL server, such as mysqlx://user:password@host .
URI format:
scheme://[user[:[password]]@]target[:port][?attribute1=value1&attribute2=value2...
-
scheme : required, the connection protocol
In mysql_xdevapi it is always 'mysqlx' (for X Protocol)
-
user : optional, the MySQL user account for authentication
-
password : optional, the MySQL user's password for authentication
-
target : required, the server instance the connection refers to:
* TCP connection (host name, IPv4 address, or IPv6 address)
* Unix socket path (local file path)
* Windows named-pipe (local file path)
-
port : optional, network port of MySQL server.
by default port for X Protocol is 33060
-
?attribute=value : this element is optional and specifies a data dictionary
that contains different options, including:
-
The auth (authentication mechanism) attribute as it relates to encrypted connections.
For additional information, see » Command
Options for Encrypted Connections.
The following 'auth' values are supported: plain ,
mysql41 , external , and sha256_mem .
-
The connect-timeout attribute affects the connection
and not subsequent operations. It is set per connection whether on
a single or multiple hosts.
Pass in a positive integer to define the connection timeout in seconds,
or pass in 0 (zero) to disable the timeout (infinite). Not defining
connect-timeout uses the default value of 10.
Related, the MYSQLX_CONNECTION_TIMEOUT (timeout in seconds) and MYSQLX_TEST_CONNECTION_TIMEOUT (used while running tests)
environment variables can be set and used instead of connect-timeout in the URI. The
connect-timeout URI option has precedence over these environment variables.
-
The optional compression attribute accepts these values:
preferred (client negotiates with server to find a supported algorithm; connection is uncompressed if a mutually supported algorithm is not found),
required (like "preferred", but connection is terminated if a mutually supported algorithm is not found), or
disabled (connection is uncompressed). Defaults to preferred .
This option was added in version 8.0.20.
-
The optional compression-algorithms attribute defines
the desired compression algorithms (and their preferred usage order):
zstd_stream (alias: zstd),
lz4_message (alias: lz4), or
deflate_stream (aliases: deflate or zlib).
By default, the order used (depending on system availability) is lz4_message, zstd_stream, then deflate_stream.
For example, passing in compression-algorithms=[lz4,zstd_stream] uses lz4 if it's available, otherwise
zstd_stream is used. If both are unavailable then behavior depends on the compression value
e.g., if compression=required then it'll fail with an error.
This option was added in version 8.0.22.
Example #1 URI examples
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]
For related information, see MySQL Shell's
» Connecting using a URI String.
Return Values
A Session object.
Errors/Exceptions
A connection failure throws an Exception.
Examples
Example #2 mysql_xdevapi\getSession example
<?php
try {
$session = mysql_xdevapi\getSession("mysqlx://user:password@host");
} catch(Exception $e) {
die("Connection could not be established: " . $e->getMessage());
}
$schemas = $session->getSchemas();
print_r($schemas);
$mysql_version = $session->getServerVersion();
print_r($mysql_version);
var_dump($collection->find("name = 'Alfred'")->execute()->fetchOne());
?>
The above example will output
something similar to:
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"
}
|