granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/copy.sgml

   1 <REFENTRY ID="SQL-COPY">
   2  <REFMETA>
   3   <REFENTRYTITLE>
   4    COPY
   5   </REFENTRYTITLE>
   6   <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
   7  </REFMETA>
   8  <REFNAMEDIV>
   9   <REFNAME>
  10    COPY
  11   </REFNAME>
  12   <REFPURPOSE>
  13    Copies data between files and tables
  14   </REFPURPOSE>
  15  <REFSYNOPSISDIV>
  16   <REFSYNOPSISDIVINFO>
  17    <DATE>1998-04-15</DATE>
  18   </REFSYNOPSISDIVINFO>
  19   <SYNOPSIS>
  20    COPY [BINARY] <replaceable class="parameter">table</replaceable> [WITH OIDS]
  21          TO|FROM '<replaceable class="parameter">filename</replaceable>'|stdin|stdout
  22          [USING DELIMITERS '<replaceable class="parameter">delimiter</replaceable>']
  23   </SYNOPSIS>
  24
  25   <REFSECT2 ID="R2-SQL-COPY-1">
  26    <REFSECT2INFO>
  27     <DATE>1998-04-15</DATE>
  28    </REFSECT2INFO>
  29    <TITLE>
  30     Inputs
  31    </TITLE>
  32    <PARA>
  33    </PARA>
  34    <VARIABLELIST>
  35     <VARLISTENTRY>
  36      <TERM>
  37      </TERM>
  38      <LISTITEM>
  39       <PARA>
  40        <VARIABLELIST>
  41         <VARLISTENTRY>
  42          <TERM>
  43           <ReturnValue><replaceable class="parameter">table</replaceable></ReturnValue>
  44          </TERM>
  45          <LISTITEM>
  46           <PARA>
  47            The name of a table.
  48           </PARA>
  49          </LISTITEM>
  50         </VARLISTENTRY>
  51         <VARLISTENTRY>
  52          <TERM>
  53           <ReturnValue><replaceable class="parameter">delimiter</replaceable></ReturnValue>
  54          </TERM>
  55          <LISTITEM>
  56           <PARA>
  57            A character that delimits fields.
  58           </PARA>
  59          </LISTITEM>
  60         </VARLISTENTRY>
  61        </variablelist>
  62      </LISTITEM>
  63     </VARLISTENTRY>
  64    </VARIABLELIST>
  65   </REFSECT2>
  66
  67   <REFSECT2 ID="R2-SQL-COPY-2">
  68    <REFSECT2INFO>
  69     <DATE>1998-04-15</DATE>
  70    </REFSECT2INFO>
  71    <TITLE>
  72     Outputs
  73    </TITLE>
  74    <PARA>
  75    </PARA>
  76    <VARIABLELIST>
  77     <VARLISTENTRY>
  78      <TERM>
  79       Status
  80      </TERM>
  81      <LISTITEM>
  82       <PARA>
  83        <VARIABLELIST>
  84         <VARLISTENTRY>
  85          <TERM>
  86           <ReturnValue>COPY</ReturnValue>
  87          </TERM>
  88          <LISTITEM>
  89           <PARA>
  90            The copy completed successfully.
  91           </PARA>
  92          </LISTITEM>
  93         </VARLISTENTRY>
  94         <VARLISTENTRY>
  95          <TERM>
  96           <ReturnValue>ERROR: <replaceable>error message</replaceable></ReturnValue>
  97          </TERM>
  98          <LISTITEM>
  99           <PARA>
 100            The copy failed for the reason stated in the error message.
 101           </PARA>
 102          </LISTITEM>
 103         </VARLISTENTRY>
 104        </variablelist>
 105      </LISTITEM>
 106     </VARLISTENTRY>
 107    </VARIABLELIST>
 108   </REFSECT2>
 109  </REFSYNOPSISDIV>
 110
 111  <REFSECT1 ID="R1-SQL-COPY-1">
 112   <REFSECT1INFO>
 113    <DATE>1998-04-15</DATE>
 114   </REFSECT1INFO>
 115   <TITLE>
 116    Description
 117   </TITLE>
 118   <PARA>
 119    <command>COPY</command> moves data between PostgreSQL tables and
 120    standard Unix files. The keyword <function>BINARY</function>
 121    changes the behavior of field formatting, as described
 122    below. <replaceable class="parameter">Table</replaceable> is the
 123    name of an existing table.  The keyword <function>WITH
 124    OIDS</function> copies the internal unique object id (OID) for each
 125    row.  <replaceable class="parameter">Filename</replaceable> is the
 126    absolute Unix pathname of the file.  In place of a filename, the
 127    keywords <function>stdin</function> and <function>stdout</function>
 128    can be used, so that input to <command>COPY</command> can be written
 129    by a libpq application and output from <command>COPY</command> can
 130    be read by a libpq application.
 131   </para>
 132   <para>
 133    The <function>BINARY</function> keyword will force all data to be
 134    stored/read as binary objects rather than as ASCII text.  It is
 135    somewhat faster than the normal copy command, but is not
 136    generally portable, and the files generated are somewhat larger,
 137    although this factor is highly dependent on the data itself.  By
 138    default, an ASCII copy uses a tab (\t) character as a delimiter.
 139    The delimiter may also be changed to any other single character
 140    with the keyword <function>USING DELIMITERS</function>.  Characters
 141    in data fields which happen to match the delimiter character will
 142    be quoted.
 143   </para>
 144
 145   <REFSECT2 ID="R2-SQL-COPY-3">
 146    <REFSECT2INFO>
 147     <DATE>1998-04-15</DATE>
 148    </REFSECT2INFO>
 149    <TITLE>
 150     Notes
 151    </TITLE>
 152   <para>
 153     You must have select access on any table whose values are read by
 154     <command>COPY</command>, and either insert or update access to a
 155     table into which values are being inserted by <command>COPY</command>.
 156     The backend also needs appropriate Unix permissions for any file read
 157     or written by <command>COPY</command>.
 158 <comment>
 159 Is this right? The man page talked of read, write and append access, which
 160 is neither SQL nor Unix terminology.
 161 </comment>
 162   </para>
 163   <para>
 164     The keyword <function>USING DELIMITERS</function> is inaptly
 165     named, since only a single character may be specified.  (If a
 166     group of characters is specified, only the first character is
 167     used.)
 168    </para>
 169    <para>
 170     WARNING: do not confuse <command>COPY</command> with the
 171     <command>psql</command> instruction <command>\copy</command>.
 172    </para>
 173   </REFSECT2>
 174  </refsect1>
 175  <refsect1 ID="R1-SQL-COPY-2">
 176   <refsect1info>
 177    <date>1998-05-04</date>
 178   </refsect1info>
 179   <title>Format of output files</title>
 180   <refsect2>
 181    <refsect2info>
 182     <date>1998-05-04</date>
 183    </refsect2info>
 184    <title>ASCII copy format</title>
 185    <para>
 186     When <command>COPY</command> is used without <function>BINARY</function>,
 187     the file generated will have each instance on a single line, with each
 188     attribute separated by the delimiter character.  Embedded
 189     delimiter characters will be preceded by a backslash character
 190     (\).  The attribute values themselves are strings generated by the
 191     output function associated with each attribute type.  The output
 192     function for a type should not try to generate the backslash
 193     character; this will be handled by <command>COPY</command> itself.
 194    </para>
 195    <para>
 196     The actual format for each instance is
 197     <programlisting>
 198      &lt;attr1&gt;&lt;<replaceable class=parameter>separator</replaceable>&gt;&lt;attr2&gt;&lt;<replaceable class=parameter>separator</replaceable>&gt;...&lt;<replaceable class=parameter>separator</replaceable>&gt;&lt;attr<replaceable class="parameter">n</replaceable>&gt;&lt;newline&gt;</programlisting>
 199     The oid is placed on the beginning of the line
 200      if <function>WITH OIDS</function> is specified.
 201    </para>
 202    <para>
 203     If <command>COPY</command> is sending its output to standard
 204     output instead of a file, it will send a backslash(\) and a period
 205     (.)  followed immediately by a newline, on a separate line,
 206     when it is done.  Similarly, if <command>COPY</command> is reading
 207     from standard input, it will expect a backslash (\) and a period
 208     (.) followed by a newline, as the first three characters on a
 209     line, to denote end-of-file.  However, <command>COPY</command>
 210     will terminate (followed by the backend itself) if a true EOF is
 211     encountered.
 212    </para>
 213    <para>
 214     The backslash character has special meaning.  NULL attributes are
 215     output as \N.  A literal backslash character is output as two
 216     consecutive backslashes.  A literal tab character is represented
 217     as a backslash and a tab.  A literal newline character is
 218     represented as a backslash and a newline.  When loading ASCII data
 219     not generated by PostgreSQL, you will need to convert backslash
 220     characters (\) to double-backslashes (\\) to ensure that they are loaded
 221     properly.
 222    </para>
 223   </refsect2>
 224   <refsect2>
 225    <refsect2info>
 226     <date>1998-05-04</date>
 227    </refsect2info>
 228    <title>Binary copy format</title>
 229    <para>
 230     In the case of <command>COPY BINARY</command>, the first four
 231     bytes in the file will be the number of instances in the file.  If
 232     this number is zero, the <command>COPY BINARY</command> command
 233     will read until end of file is encountered.  Otherwise, it will
 234     stop reading when this number of instances has been read.
 235     Remaining data in the file will be ignored.
 236    </para>
 237    <para>
 238     The format for each instance in the file is as follows.  Note that
 239     this format must be followed <emphasis>exactly</emphasis>.
 240     Unsigned four-byte integer quantities are called uint32 in the
 241     table below.
 242    </para>
 243    <table frame="all">
 244     <title>Contents of a binary copy file</title>
 245     <tgroup cols="2"colsep="1" rowsep="1" align="center">
 246      <COLSPEC COLNAME="col1">
 247      <COLSPEC COLNAME="col2">
 248      <spanspec namest="col1" nameend="col2" spanname="subhead">
 249      <tbody>
 250       <row>
 251        <entry align="center" spanname="subhead">At the start of the file</entry>
 252       </row>
 253       <row>
 254        <entry>uint32</entry>
 255        <entry>number of tuples</entry>
 256       </row>
 257       <row>
 258        <entry align="center" spanname="subhead">For each tuple</entry>
 259       </row>
 260       <row>
 261        <entry>uint32</entry>
 262        <entry>total length of tuple data</entry>
 263       </row>
 264       <row>
 265        <entry>uint32</entry>
 266        <entry>oid (if specified)</entry>
 267       </row>
 268       <row>
 269        <entry>uint32</entry>
 270        <entry>number of null attributes</entry>
 271       </row>
 272       <row>
 273        <entry>[uint32</entry>
 274        <entry>attribute number of first null attribute, counting from 0</entry>
 275       </row>
 276       <row>
 277        <entry>...</entry>
 278        <entry>...</entry>
 279       </row>
 280       <row>
 281        <entry>uint32</entry>
 282        <entry>attribute number of last null attribute]</entry>
 283       </row>
 284       <row>
 285        <entry>-</entry>
 286        <entry>&lt;tuple data&gt;</entry>
 287       </row>
 288      </tbody>
 289     </tgroup>
 290    </table>
 291
 292   </refsect2>
 293   <refsect2>
 294    <refsect2info>
 295     <date>1998-05-04</date>
 296    </refsect2info>
 297    <title>Alignment of binary data</title>
 298    <para>
 299     On Sun-3s, 2-byte attributes are aligned on two-byte boundaries,
 300     and all larger attributes are aligned on four-byte boundaries.
 301     Character attributes are aligned on single-byte boundaries.  On
 302     other machines, all attributes larger than 1 byte are aligned on
 303     four-byte boundaries.  Note that variable length attributes are
 304     preceded by the attribute's length; arrays are simply contiguous
 305     streams of the array element type.
 306    </para>
 307   </refsect2>
 308  </refsect1>
 309
 310
 311  <REFSECT1 ID="R1-SQL-COPY-3">
 312   <TITLE>
 313    Usage
 314   </TITLE>
 315   <PARA>
 316 To copy a table to standard output, using | as a delimiter
 317   </PARA>
 318   <ProgramListing>
 319  COPY country TO stdout USING DELIMITERS '|';
 320   </ProgramListing>
 321   <PARA>
 322    To copy data from a Unix file into a table:
 323   </PARA>
 324   <ProgramListing>
 325    COPY country FROM '/usr1/proj/bray/sql/country_data';
 326   </ProgramListing>
 327   <PARA>
 328    A sample of data suitable for copying into a table from <filename>stdin</filename> (so it
 329 has the termination sequence on the last line):
 330   </PARA>
 331   <ProgramListing>
 332    AF      AFGHANISTAN
 333    AL      ALBANIA
 334    DZ      ALGERIA
 335    ...
 336    ZM      ZAMBIA
 337    ZW      ZIMBABWE
 338    \.
 339   </ProgramListing>
 340   <PARA>
 341    The same data, output in binary format on a Linux Intel machine.
 342    The data is shown after filtering through the Unix utility <command>od -c</command>. The table has
 343    three fields; the first is <classname>char(2)</classname> and the second is <classname>text</classname>. All the
 344    rows have a null value in the third field).  Notice how the <classname>char(2)</classname>
 345    field is padded with nulls to four bytes and the text field is
 346    preceded by its length:
 347   </PARA>
 348   <ProgramListing>
 349    355  \0  \0  \0 027  \0  \0  \0 001  \0  \0  \0 002  \0  \0  \0
 350    006  \0  \0  \0   A   F  \0  \0 017  \0  \0  \0   A   F   G   H
 351      A   N   I   S   T   A   N 023  \0  \0  \0 001  \0  \0  \0 002
 352     \0  \0  \0 006  \0  \0  \0   A   L  \0  \0  \v  \0  \0  \0   A
 353      L   B   A   N   I   A 023  \0  \0  \0 001  \0  \0  \0 002  \0
 354     \0  \0 006  \0  \0  \0   D   Z  \0  \0  \v  \0  \0  \0   A   L
 355      G   E   R   I   A
 356    ...              \n  \0  \0  \0   Z   A   M   B   I   A 024  \0
 357     \0  \0 001  \0  \0  \0 002  \0  \0  \0 006  \0  \0  \0   Z   W
 358     \0  \0  \f  \0  \0  \0   Z   I   M   B   A   B   W   E
 359   </ProgramListing>
 360  </refsect1>
 361
 362  <refsect1 ID="R1-SQL-COPY-4">
 363   <title>See also</title>
 364   <para>
 365    insert(l), create table(l), vacuum(l), libpq.
 366   </para>
 367  </refsect1>
 368
 369  <refsect1 ID="R1-SQL-COPY-5">
 370   <title>Bugs</title>
 371   <para>
 372    <command>COPY</command> stops operation at the first error.  This
 373    should not lead to problems in the event of a copy from, but the
 374    target relation will, of course, be partially modified in a copy
 375    to.  The <command>VACUUM</command> query should be used to clean up
 376    after a failed copy.
 377   </para>
 378   <para>
 379    Because Postgres' current directory is not the same as the user's
 380    working directory, the result of copying to a file "foo" (without
 381    additional path information) may yield unexpected results for the
 382    naive user.  In this case, "foo" will wind up in $PGDATA/foo.  In
 383    general, the full pathname should be used when specifying files to
 384    be copied.
 385   </para>
 386   <para>
 387    Files used as arguments to the copy command must reside on or be
 388    accessible to the database server machine by being either on
 389    local disks or on a networked file system.
 390   </para>
 391   <para>
 392    When a TCP/IP connection from one machine to another is used, and a
 393    target file is specified, the target file will be written on the
 394    machine where the backend is running rather than the user's
 395    machine.
 396   </para>
 397  </refsect1>
 398
 399  <REFSECT1 ID="R1-SQL-COPY-6">
 400   <TITLE>
 401    Compatibility
 402   </TITLE>
 403   <PARA>
 404   </PARA>
 405
 406   <REFSECT2 ID="R2-SQL-COPY-4">
 407    <REFSECT2INFO>
 408     <DATE>1998-04-15</DATE>
 409    </REFSECT2INFO>
 410    <TITLE>
 411     SQL92
 412    </TITLE>
 413    <PARA>
 414     There is no COPY statement in SQL92.
 415    </PARA>
 416   </refsect2>
 417  </refsect1>
 418 </REFENTRY>
 419
 420 <!-- Keep this comment at the end of the file
 421 Local variables:
 422 mode: sgml
 423 sgml-omittag:t
 424 sgml-shorttag:t
 425 sgml-minimize-attributes:nil
 426 sgml-always-quote-attributes:t
 427 sgml-indent-step:1
 428 sgml-indent-data:t
 429 sgml-parent-document:nil
 430 sgml-default-dtd-file:"../reference.ced"
 431 sgml-exposed-tags:nil
 432 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 433 sgml-local-ecat-files:nil
 434 End:
 435 -->