PostgreSQLでCOPY進行状況をリアルタイムに監視する方法

Last updated at 2025-07-09Posted at 2025-07-09

はじめに

大量のデータを扱うバッチ処理やメンテナンス作業において、PostgreSQLのCOPYコマンドは非常に強力な味方です。しかし、1億件を超えるようなレコードのインポート処理ともなると、完了までに時間がかかり、サーバーのリソースも大きく消費します。

「今、どれくらい終わってるの？」

「もう少し待てば終わるの？中断すべき？」

そんな不安を解消する方法として、COPY処理の進捗状況をリアルタイムで可視化する手法を紹介します。

対象読者：

PostgreSQLを業務利用しているエンジニア
大量データのインポート/エクスポートに苦労している方
COPYコマンドの裏側をもう少し深掘りしたい方

背景と目的

XD.GROWTHでは、日次200TB以上のビッグデータをオンプレで処理しています。データ基盤としてPostgreSQLの拡張である Citus¹ を使っており、バルクインポートやバックアップ処理にはCOPYコマンドを日常的に使っています。

特に、メンテナンスやデータ移行のタイミングでは、1億件以上のレコードをCOPYすることも少なくありません。ですが、COPY中の進捗が見えないと…

本当に進んでいるのか不安になる
終わる見込みが立たない
トラブル時の判断が遅れる

こうした問題を解消するため、PostgreSQLのシステムビュー pg_stat_progress_copy を使って進捗を可視化する仕組みを導入しました。

進捗を確認するSQL

PostgreSQLでは、進行中のCOPY処理の進捗情報を確認できる専用ビュー pg_stat_progress_copy が用意されています。

以下のSQLを定期的に実行することで、現在進行中のCOPY処理の状況を把握できます。

SELECT
    cpy.pid,
    cpy.datname,
    cls.relname,
    cpy.command,
    cpy.type,
    cpy.tuples_processed
FROM pg_stat_progress_copy AS cpy
INNER JOIN pg_class AS cls ON (
    cls.oid = cpy.relid
);

出力イメージ

  pid   | datname |          relname           |  command  | type | tuples_processed
--------+---------+----------------------------+-----------+------+------------------
 456765 | test_db | session_action_202505      | COPY FROM | PIPE |          5301153
 403052 | test_db | session_measurement_202501 | COPY FROM | PIPE |         12131618
(2 rows)

各項目の意味

カラム名	意味	備考
`pid`	プロセスID
`datname`	データベース名
`relname`	テーブル名
`command`	実行中のコマンド	`COPY FROM`または`COPY TO`
`type`	入出力種別	`FILE`、`PROGRAM`、`PIPE`
`tuples_processed`	処理済み件数	途中まで取り込んだレコード数

COPY FROM → データインポート
COPY TO → データエクスポート
type が PIPE の場合、stdin/stdout を使用した処理です

実用的な使い方：`watch`コマンドで定期確認

SQLを毎回手動で実行するのは手間がかかります。

そこで便利なのが watchコマンド。Linux環境であれば、これを使うことで一定間隔で自動的に進捗をチェックできます。

以下のコマンドをターミナルで実行すれば、5秒ごとに最新のCOPY進捗が表示されます。

watch -n 5 'PGPASSWORD={パスワード} psql {DB名} -U {ユーザー名} -h {DBホスト名}   -c "SELECT
      cpy.pid,
      cpy.datname,
      cls.relname,
      cpy.command,
      cpy.type,
      cpy.tuples_processed
    FROM pg_stat_progress_copy AS cpy
    INNER JOIN pg_class AS cls ON (
      cls.oid = cpy.relid
    );"'

※環境変数でパスワードを設定するのが気になる場合は、.pgpassを使った方法も検討してください。

おわりに

PostgreSQLには、COPY処理の進捗だけでなく、以下のような他の内部処理の進行状況も確認できる仕組みがあります。

pg_stat_progress_vacuum（VACUUMの進捗）
pg_stat_progress_analyze（ANALYZEの進捗）
pg_stat_progress_cluster（CLUSTERの進捗）
pg_stat_progress_create_index（インデックス作成の進捗）

これらを活用することで、長時間処理の見通しが立ちやすくなり、メンテナンスの品質と安心感が大きく向上します。

詳しくは公式ドキュメントをご参照ください。

👉 PostgreSQL Progress Reporting