Next: Large Objects, Previous: Retrieving Data, Up: Top [Contents][Index]
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.
Optional arg async? non-#f
means don’t block
if there is no data available yet.
Return the number of data bytes in the row (always greater
than zero); zero to mean the COPY
is still in progress
and no data is yet available; -1
to mean the COPY
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.
This procedure is obsolete and WILL BE REMOVED by 2013-12-31.
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 procedure is obsolete and WILL BE REMOVED by 2013-12-31.
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, the
pg-endcopy
procedure should be called for this
connection before any further pg-exec
call is made.
Return #t
if successful.
This procedure is obsolete and WILL BE REMOVED by 2013-12-31.
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
or pg-putline
. Return #t
if successful.
This procedure is obsolete and WILL BE REMOVED by 2013-12-31.
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:
To specify a disabled flag, use no-FLAG, e.g.,
no-header
. Recognized keys:
Display result on the current output port.
Optional second arg options is an
object returned by pg-make-print-options
that
specifies various parameters of the output format.
Next: Large Objects, Previous: Retrieving Data, Up: Top [Contents][Index]