ローカルパソコンからデータをロードするための \COPY の使い方

\COPYコマンドは、自分のローカルパソコンから直接PostgreSQLにデータをロードするためのものだよ。 COPYはPostgreSQLサーバー上のファイルとやりとりするけど、 \COPYはクライアント側、つまり自分のノートPCやデスクトップにあるファイルを使うんだ。

\COPYは、ローカルパソコン（たとえばノートPC）上のファイルを扱うときに使うよ。 COPYはサーバー上のファイルを読むけど、 \COPYなら手元にあるデータをそのままアップできるんだ。

これは、自分のマシンで開発やテストをしているときや、PostgreSQLサーバーのファイルシステムにアクセスできないときに超便利。 特に、CSVファイルをサクッと検証したい開発者やアナリストに人気のやり方だよ。

COPYと\COPYの違い

一見すると COPY と \COPY は似てるけど、動き方が違うんだ：

• COPYはサーバー側で実行されて、ファイルがPostgreSQLからアクセスできるディレクトリにないとダメ。PostgreSQLがそのファイルを読む権限も必要だよ。

• \COPYはクライアント側で実行される。つまり、ファイルはクライアントアプリ（たとえばpsql）からアクセスできればOK。 \COPY を使えば、自分のパソコンにあるファイルからでもデータをアップできるし、サーバーにアクセス権がなくても大丈夫。

\COPYの基本的な使い方

コマンドの書き方：

\COPY テーブル FROM 'file_path' [WITH] (オプション)

それぞれの意味：

• テーブル: データをロードするテーブル名。
• file_path: ローカルパソコン上のファイルのパス。
• オプション: 関数の動きをカスタマイズできる追加パラメータ（省略可）。

例：

\COPY students FROM 'C:/data/students.csv' DELIMITER ',' CSV HEADER;

• students: データをロードするテーブル名。
• 'C:/data/students.csv': ローカルパソコン上のファイルパス。
• DELIMITER ',': ファイル内のデータ区切り文字（この場合カンマ）。
• CSV HEADER: ファイルの1行目がカラム名（ヘッダー）であることを指定。

例：

たとえば、students.csvという学生データのファイルがローカルフォルダ（例：C:/data/students.csv）にあるとする。 その中身はこんな感じ：

id,name,age,major
1,John Doe,20,Computer Science
2,Jane Smith,22,Mathematics
3,Emily White,21,Physics

このデータをstudentsテーブルにロードしたいとき、事前にPostgreSQLでこんなテーブルを作っておくよ：

CREATE TABLE students (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    age INTEGER NOT NULL,
    major TEXT
);

そして、\COPYコマンドでデータをロードする：

\COPY students FROM 'C:/data/students.csv' DELIMITER ',' CSV HEADER;

このコマンドを実行すると、studentsテーブルにstudents.csvの3件のデータが入るよ。 ちゃんと入ったかは、こうやって確認できる：

SELECT * FROM students;

期待される結果：

\COPYコマンドのパラメータ

\COPYを使うとき、特にCSV形式の場合は、データのフォーマットをコントロールしたり処理を楽にするための重要なパラメータがあるよ。 よく使うものを紹介するね。

FORMATパラメータ

データのフォーマットを指定する。よく使うのはtextとcsv。

例：

\COPY users FROM 'users.csv' WITH (FORMAT csv)

なぜ必要？ これを指定しないと、PostgreSQLはタブ区切りのテキスト形式だと思っちゃう。 csvのほうが汎用的で読みやすいよ。

HEADERパラメータ

CSVファイルの1行目がカラム名（ヘッダー）で、データじゃないことを指定する。

例：

\COPY users FROM 'users.csv' WITH (FORMAT csv, HEADER)

なぜ必要？ ヘッダー行をインポートから除外できる。Excelや他のシステムからエクスポートしたときに特に便利。

DELIMITERパラメータ

フィールドの区切り文字を指定する。デフォルトはCSVならカンマ、TEXTならタブ。

例：

\COPY products FROM 'products.csv' WITH (FORMAT csv, DELIMITER ';')

なぜ必要？ 変わったCSVフォーマット（ヨーロッパでよくあるセミコロン区切りなど）にも対応できるよ。

ENCODINGパラメータ

ファイルの文字コードを指定する。

例：

\COPY clients FROM 'clients.csv' WITH (FORMAT csv, HEADER, ENCODING 'WIN1251')

なぜ必要？ Windowsや他のシステムの文字コードのファイルも、手動で変換しなくても正しくロードできるよ。

NULLパラメータ

ファイル内でどの文字列をNULLとして扱うかを指定する。

例：

\COPY orders FROM 'orders.csv' WITH (FORMAT csv, NULL 'NULL')

なぜ必要？ 欠損値が'NULL'という文字列で表現されている場合、これでちゃんと空欄として認識してくれる。

\COPYの制限と注意点

1. PostgreSQLクライアントの要件

psqlは\COPYコマンドをサポートしているPostgreSQLクライアントだよ。 データベース操作にはこれを使おう。他のクライアント（たとえばpgAdmin）は\COPYをサポートしてない場合があるから注意。

2. ファイルの文字コード

ロードするファイルの文字コードに注意しよう。PostgreSQLはUTF-8を期待してる。 もしファイルが別の文字コード（例：Windows-1251）だとエラーになることも。 iconvやテキストエディタ（VS Codeなど）で変換できるよ。

3. ファイルパスのローカライズ

Windowsではファイルパスにバックスラッシュ（\）が入ってることがある。 その場合はスラッシュ（/）に変えてね。 たとえばC:\data\students.csvじゃなくてC:/data/students.csvを使おう。

よくあるエラーとその対処法

1. ファイルアクセスエラー。

こんなエラーが出たら：

could not open file "C:/data/students.csv" for reading: No such file or directory

チェックポイント：

• 指定したパスにファイルがちゃんとあるか。
• 絶対パスが正しいか。
• ファイルにアクセス権があるか。

2. データ構造の不一致エラー。 ロードするファイルの構造がテーブルと違うとエラーになるよ。 たとえば、ファイルに余計なカラムがあったり、データ型が違ったりするとエラーが出る。 ロード前にカラム名や型を確認しよう。

3. 文字コードの問題。 ファイルがUTF-8じゃないと、文字化けすることがある。 解決策は、ロード前にファイルをUTF-8に変換すること。

\COPYを使うメリット

1. シンプル。 コマンド1つでファイルからデータをロードできる。サーバーにファイルを移す必要なし。

2. 汎用性。 psqlは主要なOSで使えるから、\COPYもどこでも使えるよ。

3. アクセス権の問題なし。 クライアント側で動くから、サーバーファイルの権限を気にしなくてOK。

制限とおすすめ

便利だけど、\COPYにはいくつか制限があるよ：

• 超巨大なファイルには向いてない。クライアントとサーバー間でデータを転送するから。そういう場合はサーバーでCOPYを使ったほうが効率的。
• ファイルはロード前にちゃんと準備しておこう。エラーを直したり、余計な行を消したり、テーブルと構造が合ってるか確認しよう。

大きなプロジェクトでは、まず小さいデータセットでテストしてから本番ファイルを処理するのがおすすめだよ。