diff options
Diffstat (limited to 'doc/man/copy.l')
| -rw-r--r-- | doc/man/copy.l | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/doc/man/copy.l b/doc/man/copy.l new file mode 100644 index 00000000000..f2d00b64b7b --- /dev/null +++ b/doc/man/copy.l @@ -0,0 +1,162 @@ +.\" This is -*-nroff-*- +.\" XXX standard disclaimer belongs here.... +.\" $Header: /cvsroot/pgsql/doc/man/Attic/copy.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $ +.TH COPY SQL 11/05/95 Postgres95 Postgres95 +.SH NAME +copy \(em copy data to or from a class from or to a Unix file. +.SH SYNOPSIS +.nf +\fBcopy\fP [\fBbinary\fP] [\fBnonulls\fP] classname + \fBto\fP|\fBfrom\fP "filename"|\fBstdin\fR|\fBstdout\fR + [\fBUSING DELIMITERS\fP delim] +.fi +.SH DESCRIPTION +.BR Copy +moves data between Postgres classes and standard Unix files. The +keyword +.BR binary +changes the behavior of field formatting, as described below. +.IR Classname +is the name of an existing class. +.IR Filename +is the Unix pathname of the file. In place of a filename, the +keywords +.BR "stdin" " and " "stdout" +can be used so that input to +.BR copy +can be written by a Libpq application and output from the +.BR copy +command can be read by a Libpq application. The +.BR binary +keyword will force all data to be stored/read as binary objects rather +than as ASCII text. It is somewhat faster than the normal +.BR copy +command, but is not generally portable, and the files generated are +somewhat larger, although this factor is highly dependent on the data +itself. +.PP +By default, +.BR copy +uses a tab (\\t) character as a delimiter. The delimiter may also be changed +to any other single-character with the use of +.BR "USING DELIMITERS" . +Characters in data fields which happen to match the delimiter character +will be quoted. +.PP +You must have read access on any class whose values are read by the +.BR copy +command, and either write or append access to a class to which values +are being appended by the +.BR copy +command. +.SH FORMAT OF OUTPUT FILES +.SS "ASCII COPY FORMAT" +When +.BR copy +is used without the +.BR binary +keyword, the file generated will have each instance on a line, with +each attribute separated by the delimiter character. Embedded delimiter +characters will be preceeded by a backslash character (\\). The +attribute values themselves are strings generated by the output function +associated with each attribute type. The output function for a type +should not try to generate the backslash character; this will be handled +by +.BR copy +itself. +.PP +The actual format for each instance is +.nf +<attr1><tab><attr2><tab>...<tab><attrn><newline> +.fi +.PP +If +.BR copy +is sending its output to standard output instead of a file, it will +send a backslash(\\) and a period (.) followed immediately by a newline, +on a line by themselves, when it is done. Similarly, if +.BR copy +is reading from standard input, it will expect a backslash (\\) and +a period (.) followed +by a newline, as the first three characters on a line, to denote +end-of-file. However, +.BR copy +will terminate (followed by the backend itself) if a true EOF is +encountered. +.PP +The backslash character has special meaning. +.BR NULL +attributes are output as \\N. +A literal backslash character is output as two consecutive backslashes. +A literal tab character is represented as a backslash and a tab. +A literal newline character is represented as a backslash and a newline. +When loading ASCII data not generated by Postgres95, you will need to +convert backslash characters (\\) to double-backslashes (\\\\) so +they are loaded properly. +.SS "BINARY COPY FORMAT" +In the case of +.BR "copy binary" , +the first four bytes in the file will be the number of instances in +the file. If this number is +.IR zero, +the +.BR "copy binary" +command will read until end of file is encountered. Otherwise, it +will stop reading when this number of instances has been read. +Remaining data in the file will be ignored. +.PP +The format for each instance in the file is as follows. Note that +this format must be followed +.BR EXACTLY . +Unsigned four-byte integer quantities are called uint32 in the below +description. +.nf +uint32 totallength (not including itself), +uint32 number of null attributes +[uint32 attribute number of first null attribute + ... + uint32 attribute number of nth null attribute], +<data> +.fi +.bp +.SS "ALIGNMENT OF BINARY DATA" +On Sun-3s, 2-byte attributes are aligned on two-byte boundaries, and +all larger attributes are aligned on four-byte boundaries. Character +attributes are aligned on single-byte boundaries. On other machines, +all attributes larger than 1 byte are aligned on four-byte boundaries. +Note that variable length attributes are preceded by the attribute's +length; arrays are simply contiguous streams of the array element +type. +.SH "SEE ALSO" +insert(l), create table(l), vacuum(l), libpq. +.SH BUGS +Files used as arguments to the +.BR copy +command must reside on or be accessible to the the database server +machine by being either on local disks or a networked file system. +.PP +.BR Copy +stops operation at the first error. This should not lead to problems +in the event of a +.BR "copy from" , +but the target relation will, of course, be partially modified in a +.BR "copy to" . +The +.IR vacuum (l) +query should be used to clean up after a failed +.BR "copy" . +.PP +Because Postgres operates out of a different directory than the user's +working directory at the time Postgres is invoked, the result of copying +to a file \*(lqfoo\*(rq (without additional path information) may +yield unexpected results for the naive user. In this case, +\*(lqfoo\*(rq will wind up in +.SM $PGDATA\c +/foo. In general, the full pathname should be used when specifying +files to be copied. +.PP +.BR Copy +has virtually no error checking, and a malformed input file will +likely cause the backend to crash. You should avoid using +.BR copy +for input whenever possible. |