SYNOPSIS
COPY tablename [ ( column [, ...] ) ]
FROM { 'filename' | STDIN }
[ [ WITH ]
[ BINARY ]
[ OIDS ]
[ DELIMITER [ AS ] 'delimiter' ]
[ NULL [ AS ] 'null string' ] ]
COPY tablename [ ( column [, ...] ) ]
TO { 'filename' | STDOUT }
[ [ WITH ]
[ BINARY ]
[ OIDS ]
[ DELIMITER [ AS ] 'delimiter' ]
[ NULL [ AS ] 'null string' ] ]
DESCRIPTION Description
COPY between PostgreSQL tables and standard file system to exchange data. COPY TO all the contents of a table are copied to a file, and COPY FROM copied from one document to a data table (table of contents to the additional data that already exists in).
If you declare a field list, COPY will copy the data only in the fields declared between files and tables. If the table has any field, not in the list of fields, then COPY FROM will insert the default values for those fields.
COPY with a file name indicating the PostgreSQL server directly read and write data from the file. If you declare a file name, the file server must be visible, and the file name must be specified in terms of the server. If the statement is STDIN or STDOUT, the flow of data between the client and the server by connecting the front end.
PARAMETERS Parameters
- tablename
-
The name of an existing table (schema-qualified). - column
-
The optional field list to be copied. If no column list all the fields will be used. - filename
-
Absolute pathname of the input or output file. - STDIN
-
That input comes from the client application. - STDOUT
-
That output goes to the client application. - BINARY
-
Read and stored in binary format, rather than text. In binary mode, and can not be declared DELIMITERS NULL. - OIDS
-
Statement for each row inside the copy object identifier (OID). (If the table that does not OID declares OIDS option, then throw an error.) - delimiter
-
For a single character that separates each field in each row in the file. The default is horizontal tab. (Tab) - null string
-
A string of NULL values representative. The default is \ N (backslash -N). Of course, you can pick yourself an empty string.- Note: Note: For COPY FROM, any matches this string will be stored as a NULL value, so you should make sure you use the same string and COPY TO.
NOTES Note
COPY can only be used for tables, not with views.
BINARY keyword will force binary objects rather than as text storage / read all the data. To do so faster than traditional copy command to a certain extent, but a binary copy of the file in the plant is not very good among different machine architectures.
Any data you want to COPY TO out must have permission to select data into the data table for any insert to COPY FROM must have permission.
COPY command inside the file must be read directly by the server or writing a file, rather than by the client application to read and write. Therefore, they must be located on the database server or database server can be accessed, rather than by the client to do these things. They must be PostgreSQL user (user server running ID) may have access to and can read or write, not the client. COPY naming a file is only allowed to database superusers, since it allows reading or writing any server has access to the file.
Do not confuse COPY and psql instruction \ Copy . \ copy call COPY FROM STDIN or COPY TO STDOUT, and then the data fetch / store to file a psql client can access. Thus, using \ copy when the file access by the client rather than the server-side decision.
We recommend always using COPY absolute path in the file name. In COPY TO when the conduct is enforced by the server, but for COPY FROM, you do have the option of reading from a statement by a relative path for the file. The path will be interpreted relative to the working directory of the server (where the data directory), not the client's working directory.
COPY FROM will invoke any triggers and check constraints. However, the rules will not be activated.
COPY stopped at the first error to. These should not lead to problems in the COPY TO, but in the COPY FROM destination table will already have received earlier rows, the lines will not be visible or accessible, but still occupy disk space. If you happen to be a large copy of the data file, then accumulated, these things may occupy a large part of the disk space. You can invoke VACUUM to recover disk space.
FILE FORMATS File Format
Text format TEXT FORMAT
When used without the BINARY option, use COPY, read and write the file is a text file, each row in the table represents a row. Row column (field) separated by delimiters. The attribute values themselves are strings generated by the output function associated with each field type, either string acceptable input function. Using specific data string represented by a null value of that field is NULL. If any line of the input file contains less than expected or the field, then COPY FROM will throw an error. If you declare OIDS, then the OID as the first field read and write, in front of all user fields.
End of line data can be used only contains a backslash and a period (\.) Representation. If the data read from the file, then the end of data marker is not necessary, because the end of the file's role on the good; but before the 3.0 client protocol, the copy if the data between the client application, then you must have a closing tag.
Backslash character (\) may be used in the COPY to those characters will be ambiguous escape (otherwise those characters will be as row or column delimiters). In particular, the following characters if it is part of a field value must be preceded by a backslash: backslash itself, line feed, carriage return, and the current delimiter.
It is declared null string COPY TO without adding any backslashes; contrast, relatively COPY FROM before removing backslashes with empty input string. Thus, like \ empty string and not the actual data values such N \ confusion between the N (which would be represented as \\ N).
COPY FROM recognition sequence following special backslash:
-
\ B backspace (ASCII 8)
\ F feed (ASCII 12)
\ N newline (ASCII 10)
\ R carriage return (ASCII 13)
\ T Tab (ASCII 9)
\ V vertical tabulator (ASCII 11)
\ Digits (backslash followed by three octal value represents a character specified value)
Currently, COPY TO will never emit an octal backslash sequence, but it does use the other characters listed above for control characters.
Never put a backslash character in a data N or period (.) In front. Such combinations will be mistaken for each empty string (\.) Or the data end tag (\ N). In addition a backslash character is not listed in the above table is its own.
It is strongly recommended that applications generating COPY eight line breaks and carriage returns data are converted into \ n and \ r sequences. At present we can represent a data carriage return, and with a backslash and a newline represent a data newline by a backslash and a carriage return. However, such a representation might not be accepted by default 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).
COPY TO Jiangzai end of each line is a Unix-style newline ( "\ n"), or with ( "\ r \ n") on the server that runs on MS Windows tag line termination, but only for COPY to a server file; for consistency across platforms, COPY tO STDOUT always sends "\ n", no matter what server platform yes. COPY FROM that can be treated with a carriage return or line feed, carriage return or line feed as the end of the line data. In order to reduce the escape of a new line does not appear in the data or an error caused by the transport, if the end of the input line, unlike the above symbols, COPY FROM warns.
BINARY FORMAT binary format
COPY BINARY in PostgreSQL 7.4 in file formats do change. The new format consists of a file header, zero or more tuples, and a file trailer. Header and data are now in network byte order.
FILE HEADER header
File header consists of 15 bytes of fixed fields, followed by a variable-length header extension area. The fixed fields are:
- Signature Signature
- 11- byte sequence PGCOPY \ n \ 377 \ r \ n \ 0 --- Note that the zero byte is part of the signature is required. (The signature is designed to allow us to easily see whether a file has been a non-8-bit converter ruined. The signature will be the end of the line conversion filters, dropped zero bytes, dropped high bits, or parity is changed.)
- Flags field flag field
-
32-bit integer mask to denote important aspects of the file format. Bits are numbered from 0 (LSB) to 31 (MSB) encoded --- Note that this field is stored in network order (high byte first), as are all the integer. Bit 16--31 are reserved to denote critical file format information; if readers find a bit do not know appear in this range, then it should quit. Bits 0-15 are reserved as a symbol format backward compatible; readers may ignore any unexpected bits within this range. Currently only we define a flag, while others must be zero:-
- Bit 16
-
If 1, then the OID included in the data; if 0, then no
- Header extension length range
-
32-bit integer, in bytes remaining length of the header, excluding itself. At present, it is zero, followed by the first tuple. Future changes to the format will allow additional data to appear in the header. Readers should ignore any header extension data it does not know how to handle.
The header extension is a reserved sequence of a custom data block for use. This flag field is not intended to tell readers what the extension area yes. The specific design of header extension contents is left for future versions use.
This design allows for backwards-compatible header additions (add header extension chunks, or set low-order flag bits) and non-backwards compatible with modified (set the high flag bit to identify such changes, and add support to the extension area of data required).
TUPLES tuple
Each tuple in the beginning of a 16-bit integer count, this count is the number of fields in the tuple. (Currently, all tuples in a table have the same count, but may not always be true.) Then, repeated for each field in the tuple back, a first field word length of 32 bits, followed so long the field data. (Length word does not include themselves, and may be zero.) As a special case: -1 indicates a NULL field value. In NULL case No value bytes.
No alignment padding or any other extra data between fields.
Currently, all data values in a COPY BINARY file are assumed to be in binary format (format code one). Expected future extension may add a header field that allows per-column format codes.
To determine the appropriate binary format actual tuple data you should PostgreSQL source, in particular the field data type * send and * recv function (typically these functions in the source code of the src / backend / utils / adt / directory turn up).
If you include the OID in the file, the OID field immediately follows the field-count word. It is a common field, but it is not included in the count field. But it has a length word --- This allows us not to spend too much effort can handle 4 bytes and 8 bytes OID, and if a guy is allowed OID is optional, then it can also display the OID into air.
FILE TRAILER end of file
File trailer consists of a 16-bit integer numbers 1. This makes it easy to distinguish field-count from a tuple.
If a field-count word is neither -1 nor the expected number of columns, then the reader should report an error. This provides an extra check for missing data synchronization.
EXAMPLES Examples
The following example copies a table to the client, using the vertical bar (|) as the field delimiter:
COPY country TO STDOUT WITH DELIMITER '|';
Copy data from a Unix file into a country table:
COPY country FROM '/usr1/proj/bray/sql/country_data';
Here is an example from STDIN can be copied into the data table:
AF AFGHANISTAN AL ALBANIA DZ ALGERIA ZM ZAMBIA ZW ZIMBABWE
Note that each line in the blank here is actually a horizontal tab tab.
The following data are the same, the output in binary form on a Linux / i586 machine. These data were obtained with the Unix utility od -c After filtration output. The table has three fields; first is char (2), a second text, and the third is integer. All the rows third field is a null value.
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
COMPATIBILITY The
No COPY statement in the SQL standard.
7.3 previous applications use the following syntax still supported:
COPY [ BINARY ] tablename [ WITH OIDS ]
FROM { 'filename' | STDIN }
[ [USING] DELIMITERS 'delimiter' ]
[ WITH NULL AS 'null string' ]
COPY [ BINARY ] tablename [ WITH OIDS ]
TO { 'filename' | STDOUT }
[ [USING] DELIMITERS 'delimiter' ]
[ WITH NULL AS 'null string' ]