Database.PostgreSQL.Simple.QueryResults

The QueryResults typeclass, for converting a row of results returned by a SQL query into a more useful Haskell representation.

Predefined instances are provided for tuples containing up to ten elements.

Documentation

class QueryResults a where

A collection type that can be converted from a list of strings.

Instances should use the convert method of the Result class to perform conversion of each element of the collection.

This example instance demonstrates how to convert a two-column row into a Haskell pair. Each field in the metadata is paired up with each value from the row, and the two are passed to convert.

 instance (Result a, Result b) => QueryResults (a,b) where
     convertResults [fa,fb] [va,vb] = (a,b)
         where !a = convert fa va
               !b = convert fb vb
     convertResults fs vs  = convertError fs vs 2

Notice that this instance evaluates each element to WHNF before constructing the pair. By doing this, we guarantee two important properties:

• Keep resource usage under control by preventing the construction of potentially long-lived thunks.
• Ensure that any ResultError that might arise is thrown immediately, rather than some place later in application code that cannot handle it.

You can also declare Haskell types of your own to be instances of QueryResults.

data User { firstName :: String, lastName :: String }

instance QueryResults User where
    convertResults [fa,fb] [va,vb] = User a b
        where !a = convert fa va
              !b = convert fb vb
    convertResults fs vs  = convertError fs vs

Methods

convertResults :: [Field] -> [Maybe ByteString] -> Either SomeException a

Convert values from a row into a Haskell collection.

This function will throw a ResultError if conversion of the collection fails.

Instances

Result a => QueryResults (Only a)

(Result a, Result b) => QueryResults (a, b)

(Result a, Result b, Result c) => QueryResults (a, b, c)

(Result a, Result b, Result c, Result d) => QueryResults (a, b, c, d)

(Result a, Result b, Result c, Result d, Result e) => QueryResults (a, b, c, d, e)

(Result a, Result b, Result c, Result d, Result e, Result f) => QueryResults (a, b, c, d, e, f)

(Result a, Result b, Result c, Result d, Result e, Result f, Result g) => QueryResults (a, b, c, d, e, f, g)

(Result a, Result b, Result c, Result d, Result e, Result f, Result g, Result h) => QueryResults (a, b, c, d, e, f, g, h)

(Result a, Result b, Result c, Result d, Result e, Result f, Result g, Result h, Result i) => QueryResults (a, b, c, d, e, f, g, h, i)

(Result a, Result b, Result c, Result d, Result e, Result f, Result g, Result h, Result i, Result j) => QueryResults (a, b, c, d, e, f, g, h, i, j)

convertError

Arguments

:: [Field]

Descriptors of fields to be converted.

-> [Maybe ByteString]

Contents of the row to be converted.

-> Int

Number of columns expected for conversion. For instance, if converting to a 3-tuple, the number to provide here would be 3.

-> Either SomeException a

Throw a ConversionFailed exception, indicating a mismatch between the number of columns in the Field and row, and the number in the collection to be converted to.