【pgAdmin 4】CSVインポート/エクスポートの地獄を終わらせる：文字コード・区切り文字の完全攻略と事前チェックリスト
テックリードの私たちが、プロジェクトの終盤やデータ移行フェーズで最も時間を奪われる瞬間――それは、CSVインポート時の「謎の文字化け」と「パースエラー」のデバッグだ。
「Excelで出力したCSVをPostgreSQLに流し込んだら、日本語がすべて『?』や豆腐になった」
「ダブルクォーテーションの囲み漏れで、数万行の途中でパースが盛大に狂い、ロールバックの嵐になった」
pgAdmin 4の「Import/Export」機能は、GUIで直感的に操作できる反面、デフォルト設定のまま安易に使うと、文字コード（Encoding）と区切り文字（Delimiter）の罠に確実にハマる。
今回は、このデータインポートの泥沼から一瞬で抜け出し、チーム全体のデータ処理速度を劇的に引き上げるための「プロの事前チェックリスト」と実践知見を授けよう。
—
1. 現場で即死する「3大トラップ」の正体
なぜ、たかがCSVの入出力でこれほどハマるのか。原因はPostgreSQLの厳格さと、OS・エディタ間のエンコーディングの不一致にある。
1. Shift-JIS / CP932 と UTF-8（BOM付き）の呪い
PostgreSQLの内部エンコーディングは基本 `UTF8` だ。しかし、日本のレガシーシステムやExcelが吐き出すCSVは `Shift-JIS`（実質CP932）であることが多い。これをそのまま流し込むと、外字や特定の記号（機種依存文字）でエンコードエラー（`invalid byte sequence for encoding “UTF8″`）が発生する。
2. 区切り文字（Delimiter）とエスケープの衝突
テキストデータ内にカンマ（`,`）や改行コードが含まれている場合、ダブルクォーテーション（`”`）で囲う必要があるが、CSV生成元のツール仕様によってエスケープ文字（`Escape`）の解釈が異なり、カラムズレを引き起こす。
3. 巨大データ（数百万行）一括投入のメモリ枯渇
pgAdminのGUI経由で巨大なCSVを無理やりインポートすると、ブラウザとサーバー間のセッションタイムアウトやメモリ溢れを引き起こす。
—
2. 【実践】文字化け・パースエラーを防ぐ事前チェックリスト
実務でCSVを扱う前に、必ず以下のチェックリストをチーム内で共有し、目視ではなくツールで状態を確定させろ。
□ [エンコード確認] 対象CSVの文字コードは「UTF-8（BOMなし）」に統一されているか？
□ [改行コード確認] 改行コードは LF（UNIX標準）になっているか？（CRLF混入の排除）
□ [区切り文字確認] カンマ以外の文字（タブ、パイプ `|` など）を使う場合、設定が一致しているか？
□ [クォーテーション確認] 文字列型カラムの囲み文字（Quote）が正しく指定されているか？
□ [NULL表現の統一] CSV内の空文字が「NULL」という文字列として扱われていないか？
事前準備：CUI（iconv）による文字コードの爆速変換
pgAdminに読み込ませる前に、Linux/Macのターミナルで文字コードと改行コードを強制変換しておくのが最も安全かつ確実だ。
Shift-JIS (CP932) のCSVを、PostgreSQL最適化済みの UTF-8 (BOMなし/LF) に一撃で変換
iconv -f CP932 -t UTF-8//TRANSLIT input.csv | tr -d ‘\r’ > cleaned_input.csv
※ `//TRANSLIT` をつけておくことで、変換不可能な文字を近似文字に置き換え、インポートエラーを未然に防げる。
—
3. pgAdmin 4 「Import/Export」ダイアログの神設定
pgAdmin 4のテーブル右クリック > 「Import/Export…」を開いた際の設定値を間違えてはならない。以下のタブ設定を死守せよ。
① 「General」タブ
- Filename: 絶対パスで指定する。パーミッションエラー（`Permission denied`）を防ぐため、PostgreSQLユーザー（通常 `postgres`）が読み書きできる領域（`/tmp` など）に一度ファイルを置くのが鉄則。
- Format: `CSV`
- Role: 該当テーブルの権限を持つロール。
② 「Options」タブ（最重要）
- Delimiter: カンマなら `,`。タブ区切りの場合は `\t` を指定。
- Quote: 基本は `”`（ダブルクォーテーション）。データ内に `”` が含まれる場合はエスケープ設定（Escape）も必ず合わせる。
- Header: CSVの1行目にカラム名がある場合は `Yes`。
- Encoding: 事前チェックで統一したエンコーディング（例: `UTF8`）を明示的に選択。「Auto」に頼るな。
—
4. チームの生産性を爆発させる設定共有化とベストプラクティス
属人化しやすいデータベースのインポート手順をコード化し、チーム全体の開発スピードを底上げする。
設定のコード化（Python / psycopg2 によるインポート自動化）
GUIでのポチポチ作業はヒューマンエラーの元だ。定常的なバッチやチーム共通のインポート処理は、Pythonスクリプトとしてリポジトリにコミットし、設定を共有せよ。
以下のベストプラクティス構成例（JSON設定ファイル ＋ インポートスクリプト）をプロジェクトに導入せよ。
`import_config.json`（設定の共通化）
{
“db”: {
“host”: “localhost”,
“port”: 5432,
“database”: “production_db”,
“user”: “app_admin”,
“password_env”: “DB_PASSWORD”
},
“import_job”: {
“table_name”: “users”,
“file_path”: “./data/cleaned_input.csv”,
“delimiter”: “,”,
“encoding”: “UTF8”,
“has_header”: true
}
}
`bulk_import.py`（実用的なインポートスクリプト）
import os
import json
import psycopg2
def load_config(config_path):
with open(config_path, ‘r’, encoding=’utf-8′) as f:
return json.load(f)
def run_import(config_file):
config = load_config(config_file)
db_conf = config[‘db’]
job_conf = config[‘import_job’]
# 環境変数からセキュアにパスワードを取得
password = os.getenv(db_conf[‘password_env’])
conn = psycopg2.connect(
host=db_conf[‘host’],
port=db_conf[‘port’],
dbname=db_conf[‘database’],
user=db_conf[‘user’],
password=password
)
cursor = conn.cursor()
# COPYコマンドによる爆速インポート（pgAdminの内部でも使われている高速手法）
# GUIのタイムアウトやメモリ溢れを完全に回避できる
with open(job_conf[‘file_path’], ‘r’, encoding=job_conf[‘encoding’]) as f:
# ヘッダーのスキップ処理
if job_conf[‘has_header’]:
next(f)
copy_sql = f”””
COPY {job_conf[‘table_name’]} FROM STDIN
WITH (FORMAT CSV, DELIMITER ‘{job_conf[‘delimiter’]}’, NULL ”);
“””
try:
cursor.copy_expert(copy_sql, f)
conn.commit()
print(f”[SUCCESS] Successfully imported into {job_conf[‘table_name’]}”)
except Exception as e:
conn.rollback()
print(f”[ERROR] Import failed: {e}”)
raise
finally:
cursor.close()
conn.close()
if __name__ == ‘__main__’:
run_import(‘import_config.json’)
—
5. 開発スピードを加速させるpgAdmin 4の隠しコマンド・ショートカット
最後に、日々のDBオペレーションでマウス操作を排除し、タイムロスをゼロにするためのキーボードショートカットを伝授する。
- Query Toolを開く: `Alt + Shift + Q` (Mac: `Cmd + Option + Q`)
- クエリの実行: `F5` または `Ctrl + R`
- エディタ内の行削除: `Ctrl + D`
- オートコンプリートの強制呼び出し: `Ctrl + Space`
GUIツールは便利だが、その裏側の挙動（PostgreSQLの `COPY` コマンドやエンコードの仕組み）を理解しているか否かで、トラブルシューティングのスピードが10倍変わる。
本記事で紹介した事前チェックリストと設定構成をチームの標準とし、無駄な文字化けデバッグの地獄から完全に脱却してほしい。