Описание

COPY перемещает данные между таблицами Tantor BE и файлами в файловой системе. COPY TO копирует содержимое таблицы в файл, а COPY FROM копирует данные из файла в таблицу (добавляя данные к уже существующим в таблице). COPY TO также может копировать результаты запроса SELECT.

Если указан список столбцов, команда COPY TO копирует только данные из указанных столбцов в файл. Для команды COPY FROM каждое поле в файле вставляется в указанный столбец в порядке следования. Столбцы таблицы, не указанные в списке столбцов COPY FROM, получат свои значения по умолчанию.

COPY с указанием имени файла указывает серверу Tantor BE на прямое чтение из файла или запись в файл. Файл должен быть доступен пользователю Tantor BE (ID пользователя, от имени которого работает сервер), и имя файла должно быть указано с точки зрения сервера. Когда указано PROGRAM, сервер выполняет указанную команду и читает из стандартного вывода программы или записывает в стандартный ввод программы. Команда должна быть указана с точки зрения сервера и быть исполняемой пользователем Tantor BE. Когда указано STDIN или STDOUT, данные передаются через соединение между клиентом и сервером.

Каждый запущенный бэкенд, выполняющий команду COPY, будет отображать свой прогресс в представлении pg_stat_progress_copy. Подробности см. в разделе Раздел 26.4.3.

Параметры

Выводы

При успешном выполнении команды COPY возвращается тег команды в следующем формате:

COPY count

count - это количество скопированных строк.

Примечания

COPY TO может использоваться только с обычными таблицами, а не с представлениями, и не копирует строки из дочерних таблиц или дочерних секций. Например, COPY table TO копирует те же строки, что и SELECT * FROM ONLY table. Синтаксис COPY (SELECT * FROM table) TO ... может использоваться для выгрузки всех строк в иерархии наследования, секционированной таблице или представлении.

COPY FROM может использоваться с обычными, внешними или секционированными таблицами или с представлениями, у которых есть триггеры INSTEAD OF INSERT.

Необходимо иметь привилегию на выполнение операции SELECT для таблицы, значения которой считываются с помощью COPY TO, а также привилегию на выполнение операции INSERT для таблицы, в которую значения вставляются с помощью COPY FROM. Достаточно иметь привилегии на столбцы, указанные в команде.

Если для таблицы включена политика защиты на уровне строк, соответствующие политики SELECT будут применяться к операторам COPY table TO. В настоящее время оператор COPY FROM не поддерживается для таблиц с политикой защиты на уровне строк. Вместо этого используйте эквивалентные операторы INSERT.

Файлы, указанные в команде COPY, читаются или записываются непосредственно сервером, а не клиентским приложением. Поэтому они должны находиться на сервере базы данных или быть доступными для нее, а не для клиента. Они должны быть доступными и читаемыми или записываемыми пользователем Tantor BE (ID пользователя, от имени которого работает сервер), а не клиентом. Аналогично, команда, указанная с помощью PROGRAM, выполняется непосредственно сервером, а не клиентским приложением, и должна быть исполняемой пользователем Tantor BE. Команда 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. Чтобы обеспечить переносимость на другие установки Tantor BE, которые могут использовать нестандартные настройки DateStyle, DateStyle должен быть установлен в значение ISO перед использованием COPY TO. Также рекомендуется избегать выгрузки данных с установленным значением IntervalStyle равным sql_standard, поскольку отрицательные значения интервалов могут быть неправильно интерпретированы сервером с другой настройкой IntervalStyle.

Входные данные интерпретируются в соответствии с параметром ENCODING или текущей кодировкой клиента, а выходные данные кодируются в ENCODING или текущей кодировке клиента, даже если данные не проходят через клиент, а считываются или записываются непосредственно сервером из файла.

COPY останавливает операцию при первой ошибке. Это не должно вызывать проблем в случае использования COPY TO, но целевая таблица уже получила ранее строки в COPY FROM. Эти строки не будут видимыми или доступными, но они все еще занимают место на диске. Это может привести к значительному расходованию дискового пространства, если сбой произошел в середине большой операции копирования. Возможно, вам захочется вызвать VACUUM, чтобы восстановить затраченное пространство.

FORCE_NULL и FORCE_NOT_NULL могут быть использованы одновременно для одной и той же колонки. Это приводит к преобразованию пустых строк в кавычках в значения null и пустых строк без кавычек в пустые строки.

Форматы файлов

Примеры

Следующий пример копирует таблицу на клиентскую сторону, используя вертикальную черту (|) в качестве разделителя полей:

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

Совместимость

В стандарте SQL нет оператора COPY.

Следующий синтаксис использовался до версии PostgreSQL 9.0 и до сих пор поддерживается:

COPY table_name [ ( column_name [, ...] ) ]
    FROM { 'filename' | STDIN }
    [ [ WITH ]
          [ BINARY ]
          [ DELIMITER [ AS ] 'delimiter_character' ]
          [ NULL [ AS ] 'null_string' ]
          [ CSV [ HEADER ]
                [ QUOTE [ AS ] 'quote_character' ]
                [ ESCAPE [ AS ] 'escape_character' ]
                [ FORCE NOT NULL column_name [, ...] ] ] ]

COPY { table_name [ ( column_name [, ...] ) ] | ( query ) }
    TO { 'filename' | STDOUT }
    [ [ WITH ]
          [ BINARY ]
          [ DELIMITER [ AS ] 'delimiter_character' ]
          [ NULL [ AS ] 'null_string' ]
          [ CSV [ HEADER ]
                [ QUOTE [ AS ] 'quote_character' ]
                [ ESCAPE [ AS ] 'escape_character' ]
                [ FORCE QUOTE { column_name [, ...] | * } ] ] ]

Обратите внимание, что в этом синтаксисе BINARY и CSV рассматриваются как независимые ключевые слова, а не как аргументы опции FORMAT.

Следующий синтаксис использовался до версии Tantor BE 7.3 и до сих пор поддерживается:

COPY [ BINARY ] table_name
    FROM { 'filename' | STDIN }
    [ [USING] DELIMITERS 'delimiter_character' ]
    [ WITH NULL AS 'null_string' ]

COPY [ BINARY ] table_name
    TO { 'filename' | STDOUT }
    [ [USING] DELIMITERS 'delimiter_character' ]
    [ WITH NULL AS 'null_string' ]

См. также