@@ -64,24 +64,51 @@ data TypeInfo = TypeInfo { typ :: !NamedOid
6464 , typelem :: !(Maybe NamedOid)
6565 } deriving Show
6666
67+-- | Returns the data type name. This is the preferred way of identifying
68+-- types that do not have a stable type oid, such as types provided by
69+-- extensions to PostgreSQL.
70+--
71+-- More concretely, it returns the @typname@ column associated with the
72+-- type oid in the @pg_type@ table. First, postgresql-simple will check
73+-- built-in, static table. If the type oid is not there, postgresql-simple
74+-- will check a per-connection cache, and then finally query the database's
75+-- meta-schema.
76+
6777typename :: Field -> ByteString
6878typename = typname . typ . typeinfo
6979
80+-- | Returns the name of the column. This is often determined by a table
81+-- definition, but it can be set using an @as@ clause.
82+
7083name :: Field -> Maybe ByteString
7184name Field{..} = unsafePerformIO (PQ.fname result column)
7285
86+-- | Returns the name of the object id of the @table@ associated with the
87+-- column, if any. Returns 'invalidOid' when there is no such table;
88+-- for example a computed column does not have a table associated with it.
89+-- Analogous to libpq's @PQftable@.
90+
7391tableOid :: Field -> PQ.Oid
7492tableOid Field{..} = unsafePerformIO (PQ.ftable result column)
7593
94+-- | If the column has a table associated with it, this returns the number
95+-- of the associated table column. Numbering starts from 0. Analogous
96+-- to libpq's @PQftablecol@.
97+
7698tableColumn :: Field -> Int
7799tableColumn Field{..} = fromCol (unsafePerformIO (PQ.ftablecol result column))
78100 where
79101 fromCol (PQ.Col x) = fromIntegral x
80102
103+-- | This returns whether the data was returned in a binary or textual format.
104+-- Analogous to libpq's @PQfformat@.
81105
82106format :: Field -> PQ.Format
83107format Field{..} = unsafePerformIO (PQ.fformat result column)
84108
109+-- | This returns the type oid associated with the column. Analogous
110+-- to libpq's @PQftype@.
111+
85112typeOid :: Field -> PQ.Oid
86113typeOid = typoid . typ . typeinfo
87114