TypeCache – The internal cache for database types

class pgdb.TypeCache

Added in version 5.0.

The internal TypeCache of PyGreSQL is not part of the DB-API 2 standard, but is documented here in case you need full control and understanding of the internal handling of database types.

The TypeCache is essentially a dictionary mapping PostgreSQL internal type names and type OIDs to DB-API 2 “type codes” (which are also returned as the type_code field of the Cursor.description attribute).

These type codes are strings which are equal to the PostgreSQL internal type name, but they are also carrying additional information about the associated PostgreSQL type in the following attributes:

  • oid – the OID of the type

  • len – the internal size

  • type – 'b' = base, 'c' = composite, …

  • category – 'A' = Array, 'B' = Boolean, …

  • delim – delimiter to be used when parsing arrays

  • relid – the table OID for composite types

For details, see the PostgreSQL documentation on pg_type.

In addition to the dictionary methods, the TypeCache provides the following methods:

TypeCache.get_fields(typ)

Get the names and types of the fields of composite types

Parameters:

typ (str or int) – PostgreSQL type name or OID of a composite type

Returns:

a list of pairs of field names and types

Return type:

list

TypeCache.get_typecast(typ)

Get the cast function for the given database type

Parameters:

typ (str) – PostgreSQL type name or type code

Returns:

the typecast function for the specified type

Return type:

function or None

TypeCache.set_typecast(typ, cast)

Set a typecast function for the given database type(s)

Parameters:

  • typ (str or int) – PostgreSQL type name or type code, or list of such

  • cast – the typecast function to be set for the specified type(s)

The typecast function must take one string object as argument and return a Python object into which the PostgreSQL type shall be casted. If the function takes another parameter named connection, then the current database connection will also be passed to the typecast function. This may sometimes be necessary to look up certain database settings.

TypeCache.reset_typecast([typ])

Reset the typecasts for the specified (or all) type(s) to their defaults

Parameters:

typ (str, list or None) – PostgreSQL type name or type code, or list of such, or None to reset all typecast functions

TypeCache.typecast(value, typ)

Cast the given value according to the given database type

Parameters:

typ (str) – PostgreSQL type name or type code

Returns:

the casted value

Note

Note that the TypeCache is always bound to a database connection. You can also get, set and reset typecast functions on a global level using the functions pgdb.get_typecast(), pgdb.set_typecast() and pgdb.reset_typecast(). If you do this, the current database connections will continue to use their already cached typecast functions unless call the TypeCache.reset_typecast() method on the Connection.type_cache objects of the running connections.