34.9. Функции, связанные с командой COPY
Команда COPY
в PostgreSQL имеет возможность читать и записывать данные через сетевое подключение, установленное libpq. Описанные в этом разделе функции позволяют приложениям воспользоваться этой возможностью для передачи или приёма копируемых данных.
Общая процедура такова: сначала приложение выдаёт SQL-команду COPY
, вызывая PQexec
или одну из подобных функций. В ответ оно должно получить (если не возникла ошибка) объект PGresult
с кодом состояния PGRES_COPY_OUT
или PGRES_COPY_IN
(в зависимости от направления копирования). Затем приложение должно использовать функции, описанные в этом разделе, и принимать или передавать строки данных. По завершении передачи возвращается ещё один объект PGresult
, сообщающий о состоянии завершения передачи. В случае успеха он содержит код состояния PGRES_COMMAND_OK
, а если возникает какая-то проблема — PGRES_FATAL_ERROR
. После этого можно продолжать выполнять SQL-команды через PQexec
. (Пока операция COPY
не завершена, выполнять другие SQL-команды через то же подключение нельзя.)
Если команда COPY
была выполнена через PQexec
в строке, содержащей дополнительные команды, приложение должно продолжить получать результаты через PQgetResult
после завершения последовательности COPY
. Только когда PQgetResult
возвращает NULL
, можно с уверенностью считать, что командная строка PQexec
выполнена полностью, и безопасно передавать другие команды.
Функции, описанные в этом разделе, должны выполняться только после получения кода состояния PGRES_COPY_OUT
или PGRES_COPY_IN
от функции PQexec
или PQgetResult
.
Объект PGresult
с таким кодом состояния содержит дополнительные данные о начавшейся операции COPY
. Эти данные можно получить функциями, также применяющимися при обработке результатов запроса:
-
PQnfields
Возвращает число копируемых столбцов (полей).
-
PQbinaryTuples
Значение 0 указывает, что для всей операции копирования применяется текстовый формат (строки разделяются символами новой строки, столбцы разделяются символами-разделителями и т. д.). Значение 1 указывает, что для всей операции копирования применяется двоичный формат. За дополнительными сведениями обратитесь к COPY.
-
PQfformat
Возвращает код формата (0 — текстовый, 1 — двоичный), связанный с каждым копируемым столбцом. Коды форматов столбцов всегда будут нулевыми, если общий формат копирования — текстовый, но с двоичным форматом поддерживаются и текстовые, и двоичные столбцы. (Однако в текущей реализации
COPY
при двоичном копировании столбцы могут быть только двоичными, так что форматы столбцов должны всегда соответствовать общему формату.)
Примечание
Эти дополнительные значения данных доступны только при использовании протокола 3.0. С протоколом 2.0 все эти функции возвращают 0.
34.9.1. Функции для передачи данных COPY
Эти функции применяются для передачи данных при операции COPY FROM STDIN
. Они не будут работать, если подключение находится не в состоянии COPY_IN
.
-
PQputCopyData
Отправляет данные на сервер, когда активно состояние
COPY_IN
.int PQputCopyData(PGconn *conn, const char *buffer, int nbytes);
Передаёт серверу данные
COPY
из указанного буфера (buffer
), длинойnbytes
байт. Она возвращает 1, если данные были переданы, 0, если они не попали в очередь, так как буферы были заполнены (это возможно только в неблокирующем режиме), или -1, если произошла ошибка. (Если возвращено -1, подробности ошибки можно узнать, вызвавPQerrorMessage
. Если получен 0, дождитесь состояния готовности к записи и повторите попытку.)Приложение может разделять поток данных
COPY
на буферизуемые блоки любого удобного размера. Границы буфера не имеют семантического значения при передаче. Содержимое потока данных должно соответствовать формату данных, ожидаемому командойCOPY
; за подробностями обратитесь к COPY.-
PQputCopyEnd
Отправляет признак конца данных на сервер, когда активно состояние
COPY_IN
.int PQputCopyEnd(PGconn *conn, const char *errormsg);
Завершает операцию
COPY_IN
с успешным результатом, если вerrormsg
передаётсяNULL
. Еслиerrormsg
неNULL
, командаCOPY
будет завершена с ошибкой, а сообщением об ошибке будет строка, переданная вerrormsg
. (Однако не следует полагать, что именно это сообщение будет получено от сервера назад, так как сервер мог уже прервать операциюCOPY
по своим причинам. Также заметьте, что принудительный вызов ошибки не работает с соединениями по протоколу версии до 3.0.)Эта функция возвращает 1, если сообщение завершения было передано; в неблокирующем режиме это означает только, что сообщение завершения успешно поставлено в очередь. (Чтобы удостовериться, что данные были успешно отправлены в неблокирующем режиме, следует дождаться готовности к записи и вызывать
PQflush
в цикле, пока она не вернёт ноль.) Нулевой результат означает, что функция не смогла поставить сообщение завершения в очередь по причине заполнения буферов; это возможно только в неблокирующем режиме. (В этом случае нужно дождаться готовности к записи и попытаться вызватьPQputCopyEnd
снова.) Если действительно происходит ошибка, возвращается -1; получить её подробности можно, вызвавPQerrorMessage
.После успешного вызова
PQputCopyEnd
вызовитеPQgetResult
, чтобы узнать окончательный результат командыCOPY
. Ожидать появления этого результата можно обычным образом. Затем вернитесь к обычным операциям.
34.9.2. Функции для приёма данных COPY
Эти функции применяются для получения данных при операции COPY TO STDOUT
. Они не будут работать, если подключение находится не в состоянии COPY_OUT
.
-
PQgetCopyData
Принимает данные от сервера, когда активно состояние
COPY_OUT
.int PQgetCopyData(PGconn *conn, char **buffer, int async);
Запрашивает следующую строку данных с сервера в процессе операции
COPY
. Данные всегда возвращаются строка за строкой; если поступила только часть строки, она не возвращается. Успешное получение строки данных подразумевает выделение блока памяти для этих данных. В параметреbuffer
ей передаётся указатель, отличный отNULL
. По адресу*buffer
записывается указатель на выделенную память, либоNULL
, когда буфер не возвращается. Если буфер результата отличен отNULL
, его следует освободить, когда он станет не нужен, вызвавPQfreemem
.Когда строка получена успешно, возвращается число байт данных в этой строке (это число всегда больше нуля). Возвращаемое строковое значение всегда завершается нулём, хотя это полезно, вероятно, только для текстовой
COPY
. Нулевой результат означает, что операцияCOPY
продолжает выполняться, но строка ещё не готова (это возможно, только когда параметрasync
равен true). Возвращённое значение -1 означает, что командаCOPY
завершена, а -2 показывает, что произошла ошибка (её причину можно узнать с помощьюPQerrorMessage
).Когда параметр
async
равен true (отличен от нуля), функцияPQgetCopyData
не будет блокироваться, ожидая данных; она возвратит ноль, если выполнениеCOPY
продолжается, но полная строка ещё не получена. (В этом случае нужно дождаться готовности к чтению и затем вызватьPQconsumeInput
, прежде чем вызыватьPQgetCopyData
ещё раз.) Когдаasync
равен false (нулю),PQgetCopyData
будет заблокирована до поступления данных или окончания операции.Когда
PQgetCopyData
возвращает -1, вызовитеPQgetResult
, чтобы узнать окончательный результат командыCOPY
. Ожидать появления этого результата можно обычным образом. Затем вернитесь к обычным операциям.
34.9.3. Устаревшие функции для COPY
Эти функции представляют старые методы выполнения операции COPY
. Хотя они продолжают работать, они признаны устаревшими из-за плохой обработки ошибок, неудобных способов обнаружения конца данных и отсутствия поддержки двоичных или неблокирующих передач.
-
PQgetline
Читает передаваемую сервером строку символов, завершающуюся символом новой строки, в буфер (buffer) размера
length
.int PQgetline(PGconn *conn, char *buffer, int length);
Эта функция копирует
length
-1 символов в буфер и преобразует символ конца строки в нулевой байт.PQgetline
возвращаетEOF
в конце ввода, 0, если была прочитана вся строка, и 1, если буфер заполнен, но завершающий символ конца строки ещё не прочитан.Заметьте, что приложение должно проверить, не состоит ли новая строка в точности из двух символов
\.
, что будет означать, что сервер завершил передачу результатов командыCOPY
. Если приложение может принимать строки длиннееlength
-1 символов, необходимо позаботиться о том, чтобы оно корректно распознавало строку\.
(а не воспринимало, например, конец длинной строки данных как завершающую строку).-
PQgetlineAsync
Читает передаваемую сервером строку данных
COPY
в буфер без блокировки.int PQgetlineAsync(PGconn *conn, char *buffer, int bufsize);
Эта функция похожа на
PQgetline
, но может применяться в приложениях, которые должны читать данныеCOPY
асинхронно, то есть, без блокировки. Запустив командуCOPY
и получив ответPGRES_COPY_OUT
, приложение должно вызыватьPQconsumeInput
иPQgetlineAsync
, пока не будет получен сигнал конца данных.В отличие от
PQgetline
, эта функция сама отвечает за обнаружение конца данных.При каждом вызове
PQgetlineAsync
будет возвращать данные, если во входном буфере libpq оказывается полная строка данных. В противном случае никакие данные не возвращаются до поступления остального содержимого строки. Эта функция возвращает -1, если обнаруживается признак завершения копирования, или 0, если данные не получены, или положительное количество возвращённых байт данных. Если возвращается -1, вызывающий код должен затем вызватьPQendcopy
и после этого перейти в обычный режим работы.Возвращаемые данные не будут пересекать границы строк данных. При этом может быть возвращена одна строка целиком. Но если буфер, выделенный вызывающим кодом, оказывается слишком мал для строки, передаваемой сервером, возвращена будет часть строки. Когда передаются текстовые данные, это можно выявить, проверив, содержит ли последний возвращаемый байт символ
\n
. (ДляCOPY
в двоичном формате потребуется собственно разобрать формат данныхCOPY
, чтобы выявить подобную ситуацию.) Возвращаемая строка не завершается нулём. (Если вы хотите получить строку с нулём в конце, передайте вbufsize
число на единицу меньше фактического размера блока.)-
PQputline
Передаёт серверу строку, завершённую нулём. Возвращает 0 в случае успеха, либо
EOF
, если передать строку не удаётся.int PQputline(PGconn *conn, const char *string);
Поток данных
COPY
, передаваемых последовательностью вызововPQputline
, имеет тот же формат, что возвращаетPQgetlineAsync
, за исключением того, что приложения не обязательно должны передавать по одной строке данных за вызовPQputline
; они могут посылать части строк или сразу несколько строк.Примечание
До версии 3.0 протокола PostgreSQL приложение должно было явно отправлять два символа
\.
последней строкой, чтобы сообщить серверу, что оно закончило передачу данныхCOPY
. Хотя это по-прежнему работает, такое поведение считается устаревшим и ожидается, что особое значение\.
будет исключено в будущих версиях. Передав собственно данные, сейчас достаточно вызватьPQendcopy
.-
PQputnbytes
Передаёт серверу строку, не завершённую нулём. Возвращает 0 в случае успеха, либо
EOF
, если передать строку не удаётся.int PQputnbytes(PGconn *conn, const char *buffer, int nbytes);
Поведение этой функции не отличается от
PQputline
, но её буфер данных не должен содержать завершающий ноль, так как для неё число передаваемых байт задаётся непосредственно. Используйте эту функцию для передачи двоичных данных.-
PQendcopy
Производит синхронизацию с сервером.
int PQendcopy(PGconn *conn);
Эта функция ожидает завершения копирования сервером. Её следует вызывать, либо когда серверу была передана последняя строка функцией
PQputline
, либо когда от сервера была получена последняя строка функциейPQgetline
. Если её не вызвать, сервер «потеряет синхронизацию» с клиентом. После завершения этой функции сервер готов принимать следующую команду SQL. В случае успешного завершения возвращается 0, в противном случае — ненулевое значение. (Чтобы получить подробности ошибки при ненулевом значении, вызовитеPQerrorMessage
.)Вызывая
PQgetResult
, приложение должно обрабатывать результатPGRES_COPY_OUT
, в цикле выполняяPQgetline
, а обнаружив завершающую строку, вызватьPQendcopy
. Затем оно должно вернуться к циклуPQgetResult
, и выйти из него, когдаPQgetResult
возвратит нулевой указатель. Подобным образом, получив результатPGRES_COPY_IN
, приложение должно выполнить серию вызововPQputline
, завершить её, вызвавPQendcopy
, а затем вернуться к циклуPQgetResult
. При такой организации обработки командаCOPY
будет корректно выполняться и в составе последовательности команд SQL.Старые приложения обычно передают команду
COPY
черезPQexec
и рассчитывают, что транзакция будет завершена послеPQendcopy
. Это будет работать, только если командаCOPY
является единственной SQL-командой в строке команд.
F.68. uuid-ossp
The uuid-ossp
module provides functions to generate universally unique identifiers (UUIDs) using one of several standard algorithms. There are also functions to produce certain special UUID constants. This module is only necessary for special requirements beyond what is available in core PostgreSQL. See Section 9.14 for built-in ways to generate UUIDs.
This module is considered “trusted”, that is, it can be installed by non-superusers who have CREATE
privilege on the current database.
F.68.1. uuid-ossp
Functions
Table F.42 shows the functions available to generate UUIDs. The relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and RFC 4122 specify four algorithms for generating UUIDs, identified by the version numbers 1, 3, 4, and 5. (There is no version 2 algorithm.) Each of these algorithms could be suitable for a different set of applications.
Table F.42. Functions for UUID Generation
Function Description |
---|
Generates a version 1 UUID. This involves the MAC address of the computer and a time stamp. Note that UUIDs of this kind reveal the identity of the computer that created the identifier and the time at which it did so, which might make it unsuitable for certain security-sensitive applications. |
Generates a version 1 UUID, but uses a random multicast MAC address instead of the real MAC address of the computer. |
Generates a version 3 UUID in the given namespace using the specified input name. The namespace should be one of the special constants produced by the For example: SELECT uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org'); The name parameter will be MD5-hashed, so the cleartext cannot be derived from the generated UUID. The generation of UUIDs by this method has no random or environment-dependent element and is therefore reproducible. |
Generates a version 4 UUID, which is derived entirely from random numbers. |
Generates a version 5 UUID, which works like a version 3 UUID except that SHA-1 is used as a hashing method. Version 5 should be preferred over version 3 because SHA-1 is thought to be more secure than MD5. |
Table F.43. Functions Returning UUID Constants
Function Description |
---|
Returns a “nil” UUID constant, which does not occur as a real UUID. |
Returns a constant designating the DNS namespace for UUIDs. |
Returns a constant designating the URL namespace for UUIDs. |
Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. (This pertains to ASN.1 OIDs, which are unrelated to the OIDs used in Postgres Pro.) |
Returns a constant designating the X.500 distinguished name (DN) namespace for UUIDs. |
F.68.2. Building uuid-ossp
Historically this module depended on the OSSP UUID library, which accounts for the module's name. While the OSSP UUID library can still be found at http://www.ossp.org/pkg/lib/uuid/, it is not well maintained, and is becoming increasingly difficult to port to newer platforms. uuid-ossp
can now be built without the OSSP library on some platforms. On FreeBSD and some other BSD-derived platforms, suitable UUID creation functions are included in the core libc
library. On Linux, macOS, and some other platforms, suitable functions are provided in the libuuid
library, which originally came from the e2fsprogs
project (though on modern Linux it is considered part of util-linux-ng
). When invoking configure
, specify --with-uuid=bsd
to use the BSD functions, or --with-uuid=e2fs
to use e2fsprogs
' libuuid
, or --with-uuid=ossp
to use the OSSP UUID library. More than one of these libraries might be available on a particular machine, so configure
does not automatically choose one.
F.68.3. Author
Peter Eisentraut <peter_e@gmx.net>