mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add a note warning that COPY BINARY is very datatype-specific.

Browse Source 
Per a complaint from Gordon Shannon.
This commit is contained in:
Tom Lane 2009-09-05 23:58:01 +00:00
parent e3b3878a08
commit a2367f89ff
1 changed files with 35 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
doc/src/sgml/ref/copy.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$PostgreSQL: pgsql/doc/src/sgml/ref/copy.sgml,v 1.86 2009/07/25 00:07:10 adunstan Exp $ $PostgreSQL: pgsql/doc/src/sgml/ref/copy.sgml,v 1.87 2009/09/05 23:58:01 tgl Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -24,30 +24,30 @@ PostgreSQL documentation
<synopsis> <synopsis>
COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ] COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ]
FROM { '<replaceable class="parameter">filename</replaceable>' | STDIN } FROM { '<replaceable class="parameter">filename</replaceable>' | STDIN }
[ [ WITH ] [ [ WITH ]
[ BINARY ] [ BINARY ]
[ OIDS ] [ OIDS ]
[ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ] [ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ]
[ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ] [ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ]
[ CSV [ HEADER ] [ CSV [ HEADER ]
[ QUOTE [ AS ] '<replaceable class="parameter">quote</replaceable>' ] [ QUOTE [ AS ] '<replaceable class="parameter">quote</replaceable>' ]
[ ESCAPE [ AS ] '<replaceable class="parameter">escape</replaceable>' ] [ ESCAPE [ AS ] '<replaceable class="parameter">escape</replaceable>' ]
[ FORCE NOT NULL <replaceable class="parameter">column</replaceable> [, ...] ] [ FORCE NOT NULL <replaceable class="parameter">column</replaceable> [, ...] ]
COPY { <replaceable class="parameter">tablename</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ] | ( <replaceable class="parameter">query</replaceable> ) } COPY { <replaceable class="parameter">tablename</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ] | ( <replaceable class="parameter">query</replaceable> ) }
TO { '<replaceable class="parameter">filename</replaceable>' | STDOUT } TO { '<replaceable class="parameter">filename</replaceable>' | STDOUT }
[ [ WITH ] [ [ WITH ]
[ BINARY ] [ BINARY ]
[ OIDS ] [ OIDS ]
[ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ] [ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ]
[ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ] [ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ]
[ CSV [ HEADER ] [ CSV [ HEADER ]
[ QUOTE [ AS ] '<replaceable class="parameter">quote</replaceable>' ] [ QUOTE [ AS ] '<replaceable class="parameter">quote</replaceable>' ]
[ ESCAPE [ AS ] '<replaceable class="parameter">escape</replaceable>' ] [ ESCAPE [ AS ] '<replaceable class="parameter">escape</replaceable>' ]
[ FORCE QUOTE { <replaceable class="parameter">column</replaceable> [, ...] | * } ] [ FORCE QUOTE { <replaceable class="parameter">column</replaceable> [, ...] | * } ]
</synopsis> </synopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
<title>Description</title> <title>Description</title>
@ -79,7 +79,7 @@ COPY { <replaceable class="parameter">tablename</replaceable> [ ( <replaceable c
client and the server. client and the server.
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Parameters</title> <title>Parameters</title>
@ -215,7 +215,7 @@ COPY { <replaceable class="parameter">tablename</replaceable> [ ( <replaceable c
<listitem> <listitem>
<para> <para>
Specifies that the file contains a header line with the names of each Specifies that the file contains a header line with the names of each
column in the file. On output, the first line contains the column column in the file. On output, the first line contains the column
names from the table, and on input, the first line is ignored. names from the table, and on input, the first line is ignored.
</para> </para>
</listitem> </listitem>
@ -249,7 +249,7 @@ COPY { <replaceable class="parameter">tablename</replaceable> [ ( <replaceable c
In <literal>CSV</> <command>COPY TO</> mode, forces quoting to be In <literal>CSV</> <command>COPY TO</> mode, forces quoting to be
used for all non-<literal>NULL</> values in each specified column. used for all non-<literal>NULL</> values in each specified column.
<literal>NULL</> output is never quoted. If <literal>*</> is specified, <literal>NULL</> output is never quoted. If <literal>*</> is specified,
non-<literal>NULL</> values for all columns of the table will be non-<literal>NULL</> values for all columns of the table will be
quoted. quoted.
</para> </para>
</listitem> </listitem>
@ -300,6 +300,10 @@ COPY <replaceable class="parameter">count</replaceable>
somewhat faster than the normal text mode, but a binary-format somewhat faster than the normal text mode, but a binary-format
file is less portable across machine architectures and file is less portable across machine architectures and
<productname>PostgreSQL</productname> versions. <productname>PostgreSQL</productname> versions.
Also, the binary format is very data type specific; for example
it will not work to output binary data from a <type>smallint</> column
and read it into an <type>integer</> column, even though that would work
fine in text format.
</para> </para>
<para> <para>
@ -379,7 +383,7 @@ COPY <replaceable class="parameter">count</replaceable>
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>File Formats</title> <title>File Formats</title>
@ -479,7 +483,7 @@ COPY <replaceable class="parameter">count</replaceable>
</tgroup> </tgroup>
</informaltable> </informaltable>
Presently, <command>COPY TO</command> will never emit an octal or Presently, <command>COPY TO</command> will never emit an octal or
hex-digits backslash sequence, but it does use the other sequences hex-digits backslash sequence, but it does use the other sequences
listed above for those control characters. listed above for those control characters.
</para> </para>
@ -498,7 +502,7 @@ COPY <replaceable class="parameter">count</replaceable>
data newlines and carriage returns to the <literal>\n</> and data newlines and carriage returns to the <literal>\n</> and
<literal>\r</> sequences respectively. At present it is <literal>\r</> sequences respectively. At present it is
possible to represent a data carriage return by a backslash and carriage possible to represent a data carriage return by a backslash and carriage
return, and to represent a data newline by a backslash and newline. return, and to represent a data newline by a backslash and newline.
However, these representations might not be accepted in future releases. However, these representations might not be accepted in future releases.
They are also highly vulnerable to corruption if the <command>COPY</command> file is They are also highly vulnerable to corruption if the <command>COPY</command> file is
transferred across different machines (for example, from Unix to Windows transferred across different machines (for example, from Unix to Windows
@ -506,7 +510,7 @@ COPY <replaceable class="parameter">count</replaceable>
</para> </para>
<para> <para>
<command>COPY TO</command> will terminate each row with a Unix-style <command>COPY TO</command> will terminate each row with a Unix-style
newline (<quote><literal>\n</></>). Servers running on Microsoft Windows instead newline (<quote><literal>\n</></>). Servers running on Microsoft Windows instead
output carriage return/newline (<quote><literal>\r\n</></>), but only for output carriage return/newline (<quote><literal>\r\n</></>), but only for
<command>COPY</> to a server file; for consistency across platforms, <command>COPY</> to a server file; for consistency across platforms,
@ -543,7 +547,7 @@ COPY <replaceable class="parameter">count</replaceable>
non-<literal>NULL</> values in specific columns. non-<literal>NULL</> values in specific columns.
</para> </para>
<para> <para>
The <literal>CSV</> format has no standard way to distinguish a The <literal>CSV</> format has no standard way to distinguish a
<literal>NULL</> value from an empty string. <literal>NULL</> value from an empty string.
<productname>PostgreSQL</>'s <command>COPY</> handles this by <productname>PostgreSQL</>'s <command>COPY</> handles this by
@ -557,28 +561,28 @@ COPY <replaceable class="parameter">count</replaceable>
comparisons for specific columns. comparisons for specific columns.
</para> </para>
<para> <para>
Because backslash is not a special character in the <literal>CSV</> Because backslash is not a special character in the <literal>CSV</>
format, <literal>\.</>, the end-of-data marker, could also appear format, <literal>\.</>, the end-of-data marker, could also appear
as a data value. To avoid any misinterpretation, a <literal>\.</> as a data value. To avoid any misinterpretation, a <literal>\.</>
data value appearing as a lone entry on a line is automatically data value appearing as a lone entry on a line is automatically
quoted on output, and on input, if quoted, is not interpreted as the quoted on output, and on input, if quoted, is not interpreted as the
end-of-data marker. If you are loading a file created by another end-of-data marker. If you are loading a file created by another
application that has a single unquoted column and might have a application that has a single unquoted column and might have a
value of <literal>\.</>, you might need to quote that value in the value of <literal>\.</>, you might need to quote that value in the
input file. input file.
</para> </para>
<note> <note>
<para> <para>
In <literal>CSV</> mode, all characters are significant. A quoted value In <literal>CSV</> mode, all characters are significant. A quoted value
surrounded by white space, or any characters other than surrounded by white space, or any characters other than
<literal>DELIMITER</>, will include those characters. This can cause <literal>DELIMITER</>, will include those characters. This can cause
errors if you import data from a system that pads <literal>CSV</> errors if you import data from a system that pads <literal>CSV</>
lines with white space out to some fixed width. If such a situation lines with white space out to some fixed width. If such a situation
arises you might need to preprocess the <literal>CSV</> file to remove arises you might need to preprocess the <literal>CSV</> file to remove
the trailing white space, before importing the data into the trailing white space, before importing the data into
<productname>PostgreSQL</>. <productname>PostgreSQL</>.
</para> </para>
</note> </note>
@ -600,7 +604,7 @@ COPY <replaceable class="parameter">count</replaceable>
programs cannot process. programs cannot process.
</para> </para>
</note> </note>
</refsect2> </refsect2>
<refsect2> <refsect2>
@ -747,7 +751,7 @@ OIDs to be shown as null if that ever proves desirable.
</refsect3> </refsect3>
</refsect2> </refsect2>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Examples</title> <title>Examples</title>
@ -806,10 +810,10 @@ ZW ZIMBABWE
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Compatibility</title> <title>Compatibility</title>
<para> <para>
There is no <command>COPY</command> statement in the SQL standard. There is no <command>COPY</command> statement in the SQL standard.
</para> </para>