From 0eceaaf9b7d03f88c82f27b1e51e9e75bb7ab4ff Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 6 Oct 2003 02:38:53 +0000
Subject: Modify COPY FROM to match the null-value string against the column
 value before it is de-backslashed, not after.  This allows the null string \N
 to be reliably distinguished from the data value \N (which must be
 represented as \\N).  Per bug report from Manfred Koizar ... but it's amazing
 this hasn't been reported before ... Also, be consistent about encoding
 conversion for null string: the form specified in the command is in the
 server encoding, but what is sent to/from client must be in client encoding. 
 This never worked quite right before either.

---
 doc/src/sgml/ref/copy.sgml | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
index 83a51362c5..c8e4debea7 100644
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/copy.sgml,v 1.52 2003/09/30 01:56:11 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/copy.sgml,v 1.53 2003/10/06 02:38:53 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -257,7 +257,7 @@ COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable cla
     Columns in a row are separated by the delimiter character.
     The column values themselves are strings generated by the
     output function, or acceptable to the input function, of each
-    attribute's data type.  The specified null-value string is used in
+    attribute's data type.  The specified null string is used in
     place of columns that are null.
     <command>COPY FROM</command> will raise an error if any line of the
     input file contains more or fewer columns than are expected.
@@ -282,6 +282,15 @@ COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable cla
     newline, carriage return, and the current delimiter character.
    </para>
 
+   <para>
+    The specified null string is sent by <command>COPY TO</command> without
+    adding any backslashes; conversely, <command>COPY FROM</command> matches
+    the input against the null string before removing backslashes.  Therefore,
+    a null string such as <literal>\N</literal> cannot be confused with
+    the actual data value <literal>\N</literal> (which would be represented
+    as <literal>\\N</literal>).
+   </para>
+
    <para>
     The following special backslash sequences are recognized by
     <command>COPY FROM</command>:
@@ -335,10 +344,12 @@ COPY <replaceable class="parameter">tablename</replaceable> [ ( <replaceable cla
    </para>
 
    <para>
-    Never put a backslash before a data character <literal>N</> or period
-    (<literal>.</>). Such pairs will be mistaken for the default null string
-    or the end-of-data marker, respectively.  Any other backslashed character
-    that is not mentioned in the above table will be taken to represent itself.
+    Any other backslashed character that is not mentioned in the above table
+    will be taken to represent itself.  However, beware of adding backslashes
+    unnecessarily, since that might accidentally produce a string matching the
+    end-of-data marker (<literal>\.</>) or the null string (<literal>\N</> by
+    default).  These strings will be recognized before any other backslash
+    processing is done.
    </para>
 
    <para>
-- 
cgit v1.2.1