Next: Large Objects, Previous: Retrieving Data, Up: Top
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 1 if ok; 0 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 1 if ok; 0 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); or zero to mean the COPY is still in progress and no data is yet available; or -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 STDOUThas 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 STDOUThas 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-#fmeans 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 STDINhas 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-endcopyprocedure should be called for this connection before any furtherpg-execcall is made. Return#tif 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. This procedure must be called after the last line of a table has been transferred using
pg-getline,pg-getlineasyncorpg-putline. Return#tif 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 an opaque 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.