Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
关注 1
点赞 0
百科 捐赠
gooderp18绿色标准版
您最多选择25个主题 主题必须以字母或数字开头，可以包含连字符 (-)，并且长度不得超过35个字符
目录树: 0f75e31513
分支列表 标签列表
${ item.name }
创建分支 ${ searchTerm }
从 '0f75e31513'
${ noResults }
Green_GoodERP18_FSJ_Standard/PostgreSQL/doc/postgresql/html/sql-copy.html

629 行
44KB
原始文件 Blame 文件历史 

  1. <?xml version="1.0" encoding="UTF-8" standalone="no"?>

  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>COPY</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="prev" href="sql-commit-prepared.html" title="COMMIT PREPARED" /><link rel="next" href="sql-create-access-method.html" title="CREATE ACCESS METHOD" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">COPY</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-commit-prepared.html" title="COMMIT PREPARED">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 12.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-create-access-method.html" title="CREATE ACCESS METHOD">Next</a></td></tr></table><hr></hr></div><div class="refentry" id="SQL-COPY"><div class="titlepage"></div><a id="id-1.9.3.55.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">COPY</span></h2><p>COPY — copy data between a file and a table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">

  3. COPY <em class="replaceable"><code>table_name</code></em> [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ]

  4.     FROM { '<em class="replaceable"><code>filename</code></em>' | PROGRAM '<em class="replaceable"><code>command</code></em>' | STDIN }

  5.     [ [ WITH ] ( <em class="replaceable"><code>option</code></em> [, ...] ) ]

  6.     [ WHERE <em class="replaceable"><code>condition</code></em> ]

  7. 

  8. COPY { <em class="replaceable"><code>table_name</code></em> [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ] | ( <em class="replaceable"><code>query</code></em> ) }

  9.     TO { '<em class="replaceable"><code>filename</code></em>' | PROGRAM '<em class="replaceable"><code>command</code></em>' | STDOUT }

  10.     [ [ WITH ] ( <em class="replaceable"><code>option</code></em> [, ...] ) ]

  11. 

  12. <span class="phrase">where <em class="replaceable"><code>option</code></em> can be one of:</span>

  13. 

  14.     FORMAT <em class="replaceable"><code>format_name</code></em>

  15.     FREEZE [ <em class="replaceable"><code>boolean</code></em> ]

  16.     DELIMITER '<em class="replaceable"><code>delimiter_character</code></em>'

  17.     NULL '<em class="replaceable"><code>null_string</code></em>'

  18.     HEADER [ <em class="replaceable"><code>boolean</code></em> ]

  19.     QUOTE '<em class="replaceable"><code>quote_character</code></em>'

  20.     ESCAPE '<em class="replaceable"><code>escape_character</code></em>'

  21.     FORCE_QUOTE { ( <em class="replaceable"><code>column_name</code></em> [, ...] ) | * }

  22.     FORCE_NOT_NULL ( <em class="replaceable"><code>column_name</code></em> [, ...] )

  23.     FORCE_NULL ( <em class="replaceable"><code>column_name</code></em> [, ...] )

  24.     ENCODING '<em class="replaceable"><code>encoding_name</code></em>'

  25. </pre></div><div class="refsect1" id="id-1.9.3.55.5"><h2>Description</h2><p>

  26.    <code class="command">COPY</code> moves data between

  27.    <span class="productname">PostgreSQL</span> tables and standard file-system

  28.    files. <code class="command">COPY TO</code> copies the contents of a table

  29.    <span class="emphasis"><em>to</em></span> a file, while <code class="command">COPY FROM</code> copies

  30.    data <span class="emphasis"><em>from</em></span> a file to a table (appending the data to

  31.    whatever is in the table already).  <code class="command">COPY TO</code>

  32.    can also copy the results of a <code class="command">SELECT</code> query.

  33.   </p><p>

  34.    If a column list is specified, <code class="command">COPY TO</code> copies only

  35.    the data in the specified columns to the file.  For <code class="command">COPY

  36.    FROM</code>, each field in the file is inserted, in order, into the

  37.    specified column.  Table columns not specified in the <code class="command">COPY

  38.    FROM</code> column list will receive their default values.

  39.   </p><p>

  40.    <code class="command">COPY</code> with a file name instructs the

  41.    <span class="productname">PostgreSQL</span> server to directly read from

  42.    or write to a file. The file must be accessible by the

  43.    <span class="productname">PostgreSQL</span> user (the user ID the server

  44.    runs as) and the name must be specified from the viewpoint of the

  45.    server. When <code class="literal">PROGRAM</code> is specified, the server

  46.    executes the given command and reads from the standard output of the

  47.    program, or writes to the standard input of the program. The command

  48.    must be specified from the viewpoint of the server, and be executable

  49.    by the <span class="productname">PostgreSQL</span> user.  When

  50.    <code class="literal">STDIN</code> or <code class="literal">STDOUT</code> is

  51.    specified, data is transmitted via the connection between the

  52.    client and the server.

  53.   </p></div><div class="refsect1" id="id-1.9.3.55.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>

  54.       The name (optionally schema-qualified) of an existing table.

  55.      </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>

  56.       An optional list of columns to be copied.  If no column list is

  57.       specified, all columns of the table except generated columns will be

  58.       copied.

  59.      </p></dd><dt><span class="term"><em class="replaceable"><code>query</code></em></span></dt><dd><p>

  60.       A <a class="xref" href="sql-select.html" title="SELECT"><span class="refentrytitle">SELECT</span></a>, <a class="xref" href="sql-values.html" title="VALUES"><span class="refentrytitle">VALUES</span></a>,

  61.       <a class="xref" href="sql-insert.html" title="INSERT"><span class="refentrytitle">INSERT</span></a>, <a class="xref" href="sql-update.html" title="UPDATE"><span class="refentrytitle">UPDATE</span></a> or

  62.       <a class="xref" href="sql-delete.html" title="DELETE"><span class="refentrytitle">DELETE</span></a> command whose results are to be

  63.       copied.  Note that parentheses are required around the query.

  64.      </p><p>

  65.       For <code class="command">INSERT</code>, <code class="command">UPDATE</code> and

  66.       <code class="command">DELETE</code> queries a RETURNING clause must be provided,

  67.       and the target relation must not have a conditional rule, nor

  68.       an <code class="literal">ALSO</code> rule, nor an <code class="literal">INSTEAD</code> rule

  69.       that expands to multiple statements.

  70.      </p></dd><dt><span class="term"><em class="replaceable"><code>filename</code></em></span></dt><dd><p>

  71.       The path name of the input or output file.  An input file name can be

  72.       an absolute or relative path, but an output file name must be an absolute

  73.       path.  Windows users might need to use an <code class="literal">E''</code> string and

  74.       double any backslashes used in the path name.

  75.      </p></dd><dt><span class="term"><code class="literal">PROGRAM</code></span></dt><dd><p>

  76.       A command to execute. In <code class="command">COPY FROM</code>, the input is

  77.       read from standard output of the command, and in <code class="command">COPY TO</code>,

  78.       the output is written to the standard input of the command.

  79.      </p><p>

  80.       Note that the command is invoked by the shell, so if you need to pass

  81.       any arguments to shell command that come from an untrusted source, you

  82.       must be careful to strip or escape any special characters that might

  83.       have a special meaning for the shell. For security reasons, it is best

  84.       to use a fixed command string, or at least avoid passing any user input

  85.       in it.

  86.      </p></dd><dt><span class="term"><code class="literal">STDIN</code></span></dt><dd><p>

  87.       Specifies that input comes from the client application.

  88.      </p></dd><dt><span class="term"><code class="literal">STDOUT</code></span></dt><dd><p>

  89.       Specifies that output goes to the client application.

  90.      </p></dd><dt><span class="term"><em class="replaceable"><code>boolean</code></em></span></dt><dd><p>

  91.       Specifies whether the selected option should be turned on or off.

  92.       You can write <code class="literal">TRUE</code>, <code class="literal">ON</code>, or

  93.       <code class="literal">1</code> to enable the option, and <code class="literal">FALSE</code>,

  94.       <code class="literal">OFF</code>, or <code class="literal">0</code> to disable it.  The

  95.       <em class="replaceable"><code>boolean</code></em> value can also

  96.       be omitted, in which case <code class="literal">TRUE</code> is assumed.

  97.      </p></dd><dt><span class="term"><code class="literal">FORMAT</code></span></dt><dd><p>

  98.       Selects the data format to be read or written:

  99.       <code class="literal">text</code>,

  100.       <code class="literal">csv</code> (Comma Separated Values),

  101.       or <code class="literal">binary</code>.

  102.       The default is <code class="literal">text</code>.

  103.      </p></dd><dt><span class="term"><code class="literal">FREEZE</code></span></dt><dd><p>

  104.       Requests copying the data with rows already frozen, just as they

  105.       would be after running the <code class="command">VACUUM FREEZE</code> command.

  106.       This is intended as a performance option for initial data loading.

  107.       Rows will be frozen only if the table being loaded has been created

  108.       or truncated in the current subtransaction, there are no cursors

  109.       open and there are no older snapshots held by this transaction.  It is

  110.       currently not possible to perform a <code class="command">COPY FREEZE</code> on

  111.       a partitioned table.

  112.      </p><p>

  113.       Note that all other sessions will immediately be able to see the data

  114.       once it has been successfully loaded. This violates the normal rules

  115.       of MVCC visibility and users specifying should be aware of the

  116.       potential problems this might cause.

  117.      </p></dd><dt><span class="term"><code class="literal">DELIMITER</code></span></dt><dd><p>

  118.       Specifies the character that separates columns within each row

  119.       (line) of the file.  The default is a tab character in text format,

  120.       a comma in <code class="literal">CSV</code> format.

  121.       This must be a single one-byte character.

  122.       This option is not allowed when using <code class="literal">binary</code> format.

  123.      </p></dd><dt><span class="term"><code class="literal">NULL</code></span></dt><dd><p>

  124.       Specifies the string that represents a null value. The default is

  125.       <code class="literal">\N</code> (backslash-N) in text format, and an unquoted empty

  126.       string in <code class="literal">CSV</code> format. You might prefer an

  127.       empty string even in text format for cases where you don't want to

  128.       distinguish nulls from empty strings.

  129.       This option is not allowed when using <code class="literal">binary</code> format.

  130.      </p><div class="note"><h3 class="title">Note</h3><p>

  131.        When using <code class="command">COPY FROM</code>, any data item that matches

  132.        this string will be stored as a null value, so you should make

  133.        sure that you use the same string as you used with

  134.        <code class="command">COPY TO</code>.

  135.       </p></div></dd><dt><span class="term"><code class="literal">HEADER</code></span></dt><dd><p>

  136.       Specifies that the file contains a header line with the names of each

  137.       column in the file.  On output, the first line contains the column

  138.       names from the table, and on input, the first line is ignored.

  139.       This option is allowed only when using <code class="literal">CSV</code> format.

  140.      </p></dd><dt><span class="term"><code class="literal">QUOTE</code></span></dt><dd><p>

  141.       Specifies the quoting character to be used when a data value is quoted.

  142.       The default is double-quote.

  143.       This must be a single one-byte character.

  144.       This option is allowed only when using <code class="literal">CSV</code> format.

  145.      </p></dd><dt><span class="term"><code class="literal">ESCAPE</code></span></dt><dd><p>

  146.       Specifies the character that should appear before a

  147.       data character that matches the <code class="literal">QUOTE</code> value.

  148.       The default is the same as the <code class="literal">QUOTE</code> value (so that

  149.       the quoting character is doubled if it appears in the data).

  150.       This must be a single one-byte character.

  151.       This option is allowed only when using <code class="literal">CSV</code> format.

  152.      </p></dd><dt><span class="term"><code class="literal">FORCE_QUOTE</code></span></dt><dd><p>

  153.       Forces quoting to be

  154.       used for all non-<code class="literal">NULL</code> values in each specified column.

  155.       <code class="literal">NULL</code> output is never quoted. If <code class="literal">*</code> is specified,

  156.       non-<code class="literal">NULL</code> values will be quoted in all columns.

  157.       This option is allowed only in <code class="command">COPY TO</code>, and only when

  158.       using <code class="literal">CSV</code> format.

  159.      </p></dd><dt><span class="term"><code class="literal">FORCE_NOT_NULL</code></span></dt><dd><p>

  160.       Do not match the specified columns' values against the null string.

  161.       In the default case where the null string is empty, this means that

  162.       empty values will be read as zero-length strings rather than nulls,

  163.       even when they are not quoted.

  164.       This option is allowed only in <code class="command">COPY FROM</code>, and only when

  165.       using <code class="literal">CSV</code> format.

  166.      </p></dd><dt><span class="term"><code class="literal">FORCE_NULL</code></span></dt><dd><p>

  167.       Match the specified columns' values against the null string, even

  168.       if it has been quoted, and if a match is found set the value to

  169.       <code class="literal">NULL</code>. In the default case where the null string is empty,

  170.       this converts a quoted empty string into NULL.

  171.       This option is allowed only in <code class="command">COPY FROM</code>, and only when

  172.       using <code class="literal">CSV</code> format.

  173.      </p></dd><dt><span class="term"><code class="literal">ENCODING</code></span></dt><dd><p>

  174.       Specifies that the file is encoded in the <em class="replaceable"><code>encoding_name</code></em>.  If this option is

  175.       omitted, the current client encoding is used. See the Notes below

  176.       for more details.

  177.      </p></dd><dt><span class="term"><code class="literal">WHERE</code></span></dt><dd><p>

  178.     The optional <code class="literal">WHERE</code> clause has the general form

  179. </p><pre class="synopsis">

  180. WHERE <em class="replaceable"><code>condition</code></em>

  181. </pre><p>

  182.     where <em class="replaceable"><code>condition</code></em> is

  183.     any expression that evaluates to a result of type

  184.     <code class="type">boolean</code>.  Any row that does not satisfy this

  185.     condition will not be inserted to the table.  A row satisfies the

  186.     condition if it returns true when the actual row values are

  187.     substituted for any variable references.

  188.    </p><p>

  189.     Currently, subqueries are not allowed in <code class="literal">WHERE</code>

  190.     expressions, and the evaluation does not see any changes made by the

  191.     <code class="command">COPY</code> itself (this matters when the expression

  192.     contains calls to <code class="literal">VOLATILE</code> functions).

  193.    </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.55.7"><h2>Outputs</h2><p>

  194.    On successful completion, a <code class="command">COPY</code> command returns a command

  195.    tag of the form

  196. </p><pre class="screen">

  197. COPY <em class="replaceable"><code>count</code></em>

  198. </pre><p>

  199.    The <em class="replaceable"><code>count</code></em> is the number

  200.    of rows copied.

  201.   </p><div class="note"><h3 class="title">Note</h3><p>

  202.     <span class="application">psql</span> will print this command tag only if the command

  203.     was not <code class="literal">COPY ... TO STDOUT</code>, or the

  204.     equivalent <span class="application">psql</span> meta-command

  205.     <code class="literal">\copy ... to stdout</code>.  This is to prevent confusing the

  206.     command tag with the data that was just printed.

  207.    </p></div></div><div class="refsect1" id="id-1.9.3.55.8"><h2>Notes</h2><p>

  208.     <code class="command">COPY TO</code> can only be used with plain tables, not

  209.     with views.  However, you can write <code class="literal">COPY (SELECT * FROM

  210.     <em class="replaceable"><code>viewname</code></em>) TO ...</code>

  211.     to copy the current contents of a view.

  212.    </p><p>

  213.     <code class="command">COPY FROM</code> can be used with plain, foreign, or

  214.     partitioned tables or with views that have

  215.     <code class="literal">INSTEAD OF INSERT</code> triggers.

  216.    </p><p>

  217.     <code class="command">COPY</code> only deals with the specific table named;

  218.     it does not copy data to or from child tables.  Thus for example

  219.     <code class="literal">COPY <em class="replaceable"><code>table</code></em> TO</code>

  220.     shows the same data as <code class="literal">SELECT * FROM ONLY <em class="replaceable"><code>table</code></em></code>.  But <code class="literal">COPY

  221.     (SELECT * FROM <em class="replaceable"><code>table</code></em>) TO ...</code>

  222.     can be used to dump all of the data in an inheritance hierarchy.

  223.    </p><p>

  224.     You must have select privilege on the table

  225.     whose values are read by <code class="command">COPY TO</code>, and

  226.     insert privilege on the table into which values

  227.     are inserted by <code class="command">COPY FROM</code>.  It is sufficient

  228.     to have column privileges on the column(s) listed in the command.

  229.    </p><p>

  230.     If row-level security is enabled for the table, the relevant

  231.     <code class="command">SELECT</code> policies will apply to <code class="literal">COPY

  232.     <em class="replaceable"><code>table</code></em> TO</code> statements.

  233.     Currently, <code class="command">COPY FROM</code> is not supported for tables

  234.     with row-level security. Use equivalent <code class="command">INSERT</code>

  235.     statements instead.

  236.    </p><p>

  237.     Files named in a <code class="command">COPY</code> command are read or written

  238.     directly by the server, not by the client application. Therefore,

  239.     they must reside on or be accessible to the database server machine,

  240.     not the client. They must be accessible to and readable or writable

  241.     by the <span class="productname">PostgreSQL</span> user (the user ID the

  242.     server runs as), not the client. Similarly,

  243.     the command specified with <code class="literal">PROGRAM</code> is executed directly

  244.     by the server, not by the client application, must be executable by the

  245.     <span class="productname">PostgreSQL</span> user.

  246.     <code class="command">COPY</code> naming a file or command is only allowed to

  247.     database superusers or users who are granted one of the default roles

  248.     <code class="literal">pg_read_server_files</code>,

  249.     <code class="literal">pg_write_server_files</code>,

  250.     or <code class="literal">pg_execute_server_program</code>, since it allows reading

  251.     or writing any file or running a program that the server has privileges to

  252.     access.

  253.    </p><p>

  254.     Do not confuse <code class="command">COPY</code> with the

  255.     <span class="application">psql</span> instruction

  256.     <code class="command"><a class="link" href="app-psql.html#APP-PSQL-META-COMMANDS-COPY">\copy</a></code>. <code class="command">\copy</code> invokes

  257.     <code class="command">COPY FROM STDIN</code> or <code class="command">COPY TO

  258.     STDOUT</code>, and then fetches/stores the data in a file

  259.     accessible to the <span class="application">psql</span> client. Thus,

  260.     file accessibility and access rights depend on the client rather

  261.     than the server when <code class="command">\copy</code> is used.

  262.    </p><p>

  263.     It is recommended that the file name used in <code class="command">COPY</code>

  264.     always be specified as an absolute path. This is enforced by the

  265.     server in the case of <code class="command">COPY TO</code>, but for

  266.     <code class="command">COPY FROM</code> you do have the option of reading from

  267.     a file specified by a relative path. The path will be interpreted

  268.     relative to the working directory of the server process (normally

  269.     the cluster's data directory), not the client's working directory.

  270.    </p><p>

  271.     Executing a command with <code class="literal">PROGRAM</code> might be restricted

  272.     by the operating system's access control mechanisms, such as SELinux.

  273.    </p><p>

  274.     <code class="command">COPY FROM</code> will invoke any triggers and check

  275.     constraints on the destination table. However, it will not invoke rules.

  276.    </p><p>

  277.     For identity columns, the <code class="command">COPY FROM</code> command will always

  278.     write the column values provided in the input data, like

  279.     the <code class="command">INSERT</code> option <code class="literal">OVERRIDING SYSTEM

  280.     VALUE</code>.

  281.    </p><p>

  282.     <code class="command">COPY</code> input and output is affected by

  283.     <code class="varname">DateStyle</code>. To ensure portability to other

  284.     <span class="productname">PostgreSQL</span> installations that might use

  285.     non-default <code class="varname">DateStyle</code> settings,

  286.     <code class="varname">DateStyle</code> should be set to <code class="literal">ISO</code> before

  287.     using <code class="command">COPY TO</code>.  It is also a good idea to avoid dumping

  288.     data with <code class="varname">IntervalStyle</code> set to

  289.     <code class="literal">sql_standard</code>, because negative interval values might be

  290.     misinterpreted by a server that has a different setting for

  291.     <code class="varname">IntervalStyle</code>.

  292.    </p><p>

  293.     Input data is interpreted according to <code class="literal">ENCODING</code>

  294.     option or the current client encoding, and output data is encoded

  295.     in <code class="literal">ENCODING</code> or the current client encoding, even

  296.     if the data does not pass through the client but is read from or

  297.     written to a file directly by the server.

  298.    </p><p>

  299.     <code class="command">COPY</code> stops operation at the first error. This

  300.     should not lead to problems in the event of a <code class="command">COPY

  301.     TO</code>, but the target table will already have received

  302.     earlier rows in a <code class="command">COPY FROM</code>. These rows will not

  303.     be visible or accessible, but they still occupy disk space. This might

  304.     amount to a considerable amount of wasted disk space if the failure

  305.     happened well into a large copy operation. You might wish to invoke

  306.     <code class="command">VACUUM</code> to recover the wasted space.

  307.    </p><p>

  308.     <code class="literal">FORCE_NULL</code> and <code class="literal">FORCE_NOT_NULL</code> can be used

  309.     simultaneously on the same column. This results in converting quoted

  310.     null strings to null values and unquoted null strings to empty strings.

  311.    </p></div><div class="refsect1" id="id-1.9.3.55.9"><h2>File Formats</h2><div class="refsect2" id="id-1.9.3.55.9.2"><h3>Text Format</h3><p>

  312.     When the <code class="literal">text</code> format is used,

  313.     the data read or written is a text file with one line per table row.

  314.     Columns in a row are separated by the delimiter character.

  315.     The column values themselves are strings generated by the

  316.     output function, or acceptable to the input function, of each

  317.     attribute's data type.  The specified null string is used in

  318.     place of columns that are null.

  319.     <code class="command">COPY FROM</code> will raise an error if any line of the

  320.     input file contains more or fewer columns than are expected.

  321.    </p><p>

  322.     End of data can be represented by a single line containing just

  323.     backslash-period (<code class="literal">\.</code>).  An end-of-data marker is

  324.     not necessary when reading from a file, since the end of file

  325.     serves perfectly well; it is needed only when copying data to or from

  326.     client applications using pre-3.0 client protocol.

  327.    </p><p>

  328.     Backslash characters (<code class="literal">\</code>) can be used in the

  329.     <code class="command">COPY</code> data to quote data characters that might

  330.     otherwise be taken as row or column delimiters. In particular, the

  331.     following characters <span class="emphasis"><em>must</em></span> be preceded by a backslash if

  332.     they appear as part of a column value: backslash itself,

  333.     newline, carriage return, and the current delimiter character.

  334.    </p><p>

  335.     The specified null string is sent by <code class="command">COPY TO</code> without

  336.     adding any backslashes; conversely, <code class="command">COPY FROM</code> matches

  337.     the input against the null string before removing backslashes.  Therefore,

  338.     a null string such as <code class="literal">\N</code> cannot be confused with

  339.     the actual data value <code class="literal">\N</code> (which would be represented

  340.     as <code class="literal">\\N</code>).

  341.    </p><p>

  342.     The following special backslash sequences are recognized by

  343.     <code class="command">COPY FROM</code>:

  344. 

  345.    </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Sequence</th><th>Represents</th></tr></thead><tbody><tr><td><code class="literal">\b</code></td><td>Backspace (ASCII 8)</td></tr><tr><td><code class="literal">\f</code></td><td>Form feed (ASCII 12)</td></tr><tr><td><code class="literal">\n</code></td><td>Newline (ASCII 10)</td></tr><tr><td><code class="literal">\r</code></td><td>Carriage return (ASCII 13)</td></tr><tr><td><code class="literal">\t</code></td><td>Tab (ASCII 9)</td></tr><tr><td><code class="literal">\v</code></td><td>Vertical tab (ASCII 11)</td></tr><tr><td><code class="literal">\</code><em class="replaceable"><code>digits</code></em></td><td>Backslash followed by one to three octal digits specifies

  346.        the character with that numeric code</td></tr><tr><td><code class="literal">\x</code><em class="replaceable"><code>digits</code></em></td><td>Backslash <code class="literal">x</code> followed by one or two hex digits specifies

  347.        the character with that numeric code</td></tr></tbody></table></div><p>

  348. 

  349.     Presently, <code class="command">COPY TO</code> will never emit an octal or

  350.     hex-digits backslash sequence, but it does use the other sequences

  351.     listed above for those control characters.

  352.    </p><p>

  353.     Any other backslashed character that is not mentioned in the above table

  354.     will be taken to represent itself.  However, beware of adding backslashes

  355.     unnecessarily, since that might accidentally produce a string matching the

  356.     end-of-data marker (<code class="literal">\.</code>) or the null string (<code class="literal">\N</code> by

  357.     default).  These strings will be recognized before any other backslash

  358.     processing is done.

  359.    </p><p>

  360.     It is strongly recommended that applications generating <code class="command">COPY</code> data convert

  361.     data newlines and carriage returns to the <code class="literal">\n</code> and

  362.     <code class="literal">\r</code> sequences respectively.  At present it is

  363.     possible to represent a data carriage return by a backslash and carriage

  364.     return, and to represent a data newline by a backslash and newline.

  365.     However, these representations might not be accepted in future releases.

  366.     They are also highly vulnerable to corruption if the <code class="command">COPY</code> file is

  367.     transferred across different machines (for example, from Unix to Windows

  368.     or vice versa).

  369.    </p><p>

  370.     <code class="command">COPY TO</code> will terminate each row with a Unix-style

  371.     newline (<span class="quote">“<span class="quote"><code class="literal">\n</code></span>”</span>).  Servers running on Microsoft Windows instead

  372.     output carriage return/newline (<span class="quote">“<span class="quote"><code class="literal">\r\n</code></span>”</span>), but only for

  373.     <code class="command">COPY</code> to a server file; for consistency across platforms,

  374.     <code class="command">COPY TO STDOUT</code> always sends <span class="quote">“<span class="quote"><code class="literal">\n</code></span>”</span>

  375.     regardless of server platform.

  376.     <code class="command">COPY FROM</code> can handle lines ending with newlines,

  377.     carriage returns, or carriage return/newlines.  To reduce the risk of

  378.     error due to un-backslashed newlines or carriage returns that were

  379.     meant as data, <code class="command">COPY FROM</code> will complain if the line

  380.     endings in the input are not all alike.

  381.    </p></div><div class="refsect2" id="id-1.9.3.55.9.3"><h3>CSV Format</h3><p>

  382.     This format option is used for importing and exporting the Comma

  383.     Separated Value (<code class="literal">CSV</code>) file format used by many other

  384.     programs, such as spreadsheets. Instead of the escaping rules used by

  385.     <span class="productname">PostgreSQL</span>'s standard text format, it

  386.     produces and recognizes the common CSV escaping mechanism.

  387.    </p><p>

  388.     The values in each record are separated by the <code class="literal">DELIMITER</code>

  389.     character. If the value contains the delimiter character, the

  390.     <code class="literal">QUOTE</code> character, the <code class="literal">NULL</code> string, a carriage

  391.     return, or line feed character, then the whole value is prefixed and

  392.     suffixed by the <code class="literal">QUOTE</code> character, and any occurrence

  393.     within the value of a <code class="literal">QUOTE</code> character or the

  394.     <code class="literal">ESCAPE</code> character is preceded by the escape character.

  395.     You can also use <code class="literal">FORCE_QUOTE</code> to force quotes when outputting

  396.     non-<code class="literal">NULL</code> values in specific columns.

  397.    </p><p>

  398.     The <code class="literal">CSV</code> format has no standard way to distinguish a

  399.     <code class="literal">NULL</code> value from an empty string.

  400.     <span class="productname">PostgreSQL</span>'s <code class="command">COPY</code> handles this by quoting.

  401.     A <code class="literal">NULL</code> is output as the <code class="literal">NULL</code> parameter string

  402.     and is not quoted, while a non-<code class="literal">NULL</code> value matching the

  403.     <code class="literal">NULL</code> parameter string is quoted.  For example, with the

  404.     default settings, a <code class="literal">NULL</code> is written as an unquoted empty

  405.     string, while an empty string data value is written with double quotes

  406.     (<code class="literal">""</code>). Reading values follows similar rules. You can

  407.     use <code class="literal">FORCE_NOT_NULL</code> to prevent <code class="literal">NULL</code> input

  408.     comparisons for specific columns. You can also use

  409.     <code class="literal">FORCE_NULL</code> to convert quoted null string data values to

  410.     <code class="literal">NULL</code>.

  411.    </p><p>

  412.     Because backslash is not a special character in the <code class="literal">CSV</code>

  413.     format, <code class="literal">\.</code>, the end-of-data marker, could also appear

  414.     as a data value.  To avoid any misinterpretation, a <code class="literal">\.</code>

  415.     data value appearing as a lone entry on a line is automatically

  416.     quoted on output, and on input, if quoted, is not interpreted as the

  417.     end-of-data marker.  If you are loading a file created by another

  418.     application that has a single unquoted column and might have a

  419.     value of <code class="literal">\.</code>, you might need to quote that value in the

  420.     input file.

  421.    </p><div class="note"><h3 class="title">Note</h3><p>

  422.      In <code class="literal">CSV</code> format, all characters are significant. A quoted value

  423.      surrounded by white space, or any characters other than

  424.      <code class="literal">DELIMITER</code>, will include those characters. This can cause

  425.      errors if you import data from a system that pads <code class="literal">CSV</code>

  426.      lines with white space out to some fixed width. If such a situation

  427.      arises you might need to preprocess the <code class="literal">CSV</code> file to remove

  428.      the trailing white space, before importing the data into

  429.      <span class="productname">PostgreSQL</span>.

  430.     </p></div><div class="note"><h3 class="title">Note</h3><p>

  431.      CSV format will both recognize and produce CSV files with quoted

  432.      values containing embedded carriage returns and line feeds. Thus

  433.      the files are not strictly one line per table row like text-format

  434.      files.

  435.     </p></div><div class="note"><h3 class="title">Note</h3><p>

  436.      Many programs produce strange and occasionally perverse CSV files,

  437.      so the file format is more a convention than a standard. Thus you

  438.      might encounter some files that cannot be imported using this

  439.      mechanism, and <code class="command">COPY</code> might produce files that other

  440.      programs cannot process.

  441.     </p></div></div><div class="refsect2" id="id-1.9.3.55.9.4"><h3>Binary Format</h3><p>

  442.     The <code class="literal">binary</code> format option causes all data to be

  443.     stored/read as binary format rather than as text.  It is

  444.     somewhat faster than the text and <code class="literal">CSV</code> formats,

  445.     but a binary-format file is less portable across machine architectures and

  446.     <span class="productname">PostgreSQL</span> versions.

  447.     Also, the binary format is very data type specific; for example

  448.     it will not work to output binary data from a <code class="type">smallint</code> column

  449.     and read it into an <code class="type">integer</code> column, even though that would work

  450.     fine in text format.

  451.    </p><p>

  452.     The <code class="literal">binary</code> file format consists

  453.     of a file header, zero or more tuples containing the row data, and

  454.     a file trailer.  Headers and data are in network byte order.

  455.    </p><div class="note"><h3 class="title">Note</h3><p>

  456.      <span class="productname">PostgreSQL</span> releases before 7.4 used a

  457.      different binary file format.

  458.     </p></div><div class="refsect3" id="id-1.9.3.55.9.4.5"><h4>File Header</h4><p>

  459.      The file header consists of 15 bytes of fixed fields, followed

  460.      by a variable-length header extension area.  The fixed fields are:

  461. 

  462.     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Signature</span></dt><dd><p>

  463. 11-byte sequence <code class="literal">PGCOPY\n\377\r\n\0</code> — note that the zero byte

  464. is a required part of the signature.  (The signature is designed to allow

  465. easy identification of files that have been munged by a non-8-bit-clean

  466. transfer.  This signature will be changed by end-of-line-translation

  467. filters, dropped zero bytes, dropped high bits, or parity changes.)

  468.        </p></dd><dt><span class="term">Flags field</span></dt><dd><p>

  469. 32-bit integer bit mask to denote important aspects of the file format. Bits

  470. are numbered from 0 (<acronym class="acronym">LSB</acronym>) to 31 (<acronym class="acronym">MSB</acronym>).  Note that

  471. this field is stored in network byte order (most significant byte first),

  472. as are all the integer fields used in the file format.  Bits

  473. 16-31 are reserved to denote critical file format issues; a reader

  474. should abort if it finds an unexpected bit set in this range. Bits 0-15

  475. are reserved to signal backwards-compatible format issues; a reader

  476. should simply ignore any unexpected bits set in this range. Currently

  477. only one flag bit is defined, and the rest must be zero:

  478.         </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Bit 16</span></dt><dd><p>

  479.             If 1, OIDs are included in the data; if 0, not. Oid system columns

  480.             are not supported in <span class="productname">PostgreSQL</span>

  481.             anymore, but the format still contains the indicator.

  482.            </p></dd></dl></div></dd><dt><span class="term">Header extension area length</span></dt><dd><p>

  483. 32-bit integer, length in bytes of remainder of header, not including self.

  484. Currently, this is zero, and the first tuple follows

  485. immediately.  Future changes to the format might allow additional data

  486. to be present in the header.  A reader should silently skip over any header

  487. extension data it does not know what to do with.

  488.        </p></dd></dl></div><p>

  489.     </p><p>

  490. The header extension area is envisioned to contain a sequence of

  491. self-identifying chunks.  The flags field is not intended to tell readers

  492. what is in the extension area.  Specific design of header extension contents

  493. is left for a later release.

  494.     </p><p>

  495.      This design allows for both backwards-compatible header additions (add

  496.      header extension chunks, or set low-order flag bits) and

  497.      non-backwards-compatible changes (set high-order flag bits to signal such

  498.      changes, and add supporting data to the extension area if needed).

  499.     </p></div><div class="refsect3" id="id-1.9.3.55.9.4.6"><h4>Tuples</h4><p>

  500. Each tuple begins with a 16-bit integer count of the number of fields in the

  501. tuple.  (Presently, all tuples in a table will have the same count, but that

  502. might not always be true.)  Then, repeated for each field in the tuple, there

  503. is a 32-bit length word followed by that many bytes of field data.  (The

  504. length word does not include itself, and can be zero.)  As a special case,

  505. -1 indicates a NULL field value.  No value bytes follow in the NULL case.

  506.     </p><p>

  507. There is no alignment padding or any other extra data between fields.

  508.     </p><p>

  509. Presently, all data values in a binary-format file are

  510. assumed to be in binary format (format code one).  It is anticipated that a

  511. future extension might add a header field that allows per-column format codes

  512. to be specified.

  513.     </p><p>

  514. To determine the appropriate binary format for the actual tuple data you

  515. should consult the <span class="productname">PostgreSQL</span> source, in

  516. particular the <code class="function">*send</code> and <code class="function">*recv</code> functions for

  517. each column's data type (typically these functions are found in the

  518. <code class="filename">src/backend/utils/adt/</code> directory of the source

  519. distribution).

  520.     </p><p>

  521. If OIDs are included in the file, the OID field immediately follows the

  522. field-count word.  It is a normal field except that it's not included in the

  523. field-count.  Note that oid system columns are not supported in current

  524. versions of <span class="productname">PostgreSQL</span>.

  525.     </p></div><div class="refsect3" id="id-1.9.3.55.9.4.7"><h4>File Trailer</h4><p>

  526.      The file trailer consists of a 16-bit integer word containing -1.  This

  527.      is easily distinguished from a tuple's field-count word.

  528.     </p><p>

  529.      A reader should report an error if a field-count word is neither -1

  530.      nor the expected number of columns.  This provides an extra

  531.      check against somehow getting out of sync with the data.

  532.     </p></div></div></div><div class="refsect1" id="id-1.9.3.55.10"><h2>Examples</h2><p>

  533.    The following example copies a table to the client

  534.    using the vertical bar (<code class="literal">|</code>) as the field delimiter:

  535. </p><pre class="programlisting">

  536. COPY country TO STDOUT (DELIMITER '|');

  537. </pre><p>

  538.   </p><p>

  539.    To copy data from a file into the <code class="literal">country</code> table:

  540. </p><pre class="programlisting">

  541. COPY country FROM '/usr1/proj/bray/sql/country_data';

  542. </pre><p>

  543.   </p><p>

  544.    To copy into a file just the countries whose names start with 'A':

  545. </p><pre class="programlisting">

  546. COPY (SELECT * FROM country WHERE country_name LIKE 'A%') TO '/usr1/proj/bray/sql/a_list_countries.copy';

  547. </pre><p>

  548.   </p><p>

  549.    To copy into a compressed file, you can pipe the output through an external

  550.    compression program:

  551. </p><pre class="programlisting">

  552. COPY country TO PROGRAM 'gzip &gt; /usr1/proj/bray/sql/country_data.gz';

  553. </pre><p>

  554.   </p><p>

  555.    Here is a sample of data suitable for copying into a table from

  556.    <code class="literal">STDIN</code>:

  557. </p><pre class="programlisting">

  558. AF      AFGHANISTAN

  559. AL      ALBANIA

  560. DZ      ALGERIA

  561. ZM      ZAMBIA

  562. ZW      ZIMBABWE

  563. </pre><p>

  564.    Note that the white space on each line is actually a tab character.

  565.   </p><p>

  566.    The following is the same data, output in binary format.

  567.    The data is shown after filtering through the

  568.    Unix utility <code class="command">od -c</code>. The table has three columns;

  569.    the first has type <code class="type">char(2)</code>, the second has type <code class="type">text</code>,

  570.    and the third has type <code class="type">integer</code>. All the rows have a null value

  571.    in the third column.

  572. </p><pre class="programlisting">

  573. 0000000   P   G   C   O   P   Y  \n 377  \r  \n  \0  \0  \0  \0  \0  \0

  574. 0000020  \0  \0  \0  \0 003  \0  \0  \0 002   A   F  \0  \0  \0 013   A

  575. 0000040   F   G   H   A   N   I   S   T   A   N 377 377 377 377  \0 003

  576. 0000060  \0  \0  \0 002   A   L  \0  \0  \0 007   A   L   B   A   N   I

  577. 0000100   A 377 377 377 377  \0 003  \0  \0  \0 002   D   Z  \0  \0  \0

  578. 0000120 007   A   L   G   E   R   I   A 377 377 377 377  \0 003  \0  \0

  579. 0000140  \0 002   Z   M  \0  \0  \0 006   Z   A   M   B   I   A 377 377

  580. 0000160 377 377  \0 003  \0  \0  \0 002   Z   W  \0  \0  \0  \b   Z   I

  581. 0000200   M   B   A   B   W   E 377 377 377 377 377 377

  582. </pre></div><div class="refsect1" id="id-1.9.3.55.11"><h2>Compatibility</h2><p>

  583.    There is no <code class="command">COPY</code> statement in the SQL standard.

  584.   </p><p>

  585.    The following syntax was used before <span class="productname">PostgreSQL</span>

  586.    version 9.0 and is still supported:

  587. 

  588. </p><pre class="synopsis">

  589. COPY <em class="replaceable"><code>table_name</code></em> [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ]

  590.     FROM { '<em class="replaceable"><code>filename</code></em>' | STDIN }

  591.     [ [ WITH ]

  592.           [ BINARY ]

  593.           [ DELIMITER [ AS ] '<em class="replaceable"><code>delimiter_character</code></em>' ]

  594.           [ NULL [ AS ] '<em class="replaceable"><code>null_string</code></em>' ]

  595.           [ CSV [ HEADER ]

  596.                 [ QUOTE [ AS ] '<em class="replaceable"><code>quote_character</code></em>' ]

  597.                 [ ESCAPE [ AS ] '<em class="replaceable"><code>escape_character</code></em>' ]

  598.                 [ FORCE NOT NULL <em class="replaceable"><code>column_name</code></em> [, ...] ] ] ]

  599. 

  600. COPY { <em class="replaceable"><code>table_name</code></em> [ ( <em class="replaceable"><code>column_name</code></em> [, ...] ) ] | ( <em class="replaceable"><code>query</code></em> ) }

  601.     TO { '<em class="replaceable"><code>filename</code></em>' | STDOUT }

  602.     [ [ WITH ]

  603.           [ BINARY ]

  604.           [ DELIMITER [ AS ] '<em class="replaceable"><code>delimiter_character</code></em>' ]

  605.           [ NULL [ AS ] '<em class="replaceable"><code>null_string</code></em>' ]

  606.           [ CSV [ HEADER ]

  607.                 [ QUOTE [ AS ] '<em class="replaceable"><code>quote_character</code></em>' ]

  608.                 [ ESCAPE [ AS ] '<em class="replaceable"><code>escape_character</code></em>' ]

  609.                 [ FORCE QUOTE { <em class="replaceable"><code>column_name</code></em> [, ...] | * } ] ] ]

  610. </pre><p>

  611. 

  612.    Note that in this syntax, <code class="literal">BINARY</code> and <code class="literal">CSV</code> are

  613.    treated as independent keywords, not as arguments of a <code class="literal">FORMAT</code>

  614.    option.

  615.   </p><p>

  616.    The following syntax was used before <span class="productname">PostgreSQL</span>

  617.    version 7.3 and is still supported:

  618. 

  619. </p><pre class="synopsis">

  620. COPY [ BINARY ] <em class="replaceable"><code>table_name</code></em>

  621.     FROM { '<em class="replaceable"><code>filename</code></em>' | STDIN }

  622.     [ [USING] DELIMITERS '<em class="replaceable"><code>delimiter_character</code></em>' ]

  623.     [ WITH NULL AS '<em class="replaceable"><code>null_string</code></em>' ]

  624. 

  625. COPY [ BINARY ] <em class="replaceable"><code>table_name</code></em>

  626.     TO { '<em class="replaceable"><code>filename</code></em>' | STDOUT }

  627.     [ [USING] DELIMITERS '<em class="replaceable"><code>delimiter_character</code></em>' ]

  628.     [ WITH NULL AS '<em class="replaceable"><code>null_string</code></em>' ]

  629. </pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-commit-prepared.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-create-access-method.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">COMMIT PREPARED </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> CREATE ACCESS METHOD</td></tr></table></div></body></html>
上海开阖软件有限公司 沪ICP备12045867号-1