說明

COPY 在 PostgreSQL 表格和標準檔案系統檔案之間移動資料。COPY TO 將表格的內容複製到檔案，而 COPY FROM 將資料從檔案複製自表格（將資料附加到表格中已有的內容）。COPY TO 也可以複製 SELECT 查詢的結果。

如果指定了欄位清單，則 COPY TO 僅將指定欄位中的資料複製到檔案。對於 COPY FROM，檔案中的每個欄位會依序插入到指定的欄位中。未在 COPY FROM 欄位清單中指定的表格欄位將收到它們的預設值。

使用檔案名稱的 COPY 指示 PostgreSQL 伺服器直接從檔案讀取或寫入檔案。該檔案必須可由 PostgreSQL 使用者（伺服器執行的使用者 ID）存取，且名稱必須從伺服器的角度指定。當指定 PROGRAM 時，伺服器會執行給定的指令，並從程式的標準輸出讀取，或寫入程式的標準輸入。該指令必須從伺服器的角度指定，並且可由 PostgreSQL 使用者執行。當指定 STDIN 或 STDOUT 時，資料會透過用戶端和伺服器之間的連線傳輸。

每個執行 COPY 的後端都將在 pg_stat_progress_copy 檢視表中報告其進度。詳情請參閱 第 27.4.3 節。

預設情況下，如果在處理過程中遇到錯誤，COPY 將會失敗。對於需要盡最大努力載入整個檔案的使用案例，可以使用 ON_ERROR 子句來指定一些其他的行為。

參數

輸出

成功完成後，COPY 指令會傳回以下形式的指令標籤

COPY count

此 count 為複製的列數。

注意事項

COPY TO 只能用於一般資料表，不能用於檢視表，且不會複製子資料表或子分割區的列。例如，COPY table TO 複製的列與 SELECT * FROM ONLY table 相同。語法 COPY (SELECT * FROM table) TO ... 可用於轉儲繼承階層、分割資料表或檢視表中的所有列。

COPY FROM 可以用於一般、外部或分割資料表，或具有 INSTEAD OF INSERT 觸發器的檢視表。

您必須對 COPY TO 讀取其值的資料表擁有 SELECT 權限，以及對 COPY FROM 將值插入的資料表擁有 INSERT 權限。只要對指令中列出的欄位擁有欄位權限即可。

如果資料表啟用了列級安全，則相關的 SELECT 策略將應用於 COPY table TO 陳述式。目前，對於具有列級安全的資料表，不支援 COPY FROM。請改用等效的 INSERT 陳述式。

COPY 指令中指定名稱的檔案由伺服器直接讀取或寫入，而不是由客戶端應用程式讀取或寫入。因此，它們必須位於或可由資料庫伺服器機器存取，而不是客戶端。它們必須可由 PostgreSQL 使用者（伺服器執行的使用者 ID）存取和讀取或寫入，而不是客戶端。同樣地，使用 PROGRAM 指定的指令會直接由伺服器執行，而不是由客戶端應用程式執行，且必須可由 PostgreSQL 使用者執行。COPY 指定檔案或指令僅允許資料庫超級使用者或被授予角色 pg_read_server_files、pg_write_server_files 或 pg_execute_server_program 的使用者使用，因為它允許讀取或寫入伺服器有權存取的任何檔案或執行程式。

不要將 COPY 與 psql 指令 \copy 混淆。\copy 會呼叫 COPY FROM STDIN 或 COPY TO STDOUT，然後在 psql 客戶端可存取的檔案中提取/儲存資料。因此，當使用 \copy 時，檔案可存取性和存取權限取決於客戶端而不是伺服器。

建議 COPY 中使用的檔名始終指定為絕對路徑。在 COPY TO 的情況下，伺服器會強制執行此操作，但對於 COPY FROM，您可以選擇從相對路徑指定的檔案中讀取。該路徑將相對於伺服器進程的工作目錄（通常是叢集的資料目錄）進行解釋，而不是客戶端的工作目錄。

使用 PROGRAM 執行指令可能會受到作業系統存取控制機制（例如 SELinux）的限制。

COPY FROM 將會呼叫目標資料表上的任何觸發器和檢查約束。但是，它不會呼叫規則。

對於識別欄位，COPY FROM 指令將始終寫入輸入資料中提供的欄位值，就像 INSERT 選項 OVERRIDING SYSTEM VALUE 一樣。

COPY 的輸入和輸出會受到 DateStyle 的影響。為了確保可移植到可能使用非預設 DateStyle 設定的其他 PostgreSQL 安裝，在使用 COPY TO 之前，應將 DateStyle 設定為 ISO。避免使用將 IntervalStyle 設定為 sql_standard 轉儲資料也是一個好主意，因為負的間隔值可能會被具有不同 IntervalStyle 設定的伺服器誤解。

輸入資料根據 ENCODING 選項或目前的客戶端編碼進行解釋，輸出資料以 ENCODING 或目前的客戶端編碼進行編碼，即使資料沒有通過客戶端，而是由伺服器直接讀取或寫入檔案。

COPY FROM 指令會在進行過程中將輸入列實際插入到資料表中。如果指令失敗，這些列將處於已刪除狀態；這些列將不可見，但仍會佔用磁碟空間。如果失敗發生在大型複製操作中，這可能會浪費大量的磁碟空間。應使用 VACUUM 來恢復浪費的空間。

FORCE_NULL 和 FORCE_NOT_NULL 可以同時用於同一欄位。這會導致將帶引號的 null 字串轉換為 null 值，並將未帶引號的 null 字串轉換為空字串。

檔案格式

範例

以下範例使用垂直線 (|) 作為欄位分隔符號，將資料表複製到客戶端

COPY country TO STDOUT (DELIMITER '|');

將資料從檔案複製到 country 資料表中

COPY country FROM '/usr1/proj/bray/sql/country_data';

僅將名稱以 'A' 開頭的國家複製到檔案中

COPY (SELECT * FROM country WHERE country_name LIKE 'A%') TO '/usr1/proj/bray/sql/a_list_countries.copy';

要複製到壓縮檔案，您可以透過外部壓縮程式將輸出導向

COPY country TO PROGRAM 'gzip > /usr1/proj/bray/sql/country_data.gz';

以下是一些適合從 STDIN 複製到資料表中的資料範例

AF      AFGHANISTAN
AL      ALBANIA
DZ      ALGERIA
ZM      ZAMBIA
ZW      ZIMBABWE

請注意，每一行上的空白實際上是一個 Tab 字元。

以下是以二進位格式輸出的相同資料。資料是在透過 Unix 實用程式 od -c 篩選後顯示的。該資料表有三個欄位；第一個欄位的類型為 char(2)，第二個欄位的類型為 text，第三個欄位的類型為 integer。所有列在第三個欄位中都有一個空值。

0000000   P   G   C   O   P   Y  \n 377  \r  \n  \0  \0  \0  \0  \0  \0
0000020  \0  \0  \0  \0 003  \0  \0  \0 002   A   F  \0  \0  \0 013   A
0000040   F   G   H   A   N   I   S   T   A   N 377 377 377 377  \0 003
0000060  \0  \0  \0 002   A   L  \0  \0  \0 007   A   L   B   A   N   I
0000100   A 377 377 377 377  \0 003  \0  \0  \0 002   D   Z  \0  \0  \0
0000120 007   A   L   G   E   R   I   A 377 377 377 377  \0 003  \0  \0
0000140  \0 002   Z   M  \0  \0  \0 006   Z   A   M   B   I   A 377 377
0000160 377 377  \0 003  \0  \0  \0 002   Z   W  \0  \0  \0  \b   Z   I
0000200   M   B   A   B   W   E 377 377 377 377 377 377

相容性

SQL 標準中沒有 COPY 陳述式。

以下語法在 PostgreSQL 9.0 版之前使用，並且仍然支援

COPY table_name [ ( column_name [, ...] ) ]
    FROM { 'filename' | STDIN }
    [ [ WITH ]
          [ BINARY ]
          [ DELIMITER [ AS ] 'delimiter_character' ]
          [ NULL [ AS ] 'null_string' ]
          [ CSV [ HEADER ]
                [ QUOTE [ AS ] 'quote_character' ]
                [ ESCAPE [ AS ] 'escape_character' ]
                [ FORCE NOT NULL column_name [, ...] ] ] ]

COPY { table_name [ ( column_name [, ...] ) ] | ( query ) }
    TO { 'filename' | STDOUT }
    [ [ WITH ]
          [ BINARY ]
          [ DELIMITER [ AS ] 'delimiter_character' ]
          [ NULL [ AS ] 'null_string' ]
          [ CSV [ HEADER ]
                [ QUOTE [ AS ] 'quote_character' ]
                [ ESCAPE [ AS ] 'escape_character' ]
                [ FORCE QUOTE { column_name [, ...] | * } ] ] ]

請注意，在此語法中，BINARY 和 CSV 被視為獨立的關鍵字，而不是 FORMAT 選項的參數。

以下語法在 PostgreSQL 7.3 版之前使用，並且仍然支援

COPY [ BINARY ] table_name
    FROM { 'filename' | STDIN }
    [ [USING] DELIMITERS 'delimiter_character' ]
    [ WITH NULL AS 'null_string' ]

COPY [ BINARY ] table_name
    TO { 'filename' | STDOUT }
    [ [USING] DELIMITERS 'delimiter_character' ]
    [ WITH NULL AS 'null_string' ]

另請參閱