Orville.PostgreSQL.Plan.Operation

Since: 1.0.0.0

Documentation

data Operation param result

Operation provides a stucture for building primitive operations that can be incorporated into a Plan. An Operation provides base case implementations of the various plan execution functions. You only need to care about this type if you want to create new custom operations to include in a Plan beyond those already provided in the Plan API.

You can build your own custom Operation values either directly, or using the function and types in this module, such as WherePlanner (via findAll, etc), or SelectOperation (via selectOperation).

Since: 1.0.0.0

Constructors

Operation

Fields

• executeOperationOne :: forall m. MonadOrville m => param -> m (Either AssertionFailed result)

  executeOperationOne will be called when a plan is executed with a single input parameter.

• executeOperationMany :: forall m. MonadOrville m => NonEmpty param -> m (Either AssertionFailed (Many param result))

  executeOperationMany will be called when a plan is executed with multiple input parameters (via planMany).

• explainOperationOne :: Explanation

  explainOperationOne will be called when producing an explanation of what the plan will do when given one input parameter. Plans that do not perform any interesting IO interactions should generally return an empty explanation.

• explainOperationMany :: Explanation

  explainOperationMany will be called when producing an explanation of what the plan will do when given multiple input parameters (via planMany). Plans that do not perform any interesting IO interactions should generally return an empty explanation.

data AssertionFailed

AssertionFailed may be returned from the execute functions of an Operation to indicate that some expected invariant has failed. For example, following a foreign key that is enforced by the database only to find that no record exists. When an Operation returns an AssertionFailed value during plan execution, the error is thrown as an exception using the MonadThrow instance for whatever monad the plan is executing in.

Since: 1.0.0.0

Instances

Exception AssertionFailed

Defined in Orville.PostgreSQL.Plan.Operation

Methods

toException :: AssertionFailed -> SomeException

fromException :: SomeException -> Maybe AssertionFailed

displayException :: AssertionFailed -> String

Show AssertionFailed

Defined in Orville.PostgreSQL.Plan.Operation

Methods

showsPrec :: Int -> AssertionFailed -> ShowS

show :: AssertionFailed -> String

showList :: [AssertionFailed] -> ShowS

mkAssertionFailed :: String -> AssertionFailed

mkAssertionFailed builds an AssertionFailed error from an error message.

Since: 1.0.0.0

data WherePlanner param

The functions below (findOne, findAll, etc) accept a WherePlanner to determine how to build the where conditions for executing a Select statement as part of a plan operation.

For simple queries, you can use the functions such as byField that are provided here to build a WherePlanner, but you may also build your own custom WherePlanner for more advanced use cases.

If you need to execute a custom query that cannot be built by providing a custom where clause via WherePlanner, you may want to use more direct selectOperation functions.

Since: 1.0.0.0

Constructors

WherePlanner

Fields

• paramMarshaller :: forall entity. (entity -> param) -> SqlMarshaller entity param

  The paramMarshaller function provided here will be used to decode the parameter field from the result set so that the row can be properly associated with the input parameter that matched it.

• executeOneWhereCondition :: param -> BooleanExpr

  executeOneWhereCondition must build a where condition that will match only those rows that match the input paramater.

• executeManyWhereCondition :: NonEmpty param -> BooleanExpr

  executeManyWhereCondition must build a where condition that will match only those rows that match any (not all!) of the input parameters.

• explainOneWhereCondition :: BooleanExpr

  explainOneWhereCondition must build a where condition that is suitable to be used as an example of what executeManyWhereCondition would return when given a parameter. This where condition will be used when producing explanations of plans. For example, this could fill in either an example or dummy value.

• explainManyWhereCondition :: BooleanExpr

  explainManyWhereCondition must build a where condition that is suitable to be used as an example of what executeOneWhereCondition would return when given a list of parameters. This where condition will be used when producing explanations of plans. For example, this could fill in either an example or dummy value.

byField :: Ord fieldValue => FieldDefinition nullability fieldValue -> WherePlanner fieldValue

Builds a WherePlanner that will match on a single FieldDefinition. The resulting WherePlanner can be used with functions such as findOne and findAll to construct an Operation.

Since: 1.0.0.0

byFieldTuple :: forall nullabilityA fieldValueA nullabilityB fieldValueB. (Ord fieldValueA, Ord fieldValueB) => FieldDefinition nullabilityA fieldValueA -> FieldDefinition nullabilityB fieldValueB -> WherePlanner (fieldValueA, fieldValueB)

Builds a WherePlanner that will match on a 2-tuple of FieldDefinitions. The resulting WherePlanner can be used with functions such as findOne and findAll to construct an Operation.

Since: 1.0.0.0

findOne :: Ord param => TableDefinition key writeEntity readEntity -> WherePlanner param -> Operation param (Maybe readEntity)

findOne builds a planning primitive that finds (at most) one row from the given table where the column value for the provided FieldDefinition matches the plan's input parameter. When executed on multiple parameters, it fetches all rows where the field matches the inputs and arbitrarily picks at most one of those rows to use as the result for each input.

Since: 1.0.0.0

findOneWhere :: Ord param => TableDefinition key writeEntity readEntity -> WherePlanner param -> BooleanExpr -> Operation param (Maybe readEntity)

findOneWhere is similar to findOne but allows a BooleanExpr to be specified that is added to the database query to restrict which rows are returned.

Since: 1.0.0.0

findAll :: Ord param => TableDefinition key writeEntity readEntity -> WherePlanner param -> Operation param [readEntity]

findAll builds a planning primitive that finds all the rows from the given table where the column value for the provided field matches the plan's input parameter. When executed on multiple parameters, all rows are fetched in a single query and then associated with their respective inputs after being fetched.

Since: 1.0.0.0

findAllWhere :: Ord param => TableDefinition key writeEntity readEntity -> WherePlanner param -> BooleanExpr -> Operation param [readEntity]

findAllWhere is similar to findAll but allows a BooleanExpr to be specified that is added to the database query to restrict which rows are returned.

Since: 1.0.0.0

findSelect :: forall param row. Select row -> Operation param [row]

findSelect builds a plan Operation where the select that is run does not use the input parameters for the plan in any way. The executeOperationMany function of the resulting Operation will run the query once and use the entire result set as the result each of the input parameters in turn.

Since: 1.0.0.0

askParam :: Operation param param

askParam simply returns the parameter given from the plan.

Since: 1.0.0.0

assertRight :: Operation (Either String a) a

assertRight returns the value on the Right side of an Either. If the Either is a Left, it raises AssertionFailed with the message from the Left side of the Either.

Since: 1.0.0.0

data SelectOperation param row result

SelectOperation is a helper type for building Operation primitives that run cSelect queries. Specifying the fields of SelectOperation and then using the selectOperation function to build an Operation is more convenient than building functions to execute the queries that are required by the Operation type.

Note: If you only need to build a custom where clause based on the Operation parameter, you may want to use a custom WherePlanner with one of the existing findOne or findAll functions.

If you cannot respresent your custom operation using SelectOperation then you need to build the Operation value directly yourself.

Since: 1.0.0.0

Constructors

SelectOperation

Fields

• selectOne :: param -> Select row

  selectOne will be called to build the Select query that should be run when there is a single input parameter while executing a plan. Note that the "One-ness" here refers to the single input parameter rather than the result. See produceResult below for more information about returning one value vs. many from a SelectOperation.

• selectMany :: NonEmpty param -> Select row

  selectMany will be called to build the Select query that should be run when there are multiple parameters while executing a plan. Note that the "Many-ness" here refers to the multiple input parameters rather than the result. See produceResult below for more information about returning one value vs. many from a SelectOperation.

• explainSelectOne :: Select row

  explainSelectOne should show a representative query of what will be returned when selectOne is used. No input parameter is available here to build the query, however, because this value is used to explain a plan without actually running it.

• explainSelectMany :: Select row

  explainSelectMany should show a representative query of what will be returned when 'selectMany is used. No input parameters are available here to build the query, however, because this value is used to explain a plan without actually running it.

• categorizeRow :: row -> param

  categorizeRow will be used when a plan is executed with multiple parameters to determine which input parameter the row should be associated with.

• produceResult :: [row] -> result

  produceResult will be used to convert the row type returned by the Select queries for the operation input to the result type that is present as the output of the operation. The input rows will be all the inputs associated with a single parameter. The result type constructed here need not be a single value. For instance, findAll uses the list type as the result type and findOne uses Maybe.

selectOperation :: Ord param => SelectOperation param row result -> Operation param result

selectOperation builds a primitive planning Operation using the functions given by a SelectOperation. If you are implementing a custom operation that runs a select statement, it is probably easier to use this function rather than building the Operation functions directly.

Since: 1.0.0.0