7 Miscellaneous Procedures

This chapter describes procedures whose name begins with "pg-" that do not necessarily belong in the other chapters.

Procedure: pg-guile-pg-loaded ¶

Return a list of symbols describing the Guile-PG installation. These are basically derived from C preprocessor macros determined at build time by the configure script. Presence of this procedure is also a good indicator that the compiled module (database postgres) is available. You can test this like so:

(false-if-exception (pg-guile-pg-loaded))

Procedure: pg-set-error-verbosity conn verbosity ¶

Set the error verbosity for conn to verbosity. verbosity is a keyword, one of: #:terse, #:default or #:verbose. Return the previous verbosity.

Procedure: pg-trace conn port ¶

Start outputting low-level trace information on the connection conn to port, which must have been opened for writing. Some consider this information more useful for debugging PostgreSQL than for debugging its clients, but as usual, YMMV.

Procedure: pg-untrace conn ¶

Stop tracing on connection conn.

Example

This example defines a pair of procedures trace-on and trace-off which implement a higher-level trace procedure which opens the required file and starts/stops the trace.

(define trace-port (make-object-property))

(define (trace-on conn filename)
  (let ((port (open-output-file filename)))
    (set! (trace-port conn) port)
    (pg-trace conn port)))

(define (trace-off conn)
  (and=> (trace-port conn)
         (lambda (port)
           (close-port port)
           (set! (trace-port conn) #f)
           (pg-untrace conn))))

The next three procedures are for escape processing, changing one single-quote char into two single-quote chars, and so forth. The first two are for data to be sent to the server, the third for data received from the server. If there are problems (when they return #f), you can use pg-error-message to find out what happened.

Procedure: pg-escape-string-conn conn string ¶

Return a new string made from doubling every single-quote char in string. The escaping is consistent with the encoding for conn. The returned string does not have surrounding single-quote chars. If there is an error, return #f.

Procedure: pg-escape-bytea-conn conn bytea ¶

Return a new string made from doing the “minimal” replacement of byte values with its \\ABC (octal) representation in bytea (a string). The escaping is consistent with the encoding for conn. The returned bytea does not have surrounding single-quote chars. If there is an error, return #f.

Procedure: pg-unescape-bytea bytea ¶

Return a new bytea made from unescaping bytea. If there is an error, return #f.

For example:

(pg-escape-string-conn CONN "abc'def")
⇒ "abc''def"

(pg-escape-bytea-conn
 CONN (string #\342 #\251 #\302 #\375))
⇒ "\\\\342\\\\251\\\\302\\\\375"

Lastly, the miscellaneous miscellaneous procedures!

Procedure: pg-mblen encoding string [start] ¶

Return the number of bytes of the first character in unibyte string, which is encoded in encoding (string or symbol). Optional third arg start specifies the byte offset into string to use instead of the default (zero).

Signal error if encoding is unknown or if start is out of range. If start is exactly the length of string, return zero.