Next: , Previous: Retrieving Data, Up: Top   [Contents][Index]


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 one if ok; zero 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 one if ok; zero 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 [async?]

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.

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.

This procedure is obsolete and WILL BE REMOVED by 2013-12-31.

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.

This procedure is obsolete and WILL BE REMOVED by 2013-12-31.

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.

This procedure is obsolete and WILL BE REMOVED by 2013-12-31.

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

Procedure: pg-make-print-options spec

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:

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.


Next: , Previous: Retrieving Data, Up: Top   [Contents][Index]