MySQL サーバーに接続する

# getSession

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

getSession — MySQL サーバーに接続する

### 説明

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

MySQL サーバーに接続します。

### パラメータ

`uri`

  `mysqlx://user:password@host` のような、MySQL サーバーへのURI。

  URI のフォーマットは下記のとおりです:

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

  - `scheme` は必須です。接続プロトコルです

    mysql_xdevapi では、常に 'mysqlx' です(X プロトコル)

  - `user`: オプションです。認証される MySQL アカウント

  - `password`: オプションです。認証に使う MySQL ユーザのパスワード

  - `target`: 必須です。 接続が参照する サーバーインスタンスです:

    * TCP接続 (ホスト名, IPv4 アドレス, または IPv6 アドレス)

    * Unix ソケットのパス (ローカルファイルのパス)

    * Windows 名前付きパイプ (ローカルファイルのパス)

  - `port`: オプションです。MySQL サーバーのネットワーク ポート

    X プロトコルのデフォルトのポートは 33060 です

  - `?attribute=value`: この要素はオプションで、異なるオプションを含む 次のような辞書データを指定します:

    - `auth` (認証メカニズム) 属性は、接続の暗号化に関連があります。 追加の情報については、 » Command Options for Encrypted Connections を参照ください。 'auth' 属性については、次の値がサポートされています: `plain`, `mysql41`, `external`, `sha256_mem`.

    - `connect-timeout` 属性は、接続時と接続後の操作に影響します。 単一、複数のホストへの接続かに関わらず、接続単位で設定します。

      接続タイムアウトは秒単位で正の整数を渡します。 0 を渡すと、タイムアウトを無効(つまり無限) にします。 connect-timeout を定義しないと、デフォルト値10を使います。

      関連事項として、 MYSQLX_CONNECTION_TIMEOUT (秒単位のタイムアウト) および、 MYSQLX_TEST_CONNECTION_TIMEOUT (テスト時に使います) 環境変数を、URI に connect-timeout を設定する代わりに設定し、使うことができます。 connect-timeout URI オプションは、これらの環境変数に優先します。

    - オプションの `compression` は、以下の値を受け付けます: `preferred` (クライアントとサーバーが、お互いがサポートしているアルゴリズムを見つけるために交渉します。つまり、サポートされたアルゴリズムが見つからない場合は圧縮されません), `required` ("preferred" と似ていますが、お互いがサポートしているアルゴリズムが見つからない場合は接続を終了します), または `disabled` (この接続では圧縮が行われません)。 デフォルトは `preferred` です。

      このオプションは 8.0.20 で追加されました。

    - オプションの `compression-algorithms` 属性は、 好みの圧縮アルゴリズム(および好みの優先順) を定義します: `zstd_stream` (エイリアス: zstd), `lz4_message` (エイリアス: lz4), `deflate_stream` (エイリアス: deflate, zlib) が指定できます。 デフォルトでは、(システムで利用可能かどうかに依存しますが) lz4_message, zstd_stream, deflate_stream の順番が使われます。 たとえば、compression-algorithms=[lz4,zstd_stream] という値を渡した場合、 lz4 が利用可能であれば lz4 を使いますが、そうでない場合は、zstd_stream が使われます。 lz4, zstd_stream 双方が利用できない場合、振る舞いは compression の値に依存します。 たとえば、compression=required の場合、エラーが出て接続は失敗します。

      このオプションは 8.0.22 で追加されました。

  例1 URI の例

      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]

  関連する情報については、MySQL Shell の » Connecting using a URI String を参照ください

### 戻り値

Session オブジェクト

### エラー / 例外

接続に失敗した場合は、Exception がスローされます。

### 例

例2 mysql_xdevapi\getSession() の例

    <?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());
    ?>

上の例の出力は、 たとえば以下のようになります。

    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"
    }

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open