Next: , Previous: Retrieving Data, Up: Top


5 Procedures for Copying Data

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.

— Procedure: pg-put-copy-data conn data

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.

— Procedure: pg-put-copy-end conn [errmsg]

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.

— Procedure: pg-get-copy-data conn port [asyncp]

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.

Obsolete functions for COPY

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.

— Procedure: pg-getline conn

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.

— Procedure: pg-getlineasync conn buf [tickle]

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.

Example

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)))))))

Notes

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.

— Procedure: pg-putline conn str

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.

Example

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)))))))
— Procedure: pg-endcopy conn

Resynchronize with the backend process. 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.

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.

— Procedure: pg-make-print-options spec

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:

To specify a disabled flag, use no-FLAG, e.g.,no-header. Recognized keys:

— Procedure: pg-print result [options]

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.