]> begriffs open source - ai-pg/blob - full-docs/src/sgml/man7/COPY.7
WIP: toc builder
[ai-pg] / full-docs / src / sgml / man7 / COPY.7
1 '\" t
2 .\"     Title: COPY
3 .\"    Author: The PostgreSQL Global Development Group
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\"      Date: 2025
6 .\"    Manual: PostgreSQL 18.0 Documentation
7 .\"    Source: PostgreSQL 18.0
8 .\"  Language: English
9 .\"
10 .TH "COPY" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el       .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 COPY \- copy data between a file and a table
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 COPY \fItable_name\fR [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ]
36     FROM { \*(Aq\fIfilename\fR\*(Aq | PROGRAM \*(Aq\fIcommand\fR\*(Aq | STDIN }
37     [ [ WITH ] ( \fIoption\fR [, \&.\&.\&.] ) ]
38     [ WHERE \fIcondition\fR ]
39
40 COPY { \fItable_name\fR [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ] | ( \fIquery\fR ) }
41     TO { \*(Aq\fIfilename\fR\*(Aq | PROGRAM \*(Aq\fIcommand\fR\*(Aq | STDOUT }
42     [ [ WITH ] ( \fIoption\fR [, \&.\&.\&.] ) ]
43
44 where \fIoption\fR can be one of:
45
46     FORMAT \fIformat_name\fR
47     FREEZE [ \fIboolean\fR ]
48     DELIMITER \*(Aq\fIdelimiter_character\fR\*(Aq
49     NULL \*(Aq\fInull_string\fR\*(Aq
50     DEFAULT \*(Aq\fIdefault_string\fR\*(Aq
51     HEADER [ \fIboolean\fR | MATCH ]
52     QUOTE \*(Aq\fIquote_character\fR\*(Aq
53     ESCAPE \*(Aq\fIescape_character\fR\*(Aq
54     FORCE_QUOTE { ( \fIcolumn_name\fR [, \&.\&.\&.] ) | * }
55     FORCE_NOT_NULL { ( \fIcolumn_name\fR [, \&.\&.\&.] ) | * }
56     FORCE_NULL { ( \fIcolumn_name\fR [, \&.\&.\&.] ) | * }
57     ON_ERROR \fIerror_action\fR
58     REJECT_LIMIT \fImaxerror\fR
59     ENCODING \*(Aq\fIencoding_name\fR\*(Aq
60     LOG_VERBOSITY \fIverbosity\fR
61 .fi
62 .SH "DESCRIPTION"
63 .PP
64 \fBCOPY\fR
65 moves data between
66 PostgreSQL
67 tables and standard file\-system files\&.
68 \fBCOPY TO\fR
69 copies the contents of a table
70 \fIto\fR
71 a file, while
72 \fBCOPY FROM\fR
73 copies data
74 \fIfrom\fR
75 a file to a table (appending the data to whatever is in the table already)\&.
76 \fBCOPY TO\fR
77 can also copy the results of a
78 \fBSELECT\fR
79 query\&.
80 .PP
81 If a column list is specified,
82 \fBCOPY TO\fR
83 copies only the data in the specified columns to the file\&. For
84 \fBCOPY FROM\fR, each field in the file is inserted, in order, into the specified column\&. Table columns not specified in the
85 \fBCOPY FROM\fR
86 column list will receive their default values\&.
87 .PP
88 \fBCOPY\fR
89 with a file name instructs the
90 PostgreSQL
91 server to directly read from or write to a file\&. The file must be accessible by the
92 PostgreSQL
93 user (the user ID the server runs as) and the name must be specified from the viewpoint of the server\&. When
94 PROGRAM
95 is specified, the server executes the given command and reads from the standard output of the program, or writes to the standard input of the program\&. The command must be specified from the viewpoint of the server, and be executable by the
96 PostgreSQL
97 user\&. When
98 STDIN
99 or
100 STDOUT
101 is specified, data is transmitted via the connection between the client and the server\&.
102 .PP
103 Each backend running
104 \fBCOPY\fR
105 will report its progress in the
106 pg_stat_progress_copy
107 view\&. See
108 Section\ \&27.4.3
109 for details\&.
110 .PP
111 By default,
112 \fBCOPY\fR
113 will fail if it encounters an error during processing\&. For use cases where a best\-effort attempt at loading the entire file is desired, the
114 ON_ERROR
115 clause can be used to specify some other behavior\&.
116 .SH "PARAMETERS"
117 .PP
118 \fItable_name\fR
119 .RS 4
120 The name (optionally schema\-qualified) of an existing table\&.
121 .RE
122 .PP
123 \fIcolumn_name\fR
124 .RS 4
125 An optional list of columns to be copied\&. If no column list is specified, all columns of the table except generated columns will be copied\&.
126 .RE
127 .PP
128 \fIquery\fR
129 .RS 4
130 A
131 \fBSELECT\fR,
132 \fBVALUES\fR,
133 \fBINSERT\fR,
134 \fBUPDATE\fR,
135 \fBDELETE\fR, or
136 \fBMERGE\fR
137 command whose results are to be copied\&. Note that parentheses are required around the query\&.
138 .sp
139 For
140 \fBINSERT\fR,
141 \fBUPDATE\fR,
142 \fBDELETE\fR, and
143 \fBMERGE\fR
144 queries a
145 RETURNING
146 clause must be provided, and the target relation must not have a conditional rule, nor an
147 ALSO
148 rule, nor an
149 INSTEAD
150 rule that expands to multiple statements\&.
151 .RE
152 .PP
153 \fIfilename\fR
154 .RS 4
155 The path name of the input or output file\&. An input file name can be an absolute or relative path, but an output file name must be an absolute path\&. Windows users might need to use an
156 E\*(Aq\*(Aq
157 string and double any backslashes used in the path name\&.
158 .RE
159 .PP
160 PROGRAM
161 .RS 4
162 A command to execute\&. In
163 \fBCOPY FROM\fR, the input is read from standard output of the command, and in
164 \fBCOPY TO\fR, the output is written to the standard input of the command\&.
165 .sp
166 Note that the command is invoked by the shell, so if you need to pass any arguments that come from an untrusted source, you must be careful to strip or escape any special characters that might have a special meaning for the shell\&. For security reasons, it is best to use a fixed command string, or at least avoid including any user input in it\&.
167 .RE
168 .PP
169 STDIN
170 .RS 4
171 Specifies that input comes from the client application\&.
172 .RE
173 .PP
174 STDOUT
175 .RS 4
176 Specifies that output goes to the client application\&.
177 .RE
178 .PP
179 \fIboolean\fR
180 .RS 4
181 Specifies whether the selected option should be turned on or off\&. You can write
182 TRUE,
183 ON, or
184 1
185 to enable the option, and
186 FALSE,
187 OFF, or
188 0
189 to disable it\&. The
190 \fIboolean\fR
191 value can also be omitted, in which case
192 TRUE
193 is assumed\&.
194 .RE
195 .PP
196 FORMAT
197 .RS 4
198 Selects the data format to be read or written:
199 text,
200 csv
201 (Comma Separated Values), or
202 binary\&. The default is
203 text\&. See
204 File Formats
205 below for details\&.
206 .RE
207 .PP
208 FREEZE
209 .RS 4
210 Requests copying the data with rows already frozen, just as they would be after running the
211 \fBVACUUM FREEZE\fR
212 command\&. This is intended as a performance option for initial data loading\&. Rows will be frozen only if the table being loaded has been created or truncated in the current subtransaction, there are no cursors open and there are no older snapshots held by this transaction\&. It is currently not possible to perform a
213 \fBCOPY FREEZE\fR
214 on a partitioned table or foreign table\&. This option is only allowed in
215 \fBCOPY FROM\fR\&.
216 .sp
217 Note that all other sessions will immediately be able to see the data once it has been successfully loaded\&. This violates the normal rules of MVCC visibility and users should be aware of the potential problems this might cause\&.
218 .RE
219 .PP
220 DELIMITER
221 .RS 4
222 Specifies the character that separates columns within each row (line) of the file\&. The default is a tab character in text format, a comma in
223 CSV
224 format\&. This must be a single one\-byte character\&. This option is not allowed when using
225 binary
226 format\&.
227 .RE
228 .PP
229 NULL
230 .RS 4
231 Specifies the string that represents a null value\&. The default is
232 \eN
233 (backslash\-N) in text format, and an unquoted empty string in
234 CSV
235 format\&. You might prefer an empty string even in text format for cases where you don\*(Aqt want to distinguish nulls from empty strings\&. This option is not allowed when using
236 binary
237 format\&.
238 .if n \{\
239 .sp
240 .\}
241 .RS 4
242 .it 1 an-trap
243 .nr an-no-space-flag 1
244 .nr an-break-flag 1
245 .br
246 .ps +1
247 \fBNote\fR
248 .ps -1
249 .br
250 When using
251 \fBCOPY FROM\fR, any data item that matches this string will be stored as a null value, so you should make sure that you use the same string as you used with
252 \fBCOPY TO\fR\&.
253 .sp .5v
254 .RE
255 .RE
256 .PP
257 DEFAULT
258 .RS 4
259 Specifies the string that represents a default value\&. Each time the string is found in the input file, the default value of the corresponding column will be used\&. This option is allowed only in
260 \fBCOPY FROM\fR, and only when not using
261 binary
262 format\&.
263 .RE
264 .PP
265 HEADER
266 .RS 4
267 Specifies that the file contains a header line with the names of each column in the file\&. On output, the first line contains the column names from the table\&. On input, the first line is discarded when this option is set to
268 true
269 (or equivalent Boolean value)\&. If this option is set to
270 MATCH, the number and names of the columns in the header line must match the actual column names of the table, in order; otherwise an error is raised\&. This option is not allowed when using
271 binary
272 format\&. The
273 MATCH
274 option is only valid for
275 \fBCOPY FROM\fR
276 commands\&.
277 .RE
278 .PP
279 QUOTE
280 .RS 4
281 Specifies the quoting character to be used when a data value is quoted\&. The default is double\-quote\&. This must be a single one\-byte character\&. This option is allowed only when using
282 CSV
283 format\&.
284 .RE
285 .PP
286 ESCAPE
287 .RS 4
288 Specifies the character that should appear before a data character that matches the
289 QUOTE
290 value\&. The default is the same as the
291 QUOTE
292 value (so that the quoting character is doubled if it appears in the data)\&. This must be a single one\-byte character\&. This option is allowed only when using
293 CSV
294 format\&.
295 .RE
296 .PP
297 FORCE_QUOTE
298 .RS 4
299 Forces quoting to be used for all non\-NULL
300 values in each specified column\&.
301 NULL
302 output is never quoted\&. If
303 *
304 is specified, non\-NULL
305 values will be quoted in all columns\&. This option is allowed only in
306 \fBCOPY TO\fR, and only when using
307 CSV
308 format\&.
309 .RE
310 .PP
311 FORCE_NOT_NULL
312 .RS 4
313 Do not match the specified columns\*(Aq values against the null string\&. In the default case where the null string is empty, this means that empty values will be read as zero\-length strings rather than nulls, even when they are not quoted\&. If
314 *
315 is specified, the option will be applied to all columns\&. This option is allowed only in
316 \fBCOPY FROM\fR, and only when using
317 CSV
318 format\&.
319 .RE
320 .PP
321 FORCE_NULL
322 .RS 4
323 Match the specified columns\*(Aq values against the null string, even if it has been quoted, and if a match is found set the value to
324 NULL\&. In the default case where the null string is empty, this converts a quoted empty string into NULL\&. If
325 *
326 is specified, the option will be applied to all columns\&. This option is allowed only in
327 \fBCOPY FROM\fR, and only when using
328 CSV
329 format\&.
330 .RE
331 .PP
332 ON_ERROR
333 .RS 4
334 Specifies how to behave when encountering an error converting a column\*(Aqs input value into its data type\&. An
335 \fIerror_action\fR
336 value of
337 stop
338 means fail the command, while
339 ignore
340 means discard the input row and continue with the next one\&. The default is
341 stop\&.
342 .sp
343 The
344 ignore
345 option is applicable only for
346 \fBCOPY FROM\fR
347 when the
348 FORMAT
349 is
350 text
351 or
352 csv\&.
353 .sp
354 A
355 NOTICE
356 message containing the ignored row count is emitted at the end of the
357 \fBCOPY FROM\fR
358 if at least one row was discarded\&. When
359 LOG_VERBOSITY
360 option is set to
361 verbose, a
362 NOTICE
363 message containing the line of the input file and the column name whose input conversion has failed is emitted for each discarded row\&. When it is set to
364 silent, no message is emitted regarding ignored rows\&.
365 .RE
366 .PP
367 REJECT_LIMIT
368 .RS 4
369 Specifies the maximum number of errors tolerated while converting a column\*(Aqs input value to its data type, when
370 ON_ERROR
371 is set to
372 ignore\&. If the input causes more errors than the specified value, the
373 \fBCOPY\fR
374 command fails, even with
375 ON_ERROR
376 set to
377 ignore\&. This clause must be used with
378 ON_ERROR=ignore
379 and
380 \fImaxerror\fR
381 must be positive
382 bigint\&. If not specified,
383 ON_ERROR=ignore
384 allows an unlimited number of errors, meaning
385 \fBCOPY\fR
386 will skip all erroneous data\&.
387 .RE
388 .PP
389 ENCODING
390 .RS 4
391 Specifies that the file is encoded in the
392 \fIencoding_name\fR\&. If this option is omitted, the current client encoding is used\&. See the Notes below for more details\&.
393 .RE
394 .PP
395 LOG_VERBOSITY
396 .RS 4
397 Specifies the amount of messages emitted by a
398 \fBCOPY\fR
399 command:
400 default,
401 verbose, or
402 silent\&. If
403 verbose
404 is specified, additional messages are emitted during processing\&.
405 silent
406 suppresses both verbose and default messages\&.
407 .sp
408 This is currently used in
409 \fBCOPY FROM\fR
410 command when
411 ON_ERROR
412 option is set to
413 ignore\&.
414 .RE
415 .PP
416 WHERE
417 .RS 4
418 The optional
419 WHERE
420 clause has the general form
421 .sp
422 .if n \{\
423 .RS 4
424 .\}
425 .nf
426 WHERE \fIcondition\fR
427 .fi
428 .if n \{\
429 .RE
430 .\}
431 .sp
432 where
433 \fIcondition\fR
434 is any expression that evaluates to a result of type
435 boolean\&. Any row that does not satisfy this condition will not be inserted to the table\&. A row satisfies the condition if it returns true when the actual row values are substituted for any variable references\&.
436 .sp
437 Currently, subqueries are not allowed in
438 WHERE
439 expressions, and the evaluation does not see any changes made by the
440 \fBCOPY\fR
441 itself (this matters when the expression contains calls to
442 VOLATILE
443 functions)\&.
444 .RE
445 .SH "OUTPUTS"
446 .PP
447 On successful completion, a
448 \fBCOPY\fR
449 command returns a command tag of the form
450 .sp
451 .if n \{\
452 .RS 4
453 .\}
454 .nf
455 COPY \fIcount\fR
456 .fi
457 .if n \{\
458 .RE
459 .\}
460 .sp
461 The
462 \fIcount\fR
463 is the number of rows copied\&.
464 .if n \{\
465 .sp
466 .\}
467 .RS 4
468 .it 1 an-trap
469 .nr an-no-space-flag 1
470 .nr an-break-flag 1
471 .br
472 .ps +1
473 \fBNote\fR
474 .ps -1
475 .br
476 .PP
477 psql
478 will print this command tag only if the command was not
479 COPY \&.\&.\&. TO STDOUT, or the equivalent
480 psql
481 meta\-command
482 \ecopy \&.\&.\&. to stdout\&. This is to prevent confusing the command tag with the data that was just printed\&.
483 .sp .5v
484 .RE
485 .SH "NOTES"
486 .PP
487 \fBCOPY TO\fR
488 can be used with plain tables and populated materialized views\&. For example,
489 COPY \fItable\fR TO
490 copies the same rows as
491 SELECT * FROM ONLY \fItable\fR\&. However it doesn\*(Aqt directly support other relation types, such as partitioned tables, inheritance child tables, or views\&. To copy all rows from such relations, use
492 COPY (SELECT * FROM \fItable\fR) TO\&.
493 .PP
494 \fBCOPY FROM\fR
495 can be used with plain, foreign, or partitioned tables or with views that have
496 INSTEAD OF INSERT
497 triggers\&.
498 .PP
499 You must have select privilege on the table whose values are read by
500 \fBCOPY TO\fR, and insert privilege on the table into which values are inserted by
501 \fBCOPY FROM\fR\&. It is sufficient to have column privileges on the column(s) listed in the command\&.
502 .PP
503 If row\-level security is enabled for the table, the relevant
504 \fBSELECT\fR
505 policies will apply to
506 COPY \fItable\fR TO
507 statements\&. Currently,
508 \fBCOPY FROM\fR
509 is not supported for tables with row\-level security\&. Use equivalent
510 \fBINSERT\fR
511 statements instead\&.
512 .PP
513 Files named in a
514 \fBCOPY\fR
515 command are read or written directly by the server, not by the client application\&. Therefore, they must reside on or be accessible to the database server machine, not the client\&. They must be accessible to and readable or writable by the
516 PostgreSQL
517 user (the user ID the server runs as), not the client\&. Similarly, the command specified with
518 PROGRAM
519 is executed directly by the server, not by the client application, must be executable by the
520 PostgreSQL
521 user\&.
522 \fBCOPY\fR
523 naming a file or command is only allowed to database superusers or users who are granted one of the roles
524 pg_read_server_files,
525 pg_write_server_files, or
526 pg_execute_server_program, since it allows reading or writing any file or running a program that the server has privileges to access\&.
527 .PP
528 Do not confuse
529 \fBCOPY\fR
530 with the
531 psql
532 instruction
533 \fB\ecopy\fR\&.
534 \fB\ecopy\fR
535 invokes
536 \fBCOPY FROM STDIN\fR
537 or
538 \fBCOPY TO STDOUT\fR, and then fetches/stores the data in a file accessible to the
539 psql
540 client\&. Thus, file accessibility and access rights depend on the client rather than the server when
541 \fB\ecopy\fR
542 is used\&.
543 .PP
544 It is recommended that the file name used in
545 \fBCOPY\fR
546 always be specified as an absolute path\&. This is enforced by the server in the case of
547 \fBCOPY TO\fR, but for
548 \fBCOPY FROM\fR
549 you do have the option of reading from a file specified by a relative path\&. The path will be interpreted relative to the working directory of the server process (normally the cluster\*(Aqs data directory), not the client\*(Aqs working directory\&.
550 .PP
551 Executing a command with
552 PROGRAM
553 might be restricted by the operating system\*(Aqs access control mechanisms, such as SELinux\&.
554 .PP
555 \fBCOPY FROM\fR
556 will invoke any triggers and check constraints on the destination table\&. However, it will not invoke rules\&.
557 .PP
558 For identity columns, the
559 \fBCOPY FROM\fR
560 command will always write the column values provided in the input data, like the
561 \fBINSERT\fR
562 option
563 OVERRIDING SYSTEM VALUE\&.
564 .PP
565 \fBCOPY\fR
566 input and output is affected by
567 \fIDateStyle\fR\&. To ensure portability to other
568 PostgreSQL
569 installations that might use non\-default
570 \fIDateStyle\fR
571 settings,
572 \fIDateStyle\fR
573 should be set to
574 ISO
575 before using
576 \fBCOPY TO\fR\&. It is also a good idea to avoid dumping data with
577 \fIIntervalStyle\fR
578 set to
579 sql_standard, because negative interval values might be misinterpreted by a server that has a different setting for
580 \fIIntervalStyle\fR\&.
581 .PP
582 Input data is interpreted according to
583 ENCODING
584 option or the current client encoding, and output data is encoded in
585 ENCODING
586 or the current client encoding, even if the data does not pass through the client but is read from or written to a file directly by the server\&.
587 .PP
588 The
589 \fBCOPY FROM\fR
590 command physically inserts input rows into the table as it progresses\&. If the command fails, these rows are left in a deleted state; these rows will not be visible, but still occupy disk space\&. This might amount to considerable wasted disk space if the failure happened well into a large copy operation\&.
591 \fBVACUUM\fR
592 should be used to recover the wasted space\&.
593 .PP
594 FORCE_NULL
595 and
596 FORCE_NOT_NULL
597 can be used simultaneously on the same column\&. This results in converting quoted null strings to null values and unquoted null strings to empty strings\&.
598 .SH "FILE FORMATS"
599 .SS "Text Format"
600 .PP
601 When the
602 text
603 format is used, the data read or written is a text file with one line per table row\&. 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\*(Aqs data type\&. The specified null string is used in place of columns that are null\&.
604 \fBCOPY FROM\fR
605 will raise an error if any line of the input file contains more or fewer columns than are expected\&.
606 .PP
607 End of data can be represented by a line containing just backslash\-period (\e\&.)\&. An end\-of\-data marker is not necessary when reading from a file, since the end of file serves perfectly well; in that context this provision exists only for backward compatibility\&. However,
608 psql
609 uses
610 \e\&.
611 to terminate a
612 COPY FROM STDIN
613 operation (that is, reading in\-line
614 \fBCOPY\fR
615 data in an SQL script)\&. In that context the rule is needed to be able to end the operation before the end of the script\&.
616 .PP
617 Backslash characters (\e) can be used in the
618 \fBCOPY\fR
619 data to quote data characters that might otherwise be taken as row or column delimiters\&. In particular, the following characters
620 \fImust\fR
621 be preceded by a backslash if they appear as part of a column value: backslash itself, newline, carriage return, and the current delimiter character\&.
622 .PP
623 The specified null string is sent by
624 \fBCOPY TO\fR
625 without adding any backslashes; conversely,
626 \fBCOPY FROM\fR
627 matches the input against the null string before removing backslashes\&. Therefore, a null string such as
628 \eN
629 cannot be confused with the actual data value
630 \eN
631 (which would be represented as
632 \e\eN)\&.
633 .PP
634 The following special backslash sequences are recognized by
635 \fBCOPY FROM\fR:
636 .TS
637 allbox tab(:);
638 lB lB.
639 T{
640 Sequence
641 T}:T{
642 Represents
643 T}
644 .T&
645 l l
646 l l
647 l l
648 l l
649 l l
650 l l
651 l l
652 l l.
653 T{
654 \eb
655 T}:T{
656 Backspace (ASCII 8)
657 T}
658 T{
659 \ef
660 T}:T{
661 Form feed (ASCII 12)
662 T}
663 T{
664 \en
665 T}:T{
666 Newline (ASCII 10)
667 T}
668 T{
669 \er
670 T}:T{
671 Carriage return (ASCII 13)
672 T}
673 T{
674 \et
675 T}:T{
676 Tab (ASCII 9)
677 T}
678 T{
679 \ev
680 T}:T{
681 Vertical tab (ASCII 11)
682 T}
683 T{
684 \e\fIdigits\fR
685 T}:T{
686 Backslash followed by one to three octal digits specifies
687        the byte with that numeric code
688 T}
689 T{
690 \ex\fIdigits\fR
691 T}:T{
692 Backslash x followed by one or two hex digits specifies
693        the byte with that numeric code
694 T}
695 .TE
696 .sp 1
697 Presently,
698 \fBCOPY TO\fR
699 will never emit an octal or hex\-digits backslash sequence, but it does use the other sequences listed above for those control characters\&.
700 .PP
701 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 (\e\&.) or the null string (\eN
702 by default)\&. These strings will be recognized before any other backslash processing is done\&.
703 .PP
704 It is strongly recommended that applications generating
705 \fBCOPY\fR
706 data convert data newlines and carriage returns to the
707 \en
708 and
709 \er
710 sequences respectively\&. At present it is possible to represent a data carriage return by a backslash and carriage return, and to represent a data newline by a backslash and newline\&. However, these representations might not be accepted in future releases\&. They are also highly vulnerable to corruption if the
711 \fBCOPY\fR
712 file is transferred across different machines (for example, from Unix to Windows or vice versa)\&.
713 .PP
714 All backslash sequences are interpreted after encoding conversion\&. The bytes specified with the octal and hex\-digit backslash sequences must form valid characters in the database encoding\&.
715 .PP
716 \fBCOPY TO\fR
717 will terminate each row with a Unix\-style newline (\(lq\en\(rq)\&. Servers running on Microsoft Windows instead output carriage return/newline (\(lq\er\en\(rq), but only for
718 \fBCOPY\fR
719 to a server file; for consistency across platforms,
720 \fBCOPY TO STDOUT\fR
721 always sends
722 \(lq\en\(rq
723 regardless of server platform\&.
724 \fBCOPY FROM\fR
725 can handle lines ending with newlines, carriage returns, or carriage return/newlines\&. To reduce the risk of error due to un\-backslashed newlines or carriage returns that were meant as data,
726 \fBCOPY FROM\fR
727 will complain if the line endings in the input are not all alike\&.
728 .SS "CSV Format"
729 .PP
730 This format option is used for importing and exporting the Comma\- Separated Value (CSV) file format used by many other programs, such as spreadsheets\&. Instead of the escaping rules used by
731 PostgreSQL\*(Aqs standard text format, it produces and recognizes the common
732 CSV
733 escaping mechanism\&.
734 .PP
735 The values in each record are separated by the
736 DELIMITER
737 character\&. If the value contains the delimiter character, the
738 QUOTE
739 character, the
740 NULL
741 string, a carriage return, or line feed character, then the whole value is prefixed and suffixed by the
742 QUOTE
743 character, and any occurrence within the value of a
744 QUOTE
745 character or the
746 ESCAPE
747 character is preceded by the escape character\&. You can also use
748 FORCE_QUOTE
749 to force quotes when outputting non\-NULL
750 values in specific columns\&.
751 .PP
752 The
753 CSV
754 format has no standard way to distinguish a
755 NULL
756 value from an empty string\&.
757 PostgreSQL\*(Aqs
758 \fBCOPY\fR
759 handles this by quoting\&. A
760 NULL
761 is output as the
762 NULL
763 parameter string and is not quoted, while a non\-NULL
764 value matching the
765 NULL
766 parameter string is quoted\&. For example, with the default settings, a
767 NULL
768 is written as an unquoted empty string, while an empty string data value is written with double quotes ("")\&. Reading values follows similar rules\&. You can use
769 FORCE_NOT_NULL
770 to prevent
771 NULL
772 input comparisons for specific columns\&. You can also use
773 FORCE_NULL
774 to convert quoted null string data values to
775 NULL\&.
776 .PP
777 Because backslash is not a special character in the
778 CSV
779 format, the end\-of\-data marker used in text mode (\e\&.) is not normally treated as special when reading
780 CSV
781 data\&. An exception is that
782 psql
783 will terminate a
784 COPY FROM STDIN
785 operation (that is, reading in\-line
786 \fBCOPY\fR
787 data in an SQL script) at a line containing only
788 \e\&., whether it is text or
789 CSV
790 mode\&.
791 .if n \{\
792 .sp
793 .\}
794 .RS 4
795 .it 1 an-trap
796 .nr an-no-space-flag 1
797 .nr an-break-flag 1
798 .br
799 .ps +1
800 \fBNote\fR
801 .ps -1
802 .br
803 .PP
804 PostgreSQL
805 versions before v18 always recognized unquoted
806 \e\&.
807 as an end\-of\-data marker, even when reading from a separate file\&. For compatibility with older versions,
808 \fBCOPY TO\fR
809 will quote
810 \e\&.
811 when it\*(Aqs alone on a line, even though this is no longer necessary\&.
812 .sp .5v
813 .RE
814 .if n \{\
815 .sp
816 .\}
817 .RS 4
818 .it 1 an-trap
819 .nr an-no-space-flag 1
820 .nr an-break-flag 1
821 .br
822 .ps +1
823 \fBNote\fR
824 .ps -1
825 .br
826 .PP
827 In
828 CSV
829 format, all characters are significant\&. A quoted value surrounded by white space, or any characters other than
830 DELIMITER, will include those characters\&. This can cause errors if you import data from a system that pads
831 CSV
832 lines with white space out to some fixed width\&. If such a situation arises you might need to preprocess the
833 CSV
834 file to remove the trailing white space, before importing the data into
835 PostgreSQL\&.
836 .sp .5v
837 .RE
838 .if n \{\
839 .sp
840 .\}
841 .RS 4
842 .it 1 an-trap
843 .nr an-no-space-flag 1
844 .nr an-break-flag 1
845 .br
846 .ps +1
847 \fBNote\fR
848 .ps -1
849 .br
850 .PP
851 CSV
852 format will both recognize and produce
853 CSV
854 files with quoted values containing embedded carriage returns and line feeds\&. Thus the files are not strictly one line per table row like text\-format files\&.
855 .sp .5v
856 .RE
857 .if n \{\
858 .sp
859 .\}
860 .RS 4
861 .it 1 an-trap
862 .nr an-no-space-flag 1
863 .nr an-break-flag 1
864 .br
865 .ps +1
866 \fBNote\fR
867 .ps -1
868 .br
869 .PP
870 Many programs produce strange and occasionally perverse
871 CSV
872 files, so the file format is more a convention than a standard\&. Thus you might encounter some files that cannot be imported using this mechanism, and
873 \fBCOPY\fR
874 might produce files that other programs cannot process\&.
875 .sp .5v
876 .RE
877 .SS "Binary Format"
878 .PP
879 The
880 binary
881 format option causes all data to be stored/read as binary format rather than as text\&. It is somewhat faster than the text and
882 CSV
883 formats, but a binary\-format file is less portable across machine architectures and
884 PostgreSQL
885 versions\&. Also, the binary format is very data type specific; for example it will not work to output binary data from a
886 smallint
887 column and read it into an
888 integer
889 column, even though that would work fine in text format\&.
890 .PP
891 The
892 binary
893 file format consists of a file header, zero or more tuples containing the row data, and a file trailer\&. Headers and data are in network byte order\&.
894 .if n \{\
895 .sp
896 .\}
897 .RS 4
898 .it 1 an-trap
899 .nr an-no-space-flag 1
900 .nr an-break-flag 1
901 .br
902 .ps +1
903 \fBNote\fR
904 .ps -1
905 .br
906 .PP
907 PostgreSQL
908 releases before 7\&.4 used a different binary file format\&.
909 .sp .5v
910 .RE
911 .sp
912 .it 1 an-trap
913 .nr an-no-space-flag 1
914 .nr an-break-flag 1
915 .br
916 .ps +1
917 \fBFile Header\fR
918 .RS 4
919 .PP
920 The file header consists of 15 bytes of fixed fields, followed by a variable\-length header extension area\&. The fixed fields are:
921 .PP
922 Signature
923 .RS 4
924 11\-byte sequence
925 PGCOPY\en\e377\er\en\e0
926 \(em note that the zero byte is a required part of the signature\&. (The signature is designed to allow easy identification of files that have been munged by a non\-8\-bit\-clean transfer\&. This signature will be changed by end\-of\-line\-translation filters, dropped zero bytes, dropped high bits, or parity changes\&.)
927 .RE
928 .PP
929 Flags field
930 .RS 4
931 32\-bit integer bit mask to denote important aspects of the file format\&. Bits are numbered from 0 (LSB) to 31 (MSB)\&. Note that this field is stored in network byte order (most significant byte first), as are all the integer fields used in the file format\&. Bits 16\(en31 are reserved to denote critical file format issues; a reader should abort if it finds an unexpected bit set in this range\&. Bits 0\(en15 are reserved to signal backwards\-compatible format issues; a reader should simply ignore any unexpected bits set in this range\&. Currently only one flag bit is defined, and the rest must be zero:
932 .PP
933 Bit 16
934 .RS 4
935 If 1, OIDs are included in the data; if 0, not\&. Oid system columns are not supported in
936 PostgreSQL
937 anymore, but the format still contains the indicator\&.
938 .RE
939 .RE
940 .PP
941 Header extension area length
942 .RS 4
943 32\-bit integer, length in bytes of remainder of header, not including self\&. Currently, this is zero, and the first tuple follows immediately\&. Future changes to the format might allow additional data to be present in the header\&. A reader should silently skip over any header extension data it does not know what to do with\&.
944 .RE
945 .PP
946 The header extension area is envisioned to contain a sequence of self\-identifying chunks\&. The flags field is not intended to tell readers what is in the extension area\&. Specific design of header extension contents is left for a later release\&.
947 .PP
948 This design allows for both backwards\-compatible header additions (add header extension chunks, or set low\-order flag bits) and non\-backwards\-compatible changes (set high\-order flag bits to signal such changes, and add supporting data to the extension area if needed)\&.
949 .RE
950 .sp
951 .it 1 an-trap
952 .nr an-no-space-flag 1
953 .nr an-break-flag 1
954 .br
955 .ps +1
956 \fBTuples\fR
957 .RS 4
958 .PP
959 Each tuple begins with a 16\-bit integer count of the number of fields in the tuple\&. (Presently, all tuples in a table will have the same count, but that might not always be true\&.) Then, repeated for each field in the tuple, there is a 32\-bit length word followed by that many bytes of field data\&. (The length word does not include itself, and can be zero\&.) As a special case, \-1 indicates a NULL field value\&. No value bytes follow in the NULL case\&.
960 .PP
961 There is no alignment padding or any other extra data between fields\&.
962 .PP
963 Presently, all data values in a binary\-format file are assumed to be in binary format (format code one)\&. It is anticipated that a future extension might add a header field that allows per\-column format codes to be specified\&.
964 .PP
965 To determine the appropriate binary format for the actual tuple data you should consult the
966 PostgreSQL
967 source, in particular the
968 \fB*send\fR
969 and
970 \fB*recv\fR
971 functions for each column\*(Aqs data type (typically these functions are found in the
972 src/backend/utils/adt/
973 directory of the source distribution)\&.
974 .PP
975 If OIDs are included in the file, the OID field immediately follows the field\-count word\&. It is a normal field except that it\*(Aqs not included in the field\-count\&. Note that oid system columns are not supported in current versions of
976 PostgreSQL\&.
977 .RE
978 .sp
979 .it 1 an-trap
980 .nr an-no-space-flag 1
981 .nr an-break-flag 1
982 .br
983 .ps +1
984 \fBFile Trailer\fR
985 .RS 4
986 .PP
987 The file trailer consists of a 16\-bit integer word containing \-1\&. This is easily distinguished from a tuple\*(Aqs field\-count word\&.
988 .PP
989 A reader should report an error if a field\-count word is neither \-1 nor the expected number of columns\&. This provides an extra check against somehow getting out of sync with the data\&.
990 .RE
991 .SH "EXAMPLES"
992 .PP
993 The following example copies a table to the client using the vertical bar (|) as the field delimiter:
994 .sp
995 .if n \{\
996 .RS 4
997 .\}
998 .nf
999 COPY country TO STDOUT (DELIMITER \*(Aq|\*(Aq);
1000 .fi
1001 .if n \{\
1002 .RE
1003 .\}
1004 .PP
1005 To copy data from a file into the
1006 country
1007 table:
1008 .sp
1009 .if n \{\
1010 .RS 4
1011 .\}
1012 .nf
1013 COPY country FROM \*(Aq/usr1/proj/bray/sql/country_data\*(Aq;
1014 .fi
1015 .if n \{\
1016 .RE
1017 .\}
1018 .PP
1019 To copy into a file just the countries whose names start with \*(AqA\*(Aq:
1020 .sp
1021 .if n \{\
1022 .RS 4
1023 .\}
1024 .nf
1025 COPY (SELECT * FROM country WHERE country_name LIKE \*(AqA%\*(Aq) TO \*(Aq/usr1/proj/bray/sql/a_list_countries\&.copy\*(Aq;
1026 .fi
1027 .if n \{\
1028 .RE
1029 .\}
1030 .PP
1031 To copy into a compressed file, you can pipe the output through an external compression program:
1032 .sp
1033 .if n \{\
1034 .RS 4
1035 .\}
1036 .nf
1037 COPY country TO PROGRAM \*(Aqgzip > /usr1/proj/bray/sql/country_data\&.gz\*(Aq;
1038 .fi
1039 .if n \{\
1040 .RE
1041 .\}
1042 .PP
1043 Here is a sample of data suitable for copying into a table from
1044 STDIN:
1045 .sp
1046 .if n \{\
1047 .RS 4
1048 .\}
1049 .nf
1050 AF      AFGHANISTAN
1051 AL      ALBANIA
1052 DZ      ALGERIA
1053 ZM      ZAMBIA
1054 ZW      ZIMBABWE
1055 .fi
1056 .if n \{\
1057 .RE
1058 .\}
1059 .sp
1060 Note that the white space on each line is actually a tab character\&.
1061 .PP
1062 The following is the same data, output in binary format\&. The data is shown after filtering through the Unix utility
1063 \fBod \-c\fR\&. The table has three columns; the first has type
1064 char(2), the second has type
1065 text, and the third has type
1066 integer\&. All the rows have a null value in the third column\&.
1067 .sp
1068 .if n \{\
1069 .RS 4
1070 .\}
1071 .nf
1072 0000000   P   G   C   O   P   Y  \en 377  \er  \en  \e0  \e0  \e0  \e0  \e0  \e0
1073 0000020  \e0  \e0  \e0  \e0 003  \e0  \e0  \e0 002   A   F  \e0  \e0  \e0 013   A
1074 0000040   F   G   H   A   N   I   S   T   A   N 377 377 377 377  \e0 003
1075 0000060  \e0  \e0  \e0 002   A   L  \e0  \e0  \e0 007   A   L   B   A   N   I
1076 0000100   A 377 377 377 377  \e0 003  \e0  \e0  \e0 002   D   Z  \e0  \e0  \e0
1077 0000120 007   A   L   G   E   R   I   A 377 377 377 377  \e0 003  \e0  \e0
1078 0000140  \e0 002   Z   M  \e0  \e0  \e0 006   Z   A   M   B   I   A 377 377
1079 0000160 377 377  \e0 003  \e0  \e0  \e0 002   Z   W  \e0  \e0  \e0  \eb   Z   I
1080 0000200   M   B   A   B   W   E 377 377 377 377 377 377
1081 .fi
1082 .if n \{\
1083 .RE
1084 .\}
1085 .SH "COMPATIBILITY"
1086 .PP
1087 There is no
1088 \fBCOPY\fR
1089 statement in the SQL standard\&.
1090 .PP
1091 The following syntax was used before
1092 PostgreSQL
1093 version 9\&.0 and is still supported:
1094 .sp
1095 .if n \{\
1096 .RS 4
1097 .\}
1098 .nf
1099 COPY \fItable_name\fR [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ]
1100     FROM { \*(Aq\fIfilename\fR\*(Aq | STDIN }
1101     [ [ WITH ]
1102           [ BINARY ]
1103           [ DELIMITER [ AS ] \*(Aq\fIdelimiter_character\fR\*(Aq ]
1104           [ NULL [ AS ] \*(Aq\fInull_string\fR\*(Aq ]
1105           [ CSV [ HEADER ]
1106                 [ QUOTE [ AS ] \*(Aq\fIquote_character\fR\*(Aq ]
1107                 [ ESCAPE [ AS ] \*(Aq\fIescape_character\fR\*(Aq ]
1108                 [ FORCE NOT NULL \fIcolumn_name\fR [, \&.\&.\&.] ] ] ]
1109
1110 COPY { \fItable_name\fR [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ] | ( \fIquery\fR ) }
1111     TO { \*(Aq\fIfilename\fR\*(Aq | STDOUT }
1112     [ [ WITH ]
1113           [ BINARY ]
1114           [ DELIMITER [ AS ] \*(Aq\fIdelimiter_character\fR\*(Aq ]
1115           [ NULL [ AS ] \*(Aq\fInull_string\fR\*(Aq ]
1116           [ CSV [ HEADER ]
1117                 [ QUOTE [ AS ] \*(Aq\fIquote_character\fR\*(Aq ]
1118                 [ ESCAPE [ AS ] \*(Aq\fIescape_character\fR\*(Aq ]
1119                 [ FORCE QUOTE { \fIcolumn_name\fR [, \&.\&.\&.] | * } ] ] ]
1120 .fi
1121 .if n \{\
1122 .RE
1123 .\}
1124 .sp
1125 Note that in this syntax,
1126 BINARY
1127 and
1128 CSV
1129 are treated as independent keywords, not as arguments of a
1130 FORMAT
1131 option\&.
1132 .PP
1133 The following syntax was used before
1134 PostgreSQL
1135 version 7\&.3 and is still supported:
1136 .sp
1137 .if n \{\
1138 .RS 4
1139 .\}
1140 .nf
1141 COPY [ BINARY ] \fItable_name\fR
1142     FROM { \*(Aq\fIfilename\fR\*(Aq | STDIN }
1143     [ [USING] DELIMITERS \*(Aq\fIdelimiter_character\fR\*(Aq ]
1144     [ WITH NULL AS \*(Aq\fInull_string\fR\*(Aq ]
1145
1146 COPY [ BINARY ] \fItable_name\fR
1147     TO { \*(Aq\fIfilename\fR\*(Aq | STDOUT }
1148     [ [USING] DELIMITERS \*(Aq\fIdelimiter_character\fR\*(Aq ]
1149     [ WITH NULL AS \*(Aq\fInull_string\fR\*(Aq ]
1150 .fi
1151 .if n \{\
1152 .RE
1153 .\}
1154 .SH "SEE ALSO"
1155 Section\ \&27.4.3