@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/copy.sgml,v 1.31 2002/05/14 18:47:58 tgl Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/copy.sgml,v 1.32 2002/06/20 16:00:43 momjian Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -21,14 +21,20 @@ PostgreSQL documentation
<date>1999-12-11</date> <date>1999-12-11</date>
</refsynopsisdivinfo> </refsynopsisdivinfo>
<synopsis> <synopsis>
COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ] COPY <replaceable class="parameter">table</replaceable>
FROM { '<replaceable class="parameter">filename</replaceable>' | <filename>stdin</filename> } FROM { '<replaceable class="parameter">filename</replaceable>' | <filename>stdin</filename> }
[ [USING] DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ] [ [ WITH ]
[ WITH NULL AS '<replaceable class="parameter">null string</replaceable>' ] [ BINARY ]
COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ] [ OIDS ]
[ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ]
[ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ] ]
COPY <replaceable class="parameter">table</replaceable>
TO { '<replaceable class="parameter">filename</replaceable>' | <filename>stdout</filename> } TO { '<replaceable class="parameter">filename</replaceable>' | <filename>stdout</filename> }
[ [USING] DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ] [ [ WITH ]
[ WITH NULL AS '<replaceable class="parameter">null string</replaceable>' ] [ BINARY ]
[ OIDS ]
[ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ]
[ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ] ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-COPY-1"> <refsect2 id="R2-SQL-COPY-1">
@ -42,57 +48,57 @@ COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ]
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>BINARY </term> <term><replaceable class="parameter">table</replaceable> </term>
<listitem> <listitem>
<para> <para>
Changes the behavior of field formatting, forcing all data to be The name (possibly schema-qualified) of an existing table.
stored or read in binary format rather than as text.
The DELIMITERS and WITH NULL options are irrelevant for binary format.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable class="parameter">tabl e</replaceable></term> <term><replaceable class="parameter">filenam e</replaceable></term>
<listitem> <listitem>
<para> <para>
The name (possibly schema-qualified) of an existing tab le. The absolute Unix path name of the input or output fi le.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>WITH OIDS </term> <term><filename>stdin</filename> </term>
<listitem> <listitem>
<para> <para>
Specifies copying the internal object id (OID) for each row . Specifies that input comes from the client application .
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable class="parameter">filename</replaceabl e></term> <term><filename>stdout</filenam e></term>
<listitem> <listitem>
<para> <para>
The absolute Unix path name of the input or output file . Specifies that output goes to the client application .
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><filename>stdin</filename> </term> <term>BINARY </term>
<listitem> <listitem>
<para> <para>
Specifies that input comes from the client application. Changes the behavior of field formatting, forcing all data to be
stored or read in binary format rather than as text. You can not
specify DELIMITER or NULL in binary mode.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><filename>stdout</filename> </term> <term>OIDS </term>
<listitem> <listitem>
<para> <para>
Specifies that output goes to the client application . Specifies copying the internal object id (OID) for each row .
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -111,8 +117,8 @@ COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ]
<listitem> <listitem>
<para> <para>
The string that represents a NULL value. The default is The string that represents a NULL value. The default is
<quote><literal>\N</literal></quote> (backslash-N). <quote><literal>\N</literal></quote> (backslash-N). You might
You might prefer an empty string, for example. prefer an empty string, for example.
</para> </para>
<note> <note>
<para> <para>
@ -172,34 +178,33 @@ ERROR: <replaceable>reason</replaceable>
</title> </title>
<para> <para>
<command>COPY</command> moves data between <command>COPY</command> moves data between
<productname>PostgreSQL</productname> tables and <productname>PostgreSQL</productname> tables and standard file-system
standard file-system files. files.
<command>COPY TO</command> copies the entire contents of a table <command>COPY TO</command> copies the entire contents of a table
<emphasis>to</> <emphasis>to</> a file, while <command>COPY FROM</command> copies
a file, while <command>COPY FROM</command> copies data <emphasis>from</> a data <emphasis>from</> a file to a table (appending the data to
file to a whatever is in the table already).
table (appending the data to whatever is in the table already).
</para> </para>
<para> <para>
<command>COPY</command> with a file name instructs <command>COPY</command> with a file name instructs the
the <productname>PostgreSQL</productname> backend <productname>PostgreSQL</productname> backend to directly read from
to directly read from or write to a file. or write to a file. The file must be accessible to the backend and
The file must be accessible to the backend and the name must be specified the name must be specified from the viewpoint of the backend. When
from the viewpoint of the backend. <filename>stdin</filename> or <filename>stdout</filename> is
When <filename>stdin</filename> or <filename>stdout</filename> is specified, data flows through the client frontend to the backend.
specified, data flows through the client frontend to the backend.
<tip> <tip>
<para> <para>
Do not confuse <command>COPY</command> with the Do not confuse <command>COPY</command> with the
<application>psql</application> instruction <command>\copy</command>. <application>psql</application> instruction
<command>\copy</command> invokes <command>COPY FROM stdin</command> <command>\copy</command>. <command>\copy</command> invokes
or <command>COPY TO stdout</command>, and then fetches/stores the data <command>COPY FROM stdin</command> or <command>COPY TO
in a file accessible to the <application>psql</application> client. stdout</command>, and then fetches/stores the data in a file
Thus, file accessibility and access rights depend on the client accessible to the <application>psql</application> client. Thus,
rather than the backend when <command>\copy</command> is used. file accessibility and access rights depend on the client rather
than the backend when <command>\copy</command> is used.
</para> </para>
</tip> </tip>
</para> </para>
@ -225,20 +230,19 @@ ERROR: <replaceable>reason</replaceable>
<para> <para>
By default, a text copy uses a tab ("\t") character as a delimiter By default, a text copy uses a tab ("\t") character as a delimiter
between fields. The field delimiter may be changed to any other single between fields. The field delimiter may be changed to any other
character with the keyword phrase USING DELIMITERS . Characters single character with the keyword DELIMITER. Characters in data
in data fields that happen to match the delimiter character will fields that happen to match the delimiter character will be
be b ackslash quoted. backslash quoted.
</para> </para>
<para> <para>
You must have <firstterm>select privilege</firstterm> on any table You must have <firstterm>select privilege</firstterm> on any table
whose values are read by whose values are read by <command>COPY TO</command>, and
<command>COPY TO</command>, and <firstterm>insert privilege</firstterm> on a table into which values
<firstterm>insert privilege</firstterm> on a are being inserted by <command>COPY FROM</command>. The backend also
table into which values are being inserted by <command>COPY FROM</command>. needs appropriate Unix permissions for any file read or written by
The backend also needs appropriate Unix permissions for any file read <command>COPY</command>.
or written by <command>COPY</command>.
</para> </para>
<para> <para>
@ -247,28 +251,25 @@ ERROR: <replaceable>reason</replaceable>
</para> </para>
<para> <para>
<command>COPY</command> stops operation at the first error. This <command>COPY</command> stops operation at the first error. This
should not lead to problems in the event of should not lead to problems in the event of a <command>COPY
a <command>COPY TO</command>, but the TO</command>, but the target relation will already have received
target relation will already have received earlier rows in a earlier rows in a <command>COPY FROM</command>. These rows will not
<command>COPY FROM</command>. These rows will not be visible or be visible or accessible, but they still occupy disk space. This may
accessible, but they still occupy disk space. This may amount to a amount to a considerable amount of wasted disk space if the failure
considerable amount happened well into a large copy operation. You may wish to invoke
of wasted disk space if the failure happened well into a large copy <command>VACUUM</command> to recover the wasted space.
operation. You may wish to invoke <command>VACUUM</command> to recover
the wasted space.
</para> </para>
<para> <para>
Files named in a <command>COPY</command> command are read or written Files named in a <command>COPY</command> command are read or written
directly by the backend, not by the client application. Therefore, directly by the backend, not by the client application. Therefore,
they must reside on or be accessible to the database server machine, they must reside on or be accessible to the database server machine,
not the client. They must be accessible to and readable or writable not the client. They must be accessible to and readable or writable
by the <application>PostgreSQL</application> user (the user ID the by the <application>PostgreSQL</application> user (the user ID the
server runs as), not the client. server runs as), not the client. <command>COPY</command> naming a
<command>COPY</command> naming a file is only allowed to database file is only allowed to database superusers, since it allows reading
superusers, since it allows reading or writing any file that the backend or writing any file that the backend has privileges to access.
has privileges to access.
<tip> <tip>
<para> <para>
@ -282,11 +283,11 @@ ERROR: <replaceable>reason</replaceable>
<para> <para>
It is recommended that the file name used in <command>COPY</command> It is recommended that the file name used in <command>COPY</command>
always be specified as an absolute path. This is enforced by the backend always be specified as an absolute path. This is enforced by the
in the case of <command>COPY TO</command>, but for <command>COPY backend in the case of <command>COPY TO</command>, but for
FROM</command> you do have the option of reading from a file specified <command>COPY FROM</command> you do have the option of reading from
by a relative path. The path will be interpreted relative to the a file specified by a relative path. The path will be interpreted
backend's working directory (somewhere below relative to the backend's working directory (somewhere below
<filename>$PGDATA</filename>), not the client's working directory. <filename>$PGDATA</filename>), not the client's working directory.
</para> </para>
</refsect2> </refsect2>
@ -312,8 +313,8 @@ ERROR: <replaceable>reason</replaceable>
place of attributes that are NULL. place of attributes that are NULL.
</para> </para>
<para> <para>
If WITH OIDS is specified, the OID is read or written as the first column, If OIDS is specified, the OID is read or written as the first column,
preceding the user data columns. (An error is raised if WITH OIDS is preceding the user data columns. (An error is raised if OIDS is
specified for a table that does not have OIDs.) specified for a table that does not have OIDs.)
</para> </para>
<para> <para>
@ -325,11 +326,11 @@ ERROR: <replaceable>reason</replaceable>
</para> </para>
<para> <para>
Backslash characters (<literal>\</>) may be used in the Backslash characters (<literal>\</>) may be used in the
<command>COPY</command> data to quote data characters that might otherwise <command>COPY</command> data to quote data characters that might
be taken as row or column delimiters. In particular, the following otherwise be taken as row or column delimiters. In particular, the
characters <emphasis>must</> be preceded by a backslash if they appear following characters <emphasis>must</> be preceded by a backslash if
as part of an attribute value: backslash itself, newline, and the current they appear as part of an attribute value: backslash itself,
delimiter character. newline, and the current delimiter character.
</para> </para>
<para> <para>
The following special backslash sequences are recognized by The following special backslash sequences are recognized by
@ -412,9 +413,8 @@ ERROR: <replaceable>reason</replaceable>
<title>Binary Format</title> <title>Binary Format</title>
<para> <para>
The file format used for <command>COPY BINARY</command> changed in The file format used for <command>COPY BINARY</command> changed in
<application>PostgreSQL</application> v7.1. <application>PostgreSQL</application> v7.1. The new format consists
The new format consists of a file header, zero or more of a file header, zero or more tuples, and a file trailer.
tuples, and a file trailer.
</para> </para>
<refsect3> <refsect3>
@ -446,9 +446,9 @@ filters, dropped nulls, dropped high bits, or parity changes.)
<term>Integer layout field</term> <term>Integer layout field</term>
<listitem> <listitem>
<para> <para>
int32 constant 0x01020304 in source's byte order. int32 constant 0x01020304 in source's byte order. Potentially, a reader
Potentially, a reader could engage in byte-flipping of subsequent fieldscould engage in byte-flipping of subsequent fields if the wrong byte
if the wrong byte order is detected here.order is detected here.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -457,14 +457,14 @@ if the wrong byte order is detected here.
<term>Flags field</term> <term>Flags field</term>
<listitem> <listitem>
<para> <para>
int32 bit mask to denote important aspects of the file int32 bit mask to denote important aspects of the file format. Bits are
format. Bits are numbered from 0 (LSB) to 31 (MSB) --- note that thisnumbered from 0 (LSB) to 31 (MSB) --- note that this field is stored
field is stored with source's endianness, as are all subsequent integerwith source's endianness, as are all subsequent integer fields. Bits
fields. Bits 16-31 are reserved to denote critical file format issues;16-31 are reserved to denote critical file format issues; a reader
a reader should abort if it finds an unexpected bit set in this range.should abort if it finds an unexpected bit set in this range. Bits 0-15
Bits 0-15 are reserved to signal backwards-compatible format issues;are reserved to signal backwards-compatible format issues; a reader
a reader should simply ignore any unexpected bits set in this range.should simply ignore any unexpected bits set in this range. Currently
Currently only one flag bit is defined, and the rest must be zero:only one flag bit is defined, and the rest must be zero:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>Bit 16</term> <term>Bit 16</term>
@ -620,7 +620,7 @@ The following example copies a table to standard output,
delimiter: delimiter:
</para> </para>
<programlisting> <programlisting>
COPY country TO <filename>stdout</filename> USING DELIMITERS '|'; COPY country TO <filename>stdout</filename> WITH DELIMITER '|';
</programlisting> </programlisting>
<para> <para>
To copy data from a Unix file into a table country: To copy data from a Unix file into a table country:
@ -629,9 +629,9 @@ COPY country TO <filename>stdout</filename> USING DELIMITERS '|';
COPY country FROM '/usr1/proj/bray/sql/country_data'; COPY country FROM '/usr1/proj/bray/sql/country_data';
</programlisting> </programlisting>
<para> <para>
Here is a sample of data suitable for copying into a table Here is a sample of data suitable for copying into a table from
from <filename>stdin</filename> (so it <filename>stdin</filename> (so it has the termination sequence on the
has the termination sequence on the last line): last line):
</para> </para>
<programlisting> <programlisting>
AF AFGHANISTAN AF AFGHANISTAN
@ -645,13 +645,12 @@ ZW ZIMBABWE
Note that the white space on each line is actually a TAB. Note that the white space on each line is actually a TAB.
</para> </para>
<para> <para>
The following is the same data, output in binary format on a Linux/i586 The following is the same data, output in binary format on a
machine. The data is shown after filtering through Linux/i586 machine. The data is shown after filtering through the
the Unix utility <command>od -c</command>. The table has Unix utility <command>od -c</command>. The table has three fields;
three fields; the first is <type>char(2)</type>, the first is <type>char(2)</type>, the second is <type>text</type>,
the second is <type>text</type>, and the third is and the third is <type>integer</type>. All the rows have a null value
<type>integer</type>. All the in the third field.
rows have a null value in the third field.
</para> </para>
<programlisting> <programlisting>
0000000 P G B C O P Y \n 377 \r \n \0 004 003 002 001 0000000 P G B C O P Y \n 377 \r \n \0 004 003 002 001
Bruce Momjian
24 years ago