@ -1,5 +1,5 @@
<!--
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.103 2004/01/20 19:49:34 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.104 2004/01/20 23:48:56 tgl Exp $
PostgreSQL documentation
PostgreSQL documentation
-->
-->
@ -705,7 +705,7 @@ testdb=>
<term><literal>\copy <replaceable class="parameter">table</replaceable>
<term><literal>\copy <replaceable class="parameter">table</replaceable>
[ ( <replaceable class="parameter">column_list</replaceable> ) ]
[ ( <replaceable class="parameter">column_list</replaceable> ) ]
{ <literal>from</literal> | <literal>to</literal> }
{ <literal>from</literal> | <literal>to</literal> }
<replaceable class="parameter">filename</replaceable> | stdin | stdout
{ <replaceable class="parameter">filename</replaceable> | stdin | stdout | - }
[ <literal>with</literal> ]
[ <literal>with</literal> ]
[ <literal>oids</literal> ]
[ <literal>oids</literal> ]
[ <literal>delimiter [as] </literal> '<replaceable class="parameter">character</replaceable>' ]
[ <literal>delimiter [as] </literal> '<replaceable class="parameter">character</replaceable>' ]
@ -720,26 +720,41 @@ testdb=>
reading or writing the specified file,
reading or writing the specified file,
<application>psql</application> reads or writes the file and
<application>psql</application> reads or writes the file and
routes the data between the server and the local file system.
routes the data between the server and the local file system.
This means that file accessibility and privileges are those
This means that file accessibility and privileges are those of
of the local user, not the server, and no SQL superuser
the local user, not the server, and no SQL superuser
privileges are required.
privileges are required.
</para>
</para>
<para>
<para>
The syntax of the command is similar to that of the
The syntax of the command is similar to that of the
<acronym>SQL</acronym> <command>COPY</command> command. (See its
<acronym>SQL</acronym> <xref linkend="sql-copy"
description for the details.) Note that, because of this,
endterm="sql-copy-title"> command. Note that, because of this,
special parsing rules apply to the <command>\copy</command>
special parsing rules apply to the <command>\copy</command>
command. In particular, the variable substitution rules and
command. In particular, the variable substitution rules and
backslash escapes do not apply.
backslash escapes do not apply.
</para>
</para>
<para>
For <literal>\copy <replaceable
class="parameter">table</replaceable> from <replaceable
class="parameter">filename</replaceable></literal> operations,
<application>psql</application> adds the option of using a
hyphen instead of <replaceable
class="parameter">filename</replaceable>. This causes
<literal>\copy</literal> to read rows from the same source that
issued the command, continuing until <literal>\.</literal> is
read or the stream reaches <acronym>EOF</>. This option is
useful for populating tables in-line within a SQL script file.
In contrast, <literal>\copy from stdin</> always reads from
<application>psql</application>'s standard input.
</para>
<tip>
<tip>
<para>
<para>
This operation is not as efficient as the <acronym>SQL</acronym>
This operation is not as efficient as the <acronym>SQL</acronym>
<command>COPY</command> command because all data must pass
<command>COPY</command> command because all data must pass
through the client/server connection. For large
through the client/server connection. For large
amounts of data the other technique may be preferable.
amounts of data the <acronym>SQL</acronym> command may be preferable.
</para>
</para>
</tip>
</tip>
@ -747,11 +762,12 @@ testdb=>
<para>
<para>
Note the difference in interpretation of
Note the difference in interpretation of
<literal>stdin</literal> and <literal>stdout</literal> between
<literal>stdin</literal> and <literal>stdout</literal> between
client and server copies: in a client copy these always
<literal>\copy</literal> and <command>COPY</command>.
In <literal>\copy</literal> these always
refer to <application>psql</application>'s input and output
refer to <application>psql</application>'s input and output
stream. On a server copy <literal>stdin</literal> comes from
streams. In <command>COPY</command>, <literal>stdin</literal> comes
wherever the <command>COPY</command> itself came from (for
from wherever the <command>COPY</command> itself came from (for
example, a script run with the <option>-f</option> option), and
example, a script run with the <option>-f</option> option), while
<literal>stdout</literal> refers to the query output stream (see
<literal>stdout</literal> refers to the query output stream (see
<command>\o</command> meta-command below).
<command>\o</command> meta-command below).
</para>
</para>