How a value of a type becomes one parameter: its wire type and bytes, or why it can't be sent (what the query functions throw as EncodeError). The TdsContext is the connection's, for an encoding that depends on the negotiated protocol.

Types that can be sent as one parameter, through param or as a field of a ToSqlRow value. The usual Haskell types have instances, and Hmssql.Types has the table of which SQL type each is sent as. An instance of your own defines fieldEncoder, usually with contramap over a built-in type's encoder.

Send a value with an explicit wire type.

Any value with a ToSqlField instance, so a parameter list can mix types.

A parameter's wire type and value.

An in-memory value (Nothing is NULL), lazy bytes read as they are sent, or a source run as it is sent. A request holding either of the last two can be sent only once; a query builds a new request each time it is sent.

The constructors are public so that libraries can inspect and build values.

Where a streamed parameter's bytes come from. It is a function of what consumes the stream, so a resource can be scoped to exactly the send, for example with withBinaryFile. A bare stream couldn't scope one, and a second send would run it from wherever it had got to.

Use an existing stream. Holding on to the stream yourself keeps whatever it has produced alive, and a stream can be sent only once.

A stream made by this action when sending starts. For a resource to release after the send, use the Source constructor.

A parameter read as it is sent, so a large value needn't be in memory. Its type is a (max) type or xml; any other is an EncodeError before anything is sent.

A varbinary(max) parameter, read from the source as it is sent.

An nvarchar(max) parameter, read from the source as it is sent.

A parameter of the given (max) or xml type, read from the source as it is sent. The bytes are the caller's to encode for that type. For UTF-16, their total must be an even number of bytes.

streamAs for lazy bytes, forced as they are sent.

Produces each parameter with its name ("" means positional, @pN by position among the positional ones; otherwise the name with its leading @) and its encoding for a connection. The parameters, their number and their names never depend on the connection; only the encoded values may.

Types that can be sent as a list of parameters: the @p1, @p2, ... of mkQuery, or a row of executeMany or bulkInsert. Derive it for a record whose fields are ToSqlField types, one parameter per field in order:

data NewCustomer = NewCustomer { newName :: Text, newBirthDate :: Maybe Day }
  deriving stock (Generic)
  deriving anyclass (ToSqlRow)

Tuples of up to ten fields, (), Only, a list of one ToSqlField type, a list of SqlParam to mix types, and NamedParams have instances.

Combine two encoders over a product: the parameters of the first, then those of the second. For a ToSqlRow written by hand, e.g. a record with a field that is sent as two parameters.

A row of one positional parameter.

The encoder a derived ToSqlRow instance uses: one positional parameter per field of a record (or product constructor), in order.

A parameter's name and its value.

Parameters that the SQL text refers to by name. The leading @ is optional. A name must be a T-SQL variable name, and not of the form @pN, which is reserved for the positional parameters; the query functions check both before sending anything. Bulk copy matches the names, with that one @ removed, against the table's columns (Hmssql.BulkCopy).

mkQuery "UPDATE dbo.customer SET email = @email WHERE id = @id"
  (NamedParams [("email", SqlParam newEmail), ("id", SqlParam customerId)])