config.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 5564c64a6cafa5bc7325afe8555562df469fc6a0 Maintainer: takagi Status: ready -->
<!-- Credits: mumumu -->
<chapter xml:id="mysqlnd.config" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

  &reftitle.runtime;
  &extension.runtime;

  <para>
  <table xml:id="mysqlnd.config.options">
   <title>MySQL Native Driver 設定オプション</title>
   <tgroup cols="4">
    <thead>
     <row>
      <entry>&Name;</entry>
      <entry>&Default;</entry>
      <entry>&Changeable;</entry>
      <entry>&Changelog;</entry>
     </row>
    </thead>
    <tbody xml:id="mysqlnd.config.options.list">
     <row>
      <entry><link linkend="ini.mysqlnd.collect-statistics">mysqlnd.collect_statistics</link></entry>
      <entry>"1"</entry>
      <entry><constant>INI_SYSTEM</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.collect-memory-statistics">mysqlnd.collect_memory_statistics</link></entry>
      <entry>"0"</entry>
      <entry><constant>INI_SYSTEM</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.debug">mysqlnd.debug</link></entry>
      <entry>""</entry>
      <entry><constant>INI_SYSTEM</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.log-mask">mysqlnd.log_mask</link></entry>
      <entry>0</entry>
      <entry><constant>INI_ALL</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.mempool-default-size">mysqlnd.mempool_default_size</link></entry>
      <entry>16000</entry>
      <entry><constant>INI_ALL</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.net-read-timeout">mysqlnd.net_read_timeout</link></entry>
      <entry>"86400"</entry>
      <entry><constant>INI_ALL</constant></entry>
      <entry>
       PHP 7.2.0 より前のバージョンでは、
       デフォルト値は "31536000" で、変更可能な範囲が <constant>INI_SYSTEM</constant> でした。
      </entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.net-cmd-buffer-size">mysqlnd.net_cmd_buffer_size</link></entry>
      <entry>"4096"</entry>
      <entry><constant>INI_SYSTEM</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.net-read-buffer-size">mysqlnd.net_read_buffer_size</link></entry>
      <entry>"32768"</entry>
      <entry><constant>INI_SYSTEM</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.sha256-server-public-key">mysqlnd.sha256_server_public_key</link></entry>
      <entry>""</entry>
      <entry><constant>INI_PERDIR</constant></entry>
      <entry></entry>
     </row>
      <row>
       <entry><link linkend="ini.mysqlnd.trace-alloc">mysqlnd.trace_alloc</link></entry>
       <entry>""</entry>
       <entry><constant>INI_SYSTEM</constant></entry>
       <entry></entry>
      </row>
     <row>
      <entry><link linkend="ini.mysqlnd.fetch_data_copy">mysqlnd.fetch_data_copy</link></entry>
      <entry>0</entry>
      <entry><constant>INI_ALL</constant></entry>
      <entry>PHP 8.1.0 で削除されました。</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
  &ini.php.constants;
 </para>

  &ini.descriptions.title;

  <para>
  <variablelist>
   <varlistentry xml:id="ini.mysqlnd.collect-statistics">
    <term>
     <parameter>mysqlnd.collect_statistics</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      さまざまなクライアント統計情報の収集を有効にします。収集した情報には
      <function>mysqli_get_client_stats</function> や
      <function>mysqli_get_connection_stats</function> でアクセスでき、
      <function>phpinfo</function> 関数の出力の
      <literal>mysqlnd</literal> セクションにも表示されます。
     </para>
     <para>
      この設定項目は、メモリ管理に関するもの以外のすべての
      <link linkend="mysqlnd.stats">MySQL Native Driver
      統計情報</link> を有効にします。
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.collect-memory-statistics">
    <term>
     <parameter>mysqlnd.collect_memory_statistics</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      さまざまなメモリ統計情報の収集を有効にします。収集した情報には
      <function>mysqli_get_client_stats</function> や
      <function>mysqli_get_connection_stats</function> でアクセスでき、
      <function>phpinfo</function> 関数の出力の
      <literal>mysqlnd</literal> セクションにも表示されます。
     </para>
     <para>
      この設定項目は、<link linkend="mysqlnd.stats">MySQL Native Driver
      統計情報</link> 全体の中でメモリ管理に関する統計を有効にします。
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.debug">
    <term>
     <parameter>mysqlnd.debug</parameter> <type>string</type>
    </term>
    <listitem>
     <para>
      <literal>mysqlnd</literal> を使うすべての拡張モジュールからの通信を、指定したログファイルに記録します。
     </para>
     <para>
      この項目の書式は <literal>mysqlnd.debug =
      "option1[,parameter_option1][:option2[,parameter_option2]]"</literal>
      となります。
     </para>
     <para>
      書式文字列のオプションは、次のとおりです。
     </para>
     <itemizedlist>
      <listitem>
       <para>
        A[,file] - トレース出力を指定したファイルに追記します。
        また、データの追記はデータベースへの書き込みのたびに発生することを保証します。
        それを実現するために、トレースファイルをいったん閉じてから開きなおします
        (速度は遅くなります)。
        これで、アプリケーションがクラッシュしたときにも完全なログファイルを残せます。
       </para>
      </listitem>
      <listitem>
       <para>
        a[,file] - トレース出力を指定したファイルに追記します。
       </para>
      </listitem>
      <listitem>
       <para>
        d - DBUG_&lt;N&gt; マクロからの、現在の状態に関する出力を有効にします。
        キーワードのリストが後に続くことがあり、その場合は
        指定したキーワードの DBUG マクロからだけ出力させます。
        空のキーワードリストを指定すると、すべてのマクロを出力します。
       </para>
      </listitem>
      <listitem>
       <para>
        f[,functions] - デバッガの動作を、リストで指定した関数だけに絞り込みます。
        空の関数リストを指定すると、すべての関数を選択したことになります。
       </para>
      </listitem>
      <listitem>
       <para>
        F - デバッガからの出力の各行に、その出力の元となったマクロが含まれるソースファイル名を付加します。
       </para>
      </listitem>
      <listitem>
       <para>
        i - デバッガからの出力の各行に、現在のプロセスの PID を付加します。
       </para>
      </listitem>
      <listitem>
       <para>
        L - デバッガからの出力の各行に、その出力の元となったマクロが含まれるソースファイル内の行番号を付加します。
       </para>
      </listitem>
      <listitem>
       <para>
        n - デバッガからの出力の各行に、現在の関数のネストレベルを付加します。
       </para>
      </listitem>
      <listitem>
       <para>
        o[,file] - a[,file] と似ていますが、既存のファイルに追記するのではなく既存のファイルを上書きします。
       </para>
      </listitem>
      <listitem>
       <para>
        O[,file] - A[,file] と似ていますが、既存のファイルに追記するのではなく既存のファイルを上書きします。
       </para>
      </listitem>
      <listitem>
       <para>
        t[,N] - 関数の制御フローのトレースを有効にします。最大のネストレベルを N で指定します。
        N のデフォルトは 200 です。
       </para>
      </listitem>
      <listitem>
       <para>
        x - このオプションはプロファイリングを有効にします。
       </para>
      </listitem>
       <listitem>
       <para>
        m - 呼び出しに関連する、メモリの確保と解放をトレースします。
       </para>
      </listitem>
     </itemizedlist>
     <para>
      利用例は、このようになります。
     </para>
<programlisting>
<![CDATA[
d:t:x:O,/tmp/mysqlnd.trace
]]>
</programlisting>
     <note>
      <para>
       この機能は、デバッグビルド版の PHP でしか使えません。
      </para>
     </note>
     <para></para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.log-mask">
    <term>
     <parameter>mysqlnd.log_mask</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      どのクエリをログに記録するかを定義します。デフォルトは 0 で、これはクエリをログに記録しません。
      値は静数値で定義します。PHP の定数はありません。
      たとえば 48 (16 + 32) を設定すると、インデックスの選択が悪かったり
      (SERVER_QUERY_NO_GOOD_INDEX_USED = 16) まったくインデックスを使っていなかったり (SERVER_QUERY_NO_INDEX_USED = 32)
      といった理由で遅くなっているクエリをログに記録します。
      2043 (1 + 2 + 8 + ... + 1024) を指定すると、あらゆる型の遅いクエリを記録します。
     </para>
     <para>
      使える型は、次のとおりです。
      SERVER_STATUS_IN_TRANS=1, SERVER_STATUS_AUTOCOMMIT=2,
      SERVER_MORE_RESULTS_EXISTS=8, SERVER_QUERY_NO_GOOD_INDEX_USED=16, SERVER_QUERY_NO_INDEX_USED=32,
      SERVER_STATUS_CURSOR_EXISTS=64, SERVER_STATUS_LAST_ROW_SENT=128, SERVER_STATUS_DB_DROPPED=256,
      SERVER_STATUS_NO_BACKSLASH_ESCAPES=512, SERVER_QUERY_WAS_SLOW=1024
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.mempool-default-size">
    <term>
     <parameter>mysqlnd.mempool_default_size</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      mysqlnd メモリプールのデフォルトサイズ。これは結果セットが使います。
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.net-read-timeout">
    <term>
     <parameter>mysqlnd.net_read_timeout</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      <literal>mysqlnd</literal> は、MySQL Client Library すなわち
      <literal>libmysqlclient</literal> とは異なるネットワーク API を使います。
      <literal>mysqlnd</literal> は PHP ストリームを使いますが、
      <literal>libmysqlclient</literal> は自前のラッパーを用意して操作レベルでのネットワークコールをしています。
      PHP のデフォルト設定では、ストリームの読み込みタイムアウトは 60 秒です。これは
      <filename>php.ini</filename> の
      <literal>default_socket_timeout</literal> で設定します。
      タイムアウト値を設定しなければ、すべてのストリームに対してデフォルト値が適用されます。
      <literal>mysqlnd</literal> は何も値を設定しないので、長いクエリを実行して
      <literal>default_socket_timeout</literal> 秒が経過すると、接続を切断して
      <quote>2006 - MySQL Server has gone away</quote> というエラーが発生します。
      MySQL Client Library のデフォルトのタイムアウトは
      24 * 3600 秒 (1 日) で、TCP/IP のタイムアウトなどのその他のタイムアウトが発生するのを待ちます。
      <literal>mysqlnd</literal> も同様に、非常に長いタイムアウトを使うことができます。この値は、
      <filename>php.ini</filename> の新しい項目
      <literal>mysqlnd.net_read_timeout</literal> で設定します。
      <literal>mysqlnd.net_read_timeout</literal> は、<literal>mysqlnd</literal>
      を使うすべての拡張モジュール (<literal>ext/mysql</literal> や
      <literal>ext/mysqli</literal>、<literal>PDO_MySQL</literal>) が利用します。
      <literal>mysqlnd</literal> は、PHP ストリームに対して
      <literal>mysqlnd.net_read_timeout</literal> を使うよう指示します。
      MySQL Client Library および PHP ストリームの
      <literal>MYSQL_OPT_READ_TIMEOUT</literal> とは微妙に違いがあることに注意しましょう。
      <literal>MYSQL_OPT_READ_TIMEOUT</literal> は
      TCP/IP 接続でしか動作しないとドキュメントに記載されており、
      MySQL 5.1.2 より前のバージョンでは Windows でしか使えません。
      PHP ストリームにはこの制限はありません。
      信じられないならストリームのドキュメントを調べるとよいでしょう。
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.net-cmd-buffer-size">
    <term>
     <parameter>mysqlnd.net_cmd_buffer_size</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      <literal>mysqlnd</literal> は、内部のコマンド/ネットワークバッファとして
      <filename>php.ini</filename> の <literal>mysqlnd.net_cmd_buffer_size</literal>
      で指定しただけのバイト数をすべての接続に対して確保します。
      MySQL Client Server プロトコルのコマンド、たとえば
      <literal>COM_QUERY</literal> (通常のクエリ)
      がこのバッファに収まらない場合、<literal>mysqlnd</literal>
      はコマンドの送信に必要なだけバッファを拡張します。
      ひとつの接続でバッファの拡張が発生するたびに
      <literal>command_buffer_too_small</literal> をひとつ加算します。
     </para>
     <para>
      ほとんどすべての接続で <literal>mysqlnd</literal> が
      <literal>mysqlnd.net_cmd_buffer_size</literal> の初期値よりバッファを拡張せざるを得なくなったら、
      デフォルトのサイズを大きくしてバッファの再割り当てを回避すべきでしょう。
     </para>
     <para>
      デフォルトのバッファサイズは 4096 バイトです。これは、設定可能な最小値です。
     </para>
     <para>
      この値は <literal>mysqli_options(link,
      MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size)</literal> でも変更できます。
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.net-read-buffer-size">
    <term>
     <parameter>mysqlnd.net_read_buffer_size</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      MySQL コマンドパケットのボディを読み込むときの、読み込みチャンクの最大バイト数。
      MySQL クライアントサーバープロトコルは、すべてのコマンドをパケット内にカプセル化します。
      パケットは、小さなヘッダと実際の本体を含むボディで構成されています。
      ボディのサイズはヘッダに書き込まれています。
      <literal>mysqlnd</literal> はこのボディを、
      <literal>MIN(header.size, mysqlnd.net_read_buffer_size)</literal>
      バイトごとに分割して読み込みます。パケットのボディが
      <literal>mysqlnd.net_read_buffer_size</literal> バイトより長い場合は、
      <literal>mysqlnd</literal> は <literal>read()</literal>
      を複数回コールする必要があります。
     </para>
     <para>
      この値は <literal>mysqli_options(link,
      MYSQLI_OPT_NET_READ_BUFFER_SIZE, size)</literal>
      でも設定できます。
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.sha256-server-public-key">
    <term>
     <parameter>mysqlnd.sha256_server_public_key</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      SHA-256 認証プラグイン関連の設定。MySQL サーバーの
      RSA 公開鍵ファイル。
     </para>
     <para>
      クライアントで RSA 公開鍵の設定をせずに済ませることができます。
      そのためには、この設定項目で公開鍵を設定するか、実行時に
      <function>mysqli_options</function> で鍵を指定します。
      RSA 公開鍵をクライアントから渡さなかった場合は、
      ここで指定した鍵を使って SHA-256 認証プラグインの認証手続きを進めます。
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.trace-alloc">
    <term>
     <parameter>mysqlnd.trace_alloc</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.fetch_data_copy">
    <term>
     <parameter>mysqlnd.fetch_data_copy</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      デフォルトの参照とコピーオンライトのロジックを使わずに、
      内部結果セットのバッファから PHP の変数に結果セットをコピーします。
      詳細は
      <link linkend="mysqlnd.memory">メモリ管理の実装についての説明</link>
      を参照ください。
     </para>
     <para>
      結果セットを PHP の変数から参照させるのではなくコピーすることで、
      PHP の変数に割り当てたメモリを早めに解放できます。
      ユーザー API のコードやクエリの内容、そして結果セットの大きさにも依存しますが、
      これは mysqlnd のメモリ使用量の削減につながります。
     </para>
     <para>
       PDO_MySQL を使う場合は設定しないでください。PDO_MySQL は、まだこの新しいフェッチモードに対応していません。
     </para>
    <note>
     <simpara>この設定は、PHP 8.1.0 で削除されました。</simpara>
    </note>
    </listitem>
   </varlistentry>
  </variablelist>
 </para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->