?
本文檔使用 PHP中文網(wǎng)手冊 發(fā)布
COPY table_name [ ( column [, ...] ) ]
FROM { 'filename' | STDIN }
[ [ WITH ] ( option [, ...] ) ]
COPY { table_name [ ( column [, ...] ) ] | ( query ) }
TO { 'filename' | STDOUT }
[ [ WITH ] ( option [, ...] ) ]
where option can be one of:
FORMAT format_name
OIDS [ boolean ]
DELIMITER 'delimiter_character'
NULL 'null_string'
HEADER [ boolean ]
QUOTE 'quote_character'
ESCAPE 'escape_character'
FORCE_QUOTE { ( column [, ...] ) | * }
FORCE_NOT_NULL ( column [, ...] )
COPY在表和文件之間交換數(shù)據(jù)。COPY TO 把一個表的所有內(nèi)容都拷貝到一個文件,而COPY FROM從一個文件 里拷貝數(shù)據(jù)到一個表里(把數(shù)據(jù)附加到表中已經(jīng)存在的內(nèi)容里)。COPY TO 還能拷貝SELECT查詢的結(jié)果。
如果聲明了一個字段列表,COPY將只在文件和表之間拷貝已聲明字段的數(shù)據(jù)。 如果表中有任何不在字段列表里的字段,那么COPY FROM將為那些字段插入缺省值。
帶文件名的COPY指示PostgreSQL服務(wù)器直接 從文件中讀寫數(shù)據(jù)。如果聲明了文件名,那么服務(wù)器必須可以訪問該文件,而且文件名必須從 服務(wù)器的角度聲明。如果指定了STDIN或STDOUT,那么 數(shù)據(jù)將在客戶前端和服務(wù)器之間流動。
現(xiàn)存表的名字(可以有模式修飾)。
可選的待拷貝字段列表。如果沒有聲明字段列表,那么將使用所有字段。
一個必須用圓括弧包圍的SELECT或VALUES 命令,其結(jié)果將被拷貝。
輸入或輸出文件的絕對路徑。Windows用戶可能需要使用E''字符串 和雙反斜線作為路徑名稱。
聲明輸入是來自客戶端應(yīng)用。
聲明輸入前往客戶端應(yīng)用。
聲明選的選項是否應(yīng)該被開啟或者關(guān)閉。您可以寫 TRUE, ON, 或者1來啟用這個選項,并且用FALSE, OFF,或者0 來關(guān)閉它。 boolean值也可以被省略,此時 假定為TRUE。
選擇被讀或者寫的數(shù)據(jù)格式: text, csv(逗號分隔值), 或者binary。 默認是text。
聲明為每行拷貝內(nèi)部對象標識(OID)。如果為一個 query拷貝或者沒有OID的 表聲明了OIDS選項,則拋出一個錯誤。
指定分隔每一行(排)中的列的字符。默認是文本格式的制表符,CSV格式的逗號。 必須有一個獨立的一字節(jié)的字符。 在使用binary格式時這個選項是不允許的。
This option is not allowed when using binary format. 聲明代表一個空值的字符串。默認是文本格式的\N (backslash-N), CSV格式的一個未被引用的空字符串。即使是文本格式您可能也更偏向于空串, 例如您不想從空字符串中區(qū)分空值。
Note: 在使用COPY FROM的時候,任何匹配這個字符串的字符串將 被存儲為NULL值,所以你應(yīng)該確保你用的字符串和COPY TO相同。
聲明文件包含一個帶有文件中每列名稱的標題行。在輸出時,第一行包含表中的列名, 在輸入時,第一行是被忽略的。該選項僅僅在使用CSV格式時是允許的。
在數(shù)值被引用后指定要使用的引用字符。默認的是雙引號。這一定是一個1字節(jié)的字符。 該選項僅僅在使用CSV格式時允許。
聲明應(yīng)該出現(xiàn)在一個匹配QUOTE值的數(shù)據(jù)字符之前的字符。 默認與QUOTE值相同(所以若它出現(xiàn)在數(shù)據(jù)中,則引用字符是翻一倍)。 這一定是一個1字節(jié)的字符。該選項只有在使用CSV格式時允許。
強制引用在每個指定列的所有非空值。空輸出從不被引用。 如果聲明了*,非空值將在所有列中被引用。這個選項僅僅在 COPY TO中并且僅僅在使用CSV格式時允許。
默認情況下空字符串是空的,這意味著空值將會被讀作長度為零的字符串而不是空值, 即使當他們不被引用。這個選項僅僅在COPY FROM中并且僅僅在使用 CSV 格式時允許。
成功完成時,COPY按照如下格式返回一個命令標簽:
COPY count
其中的count是拷貝的行數(shù)。
COPY只能用于表,不能用于視圖。當然也可以用于 COPY (SELECT * FROM viewname) TO ...。
COPY僅僅處理命名了的特定表;它將不復(fù)制數(shù)據(jù)到子表或從子表 中復(fù)制數(shù)據(jù)。因此比如COPY table TO 顯示與SELECT * FROM ONLY table 相同的數(shù)據(jù)。但是COPY (SELECT * FROM table) TO ... 可以用于轉(zhuǎn)儲在繼承層次結(jié)構(gòu)的所有數(shù)據(jù)。
你對任何要COPY TO出來的數(shù)據(jù)必須有選取數(shù)據(jù)的權(quán)限, 對任何要COPY FROM入數(shù)據(jù)的表必須有插入權(quán)限。 對列在命令中的列擁有列權(quán)限是足夠的。
COPY命令里面的文件必須是由服務(wù)器直接讀或?qū)懙奈募? 而不是由客戶端應(yīng)用讀寫。因此,它們必須位于數(shù)據(jù)庫服務(wù)器上或者可以被數(shù)據(jù)庫 服務(wù)器所訪問,這些事情不應(yīng)該由客戶端來做。它們必須被運行 PostgreSQL服務(wù)器的用戶可讀或?qū)懀? 而不是客戶端。只允許數(shù)據(jù)庫超級用戶COPY一個文件, 因為它允許讀寫任意服務(wù)器有權(quán)限訪問的文件。
不要混淆COPY和psql的 \copy指令。\copy調(diào)用 COPY FROM STDIN或COPY TO STDOUT,然后把數(shù)據(jù)抓取/存儲到一個psql 客戶端可以訪問的文件中。因此,使用\copy的時候,文件訪問 權(quán)限是由客戶端而不是服務(wù)器端決定的。
建議在COPY里的文件名字總是使用絕對路徑。 在COPY TO的時候是由服務(wù)器強制進行的,但是對于 COPY FROM,你的確可從一個相對路徑的文件里讀取。 該路徑將解釋為相對于服務(wù)器的工作目錄(通常是數(shù)據(jù)目錄),而不是客戶 端的工作目錄。
COPY FROM會激活所有觸發(fā)器和檢查約束。不過,不會激活規(guī)則。
COPY輸入和輸出被DateStyle影響。 為了和其它PostgreSQL安裝移植(它們可能是非缺省 DateStyle設(shè)置),應(yīng)該在使用COPY TO前把 DateStyle設(shè)置為ISO。 通過將IntervalStyle設(shè)置為sql_standard來避免轉(zhuǎn)儲數(shù)據(jù) 也是一個好主意。因為負的區(qū)間值可能會被對IntervalStyle有不同設(shè)置的 服務(wù)器誤解。
Input data is interpreted according to the current client encoding, and output data is encoded in the current client encoding, even if the data does not pass through the client but is read from or written to a file directly by the server. 輸入數(shù)據(jù)通過當前客戶機編碼來解譯,輸出數(shù)據(jù)被編碼為當前客戶機編碼, 即使數(shù)據(jù)不經(jīng)過客戶端的,仍會通過服務(wù)器直接將數(shù)據(jù)從文件中讀出或者寫入到文件中去。
COPY在第一個錯誤處停下來。這些在COPY TO 中不應(yīng)該導(dǎo)致問題,但在COPY FROM時目標表會已經(jīng)接收到早先的行, 這些行將不可見或不可訪問,但是仍然會占據(jù)磁盤空間。如果你碰巧拷貝大塊數(shù)據(jù)文件的話, 這些東西積累起來可能會占據(jù)相當大的磁盤空間。你可以調(diào)用VACUUM 來恢復(fù)那些磁盤空間。
當使用text格式時,讀寫的文件是一個文本文件,每行代表表中一個行。 行中的列(字段)用分隔符分開。字段值本身是由與每個字段類型相關(guān)的輸出函數(shù)生成的字符串, 或者是輸入函數(shù)可接受的字符串。數(shù)據(jù)中使用特定的NULL字符串表示那些值為NULL的字段。 如果輸入文件的任意行包含比預(yù)期多或者少的字段,那么COPY FROM將拋出 一個錯誤。如果聲明了OIDS,那么OID將作為第一個字段讀寫,放在所有 用戶字段前面。
數(shù)據(jù)的結(jié)束可以用一個只包含反斜杠和句點(\.)的行表示。如果從文件中讀取數(shù)據(jù), 那么數(shù)據(jù)結(jié)束的標記是不必要的,因為文件結(jié)束起的作用就很好了;但是在3.0之前的客戶端協(xié)議里, 如果在客戶端應(yīng)用之間拷貝數(shù)據(jù),那么必須要有結(jié)束標記。
Backslash characters (\) can be used in the COPY data to quote data characters that might otherwise be taken as row or column delimiters. In particular, the following characters must be preceded by a backslash if they appear as part of a column value: backslash itself, newline, carriage return, and the current delimiter character. 反斜杠字符 (\)可以用于COPY數(shù)據(jù),來引用那些 否則會被當作行或列分隔符的數(shù)據(jù)字符。尤其,以下字符若以一列值的一部分出現(xiàn)則 必須在前面加上反斜杠:反斜杠、換行符、回車以及當前的分隔符字符。 反斜杠字符(\)可以用在COPY里給那些會有歧義的字符進行逃逸(否則那些字符會被當做行或者字段分隔符處理)。 特別是下面的字符如果是字段值的一部分時,必須前綴一個反斜杠:反斜杠本身、換行符、回車符、當前分隔符。
聲明的空字符串被COPY TO不加任何反斜杠發(fā)送;與之相對, COPY FROM在刪除反斜杠之前拿它的輸入與空字符串比較。因此, 像\N這樣的空字符串不會和實際數(shù)據(jù)值\N 之間混淆(因為后者會表現(xiàn)成\\N)。
COPY FROM能夠識別下列特殊反斜杠序列:
序列 | 含義 |
---|---|
\b | 反斜杠 (ASCII 8) |
\f | 進紙(ASCII 12) |
\n | 換行符(ASCII 10) |
\r | 回車符(ASCII 13) |
\t | 水平制表符(ASCII 9) |
\v | 垂直制表符(ASCII 11) |
\digits | 反斜杠后面跟著一到三個八進制數(shù),表示ASCII值為該數(shù)的字符 |
\xdigits | 反斜杠x后面跟著一個或兩個十六進制位聲明指定數(shù)值編碼的字符 |
任何其他未在上表中提及的斜字符將會用來表示其本身。然而,沒必要謹防添加反斜杠。 因為這可能意外地生成一個匹配數(shù)據(jù)結(jié)束標記(\.)或者空字符串 (默認為\N)的字符串。這些字符串將在任何其他反斜杠處理做完之前確認。 任何上表列出之外的其它反斜杠逃役字符將使用其字面含義。因此要小心添加不必要的反斜杠, 因為這樣做可能會生成一個含有數(shù)據(jù)結(jié)束標志(\.) 的字符串或NULL(默認為\N)。這些字符串將在識別任何其它反斜杠逃逸之前被識別。
It is strongly recommended that applications generating COPY data convert data newlines and carriage returns to the \n and \r sequences respectively. At present it is possible to represent a data carriage return by a backslash and carriage return, and to represent a data newline by a backslash and newline. However, these representations might not be accepted in future releases. They are also highly vulnerable to corruption if the COPY file is transferred across different machines (for example, from Unix to Windows or vice versa). 強烈建議產(chǎn)生COPY數(shù)據(jù)的應(yīng)用程序?qū)?shù)據(jù)換行符和回車分別轉(zhuǎn)換為 \n和\r序列。目前,可以由反斜杠和回車代表一個數(shù)據(jù)回車, 并且由反斜杠和換行符代表一個數(shù)據(jù)換行。然而,這些表示法在將來的版本中可能無法接受。 它們也非常容易收到破壞,若COPY文件在不同機器之間轉(zhuǎn)移(例如:從Unix 系統(tǒng)移到Windows系統(tǒng),或者反過來)。 強烈建議生成COPY數(shù)據(jù)的應(yīng)用把換行符和回車分別轉(zhuǎn)換成 \n和\r序列。目前可以用一個反斜杠和一個回車表示一個數(shù)據(jù)回車, 以及用一個反斜杠和一個換行符表示一個數(shù)據(jù)換行符。不過,這樣的表示在將來的版本中 可能不會被接受。并且,如果在不同機器之間傳遞COPY文件, 也非常容易出錯(比如在Unix和Windows之間)。
COPY TO將在每行的結(jié)尾用一個換行符(Unix上是"\n", Windows上是"\r\n")標記一行終止,但只是用于COPY到服務(wù)器 文件里;為了在不同平臺之間一致,COPY TO STDOUT總是發(fā)送"\n" 而不管服務(wù)器平臺是什么。COPY FROM可以處理那些以回車符、換行符、回車 換行符作為行結(jié)束的數(shù)據(jù)。為了減少在數(shù)據(jù)中出現(xiàn)的未逃逸的新行或者回車導(dǎo)致的錯誤,如果輸入 的行結(jié)尾不像上面這些符號,COPY FROM會發(fā)出警告。
這個格式用于輸入和輸出逗號分隔數(shù)值(CSV)文件格式,許多其它程序都用這個文件 格式,比如電子報表。這個模式下生成并識別逗號分隔的CSV逃逸機制,而不是使用 PostgreSQL標準文本模式的逃逸。
每條記錄的值都是用DELIMITER字符分隔的。如果數(shù)值本身包含分隔字符、 QUOTE字符、NULL字符串、回車符、換行符, 那么整個數(shù)值用QUOTE字符前綴和后綴(包圍),并且數(shù)值里任何 QUOTE字符或ESCAPE字符都前導(dǎo)逃逸字符。你也可以使用 FORCE_QUOTE在輸出非NULL的指定字段值時強制引號包圍。
CSV格式?jīng)]有標準的辦法區(qū)分一個NULL值和一個空字符串。 PostgreSQL的COPY通過引號包圍來處理這些。一個當作 NULL輸出的NULL參數(shù)值是沒有引號包圍的,而匹配非 NULL字符串的參數(shù)值是用引號包圍的。比如,使用缺省設(shè)置時, 一個NULL是寫做一個無引號包圍的空字符串,而一個空字符串數(shù)值寫做 雙引號包圍("")。讀取數(shù)值也遵循類似的規(guī)則。 你可以使用FORCE_NOT_NULL來避免為特定字段進行NULL比較。
因為對于CSV格式而言,反斜杠不是特殊字符,數(shù)據(jù)的結(jié)束標志(\.) 可以作為數(shù)據(jù)值出現(xiàn)。為了避免任何可能的歧意,一個單獨的\. 數(shù)據(jù)值在輸出中將被自動使用引號包圍;在輸入中,如果被引號界定,那么將不會當作數(shù)據(jù) 結(jié)束標志。如果你要加載其它程序創(chuàng)建的、有未用引號界定字段的文件,并且其中含有 \.值,你就必須用引號進行界定。
Note: 在CSV模式下,所有字符都是有效的。一個被空白包圍的引號界定數(shù)值,或者任何 非DELIMITER字符,都會被包含這些字符。如果你從會給CSV行填充 空白的系統(tǒng)里導(dǎo)入數(shù)據(jù)到定長字段,那么可能會導(dǎo)致錯誤。如果出現(xiàn)這種情況,你可能需要先 處理一下CSV文件,刪除結(jié)尾空白,然后再向PostgreSQL里導(dǎo)入數(shù)據(jù)。
Note: CSV模式可以識別和生成引號包圍的回車和換行的CVS文件。 因此這些文件并不像文本模式的文件那樣嚴格地每條記錄一行。
Note: 許多程序生成奇怪的并且有時候不正確的CVS文件,所以這個文件格式更像一種慣用格式,而不是一種標準。 因此你可能碰到一些不能使用這個機制輸入的文件,而COPY也可能生成一些其它程序不能處理的文件。
binary形式的選項會使得所有的數(shù)據(jù)被存儲/讀作二進制格式而不是文本。 這比文本和CSV格式的要快一些,但是一個二進制格式文件在機器架構(gòu)和 PostgreSQL版本之間的可移植性比較差。 另外,二進制格式是特定數(shù)據(jù)格式表的;例如,不能從smallint列中輸出二進制數(shù)據(jù) 并將二進制數(shù)據(jù)讀入integer列,盡管在文本格式下那會運行良好。
binary文件格式包含一個文件頭,0或更多包含行數(shù)據(jù)的元組,以及 一個尾文件。頭和數(shù)據(jù)按照網(wǎng)絡(luò)字節(jié)順序。
Note: PostgreSQL releases before 7.4 used a different binary file format. 7.4之前的PostgreSQL版本使用的是不同的 二進制文件格式。
文件頭由15個字節(jié)的固定域組成,后面跟著一個變長的頭擴展區(qū)。固定域是:
11-byte sequence PGCOPY\n\377\r\n\0 — note that the zero byte is a required part of the signature. (The signature is designed to allow easy identification of files that have been munged by a non-8-bit-clean transfer. This signature will be changed by end-of-line-translation filters, dropped zero bytes, dropped high bits, or parity changes.) 11字節(jié)的序列PGCOPY\n\377\r\n\0(請注意字節(jié)零是簽名必須的一部分)。 使用這個簽名是為了能夠很容易看出文件是否已經(jīng)被一個非8位安全的轉(zhuǎn)換器給破壞了。 這個簽名會被行尾轉(zhuǎn)換過濾器、刪除字節(jié)零、刪除高位、奇偶變化而改變。
32位整數(shù)掩碼表示該文件格式的重要方面。位是從 0(LSB)到 31(MSB) 編碼的,請注意這個域是以網(wǎng)絡(luò)字節(jié)順序存儲的(高位在前),后繼的整數(shù)都是如此。位16-31是 保留用做關(guān)鍵文件格式信息的;如果閱讀器發(fā)現(xiàn)一個不認識的位出現(xiàn)在這個范圍內(nèi),那么它應(yīng)該退出。 位0-15都保留為標志向后兼容的格式使用;閱讀器可以忽略這個范圍內(nèi)的不認識的位。目前只定義了 一個標志位,而其它的必須是零:
如果為1,那么在數(shù)據(jù)中包括了OIDS;如果為0,則沒有。
32位整數(shù),以字節(jié)計的頭剩余長度,不包括自身。目前,它是零,后面緊跟第一條記錄行。 對該格式的更多修改都將允許額外的數(shù)據(jù)出現(xiàn)在頭中。閱讀器應(yīng)該忽略任何它不知道該如 何處理的頭擴展數(shù)據(jù)。
頭擴展數(shù)據(jù)用來保存自定義數(shù)據(jù)序列塊。這個標志域無意告訴閱讀器擴展區(qū)的內(nèi)容是什么。 頭擴展的具體設(shè)計內(nèi)容留給以后的版本使用。
這樣設(shè)計就允許向后兼容的頭擴展(增加頭擴展塊或設(shè)置低位序標志位)以及非向后兼容 的修改(設(shè)置高位標志位以標識這樣的修改,并且根據(jù)需要向擴展區(qū)域增加支持數(shù)據(jù))。
每條行都以一個16位整數(shù)計數(shù)開頭,該計數(shù)是行中字段的數(shù)目(目前,在一個表里的每行都 有相同的計數(shù),但可能不會永遠這樣)。然后后面不斷出現(xiàn)行中的各個字段,字段先是一個32位 的長度字,后面跟著那么長的字段數(shù)據(jù)。長度字并不包括自己,并且可以為零。一個特例是:-1表示 一個NULL字段值。在NULL情況下,后面不會跟著數(shù)值字節(jié)。
在數(shù)據(jù)域之間沒有對齊填充或者任何其它額外的數(shù)據(jù)。
目前,一個二進制格式文件里的所有數(shù)據(jù)值都假設(shè)是二進制格式的(格式代碼為一)。預(yù)計將來的 擴展可能增加一個頭域,允許為每個字段聲明格式代碼。
為了判斷實際行數(shù)據(jù)的正確二進制格式,你應(yīng)該閱讀PostgreSQL
源代碼,特別是該字段數(shù)據(jù)類型的*send
和*recv
函數(shù)(典型的函數(shù)
可以在源代碼的src/backend/utils/adt/目錄找到)。
如果在文件中包括了OIDs,那么該OID域立即跟在字段計數(shù)字后面。它是一個普通的字段, 只不過它沒有包括在字段計數(shù)。但它包括長度字,這樣就允許方便的處理4字節(jié)和8字節(jié)的OIDs, 并且如果某個家伙允許OIDs是可選的話,那么還可以把OIDs顯示成空。
文件尾包括保存著-1的一個16位整數(shù)字。這樣就很容易與一條行的域計數(shù)字相區(qū)分。
如果一個域計數(shù)字既不是-1也不是預(yù)期的字段的數(shù)目,那么閱讀器應(yīng)該報錯。這樣就 提供了對丟失與數(shù)據(jù)同步的額外檢查。
下面的例子把一個表拷貝到客戶端,使用豎直條(|)作為域分隔符:
COPY country TO STDOUT (DELIMITER '|');
從文件中拷貝數(shù)據(jù)到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';
下面是一個可以從STDIN中拷貝數(shù)據(jù)到表中的例子:
AF AFGHANISTAN AL ALBANIA DZ ALGERIA ZM ZAMBIA ZW ZIMBABWE
注意,每行里的空白實際上是一個水平制表符。
下面的是同樣的數(shù)據(jù),以二進制形式輸出。這些數(shù)據(jù)是用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語句。
PostgreSQL9.0以前使用下面的語法,現(xiàn)在仍然支持:
COPY table_name [ ( column [, ...] ) ] FROM { 'filename' | STDIN } [ [ WITH ] [ BINARY ] [ OIDS ] [ DELIMITER [ AS ] 'delimiter' ] [ NULL [ AS ] 'null string' ] [ CSV [ HEADER ] [ QUOTE [ AS ] 'quote' ] [ ESCAPE [ AS ] 'escape' ] [ FORCE NOT NULL column [, ...] ] ] ] COPY { table_name [ ( column [, ...] ) ] | ( query ) } TO { 'filename' | STDOUT } [ [ WITH ] [ BINARY ] [ OIDS ] [ DELIMITER [ AS ] 'delimiter' ] [ NULL [ AS ] 'null string' ] [ CSV [ HEADER ] [ QUOTE [ AS ] 'quote' ] [ ESCAPE [ AS ] 'escape' ] [ FORCE QUOTE { column [, ...] | * } ] ] ]
請注意:在這個語法中,BINARY和CSV是作為獨立的關(guān)鍵字, 而不是作為FORMAT選項的一個參數(shù)。
PostgreSQL7.3以前使用下面的語法,現(xiàn)在仍然支持:
COPY [ BINARY ] table_name [ WITH OIDS ] FROM { 'filename' | STDIN } [ [USING] DELIMITERS 'delimiter' ] [ WITH NULL AS 'null string' ] COPY [ BINARY ] table_name [ WITH OIDS ] TO { 'filename' | STDOUT } [ [USING] DELIMITERS 'delimiter' ] [ WITH NULL AS 'null string' ]