mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-12-21 08:29:39 +08:00
Add a note warning that COPY BINARY is very datatype-specific.
Per a complaint from Gordon Shannon.
This commit is contained in:
Tom Lane
parent
e3b3878a08
commit
a2367f89ff
@ -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
|
||||
-->
|
||||
|
||||
@ -24,30 +24,30 @@ PostgreSQL documentation
|
||||
<synopsis>
|
||||
COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ]
|
||||
FROM { '<replaceable class="parameter">filename</replaceable>' | STDIN }
|
||||
[ [ WITH ]
|
||||
[ [ WITH ]
|
||||
[ BINARY ]
|
||||
[ OIDS ]
|
||||
[ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ]
|
||||
[ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ]
|
||||
[ CSV [ HEADER ]
|
||||
[ QUOTE [ AS ] '<replaceable class="parameter">quote</replaceable>' ]
|
||||
[ QUOTE [ AS ] '<replaceable class="parameter">quote</replaceable>' ]
|
||||
[ ESCAPE [ AS ] '<replaceable class="parameter">escape</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> ) }
|
||||
TO { '<replaceable class="parameter">filename</replaceable>' | STDOUT }
|
||||
[ [ WITH ]
|
||||
[ [ WITH ]
|
||||
[ BINARY ]
|
||||
[ OIDS ]
|
||||
[ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ]
|
||||
[ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ]
|
||||
[ CSV [ HEADER ]
|
||||
[ QUOTE [ AS ] '<replaceable class="parameter">quote</replaceable>' ]
|
||||
[ QUOTE [ AS ] '<replaceable class="parameter">quote</replaceable>' ]
|
||||
[ ESCAPE [ AS ] '<replaceable class="parameter">escape</replaceable>' ]
|
||||
[ FORCE QUOTE { <replaceable class="parameter">column</replaceable> [, ...] | * } ]
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
@ -79,7 +79,7 @@ COPY { <replaceable class="parameter">tablename</replaceable> [ ( <replaceable c
|
||||
client and the server.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1>
|
||||
<title>Parameters</title>
|
||||
|
||||
@ -215,7 +215,7 @@ COPY { <replaceable class="parameter">tablename</replaceable> [ ( <replaceable c
|
||||
<listitem>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
@ -249,7 +249,7 @@ COPY { <replaceable class="parameter">tablename</replaceable> [ ( <replaceable c
|
||||
In <literal>CSV</> <command>COPY TO</> mode, forces quoting to be
|
||||
used for all non-<literal>NULL</> values in each specified column.
|
||||
<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.
|
||||
</para>
|
||||
</listitem>
|
||||
@ -300,6 +300,10 @@ COPY <replaceable class="parameter">count</replaceable>
|
||||
somewhat faster than the normal text mode, but a binary-format
|
||||
file is less portable across machine architectures and
|
||||
<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>
|
||||
@ -379,7 +383,7 @@ COPY <replaceable class="parameter">count</replaceable>
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1>
|
||||
<title>File Formats</title>
|
||||
|
||||
@ -479,7 +483,7 @@ COPY <replaceable class="parameter">count</replaceable>
|
||||
</tgroup>
|
||||
</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
|
||||
listed above for those control characters.
|
||||
</para>
|
||||
@ -498,7 +502,7 @@ COPY <replaceable class="parameter">count</replaceable>
|
||||
data newlines and carriage returns to the <literal>\n</> and
|
||||
<literal>\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.
|
||||
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 <command>COPY</command> file is
|
||||
transferred across different machines (for example, from Unix to Windows
|
||||
@ -506,7 +510,7 @@ COPY <replaceable class="parameter">count</replaceable>
|
||||
</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
|
||||
output carriage return/newline (<quote><literal>\r\n</></>), but only for
|
||||
<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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<para>
|
||||
The <literal>CSV</> format has no standard way to distinguish a
|
||||
<literal>NULL</> value from an empty string.
|
||||
<productname>PostgreSQL</>'s <command>COPY</> handles this by
|
||||
@ -557,28 +561,28 @@ COPY <replaceable class="parameter">count</replaceable>
|
||||
comparisons for specific columns.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<para>
|
||||
Because backslash is not a special character in the <literal>CSV</>
|
||||
format, <literal>\.</>, the end-of-data marker, could also appear
|
||||
as a data value. To avoid any misinterpretation, a <literal>\.</>
|
||||
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
|
||||
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
|
||||
end-of-data marker. If you are loading a file created by another
|
||||
application that has a single unquoted column and might have a
|
||||
value of <literal>\.</>, you might need to quote that value in the
|
||||
application that has a single unquoted column and might have a
|
||||
value of <literal>\.</>, you might need to quote that value in the
|
||||
input file.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
In <literal>CSV</> mode, all characters are significant. A quoted value
|
||||
surrounded by white space, or any characters other than
|
||||
<literal>DELIMITER</>, will include those characters. This can cause
|
||||
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
|
||||
arises you might need to preprocess the <literal>CSV</> file to remove
|
||||
the trailing white space, before importing the data into
|
||||
<productname>PostgreSQL</>.
|
||||
In <literal>CSV</> mode, all characters are significant. A quoted value
|
||||
surrounded by white space, or any characters other than
|
||||
<literal>DELIMITER</>, will include those characters. This can cause
|
||||
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
|
||||
arises you might need to preprocess the <literal>CSV</> file to remove
|
||||
the trailing white space, before importing the data into
|
||||
<productname>PostgreSQL</>.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -600,7 +604,7 @@ COPY <replaceable class="parameter">count</replaceable>
|
||||
programs cannot process.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
@ -747,7 +751,7 @@ OIDs to be shown as null if that ever proves desirable.
|
||||
</refsect3>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1>
|
||||
<title>Examples</title>
|
||||
|
||||
@ -806,10 +810,10 @@ ZW ZIMBABWE
|
||||
</programlisting>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
|
||||
<para>
|
||||
There is no <command>COPY</command> statement in the SQL standard.
|
||||
</para>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user