14.2 Funky Introspection

The column definitions of an existing table can be discovered to some extent by the defs-from-psql, infer-defs and describe-table! procedures, the last one also displaying details on field/column innards.

Procedure: defs-from-psql psql db-name table-name ¶

Run psql and return a defs form for db db-name, table table-name. psql can be a string specifying the filename of the psql (or psql-workalike) program, a thunk that produces such a string, or #t, which means use the first "psql" found in the directories named by the PATH env var. defs-from-psql signals "bad psql" error otherwise.

In the returned defs, the column names are exact. The column types and options are only as exact as psql can produce. Options are returned as a list, each element of which is either a string (possibly with embedded spaces), or a sub-list of symbols and/or numbers. Typically the sub-list, if any, will be the first option. For example, if the column is specified as amount numeric(9,2) not null, the returned def is the four-element list: (amount numeric (9 2) "not null").

Procedure: infer-defs conn table-name ¶

Return a defs form suitable for use with pgtable-manager for connection conn and table-name. The column names are exact. The column types are incorrect for array types, which are described as _FOO; there is currently no way to infer whether this means *FOO or **FOO, etc, without looking at the table’s data. No type options are checked at this time.

Procedure: describe-table! db-name table-name ¶

Display information on database db-name table table-name. Include a defs form suitable for use with pgtable-manager; info about the table (kind, natts, hasindex, checks, triggers, hasrules); and info about each field in the table (typname, attlen, atttypmod, attnotnull, atthasdef, attnum).

Once you have a set of defs, you can verify that their types are supported by Guile-PG with the following procedures.

Procedure: check-type/elaborate type ¶

Check type, a symbol. If it not an array variant, return non-#f only if its converters are already registered with Guile-PG. If type is an array variant, check the base (non-array) type first, and if needed, ensure that the array variant type is registered. Return non-#f if successful.

Procedure: strictly-check-types/elaborate! table-name types ¶

For table table-name, check types (list of symbols) with check-type/elaborate and signal error for those types that do not validate, or return non-#f otherwise. The table-name is used only to form the error message.

Example

(define DEFS (defs-from-psql #t "glug" "updok"))

(car DEFS)
⇒ (time timestamp "without time zone not null")

(map type-name DEFS)
⇒ (timestamp integer integer real integer real)

(strictly-check-types/elaborate! "updok" (map type-name DEFS))
-|
ERROR: bad "updok" types: (real real)
ABORT: (misc-error)

In this example, we use the external program psql to find out the defs for the table updok in database glug; use type-name to get the types (see Column Definitions); and finally check to see which ones, if any, are unknown to Guile-PG. The error output lists real twice because two of the DEFS have that type.