Index: doc/src/sgml/ref/copy.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql-server/doc/src/sgml/ref/copy.sgml,v
retrieving revision 1.55
diff -c -r1.55 copy.sgml
*** doc/src/sgml/ref/copy.sgml 13 Dec 2003 23:59:07 -0000 1.55
--- doc/src/sgml/ref/copy.sgml 10 Apr 2004 16:22:23 -0000
***************
*** 136,142 ****
Specifies copying the OID for each row. (An error is raised if
OIDS is specified for a table that does not
! have OIDs.)
--- 136,143 ----
Specifies copying the OID for each row. (An error is raised if
OIDS is specified for a table that does not
! have OIDs, or if CSV mode is selected by specifying
! DELIMITER longer then one character.)
***************
*** 145,152 ****
delimiter
! The single character that separates columns within each row
! (line) of the file. The default is a tab character.
--- 146,162 ----
delimiter
! A one- to three-character string containing characters used in importing
! or exporting Text or Comma Separated Variable (CSV) files.
! With only one character, Text file format is used.
! If there are two or three characters, CSV format is used.
! The first character for either file format is the delimiter character
! used between values for a single row.
! The second character is the CSV quote character,
! and the third character, if present, is the CSV escape character
! used inside quoted values, and defaults to the quote character.
! The default for this parameter is a single tab character. (Thus TEXT
! file mode is the default.)
***************
*** 156,163 ****
The string that represents a null value. The default is
! \N (backslash-N). You might prefer an empty
! string, for example.
--- 166,174 ----
The string that represents a null value. The default is
! \N (backslash-N), unless a CSV is being processed,
! in which case it is an empty string. You might prefer an empty string
! in any case.
***************
*** 168,173 ****
--- 179,197 ----
COPY TO.
+
+
+
+ If you don't want anything used as null when using
+ COPY FROM, you can specify some value that is very
+ unlikely to appear in the file, such as frobnitz or
+ d5f4074b254c76cd8ae37bf1731f4aed (which is
+ md5('frobnitz')). This could be especially useful
+ when importing a CSV file into a table with NOT NULL
+ columns.
+
+
+
***************
*** 252,259 ****
Text Format
! When COPY is used without the BINARY option,
! the data read or written is a text file with one line per table row.
Columns in a row are separated by the delimiter character.
The column values themselves are strings generated by the
output function, or acceptable to the input function, of each
--- 276,285 ----
Text Format
! When COPY is used without the BINARY
! option, the data read or written is a text file with one line per table
! row unless DELIMITER is longer than one character,
! in which case CSV format is used.
Columns in a row are separated by the delimiter character.
The column values themselves are strings generated by the
output function, or acceptable to the input function, of each
***************
*** 380,385 ****
--- 406,459 ----
+ CSV format
+
+
+ This format is used for importing from and exporting to the Comma
+ Separated Variable (CSV) file format used by many other programs,
+ such as spreadsheets. Instead of escaping in
+ PostgreSQL's standard text mode, it produces
+ and recognises the common CSV escaping mechanism.
+
+
+
+ The values in each record are separated by the delimiter character, which
+ is the first character in the DELIMITER parameter.
+ If the value contains the delimiter character, the quote character (the
+ second character in the DELIMITER parameter), or a
+ carriage return or line feed character, then the whole value is prefixed
+ and suffixed by the quote character, and any occurrence within the value
+ of a quote character or the escape character (the third character in the
+ DELIMITER parameter if present, or else just the quote
+ character itself) is preceded by the escape character.
+
+
+
+ In the most common cases, simply specifying DELIMITER ',"'
+ or DELIMITER ',\'' should suffice, both for
+ COPY FROM and COPY TO.
+
+
+
+
+ CSV mode will both recognise and produce CSV files with quoted values
+ containing embedded carriage returns and line feeds. Thus the files are
+ not strictly one line per table row, as TEXT files are.
+
+
+
+
+
+ Many programs produce strange and occasionally perverse CSV files, and
+ the file format is a convention rather than a standard. Thus you might
+ encounter some files that cannot be imported using this mechanism, and
+ you might produce files that other programs fail to recognise properly.
+
+
+
+
+
+
Binary Format
***************
*** 532,537 ****
--- 606,620 ----
using the vertical bar (|) as the field delimiter:
COPY country TO STDOUT WITH DELIMITER '|';
+
+
+
+
+ To do the same thing but instead produce a standard CSV file, using
+ , as the delimiter and " as both the quote and
+ escape characters:
+
+ COPY country TO STDOUT WITH DELIMITER ',"';