Builtin Converters (Guile-PG Manual)

10.2 Builtin Converters

Here is the set of builtin converters and their default values.

smallint     "0"                    serial8      "0"
integer      "0"                    varchar      #f
bigint       "0"                    character    #f
int          "0"                    char         "?"
int2         "0"                    text         ""
int4         "0"                    name         "???"
int8         "0"                    bytea        #f
numeric      "0"                    timestamp    "1970-01-01 00:00:00"
decimal      "0"                    boolean      "f"
real         "0.0"                  bool         "f"
double       "0.0"                  inet         "0.0.0.0"
float4       "0.0"                  cidr         "0.0.0.0"
float8       "0.0"                  inet-host    "127.0.0.1"
serial       "0"                    macaddr      "00:00:00:00:00:00"
bigserial    "0"                    oid          "-1"
serial4      "0"                    aclitem      "?"

Here are the array variants:

*text
**text
*int4
*aclitem

For the most part, the built-in converters map Scheme types to PostgreSQL types almost transparently. The rest of this section lists the PostgreSQL types not (yet) covered, describes the major weakness in the mapping approach, and then finally touches upon some of the rough edges to be found in selected cases. We hope to resolve these issues (and thus be able to revise this section significantly) before Guile-PG 1.0 is released.

Converters for the following PostgreSQL 7.4.17 types are not provided. (Dot-separated numbers indicate a section in the PostgreSQL User’s Guide describing the type.)

double precision: Numeric Types (8.1). Guile-PG provides double instead of double precision.
money: Monetary Type (8.2). Since PostgreSQL itself deprecates this type, it is unlikely Guile-PG will support it ever.
character varying (n)
char (n): Character Types (8.3). Guile-PG provides varchar instead of character varying, and character instead of char.
timestamp [ (p) ] with time zone
interval [ (p) ]
date
time [ (p) ] with time zone
time [ (p) ] without time zone: Date/Time Types (8.5).
point
line
lseg
box
path
polygon
circle: Geometric Types (8.7).
bit (n)
bit varying (n): Bit String Types (8.9).
regproc
regprocedure
regoper
regoperator
regclass
regtype: Object Identifier Types (8.11).
record
any
anyarray
void
trigger
language_handler
cstring
internal
opaque: Pseudo-Types (8.12).

The large table above hints at the major weakness in Guile-PG’s type mapping approach: the names of converters and the names of the PostgreSQL types are not decoupled at all. This has several negative consequences:

Non-alphanumeric characters in the PostgreSQL type name are not handled gracefully. For example, double precision has a space; Guile-PG can provide double, but now there is ambiguity upon reflection, and the single-table abstraction #:create method fails.
When there is no native Guile type that maps cleanly, Guile-PG must choose an object representation, which may not be ideal for the client. For example, Guile-PG defines an inet object to be a two-element vector; perhaps client code uses a cons or simply one number, since all its inet objects are host addresses (constant netmask). Sure, it is no big deal to box/unbox, but that’s an extra level of conversion that the whole system was trying to avoid in the first place.
User-defined types can clobber internals. (Actually, this may not be a problem in practice.)
Parameterized types cannot be specified.
Non-array derived types cannot express their lineage. For example, Guile-PG provides inet-host, but the single-table abstraction #:create method fails because it has no way of finding out that this type is based on inet.
[probably other things i can’t recall at the moment... –ttn]

The rest of this section is a table delving into some of the more quirky converters provided, including those that do not have a PostgreSQL type. Entries marked NOCREATE indicate that the converter is for a synthetic type and that it cannot be used in the single-table abstraction to create a table, either because there is no underlying PostgreSQL type, or because information about such an underlying type is not (presently) available. Entries marked INTERNAL are “not intended for use by the general user”, according to the PostgreSQL User’s Guide. Entries marked EXPERIMENTAL should probably be avoided unless you are interested in debugging Guile-PG itself.

double: NOCREATE. This can be used to access data of PostgreSQL type double precision.
char
name: NOCREATE, INTERNAL. PostgreSQL actually provides a "char" type (name includes the double quotes) that this type (name does not include the double quotes) mimics.
timestamp: This can be used to access data of PostgreSQL type timestamp (0) without time zone.
inet
cidr: Guile has no native type that aggregates the address and the netmask, so Guile-PG defines the Scheme inet or cidr object to be a vector of two elements #(address maskcount) where address is a positive integer zero through #xffffffff (32 bits) and maskcount is the number of bits in the netmask. If maskcount has value 32, that indicates that address is a host address (not a network).
inet-host: NOCREATE. The inet-host converter can be used to access data of PostgreSQL type inet or cidr when all the data values have a netmask value of 32. The Scheme inet-host object is a positive integer zero through #xffffffff (32 bits).
aclitem: EXPERIMENTAL. Presently used by module (database postgres-meta) in a pass-through (semantically opaque) manner. (This is another way of saying we don’t know what the hell this is good for, but there it is, anyway. ;-)