
pt-index-usage
==============

概要
----

インデックスの使用状況を表示します。


実行方法
--------

.. code-block:: none

   pt-index-usage [option...]

オプション
----------

.. code-block:: none

  -h, --host=HOSTNAME
  -p, --port=PORT
  -U, --username=USERNAME
  -d, --dbname=DBNAME
  -o, --owner=STRING
  -n, --schema=STRING
  -t, --table=STRING
  -i, --index=STRING
  -u, --unused
  --help

``-h``, ``--host`` オプションは、接続するPostgreSQLデータベースのサーバ名またはIPアドレスを指定します。オプションが指定されない場合は、PGHOST環境変数に設定された値が使われます。PGHOST環境変数が設定されていない場合には、デフォルトの値として ``localhost`` が使われます。

``-p``, ``--port`` オプションは、接続するPostgreSQLデータベースのポート番号を指定します。オプションが指定されない場合は、PGPORT環境変数に設定された値が使われます。PGPORT環境変数が設定されていない場合には、デフォルトの値として ``5432`` が使われます。

``-U``, ``--username`` オプションは、PostgreSQLデータベースに接続するユーザ名を指定します。オプションが指定されない場合は、PGUSER環境変数に設定された値が使われます。PGUSER環境変数が設定されていない場合には、USER環境変数に設定された値が使われます。

``-d``, ``--dbname`` オプションは、接続するデータベース名を指定します。オプションが指定されない場合は、PGDATABASE環境変数に設定された値が使われます。PGDATABASE環境変数が設定されていない場合には、データベースに接続するユーザ名と同じ名前のデータベースに接続します。

``-o``, ``--owner`` オプションは、指定した文字列に合致する名前のユーザが所有者となっているインデックスの情報のみを表示します。

``-n``, ``--schema`` オプションは、指定した文字列に合致する名前のスキーマにあるインデックスの情報のみを表示します。

``-t``, ``--table`` オプションは、指定した文字列に合致する名前のテーブルに作成されたインデックスの情報のみを表示します。

``-i``, ``--index`` オプションは、指定した文字列に合致する名前のインデックスの情報のみを表示します。

``-u``, ``--unused`` オプションは、使われていないインデックスの情報のみを表示します。

``-d`` （または ``--dbname`` ）, ``-o`` （または ``--owner`` ）,  ``-n`` （または ``--schema`` ）, ``-t`` （または ``--table`` ）, ``-i`` （または ``--index`` ）, ``-u`` （または ``--unused`` ）を同時に指定した場合には、すべての条件に合致するインデックスのみが表示対象となります。


出力項目
--------

.. csv-table::

   ``OID``, インデックスのオブジェクトID
   ``OWNER``, インデックスの所有者のユーザ名
   ``SCHEMA``, インデックスの存在しているスキーマ名
   ``TABLE``, インデックスが作成されているテーブル名
   ``INDEX``, インデックス名
   ``BLKS``, インデックスのブロック数（8kB単位）
   ``SCAN``, インデックススキャンの実行回数
   ``T_READ``, インデックススキャンによって取得されたインデックスエントリ数
   ``T_FTCH``, インデックススキャンによってテーブルから読まれたタプル数
   ``B_READ``, ディスクから読み込まれたインデックスのブロック数
   ``B_HIT``, 共有バッファから読み込まれたインデックスのページ数
   ``STATUS``, インデックスのステータス。このステータスは ``pg_index`` システムテーブルから取得します。
   ``TABLESPACE``, インデックスの配置されているテーブルスペース名。

実行例
------

``public`` スキーマにあるテーブルのインデックスについて、利用状況を表示します。

.. code-block:: none

   $ pt-index-usage -n public -d postgres
   +-------+-------+--------+------------------+-----------------------+------+------+--------+--------+--------+-------+--------+------------+
   |  OID  | OWNER | SCHEMA |      TABLE       |         INDEX         | BLKS | SCAN | T_READ | T_FTCH | B_READ | B_HIT | STATUS | TABLESPACE |
   +-------+-------+--------+------------------+-----------------------+------+------+--------+--------+--------+-------+--------+------------+
   | 26793 | snaga | public | pgbench_accounts | pgbench_accounts_pkey |  276 |    1 |      1 |      1 |      4 |     0 |        | spc1       |
   | 26789 | snaga | public | pgbench_branches | pgbench_branches_pkey |    2 |    1 |      1 |      0 |      2 |     0 |        | pg_default |
   | 26791 | snaga | public | pgbench_tellers  | pgbench_tellers_pkey  |    2 |    0 |      0 |      0 |      0 |     0 |        | pg_default |
   +-------+-------+--------+------------------+-----------------------+------+------+--------+--------+--------+-------+--------+------------+
   $ 

``public`` スキーマ内の ``pgbench_accounts`` テーブルにあるインデックスについて、利用状況を表示します。

.. code-block:: none

   $ pt-index-usage -n public -d postgres -t pgbench_accounts
   +-------+-------+--------+------------------+-----------------------+------+------+--------+--------+--------+-------+--------+------------+
   |  OID  | OWNER | SCHEMA |      TABLE       |         INDEX         | BLKS | SCAN | T_READ | T_FTCH | B_READ | B_HIT | STATUS | TABLESPACE |
   +-------+-------+--------+------------------+-----------------------+------+------+--------+--------+--------+-------+--------+------------+
   | 26793 | snaga | public | pgbench_accounts | pgbench_accounts_pkey |  276 |    1 |      1 |      1 |      4 |     0 |        | spc1       |
   +-------+-------+--------+------------------+-----------------------+------+------+--------+--------+--------+-------+--------+------------+
   $

``public`` スキーマ内の一度も使われていないインデックスについて、利用状況を表示します。

.. code-block:: none

   $ pt-index-usage -d postgres -n public -u
   +-------+-------+--------+-----------------+----------------------+------+------+--------+--------+--------+-------+--------+------------+
   |  OID  | OWNER | SCHEMA |      TABLE      |        INDEX         | BLKS | SCAN | T_READ | T_FTCH | B_READ | B_HIT | STATUS | TABLESPACE |
   +-------+-------+--------+-----------------+----------------------+------+------+--------+--------+--------+-------+--------+------------+
   | 26791 | snaga | public | pgbench_tellers | pgbench_tellers_pkey |    2 |    0 |      0 |      0 |      0 |     0 |        | pg_default |
   +-------+-------+--------+-----------------+----------------------+------+------+--------+--------+--------+-------+--------+------------+
   $