COPY
COPY — копировать данные между файлом и таблицей
Синтаксис
COPYимя_таблицы
[ (имя_столбца
[, ...] ) ] FROM { 'имя_файла
' | PROGRAM 'команда
' | STDIN } [ [ WITH ] (параметр
[, ...] ) ] [ WHEREусловие
] COPY {имя_таблицы
[ (имя_столбца
[, ...] ) ] | (query
) } TO { 'имя_файла
' | PROGRAM 'команда
' | STDOUT } [ [ WITH ] (параметр
[, ...] ) ] Здесь допускаетсяпараметр
: FORMATимя_формата
FREEZE [boolean
] DELIMITER 'символ_разделитель
' NULL 'маркер_NULL
' DEFAULT 'строка_по_умолчанию
' HEADER [boolean
| MATCH ] QUOTE 'символ_кавычек
' ESCAPE 'символ_экранирования
' FORCE_QUOTE { (имя_столбца
[, ...] ) | * } FORCE_NOT_NULL { (имя_столбца
[, ...] ) | * } FORCE_NULL { (имя_столбца
[, ...] ) | * } ON_ERRORобработка_ошибки
ENCODING 'имя_кодировки
' LOG_VERBOSITYуровень_детализации
Описание
COPY
перемещает данные между таблицами Postgres Pro и обычными файлами в файловой системе. COPY TO
копирует содержимое таблицы в файл, а COPY FROM
— из файла в таблицу (добавляет данные к тем, что уже содержались в таблице). COPY TO
может также скопировать результаты запроса SELECT
.
Если указывается список столбцов, COPY TO
копирует в файл только данные указанных столбцов, а COPY FROM
вставляет каждое поле из файла в соответствующий ему по порядку столбец из указанного списка. В случае отсутствия в этом списке каких-либо столбцов таблицы при COPY FROM
они получают значения по умолчанию.
COPY
с именем файла указывает серверу Postgres Pro читать или записывать непосредственно этот файл. Заданный файл должен быть доступен пользователю Postgres Pro (тому пользователю, от имени которого работает сервер), и путь к файлу должен задаваться с точки зрения сервера. Когда указывается параметр PROGRAM
, сервер выполняет заданную команду и читает данные из стандартного вывода программы, либо записывает их в стандартный ввод. Команда должна определяться с точки зрения сервера и быть доступной для исполнения пользователю Postgres Pro. Когда указывается STDIN
или STDOUT
, данные передаются через соединение клиента с сервером.
Каждый процесс, выполняющий операцию COPY
, будет выдавать информацию о ходе её выполнения, отображаемую в представлении pg_stat_progress_copy
. За подробностями обратитесь к Подразделу 26.4.3.
При возникновении ошибок команда COPY
по умолчанию прерывается. Однако когда необходимо загрузить файл целиком, несмотря на ошибки, можно использовать предложение ON_ERROR
, чтобы указывать, как обработать то или иное поведение.
Параметры
имя_таблицы
Имя существующей таблицы (возможно, дополненное схемой).
имя_столбца
Необязательный список столбцов, данные которых будут копироваться. Если этот список отсутствует, копируются все столбцы таблицы, за исключением генерируемых.
query
Команда
SELECT
,VALUES
,INSERT
,UPDATE
,DELETE
илиMERGE
, результаты которой будут скопированы. Запрос должен заключаться в скобки.Для запросов
INSERT
,UPDATE
,DELETE
иMERGE
должно задаваться предложениеRETURNING
и в целевом отношении не должно быть условного правила, правилаALSO
или правилаINSTEAD
, разворачивающегося в несколько операторов.имя_файла
Путь входного или выходного файла. Путь входного файла может быть абсолютным или относительным, но путь выходного должен быть только абсолютным. Пользователям Windows следует использовать формат
E''
и продублировать каждую обратную черту в пути файла.PROGRAM
Выполняемая команда.
COPY FROM
читает стандартный вывод команды, аCOPY TO
записывает в её стандартный ввод.Заметьте, что команда запускается через командную оболочку, так что если требуется передать какие-либо аргументы, поступающие из недоверенного источника, необходимо аккуратно избавиться от всех спецсимволов, имеющих особое значение в оболочке, либо экранировать их. По соображениям безопасности лучше ограничиться фиксированной строкой команды или как минимум не позволять пользователям вводить в неё произвольное содержимое.
STDIN
Указывает, что данные будут поступать из клиентского приложения.
STDOUT
Указывает, что данные будут выдаваться клиентскому приложению.
boolean
Включает или отключает заданный параметр. Для включения параметра можно написать
TRUE
,ON
или1
, а для отключения —FALSE
,OFF
или0
. Значениеboolean
можно опустить, в этом случае подразумеваетсяTRUE
.FORMAT
Выбирает формат чтения или записи данных:
text
(текстовый),csv
(значения, разделённые запятыми, Comma Separated Values) илиbinary
(двоичный). По умолчанию выбирается форматtext
.FREEZE
Запросы копируют данные с уже замороженными строками, как после выполнения команды
VACUUM FREEZE
. Это позволяет увеличить производительность при начальном добавлении данных. Строки будут замораживаться, только если загружаемая таблица была создана или опустошена в текущей подтранзакции, с ней не связаны открытые курсоры и в данной транзакции нет других снимков. ВыполнятьCOPY FREEZE
с секционированной таблицей в настоящее время нельзя. Допускается только использование сCOPY FROM
.Заметьте, что все другие сеансы будут немедленно видеть данные, как только они будут успешно загружены. Это нарушает принятые правила видимости MVCC, так что пользователи должны понимать, какие проблемы это может вызвать.
DELIMITER
Задаёт символ, разделяющий столбцы в строках файла. По умолчанию это символ табуляции в текстовом формате и запятая в формате
CSV
. Задаваемый символ должен быть однобайтовым. Для форматаbinary
этот параметр не допускается.NULL
Определяет строку, задающую значение NULL. По умолчанию в текстовом формате это
\N
(обратная косая черта и N), а в форматеCSV
— пустая строка без кавычек. Пустую строку можно использовать и в текстовом формате, если не требуется различать пустые строки и NULL. Для форматаbinary
этот параметр не допускается.Примечание
При выполнении
COPY FROM
любые значения, совпадающие с этой строкой, сохраняются как значение NULL, так что при переносе данных важно убедиться в том, что это та же строка, что применялась вCOPY TO
.DEFAULT
Задаёт строку, представляющую значение по умолчанию. Каждый раз, когда указанная строка встречается во входном файле, вычисляется значение по умолчанию для соответствующего столбца. Этот параметр допускается только в команде
COPY FROM
и только не для форматаbinary
.HEADER
Указывает, что файл содержит строку заголовка с именами каждого столбца в файле. При выводе первая строка будет содержать имена столбцов из таблицы. При вводе первая строка отбрасывается, если для этого параметра установлено значение
true
(или равнозначное логическое значение). Если для этого параметра установлено значениеMATCH
, имена столбцов (и их количество) в строке заголовка должны совпадать с фактическими именами столбцов таблицы по порядку, иначе возникнет ошибка. Этот параметр не допускается при использовании форматаbinary
. ПараметрMATCH
действителен только для командCOPY FROM
.QUOTE
Указывает символ кавычек, используемый для заключения данных в кавычки. По умолчанию это символ двойных кавычек. Задаваемый символ должен быть однобайтовым. Этот параметр поддерживается только для формата
CSV
.ESCAPE
Задаёт символ, который будет выводиться перед символом данных, совпавшим со значением
QUOTE
. По умолчанию это тот же символ, что иQUOTE
(то есть, при появлении в данных кавычек, они дублируются). Задаваемый символ должен быть однобайтовым. Этот параметр допускается только для режимаCSV
.FORCE_QUOTE
Принудительно заключает в кавычки все значения не
NULL
в указанных столбцах. Выводимое значениеNULL
никогда не заключается в кавычки. Если указано*
, в кавычки будут заключаться значения неNULL
во всех столбцах. Этот параметр принимает только командаCOPY TO
и только для форматаCSV
.FORCE_NOT_NULL
Не сопоставлять значения в указанных столбцах с маркером NULL. По умолчанию, когда маркер пуст, это означает, что пустые значения будут считаны как строки нулевой длины, а не NULL, даже когда они не заключены в кавычки. При указании
*
параметр применяется ко всем столбцам. Этот параметр допускается только в командеCOPY FROM
и только для форматаCSV
.FORCE_NULL
Сопоставлять значения в указанных столбцах с маркером NULL, даже если они заключены в кавычки, и в случае совпадения устанавливать значение
NULL
. По умолчанию, когда этот маркер пуст, пустая строка в кавычках будет преобразовываться в NULL. При указании*
параметр применяется ко всем столбцам. Этот параметр допускается только в командеCOPY FROM
и только для форматаCSV
.ON_ERROR
Указывает, как обрабатывать ошибку при преобразовании входящих значений в тип данных столбца. При значении
stop
параметраобработка_ошибки
команда завершается с ошибкой, в то время как при значенииignore
входящая строка пропускается и происходит переход к следующей. Значение по умолчанию:stop
.Значение
ignore
можно применить только для командыCOPY FROM
, если уFORMAT
стоит значениеtext
илиcsv
.Если была пропущена хотя бы одна строчка, в конце команды
COPY FROM
выводится сообщениеNOTICE
с числом пропущенных строк. При значенииverbose
параметраLOG_VERBOSITY
сообщениеNOTICE
выводится для каждой пропущенной строки и содержит строку входящего файла и имя столбца, где преобразование завершилось с ошибкой.ENCODING
Указывает, что файл имеет кодировку
имя_кодировки
. Если этот параметр опущен, выбирается текущая кодировка клиента. Подробнее об этом говорится ниже, в примечаниях.LOG_VERBOSITY
Указывает количество сообщений, выводимых командой
COPY
, возможные значения:default
илиverbose
. При значенииverbose
во время работы команды выводятся дополнительные сообщения.На данный момент это используется для команды
COPY FROM
при значенииignore
параметраON_ERROR
.WHERE
Необязательное предложение
WHERE
имеет общую формуWHERE
условие
, где
условие
— любое выражение, выдающее результат типаboolean
. Строки, не удовлетворяющие этому условию, добавляться в таблицу не будут. Строка удовлетворяет условию, если оно возвращает true при подстановке вместо ссылок на переменные фактических значений из этой строки.В настоящее время выражения
WHERE
не могут включать подзапросы, а при вычислении выражений не видны изменения, которые вносит сама командаCOPY
(это играет роль, когда в них вызываются функции с характеристикойVOLATILE
).
Выводимая информация
В случае успешного завершения, COPY
возвращает метку команды в виде
COPY число
Здесь число
— количество скопированных записей.
Примечание
psql выводит эту метку, только если выполнялась не команда COPY ... TO STDOUT
или её аналог в psql, метакоманда \copy ... to stdout
. Это сделано для того, чтобы метка команды не смешалась с данными, выведенными перед ней.
Примечания
Команду COPY TO
можно использовать только с простыми таблицами, не представлениями, и при этом она не копирует строки из дочерних таблиц или секций. То есть, COPY
копирует те же строки, что выдаёт запрос таблица
TOSELECT * FROM ONLY
. Для выгрузки всех строк представления или таблицы с учётом иерархии наследования или секционирования можно применить таблица
COPY (SELECT * FROM
.таблица
) TO ...
COPY FROM
можно применять с обычными, сторонними и секционированными таблицами или представлениями, в которых установлены триггеры INSTEAD OF INSERT
.
В таблице, данные которой читает команда COPY TO
, требуется иметь право на выборку данных, а в таблице, куда вставляет значения COPY FROM
, требуется право на добавление. При этом, если в команде перечисляются избранные столбцы, достаточно иметь права только для них.
Если для таблицы включена защита на уровне строк, соответствующие политики SELECT
будут применяться и к операторам COPY
. Операторы таблица
TOCOPY FROM
для таблиц с защитой строк в настоящее время не поддерживаются. Вместо них следует использовать равнозначные операторы INSERT
.
Файлы, указанные в команде COPY
, читаются или записываются непосредственно сервером, не клиентским приложением. Поэтому они должны располагаться на сервере или быть доступными серверу, а не клиенту. Они должны быть доступны на чтение или запись пользователю Postgres Pro (пользователю, от имени которого работает сервер), не клиенту. Аналогично, команда, указанная параметром PROGRAM
, выполняется непосредственно сервером, а не клиентским приложением, и должна быть доступна на выполнение пользователю Postgres Pro. Выполнять COPY
с указанием файла или внешней команды разрешено только суперпользователям базы данных или членам ролей pg_read_server_files
, pg_write_server_files
или pg_execute_server_program
, так как это позволяет читать/записывать любые файлы и запускать любые программы, к которым имеет доступ сервер.
Не путайте команду COPY
с реализованной в psql метакомандой \copy
. Метакоманда \copy
вызывает COPY FROM STDIN
или COPY TO STDOUT
, а затем работает с данными в файле, доступном клиенту psql. Таким образом, когда применяется команда \copy
, доступность файла и права доступа зависят от клиента, а не от сервера.
Путь файла, указываемый в COPY
, рекомендуется всегда задавать как абсолютный, а не относительный. Это обязательное условие для команды COPY TO
, но COPY FROM
позволяет прочитать файл, заданный и относительным путём. Такой путь будет интерпретироваться относительно рабочего каталога серверного процесса (обычно это каталог данных кластера), а не рабочего каталога клиента.
Выполнение команды в PROGRAM
может быть ограничено и другими работающими в ОС механизмами контроля доступа, например SELinux.
COPY FROM
вызывает все триггеры и обрабатывает все ограничения-проверки в целевой таблице. Однако правила при загрузке данных не вызываются.
Для столбцов идентификации команда COPY FROM
всегда переносит значения, содержащиеся во входных данных, как команда INSERT
с указанием OVERRIDING SYSTEM VALUE
.
При вводе и выводе данных COPY
учитывается DateStyle
. Для обеспечения переносимости на другие инсталляции Postgres Pro, в которых могут использоваться нестандартные значения DateStyle
, значение DateStyle
следует установить равным ISO
до вызова COPY TO
. Также рекомендуется не выгружать данные с IntervalStyle
равным sql_standard
, так как сервер с другим значением IntervalStyle
может неправильно воспринимать отрицательные интервалы в таких данных.
Входные данные интерпретируются согласно кодировке, заданной параметром ENCODING
, или текущей кодировке клиента, а выходные кодируются в кодировке ENCODING
или текущей кодировке клиента, даже если данные не проходят через клиента, а считываются или записываются в файл непосредственно сервером.
Во время работы команда COPY FROM
вставляет входящие строки в таблицу. В случае сбоя эти строки остаются в удалённом состоянии: они не будут видимыми и доступными, но будут занимать место на диске. Если сбой происходит при копировании большого объёма данных, это может приводить к значительным потерям дискового пространства. При желании вернуть потерянный объём, это можно сделать с помощью команды VACUUM
.
FORCE_NULL
и FORCE_NOT_NULL
можно применить одновременно к одному столбцу. В результате NULL-значения в кавычках будут преобразованы в NULL, а NULL-значения без кавычек — в пустые строки.
Postgres Pro не принимает нулевые байты в данных. Если вы хотите импортировать такие данные с помощью команды COPY FROM
, вы можете определить в параметре конфигурации nul_byte_replacement_on_import ASCII-символ для замены нулевых байтов на лету.
Форматы файлов
Текстовый формат
Когда применяется формат text, читаемые или записываемые данные представляют собой текстовый файл, строка в котором соответствует строке таблицы. Столбцы в строке разделяются символом-разделителем. Значения самих столбцов — текстовые строки, выдаваемые функцией вывода, либо воспринимаемые функцией ввода, соответствующей типу данных столбца. Заданный маркер NULL выводится и считывается вместо столбцов со значением NULL. COPY FROM
выдаёт ошибку, если в любой из строк во входном файле оказывается больше или меньше столбцов, чем ожидается.
Конец данных может обозначаться одной строкой, содержащей только обратную косую и точку (\.
). Маркер конца данных не требуется при чтении из файла, так как его роль вполне выполняет конец файла; он необходим только при передаче данных в/из клиентского приложения по протоколу обмена до версии 3.0.
Символы обратной косой черты (\
) в данных COPY
позволяют экранировать символы данных, которые без них считались бы разделителями строк или столбцов. В частности, предваряться обратной косой должны следующие символы, когда они оказываются в значении столбца: сама обратная косая черта, перевод строки, возврат каретки и текущий разделитель.
Маркер NULL передаётся команде COPY TO
как есть, без добавления обратной косой; COPY FROM
, со своей стороны, ищет во вводимых данных маркеры NULL до удаления обратных косых. Таким образом, маркер NULL, например такой как \N
, отличается от значения \N
в данных (оно должно представляться в виде \\N
).
Команда COPY FROM
распознаёт следующие спецпоследовательности:
Последовательность | Представляет |
---|---|
\b | Забой (ASCII 8) |
\f | Подача формы (ASCII 12) |
\n | Новая строка (ASCII 10) |
\r | Возврат каретки (ASCII 13) |
\t | Табуляция (ASCII 9) |
\v | Вертикальная табуляция (ASCII 11) |
\ цифры | Обратная косая с последующими 1–3 восьмеричными цифрами представляет байт с заданным числовым кодом |
\x цифры | Обратная косая с последующим x и 1-2 шестнадцатеричными цифрами представляет байт с заданным числовым кодом |
В настоящее время COPY TO
никогда не выводит спецпоследовательности с восьмеричными или шестнадцатеричными кодами, однако выводит другие вышеперечисленные спецпоследовательности вместо управляющих символов.
Любой другой символ после обратной косой, отсутствующий в приведённой выше таблице, будет представлять себя. Однако опасайтесь излишнего добавления обратных косых, так как это может привести к случайному образованию строки, обозначающей маркер конца данных (\.
) или маркер NULL (\N
по умолчанию). Эти строки будут восприняты прежде, чем обработаются спецпоследовательности с обратной косой.
В приложениях, генерирующих данные для COPY
, настоятельно рекомендуется преобразовать символы новой строки и возврата каретки в последовательности \n
и \r
, соответственно. В настоящее время можно представить возврат каретки в данных как обратная косая и возврат каретки, а перевод строки как обратная косая и перевод строки, однако это может не поддерживаться в будущих версиях. Такие символы также подвержены искажениям, если файл с выводом COPY
переносится между разными системами (например, с Unix в Windows и наоборот).
Все последовательности с обратной косой чертой обрабатываются после преобразования кодировки. Байты, заданные в таких последовательностях восьмеричными или шестнадцатеричными цифрами, должны представлять допустимые символы в кодировке базы данных.
COPY TO
завершает каждую строку символом новой строки в стиле Unix («\n
»). Серверы, работающие в Microsoft Windows, вместо этого выводят символы возврат каретки/новая строка («\r\n
»), но только при выводе COPY
в файл на сервере; для согласованности на разных платформах, COPY TO STDOUT
всегда передаёт «\n
», вне зависимости от платформы сервера. COPY FROM
может воспринимать строки, завершающиеся символами новая строка, перевод каретки, либо возврат каретки+новая строка. Чтобы уменьшить риск ошибки из-за неэкранированных символов новой строки и возврата каретки, которые должны были быть данными, COPY FROM
сигнализирует о проблеме, если концы строк во входных данных различаются.
Формат CSV
Этот формат применяется для импорта и экспорта данных в виде списка значений, разделённых запятыми (CSV
), с которым могут работать многие другие программы, например электронные таблицы. Вместо правил экранирования значений, введённых в Postgres Pro для текстового формата, этот формат использует стандартный механизм экранирования CSV
.
Значения в каждой записи разделяются символами DELIMITER
. Если значение содержит символ разделителя, символ QUOTE
, маркер NULL
, символ возврата каретки или перевода строки, то всё значение дополнятся спереди и сзади символами QUOTE
, а любое вхождение символа QUOTE
или спецсимвола (ESCAPE
) в данных предваряется спецсимволом. С указанием FORCE_QUOTE
в кавычки будут принудительно заключаться любые значения не NULL
в указанных столбцах.
В формате CSV
отсутствует стандартный способ отличить значение NULL
от пустой строки. В Postgres Pro команда COPY
решает это с помощью кавычек. Значение NULL
выводится в виде строки, задаваемой параметром NULL
, и не заключается в кавычки, тогда как значение не NULL
, со строкой, задаваемой параметром NULL
, заключается. Например, с параметрами по умолчанию NULL
записывается в виде пустой строки без кавычек, тогда как пустая строка записывается в двойных кавычках (""
). При чтении значений действуют похожие правила. Указание FORCE_NOT_NULL
позволяет избежать сравнений на NULL
во входных данных в заданных столбцах, а FORCE_NULL
— преобразовывать в NULL
маркеры NULL, даже заключённые в кавычки.
Так как обратная косая черта не является спецсимволом в формате CSV
, маркер конца данных \.
может быть и значением данных. Во избежание ошибок интерпретации данные \.
, выводимые в виде единственного элемента строки, автоматически заключаются в кавычки при выводе, а при вводе этот маркер, заключённый в кавычки, не воспринимается как маркер конца данных. При загрузке файла, созданного другой программой, в котором в единственном столбце без кавычек оказалось значение \.
, потребуется дополнительно заключить это значение в кавычки.
Примечание
В формате CSV
все символы являются значимыми. Заключённое в кавычки значение, дополненное пробелами или любыми другими символами, кроме DELIMITER
, будет включать и эти символы. Это может приводить к ошибкам при импорте данных из системы, дополняющей строки CSV
пробельными символами до некоторой фиксированной ширины. В случае возникновения такой проблемы необходимо обработать файл CSV
и удалить из него замыкающие пробельные символы, прежде чем загружать данные из него в Postgres Pro.
Примечание
Обработчик формата CSV
воспринимает и генерирует файлы CSV
со значениями в кавычках, которые могут содержать символы возврата каретки и перевода строки. Таким образом, число строк в этих файлах не строго равно числу строк в таблице, как в файлах текстового формата.
Примечание
Многие программы генерируют странные и иногда неприемлемые файлы CSV
, так что этот формат используется скорее по соглашению, чем по стандарту. Поэтому вам могут встретиться файлы, которые невозможно импортировать, используя этот механизм, а COPY
может сформировать такие файлы, что их не смогут обработать другие программы.
Двоичный формат
При выборе формата binary
все данные сохраняются/считываются в двоичном, а не текстовом виде. Иногда этот формат обрабатывается быстрее, чем текстовый и CSV
, но он может оказаться непереносимым между разными машинными архитектурами и версиями Postgres Pro. Кроме того, двоичный формат сильно зависит от типов данных; например, он не позволяет вывести данные из столбца smallint
, а затем прочитать их в столбец integer
, хотя с текстовым форматом это вполне возможно.
Формат binary
включает заголовок файла, ноль или более записей, содержащих данные строк, и окончание файла. Для заголовков и данных принят сетевой порядок байт.
Примечание
В PostgreSQL до версии 7.4 использовался другой двоичный формат.
Заголовок файла
Заголовок файла содержит 15 байт фиксированных полей, за которыми следует область расширения заголовка переменной длины. Фиксированные поля:
- Сигнатура
Последовательность из 11 байт
PGCOPY\n\377\r\n\0
— заметьте, что нулевой байт является обязательной частью сигнатуры. (Эта сигнатура позволяет легко выявить файлы, испорченные при передаче, не сохраняющей все 8 бит данных. Она изменится при прохождении через фильтры, меняющие концы строк, отбрасывающие нулевые байты или старшие биты, либо добавляющие чётность.)- Поле флагов
Маска из 32 бит, обозначающая важные аспекты формата файла. Биты нумеруются от 0 (LSB) до 31 (MSB). Учтите, что это поле хранится в сетевом порядке байт (наиболее значащий байт первый), как и все целочисленные поля в этом формате. Биты 16–31 зарезервированы для обозначения критичных особенностей формата; обработчик должен прервать чтение, встретив любой неожиданный бит в этом диапазоне. Биты 0–15 зарезервированы для обозначения особенностей, связанных с обратной совместимостью; обработчик может просто игнорировать любые неожиданные биты в этом диапазоне. В настоящее время определён только один битовый флаг, остальные должны быть равны 0:
- Бит 16
При 1 в данные включается OID, при 0 — не включается. Системные столбцы oid в Postgres Pro больше не поддерживаются, но этот индикатор всё ещё сохраняется.
- Длина области расширения заголовка
Целое 32-битное число, определяющее длину в байтах остального заголовка, не включая само это значение. В настоящее время содержит 0, и сразу за ним следует первая запись. При будущих изменениях формата в заголовок могут быть добавлены дополнительные данные. Обработчик должен просто пропускать все расширенные данные заголовка, о которых ему ничего не известно.
Область расширения заголовка предусмотрена для размещения последовательности самоопределяемых блоков. Поле флагов не должно содержать указаний о том, что содержится в области расширения. Точное содержимое области расширения может быть определено в будущих версиях.
При таком подходе возможно как обратно-совместимое дополнение заголовка (добавить блоки расширения заголовка или установить младшие биты флагов), так и не обратно-совместимое (установить старшие биты флагов, сигнализирующие о подобном изменении, и добавить вспомогательные данные в область расширения, если это потребуется).
Записи
Каждая запись начинается с 16-битного целого числа, определяющего количество полей в записи. (В настоящее время во всех записях должно быть одинаковое число полей, но так может быть не всегда.) Затем, для каждого поля в записи указывается 32-битная длина поля, за которой следует это количество байт с данными поля. (Значение длины не включает свой размер, и может быть равно нулю.) В качестве особого варианта, -1 обозначает, что в поле содержится NULL. В случае с NULL за длиной не следуют байты данных.
Выравнивание или какие-либо дополнительные данные между полями не вставляются.
В настоящее время предполагается, что все значения данных в файле двоичного формата содержатся в двоичном формате (формате под кодом 1). Возможно, в будущем расширении в заголовок будет добавлено поле, позволяющее задавать другие коды форматов для разных столбцов.
Если в файл включается OID, поле OID следует немедленно за числом, определяющим количество полей. Это поле не отличается от других ничем, кроме того, что оно не учитывается в количестве полей. Заметьте, что в текущих версиях Postgres Pro системные столбцы oid не поддерживаются.
Окончание файла
Окончание файла состоит из 16-битного целого, содержащего -1. Это позволяет легко отличить его от счётчика полей в записи.
Обработчик, читающий файл, должен выдать ошибку, если число полей в записи не равно -1 или ожидаемому числу столбцов. Это обеспечивает дополнительную проверку синхронизации данных.
Примеры
В следующем примере таблица передаётся клиенту с разделителем полей «вертикальная черта» (|
):
COPY country TO STDOUT (DELIMITER '|');
Копирование данных из файла в таблицу country
:
COPY country FROM '/usr1/proj/bray/sql/country_data';
Копирование в файл только данных стран, название которых начинается с 'A':
COPY (SELECT * FROM country WHERE country_name LIKE 'A%') TO '/usr1/proj/bray/sql/a_list_countries.copy';
Для копирования данных в сжатый файл можно направить вывод через внешнюю программу сжатия:
COPY country TO PROGRAM 'gzip > /usr1/proj/bray/sql/country_data.gz';
Пример данных, подходящих для копирования в таблицу из STDIN
:
AF AFGHANISTAN AL ALBANIA DZ ALGERIA ZM ZAMBIA ZW ZIMBABWE
Примечание: пробелы в каждой строке на самом деле обозначают символы табуляции.
Ниже приведены те же данные, но выведенные в двоичном формате. Данные показаны после обработки Unix-утилитой od -c
. Таблица содержит три столбца; первый имеет тип char(2)
, второй — text
, а третий — integer
. Последний столбец во всех строках содержит NULL.
0000000 P G C O P Y \n 377 \r \n \0 \0 \0 \0 \0 \0 0000020 \0 \0 \0 \0 003 \0 \0 \0 002 A F \0 \0 \0 013 A 0000040 F G H A N I S T A N 377 377 377 377 \0 003 0000060 \0 \0 \0 002 A L \0 \0 \0 007 A L B A N I 0000100 A 377 377 377 377 \0 003 \0 \0 \0 002 D Z \0 \0 \0 0000120 007 A L G E R I A 377 377 377 377 \0 003 \0 \0 0000140 \0 002 Z M \0 \0 \0 006 Z A M B I A 377 377 0000160 377 377 \0 003 \0 \0 \0 002 Z W \0 \0 \0 \b Z I 0000200 M B A B W E 377 377 377 377 377 377
Совместимость
Оператор COPY
отсутствует в стандарте SQL.
До версии PostgreSQL 9.0 использовался и по-прежнему поддерживается следующий синтаксис:
COPYимя_таблицы
[ (имя_столбца
[, ...] ) ] FROM { 'имя_файла
' | STDIN } [ [ WITH ] [ BINARY ] [ DELIMITER [ AS ] 'символ_разделитель
' ] [ NULL [ AS ] 'маркер_NULL
' ] [ CSV [ HEADER ] [ QUOTE [ AS ] 'символ_кавычек
' ] [ ESCAPE [ AS ] 'символ_экранирования
' ] [ FORCE NOT NULLимя_столбца
[, ...] ] ] ] COPY {имя_таблицы
[ (имя_столбца
[, ...] ) ] | (запрос
) } TO { 'имя_файла
' | STDOUT } [ [ WITH ] [ BINARY ] [ DELIMITER [ AS ] 'символ_разделитель
' ] [ NULL [ AS ] 'маркер_NULL
' ] [ CSV [ HEADER ] [ QUOTE [ AS ] 'символ_кавычек
' ] [ ESCAPE [ AS ] 'символ_экранирования
' ] [ FORCE QUOTE {имя_столбца
[, ...] | * } ] ] ]
Заметьте, что в этом синтаксисе ключевые слова BINARY
и CSV
обрабатываются как независимые, а не как аргументы параметра FORMAT
.
До версии PostgreSQL 7.3 использовался и по-прежнему поддерживается следующий синтаксис:
COPY [ BINARY ]имя_таблицы
FROM { 'имя_файла
' | STDIN } [ [USING] DELIMITERS 'символ_разделитель
' ] [ WITH NULL AS 'маркер_NULL
' ] COPY [ BINARY ]имя_таблицы
TO { 'имя_файла
' | STDOUT } [ [USING] DELIMITERS 'символ_разделитель
' ] [ WITH NULL AS 'маркер_NULL
' ]