使用 \COPY 從本機電腦上傳資料

\COPY 這個指令就是讓你可以直接從你自己的電腦把資料丟進 PostgreSQL。跟 COPY 不一樣，COPY 只能用伺服器上的檔案，但 \COPY 是直接用你電腦上的檔案，像是你的筆電或桌機。

當你要用本機電腦上的檔案時，就該用 \COPY。COPY 只能讀伺服器上的檔案，\COPY 則可以直接用你手邊的資料。

這超適合你在自己電腦上開發或測試專案，或是你根本沒辦法碰到 PostgreSQL 伺服器的檔案系統。這種方式在開發者跟分析師之間超紅，因為要驗證 CSV 檔案內容時超方便，不用搞一堆有的沒的。

COPY 跟 \COPY 的差異

乍看之下 COPY 跟 \COPY 很像，但其實運作方式差很多：

• COPY 是在伺服器端執行，檔案必須放在 PostgreSQL 能存取的資料夾裡，還要 PostgreSQL 有讀取權限。

• \COPY 是在客戶端執行，也就是檔案要在你用的 client app（像 psql）那邊。用 \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：表示檔案第一行是欄位名稱。

範例：

假設你有個 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 來的資料。你可以這樣查：

SELECT * FROM students;

預期結果：

\COPY 指令的參數

用 \COPY（尤其是 CSV 格式）時，有幾個重要參數可以幫你控制資料格式，讓處理更順手。下面是最常用的幾個。

FORMAT 參數

決定資料格式。最常用的就是 text 跟 csv。

範例：

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

為什麼要用： 沒這個參數 PostgreSQL 會以為你用的是 tab 分隔的純文字。csv 比較通用也比較好讀。

HEADER 參數

表示 CSV 檔案第一行是欄位名稱，不是資料。

範例：

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

為什麼要用： 可以讓你匯入時自動跳過標題列，特別是從 Excel 或其他系統匯出的時候超有用。

DELIMITER 參數

設定欄位分隔符號。CSV 預設是逗號，TEXT 預設是 tab。

範例：

\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 是 PostgreSQL 的 client，支援 \COPY 指令。記得一定要用 psql 來操作資料庫。有些 client（像 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. 超簡單。 一行指令就能上傳資料，不用把檔案搬到伺服器。

2. 超通用。 psql 幾乎所有主流作業系統都能用，\COPY 到哪都能跑。

3. 不用擔心權限問題。 因為是在 client 端跑，不用管伺服器檔案權限。

限制跟建議

雖然很方便，\COPY 還是有一些限制：

• 不適合超大檔案，因為資料要從 client 傳到 server，這樣會拖慢速度。這種情況建議直接在 server 用 COPY。
• 記得檔案要先準備好：錯誤修正、不要有多餘的行，結構要跟表格一樣。

如果是大專案，建議先用小檔案測試，沒問題再上傳整個檔案。