As of PostgreSQL 7.4, you can send arbitrarily-sized chunks of data after
issuing the COPY <table> FROM STDIN
command. Also, both send and
receive (with the COPY <table> TO STDOUT
command) paths can be
performed asynchronously. See below for the older (obsolete) interface.
Send on conn the data (a string). Return one if ok; zero if the server is in nonblocking mode and the attempt would block; and
-1
if an error occurred.
Send an end-of-data indication over conn. Optional arg errmsg is a string, which if present, forces the
COPY
operation to fail with errmsg as the error message. Return one if ok; zero if the server is in nonblocking mode and the attempt would block; and-1
if an error occurred.
Get a line of
COPY
data from conn, writing it to output port. If port is a pair, construct a new string and set its car to the new string. Return the number of data bytes in the row (always greater than zero); zero to mean theCOPY
is still in progress and no data is yet available;-1
to mean theCOPY
is done; or-2
to mean an error occurred.
There are two procedures for reading a line of data associated with the
command COPY <table> TO STDOUT
. For both, when the end-of-copy
marker is recognized, that means the results from the COPY
command
have all been read and pg-endcopy
should be called to resynchronize the
connection before any further calls to pg-exec
on this connection.
Read a line from conn on which a
COPY <table> TO STDOUT
has been issued. Return a string from the connection. A returned string consisting of a backslash followed by a full stop signifies an end-of-copy marker.
Read a line from conn on which a
COPY <table> TO STDOUT
has been issued, into buf (a string). Return-1
to mean end-of-copy marker recognized, or a number (possibly zero) indicating how many bytes of data were read. The returned data may contain at most one newline (in the last byte position). Optional arg tickle non-#f
means to do a “consume input” operation prior to the read.
This example defines two functionally identical procedures that can be used
to retrieve the results of a COPY <table> TO STDOUT
command. The
second procedure optionally displays a list of received chunk sizes, if
passed a third argument.
(define (copy-to-port conn port) (let loop ((line (pg-getline conn))) (if (string=? line "\\.") (pg-endcopy conn) (begin (format port "~A\n" line) (loop (pg-getline conn)))))) (define (copy-to-port-async conn port . show-chunk-sizes?) (let ((buf (make-string 32))) (let loop ((count (pg-getlineasync conn buf)) (chunks '())) (if (< count 0) (begin (or (null? show-chunk-sizes?) (format port "chunk sizes: ~S\n" chunks)) (pg-endcopy conn)) (begin (display (substring buf 0 count) port) (loop (pg-getlineasync conn buf #t) (cons count chunks)))))))
It is an error to call pg-getline
on a connection without first
executing a COPY <table> TO STDOUT
command on that connection.
It is also an error to call pg-getline
after a terminating line has
been received, without an intervening COPY
command being issued on
that connection.
Write a line to the connection on which a
COPY <table> FROM STDIN
has been issued. The lines written should include the final newline characters. The last line should be a backslash, followed by a ‘.’ (full-stop). After this, thepg-endcopy
procedure should be called for this connection before any furtherpg-exec
call is made. Return#t
if successful.
This example defines a procedure copy-from-port
which can be used
to supply data to a COPY <table> FROM STDIN
command.
(use-modules (ice-9 rdelim)) (define (copy-from-port conn port) (let loop ((line (read-line port))) (cond ((eof-object? line) (pg-putline conn "\\.\n") (pg-endcopy conn)) (else (pg-putline conn line) (pg-putline conn "\n") (if (string=? line "\\.") (pg-endcopy conn) (loop (read-line port)))))))
Resynchronize with the backend process on conn. This procedure must be called after the last line of a table has been transferred using
pg-getline
,pg-getlineasync
orpg-putline
. Return#t
if successful.
Although not readily apparent, another form of data copying is formatted
output, which is supported by Guile-PG via the pg-print
procedure and
the accompanying pg-make-print-options
. Together these loosely mimic
the PQprint
functionality provided by libpq.
Return a print options object created from spec, suitable for use with
pg-print
. spec is a list of elements, each either a flag (symbol) or a key-value pair (with the key being a symbol). Recognized flags:
- header: Print output field headings and row count.
- align: Fill align the fields.
- standard: Old brain-dead format.
- html3: Output HTML tables.
- expanded: Expand tables.
To specify a disabled flag, use no-FLAG, e.g.,
no-header
. Recognized keys:
- field-sep String specifying field separator.
- table-opt String specifying HTML table attributes.
- caption String specifying caption to use in HTML table.
- field-names List of replacement field names, each a string.