diff --git a/doc/pg_repack_jp.rst b/doc/pg_repack_jp.rst new file mode 100644 index 0000000..21ac723 --- /dev/null +++ b/doc/pg_repack_jp.rst @@ -0,0 +1,957 @@ +.. pg_repack -- Reorganize tables in PostgreSQL databases with minimal locks + ========================================================================= + +pg_repack -- PostgreSQLデータベースのテーブルを最小限のロックで再編成します +============================================================================= + +.. contents:: + :depth: 1 + :backlinks: none + +.. pg_repack_ is a PostgreSQL extension which lets you remove bloat from + tables and indexes, and optionally restore the physical order of clustered + indexes. Unlike CLUSTER_ and `VACUUM FULL`_ it works online, without + holding an exclusive lock on the processed tables during processing. + pg_repack is efficient to boot, with performance comparable to using + CLUSTER directly. + +pg_repack_ はPostgreSQLの拡張の一つで、肥大化したテーブルやインデックスを再編成し、さらに指定したインデックスにしたがってレコードを並び替えることができます。 +PostgreSQLの CLUSTER_ や `VACUUM FULL`_ コマンドと違って、pg_repackは処理の間対象テーブルへの排他ロックを保持し続けないため、オンライン中に動作させることができます。 +pg_repackはCLUSTERコマンドを直接実行するのと同じくらいの性能で起動することができて効率的です。 + +.. pg_repack is a fork of the previous pg_reorg_ project. Please check the + `project page`_ for bug report and development information. + +pg_repack は pg_reorg_ からフォークしたプロジェクトです。 +バグ報告や開発情報については `project page`_ を参照してください。 + +.. You can choose one of the following methods to reorganize: + + * Online CLUSTER (ordered by cluster index) + * Ordered by specified columns + * Online VACUUM FULL (packing rows only) + * Rebuild or relocate only the indexes of a table + +pg_repackでは再編成する方法として次のものが選択できます。 + +* オンラインCLUSTER (cluster index順にレコードを並び替える) +* 指定したカラムでレコードを並び替える +* オンラインVACUUM FULL (レコードのすきまを詰める) +* 指定したテーブルのインデックスだけを再構築、もしくは再配置する + +.. NOTICE: + + * Only superusers can use the utility. + * Target table must have a PRIMARY KEY, or at least a UNIQUE total index on a + NOT NULL column. + +注意: + +* DBのスーパーユーザだけがpg_repackを実行できます +* 対象となるテーブルは主キー、もしくはNOT NULL制約を持つカラムへのユニーク制約をもつインデックスが存在している必要があります + +.. _pg_repack: http://reorg.github.com/pg_repack +.. _CLUSTER: http://www.postgresql.jp/document/current/html/sql-cluster.html +.. _VACUUM FULL: VACUUM_ +.. _VACUUM: http://www.postgresql.jp/document/current/html/sql-vacuum.html +.. _project page: https://github.com/reorg/pg_repack +.. _pg_reorg: http://reorg.projects.pgfoundry.org/ + + +.. Requirements + ------------ + + PostgreSQL versions + PostgreSQL 8.3, 8.4, 9.0, 9.1, 9.2, 9.3, 9.4 + + Disks + Performing a full-table repack requires free disk space about twice as + large as the target table(s) and its indexes. For example, if the total + size of the tables and indexes to be reorganized is 1GB, an additional 2GB + of disk space is required. + + +動作環境 +--------- + +PostgreSQL バージョン + PostgreSQL 8.3, 8.4, 9.0, 9.1, 9.2, 9.3, 9.4 + +ディスク + テーブル全体の再編成を行うには、対象となるテーブルと付属するインデックスのおよそ2倍のサイズのディスク空き容量が必要です。例えば、テーブルとインデックスを合わせたサイズが1GBの場合、2GBのディスク領域が必要となります。 + +.. Download + -------- + + You can `download pg_repack`__ from the PGXN website. Unpack the archive and + follow the installation_ instructions. + + .. __: http://pgxn.org/dist/pg_repack/ + + Alternatively you can use the `PGXN Client`_ to download, compile and install + the package; use:: + + $ pgxn install pg_repack + + Check the `pgxn install documentation`__ for the options available. + + .. _PGXN Client: http://pgxnclient.projects.pgfoundry.org/ + .. __: http://pgxnclient.projects.pgfoundry.org/usage.html#pgxn-install + + +ダウンロード +------------ + +pg_repackは、PGXNのWebサイトから `ダウンロード`__ できます。 +ダウンロードしたアーカイブを展開し、以下の手順にしたがって `インストール`_ してください。 + +.. __: http://pgxn.org/dist/pg_repack/ + +もしくは、 `PGXN Client`_ を使ってダウンロードからコンパイル、インストールすることもできます。:: + + $ pgxn install pg_repack + +利用可能なオプションについては `pgxn install コマンドのドキュメント`__ を参照してください。 + +.. _PGXN Client: http://pgxnclient.projects.pgfoundry.org/ +.. __: http://pgxnclient.projects.pgfoundry.org/usage.html#pgxn-install + + + +.. Installation + ------------ + + pg_repack can be built with ``make`` on UNIX or Linux. The PGXS build + framework is used automatically. Before building, you might need to install + the PostgreSQL development packages (``postgresql-devel``, etc.) and add the + directory containing ``pg_config`` to your ``$PATH``. Then you can run:: + + $ cd pg_repack + $ make + $ sudo make install + + You can also use Microsoft Visual C++ 2010 to build the program on Windows. + There are project files in the ``msvc`` folder. + + After installation, load the pg_repack extension in the database you want to + process. On PostgreSQL 9.1 and following pg_repack is packaged as an + extension, so you can execute:: + + $ psql -c "CREATE EXTENSION pg_repack" -d your_database + + For previous PostgreSQL versions you should load the script + ``$SHAREDIR/contrib/pg_repack.sql`` in the database to process; you can + get ``$SHAREDIR`` using ``pg_config --sharedir``, e.g. :: + + $ psql -f "$(pg_config --sharedir)/contrib/pg_repack.sql" -d your_database + + You can remove pg_repack from a PostgreSQL 9.1 and following database using + ``DROP EXTENSION pg_repack``. For previous Postgresql versions load the + ``$SHAREDIR/contrib/uninstall_pg_repack.sql`` script or just drop the + ``repack`` schema. + + If you are upgrading from a previous version of pg_repack or pg_reorg, just + drop the old version from the database as explained above and install the new + version. + +インストール +------------ + +Unix やLinux上では、pg_repackは ``make`` コマンドでビルドすることができます。 +その際、PostgreSQLの拡張向けの構築基盤であるPGXSが自動で利用されます。 +ビルトに当たっては、事前にPostgreSQLの開発パッケージ (``postgresql-devel``, etc.)をインストールしておく必要があるかもしれません。 +そして、 ``pg_config`` コマンドが存在するディレクトリが ``$PATH`` に追加されている必要があります。 + +その上で、以下のコマンドを実行します。:: + + $ cd pg_repack + $ make + $ sudo make install + +Windows OS上ではMicrosoft Visual C++ 2010を利用してビルドすることができます。 +``msvc`` ディレクトリ配下にプロジェクトファイルがあります。 + +インストールを行った後、pg_repack エクステンションを対象のデータベースに登録します。 +PostgreSQL 9.1以上のバージョンでは、以下のコマンドで実施できます。 :: + + $ psql -c "CREATE EXTENSION pg_repack" -d your_database + +それ以前のPostgreSQLバージョンの場合は、 ``$SHAREDIR/contrib/pg_repack.sql`` スクリプトを対象とするデータベースに対して実施します。 ``$SHAREDIR`` は ``pg_config --sharedir`` コマンドを実行することで確認できます。 :: + + $ psql -f "$(pg_config --sharedir)/contrib/pg_repack.sql" -d your_database + +pg_repackの登録を削除するには、PostgreSQL 9.1以上のバージョンでは、``DROP EXTENSION pg_repack`` を対象データベースに実行します。それ以前のPostgreSQLバージョンの場合は、 ``$SHAREDIR/contrib/uninstall_pg_repack.sql`` スクリプトを実行するか、 ``repack`` スキーマを削除します。 + +pg_repackもしくはpg_reorgの古いバージョンからのアップグレードを行うには、古いバージョンをデータベースから上記の手順で削除し、新しいバージョンを登録します。 + +.. Usage + ----- + + :: + + pg_repack [OPTION]... [DBNAME] + + The following options can be specified in ``OPTIONS``. + + Options: + -a, --all repack all databases + -t, --table=TABLE repack specific table only + -c, --schema=SCHEMA repack tables in specific schema only + -s, --tablespace=TBLSPC move repacked tables to a new tablespace + -S, --moveidx move repacked indexes to *TBLSPC* too + -o, --order-by=COLUMNS order by columns instead of cluster keys + -n, --no-order do vacuum full instead of cluster + -N, --dry-run print what would have been repacked and exit + -j, --jobs=NUM Use this many parallel jobs for each table + -i, --index=INDEX move only the specified index + -x, --only-indexes move only indexes of the specified table + -T, --wait-timeout=SECS timeout to cancel other backends on conflict + -Z, --no-analyze don't analyze at end + + Connection options: + -d, --dbname=DBNAME database to connect + -h, --host=HOSTNAME database server host or socket directory + -p, --port=PORT database server port + -U, --username=USERNAME user name to connect as + -w, --no-password never prompt for password + -W, --password force password prompt + + Generic options: + -e, --echo echo queries + -E, --elevel=LEVEL set output message level + --help show this help, then exit + --version output version information, then exit + +利用方法 +--------- + +:: + + pg_repack [OPTION]... [DBNAME] + +OPTIONには以下のものが指定できます。 + +固有オプション: + -a, --all すべてのデータベースに対して実行します + -t, --table=TABLE 指定したテーブルに対して実行します + -c, --schema=SCHEMA 指定したスキーマに存在するテーブル全てに対して実行します + -s, --tablespace=TBLSPC 指定したテーブル空間に再編成後のテーブルを配置します + -S, --moveidx -s/--tablespaceで指定したテーブル空間に再編成対象のテーブルに付与されたインデックスも配置します + -o, --order-by=COLUMNS 指定したカラムの値順に再編成します + -n, --no-order オンラインVACUUM FULL相当の処理を行います + -N, --dry-run 実際の処理は行わず、メッセージのみだけ出力します + -j, --jobs=NUM 指定した並列度で処理を行います + -i, --index=INDEX 指定したインデックスのみ再編成します + -x, --only-indexes 指定したテーブルに付与されたインデックスだけを再編成します + -T, --wait-timeout=SECS ロック競合している他のトランザクションをキャンセルするまで待機する時間を指定します + -Z, --no-analyze 再編成後にANALYZEを行いません + +接続オプション: + -d, --dbname=DBNAME 接続する対象のデータベースを指定します + -h, --host=HOSTNAME 接続する対象のホスト名、もしくはUNIXソケットドメインディレクトリを指定します + -p, --port=PORT 接続する対象のデータベース・サーバのポート番号を指定します + -U, --username=USERNAME 接続するユーザ名を指定します + -w, --no-password パスワードの入力表示を無効化します + -W, --password パスワード入力表示を強制的に表示します + +一般オプション: + -e, --echo サーバに送信するSQLを表示します + -E, --elevel=LEVEL ログ出力レベルを指定します + --help 使用方法を表示します + +.. Reorg Options + ^^^^^^^^^^^^^ + +再編成オプション +---------------- + +.. ``-a``, ``--all`` + Attempt to repack all the databases of the cluster. Databases where the + ``pg_repack`` extension is not installed will be skipped. + +``-a``, ``--all`` + データベースクラスタのすべてのデータベースを再編成します。pg_repackのエクステンションがインストールされていないデータベースはスキップされます。 + +.. ``-t TABLE``, ``--table=TABLE`` + Reorganize the specified table(s) only. Multiple tables may be + reorganized by writing multiple ``-t`` switches. By default, all eligible + tables in the target databases are reorganized. + +``-t TABLE``, ``--table=TABLE`` + 指定したテーブルのみを再編成します。 ``-t`` オプションを複数同時に使用することで、複数のテーブルを指定することができます。このオプションを指定しない限り、対象のデータベースに存在するすべてのテーブルを再編成します。 + +.. ``-c``, ``--schema`` + Repack the tables in the specified schema(s) only. Multiple schemas may + be repacked by writing multiple ``-c`` switches. May be used in + conjunction with ``--tablespace`` to move tables to a different tablespace. + +``-c``, ``--schema`` + 指定したスキーマに存在するテーブルを再編成します。 ``-c`` オプションを複数同時に指定することで、複数のスキーマを指定することができます。 ``--tablespace`` オプションと同時に使用することで、特定のスキーマのテーブルを別のテーブル空間に移動する利用例が挙げられます。 + +.. ``-o COLUMNS [,...]``, ``--order-by=COLUMNS [,...]`` + Perform an online CLUSTER ordered by the specified columns. + +``-o COLUMNS [,...]``, ``--order-by=COLUMNS [,...]`` + 指定したカラムの値を用いてオンラインCLUSTER処理を実行します。 + +.. ``-n``, ``--no-order`` + Perform an online VACUUM FULL. Since version 1.2 this is the default for + non-clustered tables. + +``-n``, ``--no-order`` + オンラインVACUUM FULL処理を実行します。バージョン1.2から、クラスタキーのないテーブルに対してはこれがデフォルトの挙動になっています。 + +.. ``-N``, ``--dry-run`` + List what would be repacked and exit. + +``-N``, ``--dry-run`` + 実際の処理は実行せずに、実施する内容についてのメッセージだけを出力します。 + +.. ``-j``, ``--jobs`` + Create the specified number of extra connections to PostgreSQL, and + use these extra connections to parallelize the rebuild of indexes + on each table. Parallel index builds are only supported for full-table + repacks, not with ``--index`` or ``--only-indexes`` options. If your + PostgreSQL server has extra cores and disk I/O available, this can be a + useful way to speed up pg_repack. + +``-j``, ``--jobs`` + 指定した数だけ追加でPostgreSQLへのコネクションを作成し、それらのコネクションを使って並列でインデックス作成処理を行います。並列でのインデックス作成は、テーブル全体を再編成する場合にのみ有効です。 ``--index`` や ``--only-indexes`` オプションとは同時に利用できません。PostgreSQLサーバのCPUコア数およびディスクI/Oに余裕がある場合には、このオプションを利用することでpg_repackの処理を高速化するための有力な手段になりえます。 + +.. ``-s TBLSPC``, ``--tablespace=TBLSPC`` + Move the repacked tables to the specified tablespace: essentially an + online version of ``ALTER TABLE ... SET TABLESPACE``. The tables' indexes + are left in the original tablespace unless ``--moveidx`` is specified too. + +``-s TBLSPC``, ``--tablespace=TBLSPC`` + 再編成したテーブルを指定したテーブル空間に移動します。即ち、 ``ALTER TABLE ... SET TABLESPACE`` 相当の処理をオンラインで実施します。 ``--moveidx`` オプションを併用しない限り、再編成したテーブルのインデックスは元のテーブル空間に残されます。 + +.. ``-S``, ``--moveidx`` + Also move the indexes of the repacked tables to the tablespace specified + by the ``--tablespace`` option. + +``-S``, ``--moveidx`` + ``--tablespace`` オプションと併用することで、再編成したテーブルのインデックスも指定したテーブル空間に移動します。 + +.. ``-i``, ``--index`` + Repack the specified index(es) only. Multiple indexes may be repacked + by writing multiple ``-i`` switches. May be used in conjunction with + ``--tablespace`` to move the index to a different tablespace. + +``-i``, ``--index`` + 指定したインデックスのみを再編成します。 ``-i`` オプションを複数同時に指定することで、複数のインデックスを指定することができます。 ``--tablespace`` オプションと同時に使用することで、特定のスキーマのテーブルを別のテーブル空間に移動する利用例が挙げられます。 + +.. ``-x``, ``--only-indexes`` + Repack only the indexes of the specified table(s), which must be specified + with the ``--table`` option. + +``-x``, ``--only-indexes`` + ``--table`` オプションと併用することで、指定したテーブルのインデックスのみを再編成します。 + +.. ``-T SECS``, ``--wait-timeout=SECS`` + pg_repack needs to take an exclusive lock at the end of the + reorganization. This setting controls how many seconds pg_repack will + wait to acquire this lock. If the lock cannot be taken after this duration, + pg_repack will forcibly cancel the conflicting queries. If you are using + PostgreSQL version 8.4 or newer, pg_repack will fall back to using + pg_terminate_backend() to disconnect any remaining backends after + twice this timeout has passed. The default is 60 seconds. + +``-T SECS``, ``--wait-timeout=SECS`` + pg_repackは再編成の完了直前に排他ロックを利用します。このオプションは、このロック取得時に何秒間pg_repackが取得を待機するかを指定します。指定した時間経ってもロックが取得できない場合、pg_repackは競合するクエリを強制的にキャンセルさせます。PostgreSQL 8.4以上のバージョンを利用している場合、指定した時間の2倍以上経ってもロックが取得できない場合、pg_repackは競合するクエリを実行しているPostgreSQLバックエンドプロセスをpg_terminate_backend()関数により強制的に停止させます。このオプションのデフォルトは60秒です。 + + +.. ``-Z``, ``--no-analyze`` + Disable ANALYZE after a full-table reorganization. If not specified, run + ANALYZE after the reorganization. + +``-Z``, ``--no-analyze`` + 再編成終了後にANALYZEを行うことを無効にします。デフォルトでは再編成完了後に統計情報を更新するためANALYZEを実行します。 + +.. Connection Options + ^^^^^^^^^^^^^^^^^^ + Options to connect to servers. You cannot use ``--all`` and ``--dbname`` or + ``--table`` together. + +接続オプション +--------------- + +PostgreSQLサーバに接続するためのオプションです。 +``--all`` オプションと同時に ``--dbname`` や ``--table`` を利用することはできません。 + + +.. ``-a``, ``--all`` + Reorganize all databases. + +``-a``, ``--all`` + すべてのデータベースを再編成します。 + +.. ``-d DBNAME``, ``--dbname=DBNAME`` + Specifies the name of the database to be reorganized. If this is not + specified and ``-a`` (or ``--all``) is not used, the database name is read + from the environment variable PGDATABASE. If that is not set, the user + name specified for the connection is used. + +``-d DBNAME``, ``--dbname=DBNAME`` + 指定したデータベースのみを再編成します。このオプションや ``-a`` ( ``--all`` )オプションを指定しなかった場合、環境変数PGDATABASEで指定されたデータベースを再編成します。PGDATABASEも指定されていない場合、接続に利用するユーザ名と同じ名称のデータベースを再編成します。 + +.. ``-h HOSTNAME``, ``--host=HOSTNAME`` + Specifies the host name of the machine on which the server is running. If + the value begins with a slash, it is used as the directory for the Unix + domain socket. + +``-h HOSTNAME``, ``--host=HOSTNAME`` + 指定したホスト名を持つサーバ上のPostgreSQLに接続します。指定した値が ``/`` で始まる場合、Unixドメインソケットが配置されたディレクトリと解釈して接続します。 + +.. ``-p PORT``, ``--port=PORT`` + Specifies the TCP port or local Unix domain socket file extension on which + the server is listening for connections. + +``-p PORT``, ``--port=PORT`` + 指定したポート番号でPostgreSQLサーバに接続します。 + +.. ``-U USERNAME``, ``--username=USERNAME`` + User name to connect as. + +``-U USERNAME``, ``--username=USERNAME`` + 指定したユーザ名でPostgreSQLサーバに接続します。 + +.. ``-w``, ``--no-password`` + Never issue a password prompt. If the server requires password + authentication and a password is not available by other means such as a + ``.pgpass`` file, the connection attempt will fail. This option can be + useful in batch jobs and scripts where no user is present to enter a + password. + +``-w``, ``--no-password`` + 接続時にパスワード入力プロンプトを表示されないようにします。もし接続先のPostgreSQLサーバがパスワード認証を要求していて、パスワードが``.pgpass``ファイルなどの手段で取得できない場合、pg_repackは接続に失敗します。このオプションはパスワード入力なしで接続できるユーザを用いたバッチ処理やスクリプトにて利用します。 + +.. ``-W``, ``--password`` + Force the program to prompt for a password before connecting to a + database. + + This option is never essential, since the program will automatically + prompt for a password if the server demands password authentication. + However, pg_repack will waste a connection attempt finding out that the + server wants a password. In some cases it is worth typing ``-W`` to avoid + the extra connection attempt. + +``-W``, ``--password`` + 接続時にパスワード入力プロンプトを強制的に表示します。 + サーバがパスワード認証を要求する場合、そもそも自動的にパスワード入力が促されるため、このオプションが重要になることはありません。 + しかし、サーバにパスワードが必要かどうかを判断するための接続試行を無駄に行います。 + こうした余計な接続試行を防ぎたいのであれば、このオプションが利用してください。 + + +.. Generic Options + ^^^^^^^^^^^^^^^ + +一般オプション +-------------- + +.. ``-e``, ``--echo`` + Echo commands sent to server. + +``-e``, ``--echo`` + サーバに送信するSQLを表示します。 + +.. ``-E LEVEL``, ``--elevel=LEVEL`` + Choose the output message level from ``DEBUG``, ``INFO``, ``NOTICE``, + ``WARNING``, ``ERROR``, ``LOG``, ``FATAL``, and ``PANIC``. The default is + ``INFO``. + +``-E LEVEL``, ``--elevel=LEVEL`` + ログ出力レベルを設定します。 ``DEBUG``, ``INFO``. ``NOTICE``, ``WARNING``, ``ERROR``, ``LOG``, ``FATAL``, ``PANIC`` から選択できます。デフォルトは ``INFO`` です。 + +.. ``--help`` + Show usage of the program. + +``--help`` + 利用方法についての説明を表示します。 + +.. ``--version`` + Show the version number of the program. + +``--version`` + バージョン情報を表示します。 + +.. Environment + ----------- + + ``PGDATABASE``, ``PGHOST``, ``PGPORT``, ``PGUSER`` + Default connection parameters + + This utility, like most other PostgreSQL utilities, also uses the + environment variables supported by libpq (see `Environment Variables`__). + + .. __: http://www.postgresql.jp/document/current/html/libpq-envars.html + +環境変数 +--------- + +``PGDATABASE``, ``PGHOST``, ``PGPORT``, ``PGUSER`` + 接続パラメータのデフォルト値として利用されます。 + +　　また、このユーティリティは、他のほとんどの PostgreSQL ユーティリティと同様、libpq でサポートされる環境変数を使用します。詳細については、 `環境変数`__ の項目を参照してください。 + + .. __: http://www.postgresql.jp/document/current/html/libpq-envars.html + +.. Examples + -------- + + Perform an online CLUSTER of all the clustered tables in the database + ``test``, and perform an online VACUUM FULL of all the non-clustered tables:: + + $ pg_repack test + + Perform an online VACUUM FULL on the tables ``foo`` and ``bar`` in the + database ``test`` (an eventual cluster index is ignored):: + + $ pg_repack --no-order --table foo --table bar test + + Move all indexes of table ``foo`` to tablespace ``tbs``:: + + $ pg_repack -d test --table foo --only-indexes --tablespace tbs + + Move the specified index to tablespace ``tbs``:: + + $ pg_repack -d test --index idx --tablespace tbs + +利用例 +------- + +以下のコマンドは、 ``test`` データベースのクラスタ可能なテーブル全てに対してオンラインCLUSTERを行い、その他のテーブルに対してオンラインVACUUM FULLを行います。:: + + $ pg_repack test + +``test`` データベースの ``foo`` テーブルと ``bar`` テーブルに対してオンラインVACUUM FULLを実行するには、以下のようにします。 :: + + $ pg_repack --no-order --table foo --table bar test + +``foo`` テーブルのインデックス全てをテーブル空間 ``tbs`` に移動するには、以下のようにします。 :: + + $ pg_repack -d test --table foo --only-indexes --tablespace tbs + +インデックス ``idx`` をテーブル空間 ``tbs`` に移動するには、以下のようにします。 :: + + $ pg_repack -d test --index idx --tablespace tbs + +.. Diagnostics + ----------- + +トラブルシューティング +---------------------- + +.. Error messages are reported when pg_repack fails. The following list shows the + cause of errors. + + You need to cleanup by hand after fatal errors. To cleanup, just remove + pg_repack from the database and install it again: for PostgreSQL 9.1 and + following execute ``DROP EXTENSION pg_repack CASCADE`` in the database where + the error occurred, followed by ``CREATE EXTENSION pg_repack``; for previous + version load the script ``$SHAREDIR/contrib/uninstall_pg_repack.sql`` into the + database where the error occured and then load + ``$SHAREDIR/contrib/pg_repack.sql`` again. + +pg_repackが失敗した場合、エラーメッセージが表示されます。 +エラーの原因について以下に列記します。 + +FATALエラーが発生した場合、手動でクリーンアップを行う必要があります。 +クリーンアップするには、pg_repackをデータベースから一度削除し、再度登録するだけです。 +PostgreSQL 9.1以降では、 ``DROP EXTENSION pg_repack CASCADE`` をエラーが起きた +データベースで実行し、続いて ``CREATE EXTENSION pg_repack`` を実行します。 +これより古いバージョンの場合、 ``$SHAREDIR/contrib/uninstall_pg_repack.sql`` +スクリプトをエラーが起きたデータベースに対して実行し、その後 +``$SHAREDIR/contrib/pg_repack.sql`` を同様に実行します。 + +.. INFO: database "db" skipped: pg_repack VER is not installed in the database + pg_repack is not installed in the database when the ``--all`` option is + specified. + + Create the pg_repack extension in the database. + +.. class:: diag + +INFO: database "db" skipped: pg_repack VER is not installed in the database + ``--all`` オプション指定時に、pg_repackがインストールされていない + データベースに対して表示されます。 + + 該当のデータベースに対してpg_repackをインストールしてください。 + +.. ERROR: pg_repack VER is not installed in the database + pg_repack is not installed in the database specified by ``--dbname``. + + Create the pg_repack extension in the database. + +.. class:: diag + +ERROR: pg_repack VER is not installed in the database + ``--dbname`` オプション指定時に、指定したデータベースにpg_repackが + インストールされていない場合に表示されます。 + + 該当のデータベースに対してpg_repackをインストールしてください。 + +.. ERROR: program 'pg_repack V1' does not match database library 'pg_repack V2' + There is a mismatch between the ``pg_repack`` binary and the database + library (``.so`` or ``.dll``). + + The mismatch could be due to the wrong binary in the ``$PATH`` or the + wrong database being addressed. Check the program directory and the + database; if they are what expected you may need to repeat pg_repack + installation. + +.. class:: diag + +ERROR: program 'pg_repack V1' does not match database library 'pg_repack V2' + There is a mismatch between the ``pg_repack`` binary and the database + library (``.so`` or ``.dll``). + + データベースに登録されたpg_repackがバージョン2系であるのに、クライアント側 + コマンドのpg_repackのバージョンが1系である場合に表示されます。 + ``$PATH`` に誤ったpg_repackのバイナリを指定していたり、接続先のデータベースが + 間違っている可能性があります。pg_repackプログラムがインストールされた + ディレクトリとデータベースを確認してください。それらが適切である場合、 + pg_repackを再インストールしてください。 + +.. ERROR: extension 'pg_repack V1' required, found extension 'pg_repack V2' + The SQL extension found in the database does not match the version + required by the pg_repack program. + + You should drop the extension from the database and reload it as described + in the installation_ section. + +.. class:: diag + +ERROR: extension 'pg_repack V1' required, found extension 'pg_repack V2' + クライアント側のpg_repackがバージョン1系であるのに、データベース側に + 登録されたpg_repackがバージョン2系の場合に表示されます。 + 当該データベースからpg_repackを削除し、 `インストール`_ に従って + 再登録してください。 + +.. ERROR: relation "table" must have a primary key or not-null unique keys + The target table doesn't have a PRIMARY KEY or any UNIQUE constraints + defined. + + Define a PRIMARY KEY or a UNIQUE constraint on the table. + +.. class:: diag + +ERROR: relation "table" must have a primary key or not-null unique keys + 対象のテーブルが主キーもしくはNOT NULLなユニーク制約を持っていない場合に表示されます。 + 主キーもしくはユニーク制約を定義してください。 + +.. ERROR: query failed: ERROR: column "col" does not exist + The target table doesn't have columns specified by ``--order-by`` option. + + Specify existing columns. + +.. class:: diag + +ERROR: query failed: ERROR: column "col" does not exist + 対象のテーブルが ``--order-by`` オプションで指定したカラムを持っていない場合に表示されます。 + 存在しているカラムを指定してください。 + +.. WARNING: the table "tbl" already has a trigger called z_repack_trigger + The trigger was probably installed during a previous attempt to run + pg_repack on the table which was interrupted and for some reason failed + to clean up the temporary objects. + + You can remove all the temporary objects by dropping and re-creating the + extension: see the installation_ section for the details. + +.. class:: diag + +WARNING: the table "tbl" already has a trigger called z_repack_trigger + 以前に実行したが何らかの理由で中断したか、あるいは失敗したpg_repackコマンドにより、 + 対象テーブルにpg_repackが利用するトリガが残存している場合に表示されます。 + pg_repackを一度削除して、再度登録することで、こうした一時オブジェクトを削除できます。 + `インストール`_ を参照してください。 + +.. WARNING: trigger "trg" conflicting on table "tbl" + The target table has a trigger whose name follows ``z_repack_trigger`` + in alphabetical order. + + The ``z_repack_trigger`` should be the last BEFORE trigger to fire. + Please rename your trigger so that it sorts alphabetically before + pg_repack's one; you can use:: + + ALTER TRIGGER zzz_my_trigger ON sometable RENAME TO yyy_my_trigger; + +.. class:: diag + +WARNING: trigger "trg" conflicting on table "tbl" + 対象のテーブルが、pg_repackが利用する ``z_repack_trigger`` という名前のトリガ + よりもアルファベット順で後ろになるような名前のトリガを持っている場合に表示されます。 + ``z_repack_trigger`` トリガは最後に実行されるBEFOREトリガになる必要があります。 + 該当のトリガ名称を変更してください。:: + + ALTER TRIGGER zzz_my_trigger ON sometable RENAME TO yyy_my_trigger; + +.. ERROR: Another pg_repack command may be running on the table. Please try again + later. + + There is a chance of deadlock when two concurrent pg_repack commands are run + on the same table. So, try to run the command after some time. + +.. class:: diag + +ERROR: Another pg_repack command may be running on the table. Please try again + 同じテーブルに複数のpg_repackが同時に実行されている場合に表示されます。 + これはデッドロックを引き起こす可能性があるため、片方のpg_repackが終了するのを + 待って再度実行してください。 + +.. WARNING: Cannot create index "schema"."index_xxxxx", already exists + DETAIL: An invalid index may have been left behind by a previous pg_repack on + the table which was interrupted. Please use DROP INDEX "schema"."index_xxxxx" + to remove this index and try again. + + A temporary index apparently created by pg_repack has been left behind, and + we do not want to risk dropping this index ourselves. If the index was in + fact created by an old pg_repack job which didn't get cleaned up, you + should just use DROP INDEX and try the repack command again. + +.. class:: diag + +WARNING: Cannot create index "schema"."index_xxxxx", already exists +DETAIL: An invalid index may have been left behind by a previous pg_repack +on the table which was interrupted. Please use DROP INDEX "schema"."index_xxxxx" +to remove this index and try again. + + 以前に実行したが何らかの理由で中断したか、あるいは失敗したpg_repackコマンドにより、 + pg_repackが利用する一時的なインデックスが残存している場合に表示されます。 + DROP INDEXコマンドにより該当のインデックスを削除して、pg_repackを再実行してください。 + + +.. Restrictions + ------------ + + pg_repack comes with the following restrictions. + +制約 +----- + +pg_repackには以下の制約があります。 + +.. Temp tables + ^^^^^^^^^^^ + + pg_repack cannot reorganize temp tables. + +一時テーブル +^^^^^^^^^^^^ + +pg_repackは一時テーブルは再編成できません。 + +.. GiST indexes + ^^^^^^^^^^^^ + + pg_repack cannot reorganize tables using GiST indexes. + +GiSTインデックス +^^^^^^^^^^^^^^^^ + +pg_repackはGiSTインデックスを使ってテーブルを再編成することはできません。 + +.. DDL commands + ^^^^^^^^^^^^ + + You will not be able to perform DDL commands of the target table(s) **except** + VACUUM or ANALYZE while pg_repack is working. pg_repack will hold an + ACCESS SHARE lock on the target table during a full-table repack, to enforce + this restriction. + + If you are using version 1.1.8 or earlier, you must not attempt to perform any + DDL commands on the target table(s) while pg_repack is running. In many cases + pg_repack would fail and rollback correctly, but there were some cases in these + earlier versions which could result in data corruption. + +DDLコマンド +^^^^^^^^^^^^ + +pg_repackを実行している間、VACUUMもしくはANALYZE以外のDDLコマンドを対象の +テーブルに対して実行することはできません。何故ならば、pg_repackは +ACCESS SHAREロックを対象テーブルに対して保持しつづけるからです。 + +バージョン1.1.8もしくはそれ以前のバージョンを使っている場合、あらゆるDDL +コマンドをpg_repackが走っているテーブルに対して実行することができません。 +大抵はpg_repackが失敗してロールバックが適切に行われますが、古いバージョンでは +いくつかのケースでデータ不整合を引き起こす可能性があります。 + +.. Details + ------- + +動作詳細 +--------- + +.. Full Table Repacks + ^^^^^^^^^^^^^^^^^^ + + To perform a full-table repack, pg_repack will: + + 1. create a log table to record changes made to the original table + 2. add a trigger onto the original table, logging INSERTs, UPDATEs and DELETEs into our log table + 3. create a new table containing all the rows in the old table + 4. build indexes on this new table + 5. apply all changes which have accrued in the log table to the new table + 6. swap the tables, including indexes and toast tables, using the system catalogs + 7. drop the original table + + pg_repack will only hold an ACCESS EXCLUSIVE lock for a short period during + initial setup (steps 1 and 2 above) and during the final swap-and-drop phase + (steps 6 and 7). For the rest of its time, pg_repack only needs + to hold an ACCESS SHARE lock on the original table, meaning INSERTs, UPDATEs, + and DELETEs may proceed as usual. + +テーブル再編成 +^^^^^^^^^^^^^^^ + +テーブル全体を再編成する場合、pg_repackは以下のように動作します: + +1. 対象のテーブルに対して実行される変更を記録するためのログテーブルを作成します +2. 対象のテーブルに、INSERT、UPDATE、DELETEが行われた際にログテーブルに変更内容を記録するトリガを追加します +3. 対象テーブルに含まれるレコードを元に、新しいテーブルを指定した編成順でレコードを並ばせながら作成します +4. 新しいテーブルに対してインデックスを作成します +5. 再編成中に行われた元のテーブルに対する変更内容をログテーブルから取り出し、新しいテーブルに反映します +6. システムカタログを更新し、元のテーブルと新しいテーブルを入れ替えます。インデックスやトーストテーブルも入れ替えます +7. 元のテーブルを削除します + +pg_repackは上の手順の中で、始めの1.と2.の時点、および最後の6.と7.の時点で対象のテーブルに対する +ACCESS EXCLUSIVEロックを取得します。その他のステップでは、ACCESS SHAREロックを必要とするだけなので、 +元のテーブルに対するINSERT, UPDATE, DELETE操作は通常通りに実行されます。 + +.. Index Only Repacks + ^^^^^^^^^^^^^^^^^^ + + To perform an index-only repack, pg_repack will: + + 1. create new indexes on the table using CONCURRENTLY matching the definitions of the old indexes + 2. swap out the old for the new indexes in the catalogs + 3. drop the old indexes + + Creating indexes concurrently comes with a few caveats, please see `the documentation`__ for details. + + .. __: http://www.postgresql.jp/document/current/html/sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY + +インデックスのみの再編成 +^^^^^^^^^^^^^^^^^^^^^^^^^ + +インデックスのみ再編成する場合、pg_repackは以下のように動作します: + +1. 元のインデックス定義に添って、新しいインデックスをCONCURRENTLYオプションを利用して作成します +2. システムカタログを更新し、元のインデックスと新しいインデックスを入れ替えます +3. 元のインデックスを削除します + +インデックス作成のCONCURRENTLYオプションにはいくつかの注意点があります。 +詳細は、 `PostgreSQLドキュメント`__ を参照してください。 + + .. __: http://www.postgresql.jp/document/current/html/sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY + + +.. Releases + -------- + +リリースノート +--------------- + +.. * pg_repack 1.3.1 +.. * Added support for PostgreSQL 9.4. + +* pg_repack 1.3.1 + + * PostgreSQL 9.4をサポートしました + + +.. * pg_repack 1.3 +.. * Added ``--schema`` to repack only the specified schema (issue #20). +.. * Added ``--dry-run`` to do a dry run (issue #21). +.. * Fixed advisory locking for >2B OID values (issue #30). +.. * Avoid possible deadlock when other sessions lock a to-be-repacked + table (issue #32). +.. * Performance improvement for performing sql_pop DELETEs many-at-a-time. +.. * Attempt to avoid pg_repack taking forever when dealing with a + constant heavy stream of changes to a table. + +* pg_repack 1.3 + + * 特定のスキーマのみを再編成対象とする ``--schema`` オプションを追加しました ( issue #20) + * ドライランのための ``--dry-run`` オプションを追加しました (issue #21) + * 勧告的ロックを取得する際のOIDの扱いを修正しました (issue #30) + * 再編成予定のテーブルに対して別のセッションたロックを保持している場合にデッドロックが起きないように修正しました (issue #32) + * 一度に複数のDELETE操作をsql_popで取り扱う際の性能を改善しました + * 常に高負荷の更新が行われているテーブルに対する再編成処理が終わらない事象が起きないように修正しました + +.. * pg_repack 1.2 + + * Support PostgreSQL 9.3. + * Added ``--tablespace`` and ``--moveidx`` options to perform online + SET TABLESPACE. + * Added ``--index`` to repack the specified index only. + * Added ``--only-indexes`` to repack only the indexes of the specified table + * Added ``--jobs`` option for parallel operation. + * Don't require ``--no-order`` to perform a VACUUM FULL on non-clustered + tables (pg_repack issue #6). + * Don't wait for locks held in other databases (pg_repack issue #11). + * Bugfix: correctly handle key indexes with options such as DESC, NULL + FIRST/LAST, COLLATE (pg_repack issue #3). + * Fixed data corruption bug on delete (pg_repack issue #23). + * More helpful program output and error messages. + +* pg_repack 1.2 + + * PostgreSQL 9.3をサポートしました + * オンラインSET TABLESPACE文に相当する処理を行うためのオプション ``--tablespace``, ``--moveidx`` を追加しました + * 特定のインデックスのみを再編成するためのオプション ``--index`` を追加しました + * 特定のテーブルのインデックスをまとめて再編成するオプション ``--only-indexes`` を追加しました + * 並列実行のためのオプション ``--jobs`` を追加しました + * クラスタキーを持たないテーブルに対してVACUUM FULL相当の処理を行うために ``--no-order`` オプションを明示的に指定しなくてもよいようにしました (pg_repack issue #6) + * 他のデータベースにおけるロックを待たないようにしました (pg_repack issue #11) + * バグ修正: DESC, NULL FIRST/LAST, COLLATEを持つインデックスキーを正しく取り扱えるように修正しました (pg_repack issue #3) + * 同時に行われる削除操作によってデータ破壊が起こる可能性があったため修正しました (pg_repack issue #23) + * 出力メッセージとエラーメッセージを改善しました + +.. * pg_repack 1.1.8 + + * Added support for PostgreSQL 9.2. + * Added support for CREATE EXTENSION on PostgreSQL 9.1 and following. + * Give user feedback while waiting for transactions to finish (pg_reorg + issue #5). + * Bugfix: Allow running on newly promoted streaming replication slaves + (pg_reorg issue #1). + * Bugfix: Fix interaction between pg_repack and Slony 2.0/2.1 (pg_reorg + issue #4) + * Bugfix: Properly escape column names (pg_reorg issue #6). + * Bugfix: Avoid recreating invalid indexes, or choosing them as key + (pg_reorg issue #9). + * Bugfix: Never choose a partial index as primary key (pg_reorg issue #22). + +* pg_repack 1.1.8 + + * PostgreSQL 9.2をサポートしました + * PostgreSQL 9.1およびそれ以降のバージョンでCREATE EXTENSIONによるインストールが行えるようにしました + * 他のトランザクションの終了を待っていることをユーザに通知するようにしました (pg_reorg issue #5) + * バグ修正: ストリーミングレプリケーション構成において、新たにマスタに昇格したサーバ上で動作するように修正しました (pg_reorg issue #1) + * バグ修正: pg_repackとSlony 2.0/2.1が競合しないように修正しました (pg_reorg issue #4) + * バグ修正: カラム名を適切にエスケープするように修正しました (pg_reorg issue #6) + * バグ修正: invalidなインデックスを再編成の対象としたり、クラスタキーとして扱うことがないように修正しました (pg_reorg issue #9) + * バグ修正: 部分インデックスを主キーとして選択しないように修正しました (pg_reorg issue #22) + +.. * pg_reorg 1.1.7 (2011-08-07) + + * Bugfix: VIEWs and FUNCTIONs could be corrupted that used a reorganized + table which has a dropped column. + * Supports PostgreSQL 9.1 and 9.2dev. (but EXTENSION is not yet) + +* pg_reorg 1.1.7 (2011-08-07) + + * バグ修正: 削除されたカラムを持つテーブルを再編成した際に、そのテーブルに対するビューや関数が壊れないように修正しました + * PostgreSQL 9.1および9.2devをサポートしました (EXTENSIONはまだサポートしていません) + +.. See Also + -------- + +関連項目 +-------- + +* `clusterdb `__ +* `vacuumdb `__ +