Types that decode from one column. The usual Haskell types have instances, and Hmssql.Types has the table of which SQL types each accepts. Maybe accepts NULL; without it, a NULL is a DecodeError. An instance of your own defines fieldDecoder, usually with refineField over a built-in type's decoder.

How to decode one column. Given the connection's context and the column, it returns a CellDecoder for the column's values, or why it can't decode them.

The check runs when a result set's columns arrive, before its first row, so a type mismatch is reported even for an empty result.

A decoder from a value's bytes, given a name for error messages, the wire types it accepts and the conversion. A NULL is a DecodeError unless the decoder is wrapped in nullableField. The bytes may be part of a receive buffer, so a conversion should copy any it keeps, as CellDecoder explains.

fieldDecoderFor, accepting by SQL data type rather than by wire type. The conversion still receives the column's TypeInfo.

Convert a decoded value further. A Left becomes a DecodeError naming the column. The inner decoder's type check and NULL handling still apply.

instance FromSqlField Status where
  fieldDecoder = refineField parseStatus fieldDecoder

Decode NULL as Nothing, keeping the inner decoder's type check. A streaming consumer isn't called for a NULL.

The bytes of any column's value as the server sends them, including the CLR types hmssql doesn't otherwise decode.

A decoder of the types LocalTime accepts (date, datetime, smalldatetime and datetime2), given a name for error messages and a function of each value's day and picoseconds since midnight, which are 0 for a date. A datetime's picoseconds are rounded down, as LocalTime's are, and a day count or a time count out of range is a DecodeError, as it is for LocalTime.

A decoder of datetimeoffset, given a name for error messages and a function of each value's day and picoseconds since midnight, both in UTC, and its offset in minutes, as DateTimeOffset holds them. The value is checked as DateTimeOffset is: the offset must lie within ±14:00, and the local date must be in range.

A decoder of time at any scale, given a name for error messages and a function of each value's picoseconds since midnight.

A decoder of the types Decimal accepts (decimal, numeric, money, smallmoney and the integer types), given a name for error messages and a function of each value's parts: whether it is negative, the high and low 64 bits of its magnitude, and its scale. A decimal is checked as Decimal checks it, a money value has scale 4 and an integer scale 0, and a zero is never negative. The high bits are 0 unless the value needs more than 64, which only a decimal of precision 20 or more can.

-- a value's whole part, when its magnitude fits 64 bits
wholePart :: FieldDecoder (Maybe Integer)
wholePart = decimalFieldDecoder "whole part" $ \negative hi lo scale ->
  if hi /= 0 then Nothing
  else Just ((if negative then negate else id) (toInteger (lo `quot` 10 ^ scale)))

A non-NULL value's bytes as they arrive, with its column and its total length if the server sent it. A chunk is safe to keep. The stream is valid only inside its consumer, and bytes the consumer doesn't read are skipped.

A decoder that gives any non-NULL value to a consumer as it arrives, so a large value needn't be in memory. A NULL is a DecodeError unless the decoder is wrapped in nullableField. The consumer runs on the thread reading the rows. Reading this stream twice or after the consumer returns throws ResultAbandoned. On a plain connection, the consumer must not use the connection; on MARS it may use other responses.

streamField for character and XML columns, as Text chunks. A column whose encoding can't be decoded is rejected before any row is read.

Types that decode from a whole row, one column per field in order. Tuples of up to twelve fields and Only have instances. Derive one for a record whose fields are FromSqlField types, one field per column of the SELECT, in order:

data Customer = Customer { customerId :: Int, name :: Text, birthDate :: Maybe Day }
  deriving stock (Show, Generic)
  deriving anyclass (FromSqlRow)

The column types are checked against the fields before the first row is decoded, and a mismatch is a DecodeError naming the column. For a row decoder written by hand, see singleField.

A decoder of a whole row, with a fixed column count, checked against a result set's columns before its first row. Compose it with its Applicative instance. It has no Monad instance; use RowDecoderMonadic when later columns depend on earlier values.

A row decoder of one column, with this field decoder. For a type's own decoder, fieldRowDecoder is the same.

singleField, compiled as a built-in type's fieldRowDecoder is. The reading of a value that lies in the packet behind a fixed width or a one- or two-byte length is copied around the decoder's conversion, which the copy then calls as a known function on the value's place in the buffer, rather than as an unknown function on a ByteString made for it. The result decodes exactly what singleField decodes: the column's type is checked once per result set, a NULL is a DecodeError unless the decoder allows it, and a value cut by a packet, like every value of a max, legacy LOB or sql_variant column, is read through singleField's own path.

It pays for a decoder of your own whose conversion is small and runs for many rows, such as one made by fieldDecoderFor. A large conversion, such as a date's, is cheaper left a call through singleField, as the built-in date and time decoders leave theirs, because inlined it allocates more than the call saves.

Each use is a copy of the cell's reading, a few kilobytes of object code where singleField is one call, so bind the result once at the top level with NOINLINE, which keeps GHC from copying the binding into its uses. The conversion inlines into the copy when its definition is visible there, which an INLINE definition or one in the same module is.

idField :: RowDecoder Builder
idField = inlinedField (fieldDecoderFor "id" isIdType (\_ _ bytes -> Right (idDigits bytes)))
{-# NOINLINE idField #-}

inlinedField of a nullable column, with the NULL and the Just handled in the copy as well. Use it rather than inlinedField . nullableField, which gains nothing over singleField, because nullableField is out of line and the copy can't see the conversion through it. singleField needs no such counterpart, since its conversion is a call either way, so singleField . nullableField is its nullable form.

A row decoder of one column, chosen by the function from the column's ColumnInfo when a result set's columns arrive, before its first row; the decoder chosen reads every value of the column, and must read one column. This is for a program that builds its queries and their decoders at runtime and decodes a column by what the server says it is, such as a long column through a FoldingCell and a short one through its type's fieldRowDecoder. The choice costs nothing per row, where RowDecoderMonadic makes it for every row and reads each column through singleField.

-- a long text a piece at a time, any other whole
textOrFold :: RowDecoder Summary
textOrFold = byColumn $ \col ->
  if columnIsLong col then singleField folded else summarize <$> fieldRowDecoder @Text

The decoder a derived FromSqlRow instance uses: one column per field of a record or product constructor, in order.

A row decoder that runs per row, so later columns can depend on earlier values or on the columns themselves (remainingColumns). Each row must read all the columns. Its checks run per row, so an empty result set isn't checked at all.

Decode the next column with this field decoder.

The columns not yet read.

Read the next columns with a RowDecoder.

Decode the remaining columns as SqlValues, keeping their ColumnInfos.

Any column as a SqlValue (the FromSqlField instance), with the reader chosen by the column's type.

A decoder of every column as a SqlValue. A column with no such conversion fails on the first row rather than at the check, so an empty result set still gives its columns.

Run a FieldDecoder against a column: the CellDecoder for its values, or why it can't decode them.

How to decode a column's values, once the column has been checked. There are two ways, because nearly every value is small and a few are too large to hold in memory; the ordinary way is much the cheaper, since it runs no IO and needs no stream or exception handler per value.

A value as a StreamingCell receives it: NULL, the whole value, or its total length if known and a stream of its bytes. A value of at most streamWholeLimit bytes is read whole first, since giving it to the consumer as it arrives costs several times what reading it does; a larger one is streamed.

The largest value a StreamingCell is given whole, 64 KiB. Up to this size a value read whole and handed over costs about what fieldDecoder does, where streaming it cost seven times as much for a value of 100 bytes; past it, the stream's cost per value is small beside the value's own bytes, and what is held at once stays bounded.

Why a value or a row was read past without a result.

Decode a value already in memory (Nothing is NULL). A StreamingCell gives a Left, because it reads its value as the value arrives.

A decoder from a function that checks the column and chooses how to decode its values. For a decoder fieldDecoderFor can't express.

Read and decode one value, given the column, its decoder, the column's connectValueAllocAhead and the value's header. A value that doesn't decode fails the recipe (failValue) once its bytes have been read.

Check a row decoder against a result set's columns, before any row is read. A wrong column count or an incompatible type is a DecodeError.

compileRowDecoder for columns already prepared with compileResultSet.

Prepare a RowDecoderMonadic to read rows. A failed conversion or a wrong column count is reported once the rest of the row has been read past, so the following rows can still be read.

Read past each row of a result set without decoding it or keeping its values in memory.

A row decoder compiled against a result set's columns.

A value built once and then used many times, such as a row's recipe, which is prepared once for a result set and then read for each row.

The row's recipe, given the bound on allocating ahead of a value's bytes. A Left is a failure of this row alone, with the row fully read: the driver stops the batch there and a DecodeFailed is thrown once the response is drained. An exception thrown by the recipe means the bytes can't be read, and it breaks the connection. Prepare it once per result set and use it for each row.

Decode a stream of a character column's bytes to Text chunks, or why the column's encoding can't be decoded.

Decode a character value; see columnTextDecoder.