描述

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

請注意，每行上的空格實際上是一個製表符。

以下是相同的資料，以二進位制格式輸出。資料經過 Unix 工具 od -c 過濾後顯示。該表有三列；第一列型別為 char(2)，第二列型別為 text，第三列型別為 integer。所有行在第三列中都有一個 null 值。

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' ]

另請參閱