-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Monad classes for running queries with Persistent and Esqueleto
--   
--   This package introduces two classes: MonadSqlBackend for monadic
--   contexts in which a SqlBackend is available, and MonadSqlTx for
--   contexts in which we can execute a SQL transaction.
--   
--   Additionally, this package provides variants of query-running
--   utilities from Persistent and Esqueleto which are concretized to use
--   SqlBackend, generalized to a MonadSqlBackend m constraint rather than
--   "ReaderT backend", and wrapped in checkpointCallStack so that
--   exceptions will include call stacks.
@package persistent-sql-lifted
@version 0.3.0.0

module Database.Persist.Sql.Lifted.Expression.Bool
not_ :: SqlExpr (Value Bool) -> SqlExpr (Value Bool)

-- | This operator translates to the SQL operator <tt>AND</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $
--           user ^. UserName ==. val <a>Matt</a>
--       &amp;&amp;. user ^. UserAge &gt;=. val 21
--   </pre>
(&&.) :: SqlExpr (Value Bool) -> SqlExpr (Value Bool) -> SqlExpr (Value Bool)
infixr 3 &&.

-- | This operator translates to the SQL operator <tt>AND</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $
--           user ^. UserName ==. val <a>Matt</a>
--       ||. user ^. UserName ==. val <a>John</a>
--   </pre>
(||.) :: SqlExpr (Value Bool) -> SqlExpr (Value Bool) -> SqlExpr (Value Bool)
infixr 2 ||.

module Database.Persist.Sql.Lifted.Expression.Case

-- | <tt>CASE</tt> statement. For example:
--   
--   <pre>
--   select $
--   return $
--   <a>case_</a>
--      [ <a>when_</a>
--          (<a>exists</a> $
--          <a>from</a> $ \p -&gt; do
--          <a>where_</a> (p <a>^.</a> PersonName <a>==.</a> <a>val</a> "Mike"))
--        <a>then_</a>
--          (<a>subSelect</a> $
--          <a>from</a> $ \v -&gt; do
--          let sub =
--                  <a>from</a> $ \c -&gt; do
--                  <a>where_</a> (c <a>^.</a> PersonName <a>==.</a> <a>val</a> "Mike")
--                  return (c <a>^.</a> PersonFavNum)
--          <a>where_</a> (<a>just</a> (v <a>^.</a> PersonFavNum) &gt;. <a>subSelect</a> sub)
--          return $ <a>count</a> (v <a>^.</a> PersonName) +. <a>val</a> (1 :: Int)) ]
--      (<a>else_</a> $ <a>val</a> (-1))
--   </pre>
--   
--   This query is a bit complicated, but basically it checks if a person
--   named <tt>"Mike"</tt> exists, and if that person does, run the
--   subquery to find out how many people have a ranking (by Fav Num)
--   higher than <tt>"Mike"</tt>.
--   
--   <b>NOTE:</b> There are a few things to be aware about this statement.
--   
--   <ul>
--   <li>This only implements the full CASE statement, it does not
--   implement the "simple" CASE statement.</li>
--   <li>At least one <a>when_</a> and <a>then_</a> is mandatory otherwise
--   it will emit an error.</li>
--   <li>The <a>else_</a> is also mandatory, unlike the SQL statement in
--   which if the <tt>ELSE</tt> is omitted it will return a <tt>NULL</tt>.
--   You can reproduce this via <a>nothing</a>.</li>
--   </ul>
case_ :: PersistField a => [(SqlExpr (Value Bool), SqlExpr (Value a))] -> SqlExpr (Value a) -> SqlExpr (Value a)

-- | Syntax sugar for <a>case_</a>.
when_ :: expr (Value Bool) -> () -> expr a -> (expr (Value Bool), expr a)

-- | Syntax sugar for <a>case_</a>.
then_ :: ()

-- | Syntax sugar for <a>case_</a>.
else_ :: expr a -> expr a

module Database.Persist.Sql.Lifted.Expression.Comparison

-- | This operator produces the SQL operator <tt>=</tt>, which is used to
--   compare values for equality.
--   
--   Example:
--   
--   <pre>
--   query :: UserId -&gt; SqlPersistT IO [Entity User]
--   query userId = select $ do
--       user &lt;- from $ table @User
--       where_ (user ^. UserId ==. val userId)
--       pure user
--   </pre>
--   
--   This would generate the following SQL:
--   
--   <pre>
--   SELECT user.*
--   FROM user
--   WHERE user.id = ?
--   </pre>
(==.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
infix 4 ==.

-- | This operator translates to the SQL operator <tt>!=</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $ user ^. UserName !=. val <a>Bob</a>
--   </pre>
(!=.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
infix 4 !=.

-- | This operator translates to the SQL operator <tt>&gt;=</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $ user ^. UserAge &gt;=. val 21
--   </pre>
(>=.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
infix 4 >=.

-- | This operator translates to the SQL operator <tt>&gt;</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $ user ^. UserAge &gt;. val 20
--   </pre>
(>.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
infix 4 >.

-- | This operator translates to the SQL operator <tt>&lt;=</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $ val 21 &lt;=. user ^. UserAge
--   </pre>
(<=.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
infix 4 <=.

-- | This operator translates to the SQL operator <tt>&lt;</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $ val 20 &lt;. user ^. UserAge
--   </pre>
(<.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
infix 4 <.

-- | <tt>a <a>between</a> (b, c)</tt> translates to the SQL expression
--   <tt>a &gt;= b AND a &lt;= c</tt>. It does not use a SQL
--   <tt>BETWEEN</tt> operator.
--   
--   @since: 3.1.0
between :: PersistField a => SqlExpr (Value a) -> (SqlExpr (Value a), SqlExpr (Value a)) -> SqlExpr (Value Bool)

module Database.Persist.Sql.Lifted.Expression.Constant

-- | Lift a constant value from Haskell-land to the query.
val :: PersistField typ => typ -> SqlExpr (Value typ)

module Database.Persist.Sql.Lifted.Expression.Count

-- | <tt>COUNT</tt>.
count :: Num a => SqlExpr (Value typ) -> SqlExpr (Value a)

-- | <tt>COUNT(*)</tt> value.
countRows :: Num a => SqlExpr (Value a)

-- | <tt>COUNT(DISTINCT x)</tt>.
countDistinct :: Num a => SqlExpr (Value typ) -> SqlExpr (Value a)

module Database.Persist.Sql.Lifted.Expression.Exists

-- | <tt>EXISTS</tt> operator. For example:
--   
--   <pre>
--   select $
--   <a>from</a> $ \person -&gt; do
--   <a>where_</a> $ <a>exists</a> $
--            <a>from</a> $ \post -&gt; do
--            <a>where_</a> (post <a>^.</a> BlogPostAuthorId <a>==.</a> person <a>^.</a> PersonId)
--   return person
--   </pre>
exists :: SqlQuery () -> SqlExpr (Value Bool)

-- | <tt>NOT EXISTS</tt> operator.
notExists :: SqlQuery () -> SqlExpr (Value Bool)

module Database.Persist.Sql.Lifted.Expression.Insert

-- | Apply a <a>PersistField</a> constructor to <tt>SqlExpr Value</tt>
--   arguments.
(<#) :: (a -> b) -> SqlExpr (Value a) -> SqlExpr (Insertion b)

-- | Apply extra <tt>SqlExpr Value</tt> arguments to a <a>PersistField</a>
--   constructor
(<&>) :: SqlExpr (Insertion (a -> b)) -> SqlExpr (Value a) -> SqlExpr (Insertion b)

module Database.Persist.Sql.Lifted.Expression.Key

-- | Convert an entity's key into another entity's.
--   
--   This function is to be used when you change an entity's <tt>Id</tt> to
--   be that of another entity. For example:
--   
--   <pre>
--   Bar
--     barNum Int
--   Foo
--     bar BarId
--     fooNum Int
--     Primary bar
--   </pre>
--   
--   In this example, Bar is said to be the BaseEnt(ity), and Foo the
--   child. To model this in Esqueleto, declare:
--   
--   <pre>
--   instance ToBaseId Foo where
--     type BaseEnt Foo = Bar
--     toBaseIdWitness barId = FooKey barId
--   </pre>
--   
--   Now you're able to write queries such as:
--   
--   <pre>
--   <a>select</a> $
--   <a>from</a> $ (bar `<a>InnerJoin</a>` foo) -&gt; do
--   <a>on</a> (<a>toBaseId</a> (foo <a>^.</a> FooId) <a>==.</a> bar <a>^.</a> BarId)
--   return (bar, foo)
--   </pre>
--   
--   Note: this function may be unsafe to use in conditions not like the
--   one of the example above.
toBaseId :: ToBaseId ent => SqlExpr (Value (Key ent)) -> SqlExpr (Value (Key (BaseEnt ent)))

-- | Class that enables one to use <a>toBaseId</a> to convert an entity's
--   key on a query into another (cf. <a>toBaseId</a>).
class () => ToBaseId ent where {
    
    -- | e.g. <tt>type BaseEnt MyBase = MyChild</tt>
    type family BaseEnt ent;
}

-- | Convert from the key of the BaseEnt(ity) to the key of the child
--   entity. This function is not actually called, but that it typechecks
--   proves this operation is safe.
toBaseIdWitness :: ToBaseId ent => Key (BaseEnt ent) -> Key ent

module Database.Persist.Sql.Lifted.Expression.List

-- | <tt>IN</tt> operator. For example if you want to select all
--   <tt>Person</tt>s by a list of IDs:
--   
--   <pre>
--   SELECT *
--   FROM Person
--   WHERE Person.id IN (?)
--   </pre>
--   
--   In <tt>esqueleto</tt>, we may write the same query above as:
--   
--   <pre>
--   select $
--   <a>from</a> $ \person -&gt; do
--   <a>where_</a> $ person <a>^.</a> PersonId `<a>in_</a>` <a>valList</a> personIds
--   return person
--   </pre>
--   
--   Where <tt>personIds</tt> is of type <tt>[Key Person]</tt>.
in_ :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (ValueList typ) -> SqlExpr (Value Bool)

-- | <tt>NOT IN</tt> operator.
notIn :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (ValueList typ) -> SqlExpr (Value Bool)

-- | Execute a subquery <tt>SELECT</tt> in an SqlExpression. Returns a list
--   of values.
subList_select :: PersistField a => SqlQuery (SqlExpr (Value a)) -> SqlExpr (ValueList a)

-- | Lift a list of constant value from Haskell-land to the query.
valList :: PersistField typ => [typ] -> SqlExpr (ValueList typ)

-- | Same as <a>just</a> but for <a>ValueList</a>. Most of the time you
--   won't need it, though, because you can use <a>just</a> from inside
--   <a>subList_select</a> or <a>Just</a> from inside <a>valList</a>.
justList :: SqlExpr (ValueList typ) -> SqlExpr (ValueList (Maybe typ))

module Database.Persist.Sql.Lifted.Expression.Maybe

-- | <tt>IS NULL</tt> comparison.
--   
--   For <tt>IS NOT NULL</tt>, you can negate this with <a>not_</a>, as in
--   <tt>not_ (isNothing (person ^. PersonAge))</tt>
--   
--   Warning: Persistent and Esqueleto have different behavior for <tt>!=
--   Nothing</tt>:
--   
--   TODO: table
--   
--   In SQL, <tt>= NULL</tt> and <tt>!= NULL</tt> return NULL instead of
--   true or false. For this reason, you very likely do not want to use
--   <tt><a>!=.</a> Nothing</tt> in Esqueleto. You may find these
--   <tt>hlint</tt> rules helpful to enforce this:
--   
--   <pre>
--   - error: {lhs: v Database.Esqueleto.==. Database.Esqueleto.nothing, rhs: Database.Esqueleto.isNothing v, name: Use Esqueleto's isNothing}
--   - error: {lhs: v Database.Esqueleto.==. Database.Esqueleto.val Nothing, rhs: Database.Esqueleto.isNothing v, name: Use Esqueleto's isNothing}
--   - error: {lhs: v Database.Esqueleto.!=. Database.Esqueleto.nothing, rhs: not_ (Database.Esqueleto.isNothing v), name: Use Esqueleto's not isNothing}
--   - error: {lhs: v Database.Esqueleto.!=. Database.Esqueleto.val Nothing, rhs: not_ (Database.Esqueleto.isNothing v), name: Use Esqueleto's not isNothing}
--   </pre>
isNothing :: PersistField typ => SqlExpr (Value (Maybe typ)) -> SqlExpr (Value Bool)

-- | An alias for <a>isNothing</a> that avoids clashing with the function
--   from <a>Data.Maybe</a> <a>isNothing</a>.
isNothing_ :: PersistField typ => SqlExpr (Value (Maybe typ)) -> SqlExpr (Value Bool)

-- | Analogous to <a>Just</a>, promotes a value of type <tt>typ</tt> into
--   one of type <tt>Maybe typ</tt>. It should hold that <tt><a>val</a> .
--   Just === just . <a>val</a></tt>.
--   
--   This function will try not to produce a nested <a>Maybe</a>. This is
--   in accord with how SQL represents <tt>NULL</tt>. That means that
--   <tt><a>just</a> . <a>just</a> = <a>just</a></tt>. This behavior was
--   changed in v3.6.0.0. If you want to produce nested <a>Maybe</a>, see
--   <a>just'</a>.
just :: NullableFieldProjection typ typ' => SqlExpr (Value typ) -> SqlExpr (Value (Maybe typ'))

-- | <tt>NULL</tt> value.
nothing :: SqlExpr (Value (Maybe typ))

-- | Join nested <a>Maybe</a>s in a <a>Value</a> into one. This is useful
--   when calling aggregate functions on nullable fields.
--   
--   As of v3.6.0.0, this function will attempt to work on both
--   <tt><a>SqlExpr</a> (<a>Value</a> (<a>Maybe</a> a))</tt> as well as
--   <tt><a>SqlExpr</a> (<a>Value</a> (<a>Maybe</a> (<a>Maybe</a> a)))</tt>
--   inputs to make transitioning to <a>NullableFieldProjection</a> easier.
--   This may make type inference worse in some cases. If you want the
--   monomorphic variant, see <a>joinV'</a>
joinV :: NullableFieldProjection typ typ' => SqlExpr (Value (Maybe typ)) -> SqlExpr (Value (Maybe typ'))

-- | <tt>COALESCE</tt> function. Evaluates the arguments in order and
--   returns the value of the first non-NULL SqlExpression, or NULL
--   (Nothing) otherwise. Some RDBMSs (such as SQLite) require at least two
--   arguments; please refer to the appropriate documentation.
coalesce :: (PersistField a, NullableFieldProjection a a') => [SqlExpr (Value (Maybe a))] -> SqlExpr (Value (Maybe a'))

-- | Like <tt>coalesce</tt>, but takes a non-nullable SqlExpression placed
--   at the end of the SqlExpression list, which guarantees a non-NULL
--   result.
coalesceDefault :: PersistField a => [SqlExpr (Value (Maybe a))] -> SqlExpr (Value a) -> SqlExpr (Value a)

module Database.Persist.Sql.Lifted.Expression.Number

-- | This operator translates to the SQL operator <tt>+</tt>.
--   
--   This does not require or assume anything about the SQL values.
--   Interpreting what <tt>+.</tt> means for a given type is left to the
--   database engine.
--   
--   Example:
--   
--   <pre>
--   user ^. UserAge +. val 10
--   </pre>
(+.) :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value a) -> SqlExpr (Value a)
infixl 6 +.

-- | This operator translates to the SQL operator <tt>-</tt>.
--   
--   This does not require or assume anything about the SQL values.
--   Interpreting what <tt>-.</tt> means for a given type is left to the
--   database engine.
--   
--   Example:
--   
--   <pre>
--   user ^. UserAge -. val 10
--   </pre>
(-.) :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value a) -> SqlExpr (Value a)
infixl 6 -.

-- | This operator translates to the SQL operator <tt>/</tt>.
--   
--   This does not require or assume anything about the SQL values.
--   Interpreting what <tt>/.</tt> means for a given type is left to the
--   database engine.
--   
--   Example:
--   
--   <pre>
--   user ^. UserAge /. val 10
--   </pre>
(/.) :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value a) -> SqlExpr (Value a)
infixl 7 /.

-- | This operator translates to the SQL operator <tt>*</tt>.
--   
--   This does not require or assume anything about the SQL values.
--   Interpreting what <tt>*.</tt> means for a given type is left to the
--   database engine.
--   
--   Example:
--   
--   <pre>
--   user ^. UserAge *. val 10
--   </pre>
(*.) :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value a) -> SqlExpr (Value a)
infixl 7 *.
round_ :: (PersistField a, Num a, PersistField b, Num b) => SqlExpr (Value a) -> SqlExpr (Value b)
ceiling_ :: (PersistField a, Num a, PersistField b, Num b) => SqlExpr (Value a) -> SqlExpr (Value b)
floor_ :: (PersistField a, Num a, PersistField b, Num b) => SqlExpr (Value a) -> SqlExpr (Value b)
min_ :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value (Maybe (Nullable a)))
max_ :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value (Maybe (Nullable a)))
sum_ :: (PersistField a, PersistField b) => SqlExpr (Value a) -> SqlExpr (Value (Maybe b))
avg_ :: (PersistField a, PersistField b) => SqlExpr (Value a) -> SqlExpr (Value (Maybe b))

-- | Allow a number of one type to be used as one of another type via an
--   implicit cast. An explicit cast is not made, this function changes
--   only the types on the Haskell side.
--   
--   <i>Caveat</i>: Trying to use <tt>castNum</tt> from <tt>Double</tt> to
--   <tt>Int</tt> will not result in an integer, the original fractional
--   number will still be used! Use <a>round_</a>, <a>ceiling_</a> or
--   <a>floor_</a> instead.
--   
--   <i>Safety</i>: This operation is mostly safe due to the <a>Num</a>
--   constraint between the types and the fact that RDBMSs usually allow
--   numbers of different types to be used interchangeably. However, there
--   may still be issues with the query not being accepted by the RDBMS or
--   <tt>persistent</tt> not being able to parse it.
castNum :: (Num a, Num b) => SqlExpr (Value a) -> SqlExpr (Value b)

-- | Same as <a>castNum</a>, but for nullable values.
castNumM :: (Num a, Num b) => SqlExpr (Value (Maybe a)) -> SqlExpr (Value (Maybe b))

module Database.Persist.Sql.Lifted.Expression.OrderBy

-- | Ascending order of this field or SqlExpression.
asc :: PersistField a => SqlExpr (Value a) -> SqlExpr OrderBy

-- | Descending order of this field or SqlExpression.
desc :: PersistField a => SqlExpr (Value a) -> SqlExpr OrderBy

module Database.Persist.Sql.Lifted.Expression.Projection

-- | Project a field of an entity.
(^.) :: forall typ val. (PersistEntity val, PersistField typ) => SqlExpr (Entity val) -> EntityField val typ -> SqlExpr (Value typ)
infixl 9 ^.

-- | Project an <a>EntityField</a> of a nullable entity. The result type
--   will be <a>Nullable</a>, meaning that nested <a>Maybe</a> won't be
--   produced here.
--   
--   As of v3.6.0.0, this will attempt to combine nested <a>Maybe</a>. If
--   you want to keep nested <a>Maybe</a>, then see <a>??.</a>.
(?.) :: (PersistEntity val, PersistField typ) => SqlExpr (Maybe (Entity val)) -> EntityField val typ -> SqlExpr (Value (Maybe (Nullable typ)))
infixl 9 ?.

module Database.Persist.Sql.Lifted.Expression.String

-- | <tt>LOWER</tt> function.
lower_ :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s)

-- | <tt>UPPER</tt> function. @since 3.3.0
upper_ :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s)

-- | <tt>TRIM</tt> function. @since 3.3.0
trim_ :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s)

-- | <tt>LTRIM</tt> function. @since 3.3.0
ltrim_ :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s)

-- | <tt>RTRIM</tt> function. @since 3.3.0
rtrim_ :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s)

-- | <tt>LENGTH</tt> function. @since 3.3.0
length_ :: (SqlString s, Num a) => SqlExpr (Value s) -> SqlExpr (Value a)

-- | <tt>LEFT</tt> function. @since 3.3.0
left_ :: (SqlString s, Num a) => (SqlExpr (Value s), SqlExpr (Value a)) -> SqlExpr (Value s)

-- | <tt>RIGHT</tt> function. @since 3.3.0
right_ :: (SqlString s, Num a) => (SqlExpr (Value s), SqlExpr (Value a)) -> SqlExpr (Value s)

-- | <tt>LIKE</tt> operator.
like :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s) -> SqlExpr (Value Bool)
infixr 2 `like`

-- | <tt>ILIKE</tt> operator (case-insensitive <tt>LIKE</tt>).
--   
--   Supported by PostgreSQL only. Deprecated in version 3.6.0 in favor of
--   the version available from <a>Database.Esqueleto.PostgreSQL</a>.
ilike :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s) -> SqlExpr (Value Bool)
infixr 2 `ilike`

-- | The string <tt><a>%</a></tt>. May be useful while using <a>like</a>
--   and concatenation (<a>concat_</a> or <a>++.</a>, depending on your
--   database). Note that you always have to type the parenthesis, for
--   example:
--   
--   <pre>
--   name `<a>like</a>` (%) ++. <a>val</a> "John" ++. (%)
--   </pre>
(%) :: SqlString s => SqlExpr (Value s)

-- | The <tt>CONCAT</tt> function with a variable number of parameters.
--   Supported by MySQL and PostgreSQL. SQLite supports this in versions
--   after 3.44.0, and <tt>persistent-sqlite</tt> supports this in versions
--   <tt>2.13.3.0</tt> and after.
concat_ :: SqlString s => [SqlExpr (Value s)] -> SqlExpr (Value s)

-- | The <tt>||</tt> string concatenation operator (named after Haskell's
--   <a>++</a> in order to avoid naming clash with <a>||.</a>).
--   
--   Supported by SQLite and PostgreSQL.
--   
--   MySQL support requires setting the SQL mode to
--   <tt>PIPES_AS_CONCAT</tt> or <tt>ANSI</tt> - see <a>this StackOverflow
--   answer</a>.
(++.) :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s) -> SqlExpr (Value s)
infixr 5 ++.

-- | Cast a string type into <a>Text</a>. This function is very useful if
--   you want to use <tt>newtype</tt>s, or if you want to apply functions
--   such as <a>like</a> to strings of different types.
--   
--   <i>Safety:</i> This is a slightly unsafe function, especially if you
--   have defined your own instances of <a>SqlString</a>. Also, since
--   <a>Maybe</a> is an instance of <a>SqlString</a>, it's possible to turn
--   a nullable value into a non-nullable one. Avoid using this function if
--   possible.
castString :: (SqlString s, SqlString r) => SqlExpr (Value s) -> SqlExpr (Value r)

module Database.Persist.Sql.Lifted.Expression.SubSelect

-- | Execute a subquery <tt>SELECT</tt> in a <a>SqlExpr</a>. The query
--   passed to this function will only return a single result - it has a
--   <tt>LIMIT 1</tt> passed in to the query to make it safe, and the
--   return type is <a>Maybe</a> to indicate that the subquery might result
--   in 0 rows.
--   
--   If you find yourself writing <tt><a>joinV</a> . <a>subSelect</a></tt>,
--   then consider using <a>subSelectMaybe</a>.
--   
--   If you're performing a <a>countRows</a>, then you can use
--   <a>subSelectCount</a> which is safe.
--   
--   If you know that the subquery will always return exactly one row (eg a
--   foreign key constraint guarantees that you'll get exactly one row),
--   then consider <a>subSelectUnsafe</a>, along with a comment explaining
--   why it is safe.
subSelect :: (PersistField a, NullableFieldProjection a a') => SqlQuery (SqlExpr (Value a)) -> SqlExpr (Value (Maybe a'))

-- | Execute a subquery <tt>SELECT</tt> in a <a>SqlExpr</a>. This function
--   is a shorthand for the common <tt><a>joinV</a> . <a>subSelect</a></tt>
--   idiom, where you are calling <a>subSelect</a> on an expression that
--   would be <a>Maybe</a> already.
--   
--   As an example, you would use this function when calling <a>sum_</a> or
--   <a>max_</a>, which have <a>Maybe</a> in the result type (for a 0 row
--   query).
subSelectMaybe :: PersistField a => SqlQuery (SqlExpr (Value (Maybe a))) -> SqlExpr (Value (Maybe a))

-- | Performs a <tt>COUNT</tt> of the given query in a <tt>subSelect</tt>
--   manner. This is always guaranteed to return a result value, and is
--   completely safe.
subSelectCount :: (Num a, PersistField a) => SqlQuery ignored -> SqlExpr (Value a)

-- | Performs a sub-select using the given foreign key on the entity. This
--   is useful to extract values that are known to be present by the
--   database schema.
--   
--   As an example, consider the following persistent definition:
--   
--   <pre>
--   User
--     profile ProfileId
--   
--   Profile
--     name    Text
--   </pre>
--   
--   The following query will return the name of the user.
--   
--   <pre>
--   getUserWithName =
--       <a>select</a> $
--       <a>from</a> $ user -&gt;
--       <a>pure</a> (user, <a>subSelectForeign</a> user UserProfile (^. ProfileName)
--   </pre>
subSelectForeign :: (BackendCompatible SqlBackend (PersistEntityBackend val1), PersistEntity val1, PersistEntity val2, PersistField a) => SqlExpr (Entity val2) -> EntityField val2 (Key val1) -> (SqlExpr (Entity val1) -> SqlExpr (Value a)) -> SqlExpr (Value a)

-- | Execute a subquery <tt>SELECT</tt> in a <a>SqlExpr</a> that returns a
--   list. This is an alias for <a>subList_select</a> and is provided for
--   symmetry with the other safe subselect functions.
subSelectList :: PersistField a => SqlQuery (SqlExpr (Value a)) -> SqlExpr (ValueList a)

-- | Execute a subquery <tt>SELECT</tt> in a <a>SqlExpr</a>. This function
--   is unsafe, because it can throw runtime exceptions in two cases:
--   
--   <ol>
--   <li>If the query passed has 0 result rows, then it will return a
--   <tt>NULL</tt> value. The <tt>persistent</tt> parsing operations will
--   fail on an unexpected <tt>NULL</tt>.</li>
--   <li>If the query passed returns more than one row, then the SQL engine
--   will fail with an error like "More than one row returned by a subquery
--   used as an expression".</li>
--   </ol>
--   
--   This function is safe if you guarantee that exactly one row will be
--   returned, or if the result already has a <a>Maybe</a> type for some
--   reason.
--   
--   For variants with the safety encoded already, see <a>subSelect</a> and
--   <a>subSelectMaybe</a>. For the most common safe use of this, see
--   <a>subSelectCount</a>.
subSelectUnsafe :: PersistField a => SqlQuery (SqlExpr (Value a)) -> SqlExpr (Value a)

module Database.Persist.Sql.Lifted.Expression.Table

-- | Get the first table of a given type from a chain of tables joined with
--   <a>(:&amp;)</a>.
--   
--   This can make it easier to write queries with a large number of join
--   clauses:
--   
--   <pre>
--   select $ do
--   (people :&amp; followers :&amp; blogPosts) &lt;-
--       from $ table @Person
--       `innerJoin` table @Follow
--       `on` (\(person :&amp; follow) -&gt;
--               person ^. PersonId ==. follow ^. FollowFollowed)
--       `innerJoin` table @BlogPost
--       `on` (\((getTable @Follow -&gt; follow) :&amp; blogPost) -&gt;
--               blogPost ^. BlogPostAuthorId ==. follow ^. FollowFollower)
--   where_ (people1 ^. PersonName ==. val "John")
--   pure (followers, people2)
--   </pre>
--   
--   This example is a bit trivial, but once you've joined five or six
--   tables it becomes enormously helpful. The above example uses a
--   <tt>ViewPattern</tt> to call the function and assign the variable
--   directly, but you can also imagine it being written like this:
--   
--   <pre>
--   `on` (\(prev :&amp; blogPost) -&gt;
--           let
--               follow = getTable @Follow prev
--            in
--               blogPost ^. BlogPostAuthorId ==. follow ^. FollowFollower)
--   </pre>
--   
--   This function will pluck out the first table that matches the applied
--   type, so if you join on the same table multiple times, it will always
--   select the first one provided.
--   
--   The <a>(:&amp;)</a> operator associates so that the left hand side can
--   be a wildcard for an arbitrary amount of nesting, and the "most
--   recent" or "newest" table in a join sequence is always available on
--   the rightmost - so <tt>(prev :&amp; bar)</tt> is a pattern that
--   matches <tt>bar</tt> table (the most recent table added) and
--   <tt>prev</tt> tables (all prior tables in the join match).
--   
--   By calling <a>getTable</a> on the <tt>prev</tt>, you can select
--   exactly the table you want, allowing you to omit a large number of
--   spurious pattern matches. Consider a query that does several <tt>LEFT
--   JOIN</tt> on a first table:
--   
--   <pre>
--   SELECT *
--   FROM person
--   LEFT JOIN car
--     ON person.id = car.person_id
--   LEFT JOIN bike
--     ON person.id = bike.person_id
--   LEFT JOIN food
--     ON person.id = food.person_id
--   LEFT JOIN address
--     ON person.id = address.person_id
--   </pre>
--   
--   The final <a>on</a> clause in esqueleto would look like this:
--   
--   <pre>
--   `on` do
--       \(person :&amp; _car :&amp; _bike :&amp; _food :&amp; address) -&gt;
--           person.id ==. address.personId
--   </pre>
--   
--   First, we can change it to a <tt>prev :&amp; newest</tt> match. We can
--   do this because of the operator associativity. This is kind of like
--   how a list <tt>:</tt> operator associates, but in the other direction:
--   <tt>a : (b : c) = a : b : c</tt>.
--   
--   <pre>
--   `on` do
--       \(prev :&amp; address) -&gt;
--           let (person :&amp; _car :&amp; _bike :&amp; _food) = prev
--            in person.id ==. address.personId
--   </pre>
--   
--   Then, we can use <a>getTable</a> to select the <tt>Person</tt> table
--   directly, instead of pattern matching manually.
--   
--   <pre>
--   `on` do
--       \(prev :&amp; address) -&gt;
--           let person = getTable @Person prev
--            in person.id ==. address.personId
--   </pre>
--   
--   Finally, we can use a <tt>ViewPattern</tt> language extension to
--   "inline" the access.
--   
--   <pre>
--   `on` do
--       \((getTable @Person -&gt; person) :&amp; address) -&gt;
--          person.id ==. address.personId
--   </pre>
--   
--   With this form, you do not need to be concerned about the number and
--   wildcard status of tables that do not matter to the specific
--   <tt>ON</tt> clause.
getTable :: GetFirstTable (SqlExpr (Entity t)) ts => ts -> SqlExpr (Entity t)

-- | A variant of <a>getTable</a> that operates on possibly-null entities.
getTableMaybe :: GetFirstTable (SqlExpr (Maybe (Entity t))) ts => ts -> SqlExpr (Maybe (Entity t))

module Database.Persist.Sql.Lifted.Expression.Type

-- | An expression on the SQL backend.
--   
--   Raw expression: Contains a <a>SqlExprMeta</a> and a function for
--   building the expr. It recieves a parameter telling it whether it is in
--   a parenthesized context, and takes information about the SQL
--   connection (mainly for escaping names) and returns both an string
--   (<a>Builder</a>) and a list of values to be interpolated by the SQL
--   backend.
data () => SqlExpr a

module Database.Persist.Sql.Lifted.Expression.Update
(=.) :: (PersistEntity val, PersistField typ) => EntityField val typ -> SqlExpr (Value typ) -> SqlExpr (Entity val) -> SqlExpr Update
infixr 3 =.
(+=.) :: (PersistEntity val, PersistField a) => EntityField val a -> SqlExpr (Value a) -> SqlExpr (Entity val) -> SqlExpr Update
infixr 3 +=.
(-=.) :: (PersistEntity val, PersistField a) => EntityField val a -> SqlExpr (Value a) -> SqlExpr (Entity val) -> SqlExpr Update
infixr 3 -=.
(*=.) :: (PersistEntity val, PersistField a) => EntityField val a -> SqlExpr (Value a) -> SqlExpr (Entity val) -> SqlExpr Update
infixr 3 *=.
(/=.) :: (PersistEntity val, PersistField a) => EntityField val a -> SqlExpr (Value a) -> SqlExpr (Entity val) -> SqlExpr Update
infixr 3 /=.

module Database.Persist.Sql.Lifted.Expression

-- | An expression on the SQL backend.
--   
--   Raw expression: Contains a <a>SqlExprMeta</a> and a function for
--   building the expr. It recieves a parameter telling it whether it is in
--   a parenthesized context, and takes information about the SQL
--   connection (mainly for escaping names) and returns both an string
--   (<a>Builder</a>) and a list of values to be interpolated by the SQL
--   backend.
data () => SqlExpr a

-- | Lift a constant value from Haskell-land to the query.
val :: PersistField typ => typ -> SqlExpr (Value typ)
not_ :: SqlExpr (Value Bool) -> SqlExpr (Value Bool)

-- | This operator translates to the SQL operator <tt>AND</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $
--           user ^. UserName ==. val <a>Matt</a>
--       &amp;&amp;. user ^. UserAge &gt;=. val 21
--   </pre>
(&&.) :: SqlExpr (Value Bool) -> SqlExpr (Value Bool) -> SqlExpr (Value Bool)
infixr 3 &&.

-- | This operator translates to the SQL operator <tt>AND</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $
--           user ^. UserName ==. val <a>Matt</a>
--       ||. user ^. UserName ==. val <a>John</a>
--   </pre>
(||.) :: SqlExpr (Value Bool) -> SqlExpr (Value Bool) -> SqlExpr (Value Bool)
infixr 2 ||.

-- | <tt>CASE</tt> statement. For example:
--   
--   <pre>
--   select $
--   return $
--   <a>case_</a>
--      [ <a>when_</a>
--          (<a>exists</a> $
--          <a>from</a> $ \p -&gt; do
--          <a>where_</a> (p <a>^.</a> PersonName <a>==.</a> <a>val</a> "Mike"))
--        <a>then_</a>
--          (<a>subSelect</a> $
--          <a>from</a> $ \v -&gt; do
--          let sub =
--                  <a>from</a> $ \c -&gt; do
--                  <a>where_</a> (c <a>^.</a> PersonName <a>==.</a> <a>val</a> "Mike")
--                  return (c <a>^.</a> PersonFavNum)
--          <a>where_</a> (<a>just</a> (v <a>^.</a> PersonFavNum) &gt;. <a>subSelect</a> sub)
--          return $ <a>count</a> (v <a>^.</a> PersonName) +. <a>val</a> (1 :: Int)) ]
--      (<a>else_</a> $ <a>val</a> (-1))
--   </pre>
--   
--   This query is a bit complicated, but basically it checks if a person
--   named <tt>"Mike"</tt> exists, and if that person does, run the
--   subquery to find out how many people have a ranking (by Fav Num)
--   higher than <tt>"Mike"</tt>.
--   
--   <b>NOTE:</b> There are a few things to be aware about this statement.
--   
--   <ul>
--   <li>This only implements the full CASE statement, it does not
--   implement the "simple" CASE statement.</li>
--   <li>At least one <a>when_</a> and <a>then_</a> is mandatory otherwise
--   it will emit an error.</li>
--   <li>The <a>else_</a> is also mandatory, unlike the SQL statement in
--   which if the <tt>ELSE</tt> is omitted it will return a <tt>NULL</tt>.
--   You can reproduce this via <a>nothing</a>.</li>
--   </ul>
case_ :: PersistField a => [(SqlExpr (Value Bool), SqlExpr (Value a))] -> SqlExpr (Value a) -> SqlExpr (Value a)

-- | Syntax sugar for <a>case_</a>.
when_ :: expr (Value Bool) -> () -> expr a -> (expr (Value Bool), expr a)

-- | Syntax sugar for <a>case_</a>.
then_ :: ()

-- | Syntax sugar for <a>case_</a>.
else_ :: expr a -> expr a

-- | This operator produces the SQL operator <tt>=</tt>, which is used to
--   compare values for equality.
--   
--   Example:
--   
--   <pre>
--   query :: UserId -&gt; SqlPersistT IO [Entity User]
--   query userId = select $ do
--       user &lt;- from $ table @User
--       where_ (user ^. UserId ==. val userId)
--       pure user
--   </pre>
--   
--   This would generate the following SQL:
--   
--   <pre>
--   SELECT user.*
--   FROM user
--   WHERE user.id = ?
--   </pre>
(==.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
infix 4 ==.

-- | This operator translates to the SQL operator <tt>!=</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $ user ^. UserName !=. val <a>Bob</a>
--   </pre>
(!=.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
infix 4 !=.

-- | This operator translates to the SQL operator <tt>&gt;=</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $ user ^. UserAge &gt;=. val 21
--   </pre>
(>=.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
infix 4 >=.

-- | This operator translates to the SQL operator <tt>&gt;</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $ user ^. UserAge &gt;. val 20
--   </pre>
(>.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
infix 4 >.

-- | This operator translates to the SQL operator <tt>&lt;=</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $ val 21 &lt;=. user ^. UserAge
--   </pre>
(<=.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
infix 4 <=.

-- | This operator translates to the SQL operator <tt>&lt;</tt>.
--   
--   Example:
--   
--   <pre>
--   where_ $ val 20 &lt;. user ^. UserAge
--   </pre>
(<.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
infix 4 <.

-- | <tt>a <a>between</a> (b, c)</tt> translates to the SQL expression
--   <tt>a &gt;= b AND a &lt;= c</tt>. It does not use a SQL
--   <tt>BETWEEN</tt> operator.
--   
--   @since: 3.1.0
between :: PersistField a => SqlExpr (Value a) -> (SqlExpr (Value a), SqlExpr (Value a)) -> SqlExpr (Value Bool)

-- | <tt>COUNT</tt>.
count :: Num a => SqlExpr (Value typ) -> SqlExpr (Value a)

-- | <tt>COUNT(*)</tt> value.
countRows :: Num a => SqlExpr (Value a)

-- | <tt>COUNT(DISTINCT x)</tt>.
countDistinct :: Num a => SqlExpr (Value typ) -> SqlExpr (Value a)

-- | <tt>EXISTS</tt> operator. For example:
--   
--   <pre>
--   select $
--   <a>from</a> $ \person -&gt; do
--   <a>where_</a> $ <a>exists</a> $
--            <a>from</a> $ \post -&gt; do
--            <a>where_</a> (post <a>^.</a> BlogPostAuthorId <a>==.</a> person <a>^.</a> PersonId)
--   return person
--   </pre>
exists :: SqlQuery () -> SqlExpr (Value Bool)

-- | <tt>NOT EXISTS</tt> operator.
notExists :: SqlQuery () -> SqlExpr (Value Bool)

-- | Apply a <a>PersistField</a> constructor to <tt>SqlExpr Value</tt>
--   arguments.
(<#) :: (a -> b) -> SqlExpr (Value a) -> SqlExpr (Insertion b)

-- | Apply extra <tt>SqlExpr Value</tt> arguments to a <a>PersistField</a>
--   constructor
(<&>) :: SqlExpr (Insertion (a -> b)) -> SqlExpr (Value a) -> SqlExpr (Insertion b)

-- | Convert an entity's key into another entity's.
--   
--   This function is to be used when you change an entity's <tt>Id</tt> to
--   be that of another entity. For example:
--   
--   <pre>
--   Bar
--     barNum Int
--   Foo
--     bar BarId
--     fooNum Int
--     Primary bar
--   </pre>
--   
--   In this example, Bar is said to be the BaseEnt(ity), and Foo the
--   child. To model this in Esqueleto, declare:
--   
--   <pre>
--   instance ToBaseId Foo where
--     type BaseEnt Foo = Bar
--     toBaseIdWitness barId = FooKey barId
--   </pre>
--   
--   Now you're able to write queries such as:
--   
--   <pre>
--   <a>select</a> $
--   <a>from</a> $ (bar `<a>InnerJoin</a>` foo) -&gt; do
--   <a>on</a> (<a>toBaseId</a> (foo <a>^.</a> FooId) <a>==.</a> bar <a>^.</a> BarId)
--   return (bar, foo)
--   </pre>
--   
--   Note: this function may be unsafe to use in conditions not like the
--   one of the example above.
toBaseId :: ToBaseId ent => SqlExpr (Value (Key ent)) -> SqlExpr (Value (Key (BaseEnt ent)))

-- | Class that enables one to use <a>toBaseId</a> to convert an entity's
--   key on a query into another (cf. <a>toBaseId</a>).
class () => ToBaseId ent where {
    
    -- | e.g. <tt>type BaseEnt MyBase = MyChild</tt>
    type family BaseEnt ent;
}

-- | Convert from the key of the BaseEnt(ity) to the key of the child
--   entity. This function is not actually called, but that it typechecks
--   proves this operation is safe.
toBaseIdWitness :: ToBaseId ent => Key (BaseEnt ent) -> Key ent

-- | <tt>IN</tt> operator. For example if you want to select all
--   <tt>Person</tt>s by a list of IDs:
--   
--   <pre>
--   SELECT *
--   FROM Person
--   WHERE Person.id IN (?)
--   </pre>
--   
--   In <tt>esqueleto</tt>, we may write the same query above as:
--   
--   <pre>
--   select $
--   <a>from</a> $ \person -&gt; do
--   <a>where_</a> $ person <a>^.</a> PersonId `<a>in_</a>` <a>valList</a> personIds
--   return person
--   </pre>
--   
--   Where <tt>personIds</tt> is of type <tt>[Key Person]</tt>.
in_ :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (ValueList typ) -> SqlExpr (Value Bool)

-- | <tt>NOT IN</tt> operator.
notIn :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (ValueList typ) -> SqlExpr (Value Bool)

-- | Execute a subquery <tt>SELECT</tt> in an SqlExpression. Returns a list
--   of values.
subList_select :: PersistField a => SqlQuery (SqlExpr (Value a)) -> SqlExpr (ValueList a)

-- | Lift a list of constant value from Haskell-land to the query.
valList :: PersistField typ => [typ] -> SqlExpr (ValueList typ)

-- | Same as <a>just</a> but for <a>ValueList</a>. Most of the time you
--   won't need it, though, because you can use <a>just</a> from inside
--   <a>subList_select</a> or <a>Just</a> from inside <a>valList</a>.
justList :: SqlExpr (ValueList typ) -> SqlExpr (ValueList (Maybe typ))

-- | <tt>IS NULL</tt> comparison.
--   
--   For <tt>IS NOT NULL</tt>, you can negate this with <a>not_</a>, as in
--   <tt>not_ (isNothing (person ^. PersonAge))</tt>
--   
--   Warning: Persistent and Esqueleto have different behavior for <tt>!=
--   Nothing</tt>:
--   
--   TODO: table
--   
--   In SQL, <tt>= NULL</tt> and <tt>!= NULL</tt> return NULL instead of
--   true or false. For this reason, you very likely do not want to use
--   <tt><a>!=.</a> Nothing</tt> in Esqueleto. You may find these
--   <tt>hlint</tt> rules helpful to enforce this:
--   
--   <pre>
--   - error: {lhs: v Database.Esqueleto.==. Database.Esqueleto.nothing, rhs: Database.Esqueleto.isNothing v, name: Use Esqueleto's isNothing}
--   - error: {lhs: v Database.Esqueleto.==. Database.Esqueleto.val Nothing, rhs: Database.Esqueleto.isNothing v, name: Use Esqueleto's isNothing}
--   - error: {lhs: v Database.Esqueleto.!=. Database.Esqueleto.nothing, rhs: not_ (Database.Esqueleto.isNothing v), name: Use Esqueleto's not isNothing}
--   - error: {lhs: v Database.Esqueleto.!=. Database.Esqueleto.val Nothing, rhs: not_ (Database.Esqueleto.isNothing v), name: Use Esqueleto's not isNothing}
--   </pre>
isNothing :: PersistField typ => SqlExpr (Value (Maybe typ)) -> SqlExpr (Value Bool)

-- | An alias for <a>isNothing</a> that avoids clashing with the function
--   from <a>Data.Maybe</a> <a>isNothing</a>.
isNothing_ :: PersistField typ => SqlExpr (Value (Maybe typ)) -> SqlExpr (Value Bool)

-- | Analogous to <a>Just</a>, promotes a value of type <tt>typ</tt> into
--   one of type <tt>Maybe typ</tt>. It should hold that <tt><a>val</a> .
--   Just === just . <a>val</a></tt>.
--   
--   This function will try not to produce a nested <a>Maybe</a>. This is
--   in accord with how SQL represents <tt>NULL</tt>. That means that
--   <tt><a>just</a> . <a>just</a> = <a>just</a></tt>. This behavior was
--   changed in v3.6.0.0. If you want to produce nested <a>Maybe</a>, see
--   <a>just'</a>.
just :: NullableFieldProjection typ typ' => SqlExpr (Value typ) -> SqlExpr (Value (Maybe typ'))

-- | <tt>NULL</tt> value.
nothing :: SqlExpr (Value (Maybe typ))

-- | Join nested <a>Maybe</a>s in a <a>Value</a> into one. This is useful
--   when calling aggregate functions on nullable fields.
--   
--   As of v3.6.0.0, this function will attempt to work on both
--   <tt><a>SqlExpr</a> (<a>Value</a> (<a>Maybe</a> a))</tt> as well as
--   <tt><a>SqlExpr</a> (<a>Value</a> (<a>Maybe</a> (<a>Maybe</a> a)))</tt>
--   inputs to make transitioning to <a>NullableFieldProjection</a> easier.
--   This may make type inference worse in some cases. If you want the
--   monomorphic variant, see <a>joinV'</a>
joinV :: NullableFieldProjection typ typ' => SqlExpr (Value (Maybe typ)) -> SqlExpr (Value (Maybe typ'))

-- | <tt>COALESCE</tt> function. Evaluates the arguments in order and
--   returns the value of the first non-NULL SqlExpression, or NULL
--   (Nothing) otherwise. Some RDBMSs (such as SQLite) require at least two
--   arguments; please refer to the appropriate documentation.
coalesce :: (PersistField a, NullableFieldProjection a a') => [SqlExpr (Value (Maybe a))] -> SqlExpr (Value (Maybe a'))

-- | Like <tt>coalesce</tt>, but takes a non-nullable SqlExpression placed
--   at the end of the SqlExpression list, which guarantees a non-NULL
--   result.
coalesceDefault :: PersistField a => [SqlExpr (Value (Maybe a))] -> SqlExpr (Value a) -> SqlExpr (Value a)

-- | This operator translates to the SQL operator <tt>+</tt>.
--   
--   This does not require or assume anything about the SQL values.
--   Interpreting what <tt>+.</tt> means for a given type is left to the
--   database engine.
--   
--   Example:
--   
--   <pre>
--   user ^. UserAge +. val 10
--   </pre>
(+.) :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value a) -> SqlExpr (Value a)
infixl 6 +.

-- | This operator translates to the SQL operator <tt>-</tt>.
--   
--   This does not require or assume anything about the SQL values.
--   Interpreting what <tt>-.</tt> means for a given type is left to the
--   database engine.
--   
--   Example:
--   
--   <pre>
--   user ^. UserAge -. val 10
--   </pre>
(-.) :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value a) -> SqlExpr (Value a)
infixl 6 -.

-- | This operator translates to the SQL operator <tt>/</tt>.
--   
--   This does not require or assume anything about the SQL values.
--   Interpreting what <tt>/.</tt> means for a given type is left to the
--   database engine.
--   
--   Example:
--   
--   <pre>
--   user ^. UserAge /. val 10
--   </pre>
(/.) :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value a) -> SqlExpr (Value a)
infixl 7 /.

-- | This operator translates to the SQL operator <tt>*</tt>.
--   
--   This does not require or assume anything about the SQL values.
--   Interpreting what <tt>*.</tt> means for a given type is left to the
--   database engine.
--   
--   Example:
--   
--   <pre>
--   user ^. UserAge *. val 10
--   </pre>
(*.) :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value a) -> SqlExpr (Value a)
infixl 7 *.
round_ :: (PersistField a, Num a, PersistField b, Num b) => SqlExpr (Value a) -> SqlExpr (Value b)
ceiling_ :: (PersistField a, Num a, PersistField b, Num b) => SqlExpr (Value a) -> SqlExpr (Value b)
floor_ :: (PersistField a, Num a, PersistField b, Num b) => SqlExpr (Value a) -> SqlExpr (Value b)
min_ :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value (Maybe (Nullable a)))
max_ :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value (Maybe (Nullable a)))
sum_ :: (PersistField a, PersistField b) => SqlExpr (Value a) -> SqlExpr (Value (Maybe b))
avg_ :: (PersistField a, PersistField b) => SqlExpr (Value a) -> SqlExpr (Value (Maybe b))

-- | Allow a number of one type to be used as one of another type via an
--   implicit cast. An explicit cast is not made, this function changes
--   only the types on the Haskell side.
--   
--   <i>Caveat</i>: Trying to use <tt>castNum</tt> from <tt>Double</tt> to
--   <tt>Int</tt> will not result in an integer, the original fractional
--   number will still be used! Use <a>round_</a>, <a>ceiling_</a> or
--   <a>floor_</a> instead.
--   
--   <i>Safety</i>: This operation is mostly safe due to the <a>Num</a>
--   constraint between the types and the fact that RDBMSs usually allow
--   numbers of different types to be used interchangeably. However, there
--   may still be issues with the query not being accepted by the RDBMS or
--   <tt>persistent</tt> not being able to parse it.
castNum :: (Num a, Num b) => SqlExpr (Value a) -> SqlExpr (Value b)

-- | Same as <a>castNum</a>, but for nullable values.
castNumM :: (Num a, Num b) => SqlExpr (Value (Maybe a)) -> SqlExpr (Value (Maybe b))

-- | Ascending order of this field or SqlExpression.
asc :: PersistField a => SqlExpr (Value a) -> SqlExpr OrderBy

-- | Descending order of this field or SqlExpression.
desc :: PersistField a => SqlExpr (Value a) -> SqlExpr OrderBy

-- | Project a field of an entity.
(^.) :: forall typ val. (PersistEntity val, PersistField typ) => SqlExpr (Entity val) -> EntityField val typ -> SqlExpr (Value typ)
infixl 9 ^.

-- | Project an <a>EntityField</a> of a nullable entity. The result type
--   will be <a>Nullable</a>, meaning that nested <a>Maybe</a> won't be
--   produced here.
--   
--   As of v3.6.0.0, this will attempt to combine nested <a>Maybe</a>. If
--   you want to keep nested <a>Maybe</a>, then see <a>??.</a>.
(?.) :: (PersistEntity val, PersistField typ) => SqlExpr (Maybe (Entity val)) -> EntityField val typ -> SqlExpr (Value (Maybe (Nullable typ)))
infixl 9 ?.

-- | <tt>LOWER</tt> function.
lower_ :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s)

-- | <tt>UPPER</tt> function. @since 3.3.0
upper_ :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s)

-- | <tt>TRIM</tt> function. @since 3.3.0
trim_ :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s)

-- | <tt>LTRIM</tt> function. @since 3.3.0
ltrim_ :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s)

-- | <tt>RTRIM</tt> function. @since 3.3.0
rtrim_ :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s)

-- | <tt>LENGTH</tt> function. @since 3.3.0
length_ :: (SqlString s, Num a) => SqlExpr (Value s) -> SqlExpr (Value a)

-- | <tt>LEFT</tt> function. @since 3.3.0
left_ :: (SqlString s, Num a) => (SqlExpr (Value s), SqlExpr (Value a)) -> SqlExpr (Value s)

-- | <tt>RIGHT</tt> function. @since 3.3.0
right_ :: (SqlString s, Num a) => (SqlExpr (Value s), SqlExpr (Value a)) -> SqlExpr (Value s)

-- | <tt>LIKE</tt> operator.
like :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s) -> SqlExpr (Value Bool)
infixr 2 `like`

-- | <tt>ILIKE</tt> operator (case-insensitive <tt>LIKE</tt>).
--   
--   Supported by PostgreSQL only. Deprecated in version 3.6.0 in favor of
--   the version available from <a>Database.Esqueleto.PostgreSQL</a>.
ilike :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s) -> SqlExpr (Value Bool)
infixr 2 `ilike`

-- | The string <tt><a>%</a></tt>. May be useful while using <a>like</a>
--   and concatenation (<a>concat_</a> or <a>++.</a>, depending on your
--   database). Note that you always have to type the parenthesis, for
--   example:
--   
--   <pre>
--   name `<a>like</a>` (%) ++. <a>val</a> "John" ++. (%)
--   </pre>
(%) :: SqlString s => SqlExpr (Value s)

-- | The <tt>CONCAT</tt> function with a variable number of parameters.
--   Supported by MySQL and PostgreSQL. SQLite supports this in versions
--   after 3.44.0, and <tt>persistent-sqlite</tt> supports this in versions
--   <tt>2.13.3.0</tt> and after.
concat_ :: SqlString s => [SqlExpr (Value s)] -> SqlExpr (Value s)

-- | The <tt>||</tt> string concatenation operator (named after Haskell's
--   <a>++</a> in order to avoid naming clash with <a>||.</a>).
--   
--   Supported by SQLite and PostgreSQL.
--   
--   MySQL support requires setting the SQL mode to
--   <tt>PIPES_AS_CONCAT</tt> or <tt>ANSI</tt> - see <a>this StackOverflow
--   answer</a>.
(++.) :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s) -> SqlExpr (Value s)
infixr 5 ++.

-- | Cast a string type into <a>Text</a>. This function is very useful if
--   you want to use <tt>newtype</tt>s, or if you want to apply functions
--   such as <a>like</a> to strings of different types.
--   
--   <i>Safety:</i> This is a slightly unsafe function, especially if you
--   have defined your own instances of <a>SqlString</a>. Also, since
--   <a>Maybe</a> is an instance of <a>SqlString</a>, it's possible to turn
--   a nullable value into a non-nullable one. Avoid using this function if
--   possible.
castString :: (SqlString s, SqlString r) => SqlExpr (Value s) -> SqlExpr (Value r)

-- | Execute a subquery <tt>SELECT</tt> in a <a>SqlExpr</a>. The query
--   passed to this function will only return a single result - it has a
--   <tt>LIMIT 1</tt> passed in to the query to make it safe, and the
--   return type is <a>Maybe</a> to indicate that the subquery might result
--   in 0 rows.
--   
--   If you find yourself writing <tt><a>joinV</a> . <a>subSelect</a></tt>,
--   then consider using <a>subSelectMaybe</a>.
--   
--   If you're performing a <a>countRows</a>, then you can use
--   <a>subSelectCount</a> which is safe.
--   
--   If you know that the subquery will always return exactly one row (eg a
--   foreign key constraint guarantees that you'll get exactly one row),
--   then consider <a>subSelectUnsafe</a>, along with a comment explaining
--   why it is safe.
subSelect :: (PersistField a, NullableFieldProjection a a') => SqlQuery (SqlExpr (Value a)) -> SqlExpr (Value (Maybe a'))

-- | Execute a subquery <tt>SELECT</tt> in a <a>SqlExpr</a>. This function
--   is a shorthand for the common <tt><a>joinV</a> . <a>subSelect</a></tt>
--   idiom, where you are calling <a>subSelect</a> on an expression that
--   would be <a>Maybe</a> already.
--   
--   As an example, you would use this function when calling <a>sum_</a> or
--   <a>max_</a>, which have <a>Maybe</a> in the result type (for a 0 row
--   query).
subSelectMaybe :: PersistField a => SqlQuery (SqlExpr (Value (Maybe a))) -> SqlExpr (Value (Maybe a))

-- | Performs a <tt>COUNT</tt> of the given query in a <tt>subSelect</tt>
--   manner. This is always guaranteed to return a result value, and is
--   completely safe.
subSelectCount :: (Num a, PersistField a) => SqlQuery ignored -> SqlExpr (Value a)

-- | Performs a sub-select using the given foreign key on the entity. This
--   is useful to extract values that are known to be present by the
--   database schema.
--   
--   As an example, consider the following persistent definition:
--   
--   <pre>
--   User
--     profile ProfileId
--   
--   Profile
--     name    Text
--   </pre>
--   
--   The following query will return the name of the user.
--   
--   <pre>
--   getUserWithName =
--       <a>select</a> $
--       <a>from</a> $ user -&gt;
--       <a>pure</a> (user, <a>subSelectForeign</a> user UserProfile (^. ProfileName)
--   </pre>
subSelectForeign :: (BackendCompatible SqlBackend (PersistEntityBackend val1), PersistEntity val1, PersistEntity val2, PersistField a) => SqlExpr (Entity val2) -> EntityField val2 (Key val1) -> (SqlExpr (Entity val1) -> SqlExpr (Value a)) -> SqlExpr (Value a)

-- | Execute a subquery <tt>SELECT</tt> in a <a>SqlExpr</a> that returns a
--   list. This is an alias for <a>subList_select</a> and is provided for
--   symmetry with the other safe subselect functions.
subSelectList :: PersistField a => SqlQuery (SqlExpr (Value a)) -> SqlExpr (ValueList a)

-- | Execute a subquery <tt>SELECT</tt> in a <a>SqlExpr</a>. This function
--   is unsafe, because it can throw runtime exceptions in two cases:
--   
--   <ol>
--   <li>If the query passed has 0 result rows, then it will return a
--   <tt>NULL</tt> value. The <tt>persistent</tt> parsing operations will
--   fail on an unexpected <tt>NULL</tt>.</li>
--   <li>If the query passed returns more than one row, then the SQL engine
--   will fail with an error like "More than one row returned by a subquery
--   used as an expression".</li>
--   </ol>
--   
--   This function is safe if you guarantee that exactly one row will be
--   returned, or if the result already has a <a>Maybe</a> type for some
--   reason.
--   
--   For variants with the safety encoded already, see <a>subSelect</a> and
--   <a>subSelectMaybe</a>. For the most common safe use of this, see
--   <a>subSelectCount</a>.
subSelectUnsafe :: PersistField a => SqlQuery (SqlExpr (Value a)) -> SqlExpr (Value a)

-- | Get the first table of a given type from a chain of tables joined with
--   <a>(:&amp;)</a>.
--   
--   This can make it easier to write queries with a large number of join
--   clauses:
--   
--   <pre>
--   select $ do
--   (people :&amp; followers :&amp; blogPosts) &lt;-
--       from $ table @Person
--       `innerJoin` table @Follow
--       `on` (\(person :&amp; follow) -&gt;
--               person ^. PersonId ==. follow ^. FollowFollowed)
--       `innerJoin` table @BlogPost
--       `on` (\((getTable @Follow -&gt; follow) :&amp; blogPost) -&gt;
--               blogPost ^. BlogPostAuthorId ==. follow ^. FollowFollower)
--   where_ (people1 ^. PersonName ==. val "John")
--   pure (followers, people2)
--   </pre>
--   
--   This example is a bit trivial, but once you've joined five or six
--   tables it becomes enormously helpful. The above example uses a
--   <tt>ViewPattern</tt> to call the function and assign the variable
--   directly, but you can also imagine it being written like this:
--   
--   <pre>
--   `on` (\(prev :&amp; blogPost) -&gt;
--           let
--               follow = getTable @Follow prev
--            in
--               blogPost ^. BlogPostAuthorId ==. follow ^. FollowFollower)
--   </pre>
--   
--   This function will pluck out the first table that matches the applied
--   type, so if you join on the same table multiple times, it will always
--   select the first one provided.
--   
--   The <a>(:&amp;)</a> operator associates so that the left hand side can
--   be a wildcard for an arbitrary amount of nesting, and the "most
--   recent" or "newest" table in a join sequence is always available on
--   the rightmost - so <tt>(prev :&amp; bar)</tt> is a pattern that
--   matches <tt>bar</tt> table (the most recent table added) and
--   <tt>prev</tt> tables (all prior tables in the join match).
--   
--   By calling <a>getTable</a> on the <tt>prev</tt>, you can select
--   exactly the table you want, allowing you to omit a large number of
--   spurious pattern matches. Consider a query that does several <tt>LEFT
--   JOIN</tt> on a first table:
--   
--   <pre>
--   SELECT *
--   FROM person
--   LEFT JOIN car
--     ON person.id = car.person_id
--   LEFT JOIN bike
--     ON person.id = bike.person_id
--   LEFT JOIN food
--     ON person.id = food.person_id
--   LEFT JOIN address
--     ON person.id = address.person_id
--   </pre>
--   
--   The final <a>on</a> clause in esqueleto would look like this:
--   
--   <pre>
--   `on` do
--       \(person :&amp; _car :&amp; _bike :&amp; _food :&amp; address) -&gt;
--           person.id ==. address.personId
--   </pre>
--   
--   First, we can change it to a <tt>prev :&amp; newest</tt> match. We can
--   do this because of the operator associativity. This is kind of like
--   how a list <tt>:</tt> operator associates, but in the other direction:
--   <tt>a : (b : c) = a : b : c</tt>.
--   
--   <pre>
--   `on` do
--       \(prev :&amp; address) -&gt;
--           let (person :&amp; _car :&amp; _bike :&amp; _food) = prev
--            in person.id ==. address.personId
--   </pre>
--   
--   Then, we can use <a>getTable</a> to select the <tt>Person</tt> table
--   directly, instead of pattern matching manually.
--   
--   <pre>
--   `on` do
--       \(prev :&amp; address) -&gt;
--           let person = getTable @Person prev
--            in person.id ==. address.personId
--   </pre>
--   
--   Finally, we can use a <tt>ViewPattern</tt> language extension to
--   "inline" the access.
--   
--   <pre>
--   `on` do
--       \((getTable @Person -&gt; person) :&amp; address) -&gt;
--          person.id ==. address.personId
--   </pre>
--   
--   With this form, you do not need to be concerned about the number and
--   wildcard status of tables that do not matter to the specific
--   <tt>ON</tt> clause.
getTable :: GetFirstTable (SqlExpr (Entity t)) ts => ts -> SqlExpr (Entity t)

-- | A variant of <a>getTable</a> that operates on possibly-null entities.
getTableMaybe :: GetFirstTable (SqlExpr (Maybe (Entity t))) ts => ts -> SqlExpr (Maybe (Entity t))
(=.) :: (PersistEntity val, PersistField typ) => EntityField val typ -> SqlExpr (Value typ) -> SqlExpr (Entity val) -> SqlExpr Update
infixr 3 =.
(+=.) :: (PersistEntity val, PersistField a) => EntityField val a -> SqlExpr (Value a) -> SqlExpr (Entity val) -> SqlExpr Update
infixr 3 +=.
(-=.) :: (PersistEntity val, PersistField a) => EntityField val a -> SqlExpr (Value a) -> SqlExpr (Entity val) -> SqlExpr Update
infixr 3 -=.
(*=.) :: (PersistEntity val, PersistField a) => EntityField val a -> SqlExpr (Value a) -> SqlExpr (Entity val) -> SqlExpr Update
infixr 3 *=.
(/=.) :: (PersistEntity val, PersistField a) => EntityField val a -> SqlExpr (Value a) -> SqlExpr (Entity val) -> SqlExpr Update
infixr 3 /=.

module Database.Persist.Sql.Lifted.Filter

-- | Filters which are available for <tt>select</tt>, <tt>updateWhere</tt>
--   and <tt>deleteWhere</tt>. Each filter constructor specifies the field
--   being filtered on, the type of comparison applied (equals, not equals,
--   etc) and the argument for the comparison.
--   
--   Persistent users use combinators to create these.
--   
--   Note that it's important to be careful about the <a>PersistFilter</a>
--   that you are using, if you use this directly. For example, using the
--   <a>In</a> <a>PersistFilter</a> requires that you have an array- or
--   list-shaped <a>EntityField</a>. It is possible to construct values
--   using this that will create malformed runtime values.
data () => Filter record

-- | Check for equality.
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   selectSPJ :: MonadIO m =&gt; ReaderT SqlBackend m [Entity User]
--   selectSPJ = selectList [UserName ==. "SPJ" ] []
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+-----+
--   |id   |name |age  |
--   +-----+-----+-----+
--   |1    |SPJ  |40   |
--   +-----+-----+-----+
--   </pre>
(==.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Filter v
infix 4 ==.

-- | Non-equality check.
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   selectSimon :: MonadIO m =&gt; ReaderT SqlBackend m [Entity User]
--   selectSimon = selectList [UserName !=. "SPJ" ] []
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+-----+
--   |id   |name |age  |
--   +-----+-----+-----+
--   |2    |Simon|41   |
--   +-----+-----+-----+
--   </pre>
(!=.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Filter v
infix 4 !=.

-- | Less-than check.
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   selectLessAge :: MonadIO m =&gt; ReaderT SqlBackend m [Entity User]
--   selectLessAge = selectList [UserAge &lt;. 41 ] []
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+-----+
--   |id   |name |age  |
--   +-----+-----+-----+
--   |1    |SPJ  |40   |
--   +-----+-----+-----+
--   </pre>
(<.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Filter v
infix 4 <.

-- | Greater-than check.
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   selectGreaterAge :: MonadIO m =&gt; ReaderT SqlBackend m [Entity User]
--   selectGreaterAge = selectList [UserAge &gt;. 40 ] []
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+-----+
--   |id   |name |age  |
--   +-----+-----+-----+
--   |2    |Simon|41   |
--   +-----+-----+-----+
--   </pre>
(>.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Filter v
infix 4 >.

-- | Less-than or equal check.
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   selectLessEqualAge :: MonadIO m =&gt; ReaderT SqlBackend m [Entity User]
--   selectLessEqualAge = selectList [UserAge &lt;=. 40 ] []
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+-----+
--   |id   |name |age  |
--   +-----+-----+-----+
--   |1    |SPJ  |40   |
--   +-----+-----+-----+
--   </pre>
(<=.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Filter v
infix 4 <=.

-- | Greater-than or equal check.
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   selectGreaterEqualAge :: MonadIO m =&gt; ReaderT SqlBackend m [Entity User]
--   selectGreaterEqualAge = selectList [UserAge &gt;=. 41 ] []
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+-----+
--   |id   |name |age  |
--   +-----+-----+-----+
--   |2    |Simon|41   |
--   +-----+-----+-----+
--   </pre>
(>=.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Filter v
infix 4 >=.

-- | Check if value is in given list.
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   selectUsers :: MonadIO m =&gt; ReaderT SqlBackend m [Entity User]
--   selectUsers = selectList [UserAge &lt;-. [40, 41]] []
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+-----+
--   |id   |name |age  |
--   +-----+-----+-----+
--   |1    |SPJ  |40   |
--   +-----+-----+-----+
--   |2    |Simon|41   |
--   +-----+-----+-----+
--   </pre>
--   
--   <pre>
--   selectSPJ :: MonadIO m =&gt; ReaderT SqlBackend m [Entity User]
--   selectSPJ = selectList [UserAge &lt;-. [40]] []
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+-----+
--   |id   |name |age  |
--   +-----+-----+-----+
--   |1    |SPJ  |40   |
--   +-----+-----+-----+
--   </pre>
(<-.) :: forall v typ. PersistField typ => EntityField v typ -> [typ] -> Filter v
infix 4 <-.

-- | Check if value is not in given list.
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   selectSimon :: MonadIO m =&gt; ReaderT SqlBackend m [Entity User]
--   selectSimon = selectList [UserAge /&lt;-. [40]] []
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+-----+
--   |id   |name |age  |
--   +-----+-----+-----+
--   |2    |Simon|41   |
--   +-----+-----+-----+
--   </pre>
(/<-.) :: forall v typ. PersistField typ => EntityField v typ -> [typ] -> Filter v
infix 4 /<-.

-- | The OR of two lists of filters. For example:
--   
--   <pre>
--   selectList
--       ([ PersonAge &gt;. 25
--        , PersonAge &lt;. 30 ] ||.
--        [ PersonIncome &gt;. 15000
--        , PersonIncome &lt;. 25000 ])
--       []
--   </pre>
--   
--   will filter records where a person's age is between 25 and 30
--   <i>or</i> a person's income is between (15000 and 25000).
--   
--   If you are looking for an <tt>(&amp;&amp;.)</tt> operator to do <tt>(A
--   AND B AND (C OR D))</tt> you can use the <tt>(++)</tt> operator
--   instead as there is no <tt>(&amp;&amp;.)</tt>. For example:
--   
--   <pre>
--   selectList
--       ([ PersonAge &gt;. 25
--        , PersonAge &lt;. 30 ] ++
--       ([PersonCategory ==. 1] ||.
--        [PersonCategory ==. 5]))
--       []
--   </pre>
--   
--   will filter records where a person's age is between 25 and 30
--   <i>and</i> (person's category is either 1 or 5).
(||.) :: [Filter v] -> [Filter v] -> [Filter v]
infixl 3 ||.

module Database.Persist.Sql.Lifted.From

-- | Data type defining the <a>From</a> language. This should not
--   constructed directly in application code.
--   
--   A <tt>From</tt> is a SqlQuery which returns a reference to the result
--   of calling from and a function that produces a portion of a FROM
--   clause. This gets passed to the FromRaw FromClause constructor
--   directly when converting from a <tt>From</tt> to a <tt>SqlQuery</tt>
--   using <tt>from</tt>
data () => From a

-- | <tt>FROM</tt> clause, used to bring entities into scope.
--   
--   Internally, this function uses the <a>From</a> datatype. Unlike the
--   old <a>from</a>, this does not take a function as a parameter, but
--   rather a value that represents a <tt>JOIN</tt> tree constructed out of
--   instances of <a>From</a>. This implementation eliminates certain types
--   of runtime errors by preventing the construction of invalid SQL (e.g.
--   illegal nested-<tt>from</tt>).
from :: ToFrom a a' => a -> SqlQuery a'

-- | Bring a PersistEntity into scope from a table
--   
--   <pre>
--   select $ from $ table @People
--   </pre>
table :: PersistEntity ent => From (SqlExpr (Entity ent))

-- | A left-precedence pair. Pronounced "and". Used to represent
--   expressions that have been joined together.
--   
--   The precedence behavior can be demonstrated by:
--   
--   <pre>
--   a :&amp; b :&amp; c == ((a :&amp; b) :&amp; c)
--   </pre>
--   
--   See the examples at the beginning of this module to see how this
--   operator is used in <tt>JOIN</tt> operations.
data () => a :& b
(:&) :: a -> b -> (:&) a b
infixl 2 :&
infixl 2 :&

-- | An <tt>ON</tt> clause that describes how two tables are related. This
--   should be used as an infix operator after a <tt>JOIN</tt>. For
--   example,
--   
--   <pre>
--   select $
--   from $ table @Person
--   `innerJoin` table @BlogPost
--   `on` (\(p :&amp; bP) -&gt;
--           p ^. PersonId ==. bP ^. BlogPostAuthorId)
--   </pre>
on :: ValidOnClause a => a -> (b -> SqlExpr (Value Bool)) -> (a, b -> SqlExpr (Value Bool))
infix 9 `on`

-- | INNER JOIN
--   
--   Used as an infix operator `innerJoin`
--   
--   <pre>
--   select $
--   from $ table @Person
--   `innerJoin` table @BlogPost
--   `on` (\(p :&amp; bp) -&gt;
--           p ^. PersonId ==. bp ^. BlogPostAuthorId)
--   </pre>
innerJoin :: (ToFrom a a', ToFrom b b', HasOnClause rhs (a' :& b'), rhs ~ (b, (a' :& b') -> SqlExpr (Value Bool))) => a -> rhs -> From (a' :& b')
infixl 2 `innerJoin`

-- | INNER JOIN LATERAL
--   
--   A Lateral subquery join allows the joined query to reference entities
--   from the left hand side of the join. Discards rows that don't match
--   the on clause
--   
--   Used as an infix operator `innerJoinLateral`
--   
--   See example 6
innerJoinLateral :: (ToFrom a a', HasOnClause rhs (a' :& b), SqlSelect b r, ToAlias b, ToAliasReference b, rhs ~ (a' -> SqlQuery b, (a' :& b) -> SqlExpr (Value Bool))) => a -> rhs -> From (a' :& b)
infixl 2 `innerJoinLateral`

-- | LEFT OUTER JOIN
--   
--   Join where the right side may not exist. If the on clause fails then
--   the right side will be NULL'ed Because of this the right side needs to
--   be handled as a Maybe
--   
--   Used as an infix operator `leftJoin`
--   
--   <pre>
--   select $
--   from $ table @Person
--   `leftJoin` table @BlogPost
--   `on` (\(p :&amp; bp) -&gt;
--           just (p ^. PersonId) ==. bp ?. BlogPostAuthorId)
--   </pre>
leftJoin :: (ToFrom a a', ToFrom b b', ToMaybe b', HasOnClause rhs (a' :& ToMaybeT b'), rhs ~ (b, (a' :& ToMaybeT b') -> SqlExpr (Value Bool))) => a -> rhs -> From (a' :& ToMaybeT b')
infixl 2 `leftJoin`

-- | LEFT OUTER JOIN LATERAL
--   
--   Lateral join where the right side may not exist. In the case that the
--   query returns nothing or the on clause fails the right side of the
--   join will be NULL'ed Because of this the right side needs to be
--   handled as a Maybe
--   
--   Used as an infix operator `leftJoinLateral`
--   
--   See example 6 for how to use LATERAL
leftJoinLateral :: (ToFrom a a', SqlSelect b r, HasOnClause rhs (a' :& ToMaybeT b), ToAlias b, ToAliasReference b, ToMaybe b, rhs ~ (a' -> SqlQuery b, (a' :& ToMaybeT b) -> SqlExpr (Value Bool))) => a -> rhs -> From (a' :& ToMaybeT b)
infixl 2 `leftJoinLateral`

-- | RIGHT OUTER JOIN
--   
--   Join where the left side may not exist. If the on clause fails then
--   the left side will be NULL'ed Because of this the left side needs to
--   be handled as a Maybe
--   
--   Used as an infix operator `rightJoin`
--   
--   <pre>
--   select $
--   from $ table @Person
--   `rightJoin` table @BlogPost
--   `on` (\(p :&amp; bp) -&gt;
--           p ?. PersonId ==. bp ^. BlogPostAuthorId)
--   </pre>
rightJoin :: (ToFrom a a', ToFrom b b', ToMaybe a', HasOnClause rhs (ToMaybeT a' :& b'), rhs ~ (b, (ToMaybeT a' :& b') -> SqlExpr (Value Bool))) => a -> rhs -> From (ToMaybeT a' :& b')
infixl 2 `rightJoin`

-- | FULL OUTER JOIN
--   
--   Join where both sides of the join may not exist. Because of this the
--   result needs to be handled as a Maybe
--   
--   Used as an infix operator `fullOuterJoin`
--   
--   <pre>
--   select $
--   from $ table @Person
--   `fullOuterJoin` table @BlogPost
--   `on` (\(p :&amp; bp) -&gt;
--           p ?. PersonId ==. bp ?. BlogPostAuthorId)
--   </pre>
fullOuterJoin :: (ToFrom a a', ToFrom b b', ToMaybe a', ToMaybe b', HasOnClause rhs (ToMaybeT a' :& ToMaybeT b'), rhs ~ (b, (ToMaybeT a' :& ToMaybeT b') -> SqlExpr (Value Bool))) => a -> rhs -> From (ToMaybeT a' :& ToMaybeT b')
infixl 2 `fullOuterJoin`

-- | CROSS JOIN
--   
--   Used as an infix `crossJoin`
--   
--   <pre>
--   select $ do
--   from $ table @Person
--   `crossJoin` table @BlogPost
--   </pre>
crossJoin :: (ToFrom a a', ToFrom b b') => a -> b -> From (a' :& b')
infixl 2 `crossJoin`

-- | CROSS JOIN LATERAL
--   
--   A Lateral subquery join allows the joined query to reference entities
--   from the left hand side of the join.
--   
--   Used as an infix operator `crossJoinLateral`
--   
--   See example 6
crossJoinLateral :: (ToFrom a a', SqlSelect b r, ToAlias b, ToAliasReference b) => a -> (a' -> SqlQuery b) -> From (a' :& b)
infixl 2 `crossJoinLateral`

module Database.Persist.Sql.Lifted.HasSqlBackend
class HasSqlBackend a
getSqlBackend :: HasSqlBackend a => a -> SqlBackend
instance Database.Persist.Sql.Lifted.HasSqlBackend.HasSqlBackend Database.Persist.SqlBackend.Internal.SqlBackend

module Database.Persist.Sql.Lifted.MonadSqlBackend

-- | A monadic context in which a SQL backend is available for running
--   database queries
class MonadUnliftIO m => MonadSqlBackend m
getSqlBackendM :: MonadSqlBackend m => m SqlBackend

-- | Generalize from <tt>SqlPersistT</tt> to <a>MonadSqlBackend</a>
liftSql :: (MonadSqlBackend m, HasCallStack) => ReaderT SqlBackend m a -> m a
instance (Database.Persist.Sql.Lifted.HasSqlBackend.HasSqlBackend r, Control.Monad.IO.Unlift.MonadUnliftIO m) => Database.Persist.Sql.Lifted.MonadSqlBackend.MonadSqlBackend (Control.Monad.Trans.Reader.ReaderT r m)

module Database.Persist.Sql.Lifted.MonadSqlTx

-- | The constraint <tt><a>MonadSqlTx</a> db m</tt> indicates that
--   <tt>m</tt> is a monadic context that can run <tt>db</tt> actions,
--   usually as a SQL transaction. Typically, this means that <tt>db</tt>
--   needs a connection and <tt>m</tt> can provide one, e.g. from a
--   connection pool.
class (MonadSqlBackend db, MonadUnliftIO m) => MonadSqlTx db m | m -> db

-- | Runs the action in a SQL transaction
runSqlTx :: (MonadSqlTx db m, HasCallStack) => db a -> m a

module Database.Persist.Sql.Lifted.Core

-- | The constraint <tt><a>MonadSqlTx</a> db m</tt> indicates that
--   <tt>m</tt> is a monadic context that can run <tt>db</tt> actions,
--   usually as a SQL transaction. Typically, this means that <tt>db</tt>
--   needs a connection and <tt>m</tt> can provide one, e.g. from a
--   connection pool.
class (MonadSqlBackend db, MonadUnliftIO m) => MonadSqlTx db m | m -> db

-- | Runs the action in a SQL transaction
runSqlTx :: (MonadSqlTx db m, HasCallStack) => db a -> m a
class HasSqlBackend a
getSqlBackend :: HasSqlBackend a => a -> SqlBackend

-- | A <a>SqlBackend</a> represents a handle or connection to a database.
--   It contains functions and values that allow databases to have more
--   optimized implementations, as well as references that benefit
--   performance and sharing.
--   
--   Instead of using the <a>SqlBackend</a> constructor directly, use the
--   <a>mkSqlBackend</a> function.
--   
--   A <a>SqlBackend</a> is *not* thread-safe. You should not assume that a
--   <a>SqlBackend</a> can be shared among threads and run concurrent
--   queries. This *will* result in problems. Instead, you should create a
--   <tt><tt>Pool</tt> <a>SqlBackend</a></tt>, known as a
--   <tt>ConnectionPool</tt>, and pass that around in multi-threaded
--   applications.
--   
--   To run actions in the <tt>persistent</tt> library, you should use the
--   <tt>runSqlConn</tt> function. If you're using a multithreaded
--   application, use the <tt>runSqlPool</tt> function.
data () => SqlBackend

-- | A monadic context in which a SQL backend is available for running
--   database queries
class MonadUnliftIO m => MonadSqlBackend m
getSqlBackendM :: MonadSqlBackend m => m SqlBackend

-- | Generalize from <tt>SqlPersistT</tt> to <a>MonadSqlBackend</a>
liftSql :: (MonadSqlBackend m, HasCallStack) => ReaderT SqlBackend m a -> m a


-- | Wrappers that apply <a>liftSql</a> to Esqueleto utilities of the same
--   name.
module Database.Persist.Sql.Lifted.Esqueleto

-- | Execute an Esqueleto DELETE query
delete :: forall m. (MonadSqlBackend m, HasCallStack) => SqlQuery () -> m ()

-- | Execute an Esqueleto DELETE query
deleteCount :: forall m. (MonadSqlBackend m, HasCallStack) => SqlQuery () -> m Int64

-- | Delete a specific record by identifier
--   
--   Does nothing if record does not exist.
deleteKey :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> m ()

-- | Insert a <a>PersistField</a> for every selected value
insertSelect :: forall a m. (PersistEntity a, MonadSqlBackend m, HasCallStack) => SqlQuery (SqlExpr (Insertion a)) -> m ()

-- | Insert a <tt>PersistField</tt> for every selected value, returning the
--   count
insertSelectCount :: forall a m. (PersistEntity a, MonadSqlBackend m, HasCallStack) => SqlQuery (SqlExpr (Insertion a)) -> m Int64

-- | Renders a <a>SqlQuery</a> to <a>Text</a> along with the list of
--   <a>PersistValue</a>s that would be supplied to the database for
--   <tt>?</tt> placeholders
renderQueryDelete :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => SqlQuery a -> m (Text, [PersistValue])

-- | Renders a <a>SqlQuery</a> to <a>Text</a> along with the list of
--   <a>PersistValue</a>s that would be supplied to the database for
--   <tt>?</tt> placeholders
renderQueryInsertInto :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => SqlQuery a -> m (Text, [PersistValue])

-- | Renders a <a>SqlQuery</a> to <a>Text</a> along with the list of
--   <a>PersistValue</a>s that would be supplied to the database for
--   <tt>?</tt> placeholders
renderQuerySelect :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => SqlQuery a -> m (Text, [PersistValue])

-- | Renders a <a>SqlQuery</a> to <a>Text</a> along with the list of
--   <a>PersistValue</a>s that would be supplied to the database for
--   <tt>?</tt> placeholders
renderQueryToText :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => Mode -> SqlQuery a -> m (Text, [PersistValue])

-- | Renders a <a>SqlQuery</a> to <a>Text</a> along with the list of
--   <a>PersistValue</a>s that would be supplied to the database for
--   <tt>?</tt> placeholders
renderQueryUpdate :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => SqlQuery a -> m (Text, [PersistValue])

-- | Execute an Esqueleto SELECT query
select :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => SqlQuery a -> m [r]

-- | Execute an Esqueleto SELECT query, getting only the first row
selectOne :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => SqlQuery a -> m (Maybe r)

-- | Execute an Esqueleto UPDATE query
update :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => (SqlExpr (Entity a) -> SqlQuery ()) -> m ()

-- | Execute an Esqueleto UPDATE query, returning the count
updateCount :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => (SqlExpr (Entity a) -> SqlQuery ()) -> m Int64


-- | Wrappers that apply <a>liftSql</a> to Persistent utilities of the same
--   name.
module Database.Persist.Sql.Lifted.Persistent

-- | Check whether there are any conflicts for unique keys with this entity
--   and existing entities in the database
checkUnique :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => a -> m (Maybe (Unique a))

-- | Check whether there are any conflicts for unique keys with this entity
--   and existing entities in the database
--   
--   This is useful for updating because it ignores conflicts when the
--   particular entity already exists.
checkUniqueUpdateable :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Entity a -> m (Maybe (Unique a))

-- | The total number of records fulfilling the given criteria
count :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> m Int

-- | Delete a specific record by identifier
--   
--   Does nothing if record does not exist.
delete :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> m ()

-- | Delete a specific record by unique key
--   
--   Does nothing if no record matches.
deleteBy :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Unique a -> m ()

-- | Delete all records matching the given criteria
deleteWhere :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> m ()

-- | Check if there is at least one record fulfilling the given criteria
exists :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> m Bool

-- | Get a record by identifier, if available
get :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> m (Maybe a)

-- | Get a record by unique key, if available, returning both the
--   identifier and the record
getBy :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Unique a -> m (Maybe (Entity a))
getByValue :: forall a m. (PersistEntityBackend a ~ SqlBackend, AtLeastOneUniqueKey a, MonadSqlBackend m, HasCallStack) => a -> m (Maybe (Entity a))

-- | Get a record by identifier, if available
getEntity :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> m (Maybe (Entity a))

-- | Get a record by identifier, if available, for a non-null (not
--   <a>Maybe</a>) foreign key
--   
--   Unsafe unless your database is enforcing that the foreign key is
--   valid.
getJust :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> m a

-- | Get a record by identifier, if available, for a non-null (not
--   <a>Maybe</a>) foreign key
--   
--   Unsafe unless your database is enforcing that the foreign key is
--   valid.
getJustEntity :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> m (Entity a)

-- | Get many records by their respective identifiers, if available
getMany :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Key a] -> m (Map (Key a) a)

-- | Create a new record in the database
insert :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m (Key a)

-- | Create a new record in the database
insert_ :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m ()

-- | Insert a value, checking for conflicts with any unique constraints
insertBy :: forall a m. (PersistEntityBackend a ~ SqlBackend, AtLeastOneUniqueKey a, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m (Either (Entity a) (Key a))

-- | Create a new record in the database, returning an auto-increment ID
--   and the inserted record
insertEntity :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m (Entity a)

-- | Create multiple records in the database, with specified keys
insertEntityMany :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Entity a] -> m ()

-- | Create a new record in the database using the given key
insertKey :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> a -> m ()

-- | Create multiple records in the database and return their <a>Key</a>s
insertMany :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => [a] -> m [Key a]

-- | Create multiple records in the database
insertMany_ :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => [a] -> m ()

-- | Create a new record in the database
insertRecord :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m a

-- | Create a new record in the database
insertUnique :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m (Maybe (Key a))

-- | Create a new record in the database
insertUniqueEntity :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m (Maybe (Entity a))

-- | Return the single unique key for a record
onlyUnique :: forall a m. (PersistEntityBackend a ~ SqlBackend, OnlyOneUniqueKey a, MonadSqlBackend m, HasCallStack) => a -> m (Unique a)

-- | Put many records into the database
--   
--   <ul>
--   <li>Insert new records that do not exist (or violate any unique
--   constraints);</li>
--   <li>Replace existing records (matching any unique constraint).</li>
--   </ul>
putMany :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => [a] -> m ()

-- | Replace the record in the database with the given key
--   
--   The result is undefined if such record does not exist.
replace :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> a -> m ()

-- | Attempt to replace the record of the given key with the given new
--   record
--   
--   First query the unique fields to make sure the replacement maintains
--   uniqueness constraints.
replaceUnique :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, Eq (Unique a), MonadSqlBackend m, HasCallStack) => Key a -> a -> m (Maybe (Unique a))

-- | Put the record in the database with the given key
--   
--   If a record with the given key does not exist then a new record will
--   be inserted.
repsert :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> a -> m ()

-- | Put many entities into the database
--   
--   For each item, if a record with the given key does not exist then a
--   new record will be inserted.
repsertMany :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [(Key a, a)] -> m ()

-- | Get just the first record for the criteria
selectFirst :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> [SelectOpt a] -> m (Maybe (Entity a))

-- | Get the <a>Key</a>s of all records matching the given criteria
selectKeys :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, MonadResource m, HasCallStack) => [Filter a] -> [SelectOpt a] -> ConduitT () (Key a) m ()

-- | Get the <a>Key</a>s of all records matching the given criteria
selectKeysList :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> [SelectOpt a] -> m [Key a]
selectList :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> [SelectOpt a] -> m [Entity a]

-- | Commit the current transaction and begin a new one
transactionSave :: forall m. (MonadSqlBackend m, HasCallStack) => m ()

-- | Commit the current transaction and begin a new one
transactionSaveWithIsolation :: forall m. (MonadSqlBackend m, HasCallStack) => IsolationLevel -> m ()

-- | Roll back the current transaction and begin a new one
transactionUndo :: forall m. (MonadSqlBackend m, HasCallStack) => m ()

-- | Roll back the current transaction and begin a new one
transactionUndoWithIsolation :: forall m. (MonadSqlBackend m, HasCallStack) => IsolationLevel -> m ()

-- | Update individual fields on a specific record
update :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> [Update a] -> m ()

-- | Update individual fields on a specific record, and retrieve the
--   updated value from the database
--   
--   This function will throw an exception if the given key is not found in
--   the database.
updateGet :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> [Update a] -> m a

-- | Update individual fields on any record matching the given criteria
updateWhere :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> [Update a] -> m ()

-- | Update based on a uniqueness constraint or insert:
--   
--   <ul>
--   <li>Unsert the new record if it does not exist;</li>
--   <li>If the record exists (matched via it's uniqueness constraint),
--   then update the existing record with the parameters which is passed on
--   as list to the function.</li>
--   </ul>
upsert :: forall a m. (PersistEntityBackend a ~ SqlBackend, SafeToInsert a, OnlyOneUniqueKey a, MonadSqlBackend m, HasCallStack) => a -> [Update a] -> m (Entity a)

-- | Update based on a given uniqueness constraint or insert:
--   
--   <ul>
--   <li>Insert the new record if it does not exist;</li>
--   <li>Update the existing record that matches the given uniqueness
--   constraint.</li>
--   </ul>
upsertBy :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => Unique a -> a -> [Update a] -> m (Entity a)


-- | Re-exports from:
--   
--   <ul>
--   <li><a>Database.Persist.Sql.Lifted.Core</a></li>
--   <li><a>Database.Persist.Sql.Lifted.Persistent</a></li>
--   <li><a>Database.Persist.Sql.Lifted.Esqueleto</a></li>
--   </ul>
--   
--   There are a few name conflicts between Persistent and Esqueleto. Where
--   conflicts occur, this module gives preference to Esqueleto. The
--   following Persistent definitions are renamed:
--   
--   <ul>
--   <li><a>delete</a> -&gt; <a>deleteKey</a></li>
--   <li><a>update</a> -&gt; <a>update'</a></li>
--   </ul>
module Database.Persist.Sql.Lifted

-- | The constraint <tt><a>MonadSqlTx</a> db m</tt> indicates that
--   <tt>m</tt> is a monadic context that can run <tt>db</tt> actions,
--   usually as a SQL transaction. Typically, this means that <tt>db</tt>
--   needs a connection and <tt>m</tt> can provide one, e.g. from a
--   connection pool.
class (MonadSqlBackend db, MonadUnliftIO m) => MonadSqlTx db m | m -> db

-- | Runs the action in a SQL transaction
runSqlTx :: (MonadSqlTx db m, HasCallStack) => db a -> m a
class HasSqlBackend a
getSqlBackend :: HasSqlBackend a => a -> SqlBackend

-- | A <a>SqlBackend</a> represents a handle or connection to a database.
--   It contains functions and values that allow databases to have more
--   optimized implementations, as well as references that benefit
--   performance and sharing.
--   
--   Instead of using the <a>SqlBackend</a> constructor directly, use the
--   <a>mkSqlBackend</a> function.
--   
--   A <a>SqlBackend</a> is *not* thread-safe. You should not assume that a
--   <a>SqlBackend</a> can be shared among threads and run concurrent
--   queries. This *will* result in problems. Instead, you should create a
--   <tt><tt>Pool</tt> <a>SqlBackend</a></tt>, known as a
--   <tt>ConnectionPool</tt>, and pass that around in multi-threaded
--   applications.
--   
--   To run actions in the <tt>persistent</tt> library, you should use the
--   <tt>runSqlConn</tt> function. If you're using a multithreaded
--   application, use the <tt>runSqlPool</tt> function.
data () => SqlBackend

-- | A monadic context in which a SQL backend is available for running
--   database queries
class MonadUnliftIO m => MonadSqlBackend m
getSqlBackendM :: MonadSqlBackend m => m SqlBackend

-- | Generalize from <tt>SqlPersistT</tt> to <a>MonadSqlBackend</a>
liftSql :: (MonadSqlBackend m, HasCallStack) => ReaderT SqlBackend m a -> m a

-- | Get a record by identifier, if available
get :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> m (Maybe a)

-- | Get a record by unique key, if available, returning both the
--   identifier and the record
getBy :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Unique a -> m (Maybe (Entity a))
getByValue :: forall a m. (PersistEntityBackend a ~ SqlBackend, AtLeastOneUniqueKey a, MonadSqlBackend m, HasCallStack) => a -> m (Maybe (Entity a))

-- | Get a record by identifier, if available
getEntity :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> m (Maybe (Entity a))

-- | Get a record by identifier, if available, for a non-null (not
--   <a>Maybe</a>) foreign key
--   
--   Unsafe unless your database is enforcing that the foreign key is
--   valid.
getJust :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> m a

-- | Get a record by identifier, if available, for a non-null (not
--   <a>Maybe</a>) foreign key
--   
--   Unsafe unless your database is enforcing that the foreign key is
--   valid.
getJustEntity :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> m (Entity a)

-- | Get many records by their respective identifiers, if available
getMany :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Key a] -> m (Map (Key a) a)

-- | Execute an Esqueleto SELECT query
select :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => SqlQuery a -> m [r]

-- | Execute an Esqueleto SELECT query, getting only the first row
selectOne :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => SqlQuery a -> m (Maybe r)

-- | Get just the first record for the criteria
selectFirst :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> [SelectOpt a] -> m (Maybe (Entity a))

-- | Get the <a>Key</a>s of all records matching the given criteria
selectKeys :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, MonadResource m, HasCallStack) => [Filter a] -> [SelectOpt a] -> ConduitT () (Key a) m ()

-- | Get the <a>Key</a>s of all records matching the given criteria
selectKeysList :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> [SelectOpt a] -> m [Key a]
selectList :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> [SelectOpt a] -> m [Entity a]

-- | The total number of records fulfilling the given criteria
count :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> m Int

-- | Check if there is at least one record fulfilling the given criteria
exists :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> m Bool

-- | Insert a <a>PersistField</a> for every selected value
insertSelect :: forall a m. (PersistEntity a, MonadSqlBackend m, HasCallStack) => SqlQuery (SqlExpr (Insertion a)) -> m ()

-- | Insert a <tt>PersistField</tt> for every selected value, returning the
--   count
insertSelectCount :: forall a m. (PersistEntity a, MonadSqlBackend m, HasCallStack) => SqlQuery (SqlExpr (Insertion a)) -> m Int64

-- | Create a new record in the database
insert :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m (Key a)

-- | Create a new record in the database
insert_ :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m ()

-- | Insert a value, checking for conflicts with any unique constraints
insertBy :: forall a m. (PersistEntityBackend a ~ SqlBackend, AtLeastOneUniqueKey a, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m (Either (Entity a) (Key a))

-- | Create a new record in the database, returning an auto-increment ID
--   and the inserted record
insertEntity :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m (Entity a)

-- | Create multiple records in the database, with specified keys
insertEntityMany :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Entity a] -> m ()

-- | Create a new record in the database using the given key
insertKey :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> a -> m ()

-- | Create multiple records in the database and return their <a>Key</a>s
insertMany :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => [a] -> m [Key a]

-- | Create multiple records in the database
insertMany_ :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => [a] -> m ()

-- | Create a new record in the database
insertRecord :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m a

-- | Create a new record in the database
insertUnique :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m (Maybe (Key a))

-- | Create a new record in the database
insertUniqueEntity :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => a -> m (Maybe (Entity a))

-- | Execute an Esqueleto UPDATE query
update :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => (SqlExpr (Entity a) -> SqlQuery ()) -> m ()

-- | Execute an Esqueleto UPDATE query, returning the count
updateCount :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => (SqlExpr (Entity a) -> SqlQuery ()) -> m Int64

-- | Update individual fields on a specific record
update' :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> [Update a] -> m ()

-- | Update individual fields on a specific record, and retrieve the
--   updated value from the database
--   
--   This function will throw an exception if the given key is not found in
--   the database.
updateGet :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> [Update a] -> m a

-- | Update individual fields on any record matching the given criteria
updateWhere :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> [Update a] -> m ()

-- | Replace the record in the database with the given key
--   
--   The result is undefined if such record does not exist.
replace :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> a -> m ()

-- | Attempt to replace the record of the given key with the given new
--   record
--   
--   First query the unique fields to make sure the replacement maintains
--   uniqueness constraints.
replaceUnique :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, Eq (Unique a), MonadSqlBackend m, HasCallStack) => Key a -> a -> m (Maybe (Unique a))

-- | Put the record in the database with the given key
--   
--   If a record with the given key does not exist then a new record will
--   be inserted.
repsert :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> a -> m ()

-- | Put many entities into the database
--   
--   For each item, if a record with the given key does not exist then a
--   new record will be inserted.
repsertMany :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [(Key a, a)] -> m ()

-- | Update based on a uniqueness constraint or insert:
--   
--   <ul>
--   <li>Unsert the new record if it does not exist;</li>
--   <li>If the record exists (matched via it's uniqueness constraint),
--   then update the existing record with the parameters which is passed on
--   as list to the function.</li>
--   </ul>
upsert :: forall a m. (PersistEntityBackend a ~ SqlBackend, SafeToInsert a, OnlyOneUniqueKey a, MonadSqlBackend m, HasCallStack) => a -> [Update a] -> m (Entity a)

-- | Update based on a given uniqueness constraint or insert:
--   
--   <ul>
--   <li>Insert the new record if it does not exist;</li>
--   <li>Update the existing record that matches the given uniqueness
--   constraint.</li>
--   </ul>
upsertBy :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => Unique a -> a -> [Update a] -> m (Entity a)

-- | Put many records into the database
--   
--   <ul>
--   <li>Insert new records that do not exist (or violate any unique
--   constraints);</li>
--   <li>Replace existing records (matching any unique constraint).</li>
--   </ul>
putMany :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, SafeToInsert a, MonadSqlBackend m, HasCallStack) => [a] -> m ()

-- | Check whether there are any conflicts for unique keys with this entity
--   and existing entities in the database
checkUnique :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => a -> m (Maybe (Unique a))

-- | Check whether there are any conflicts for unique keys with this entity
--   and existing entities in the database
--   
--   This is useful for updating because it ignores conflicts when the
--   particular entity already exists.
checkUniqueUpdateable :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Entity a -> m (Maybe (Unique a))

-- | Return the single unique key for a record
onlyUnique :: forall a m. (PersistEntityBackend a ~ SqlBackend, OnlyOneUniqueKey a, MonadSqlBackend m, HasCallStack) => a -> m (Unique a)

-- | Execute an Esqueleto DELETE query
delete :: forall m. (MonadSqlBackend m, HasCallStack) => SqlQuery () -> m ()

-- | Delete a specific record by identifier
--   
--   Does nothing if record does not exist.
deleteKey :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Key a -> m ()

-- | Delete a specific record by unique key
--   
--   Does nothing if no record matches.
deleteBy :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => Unique a -> m ()

-- | Delete all records matching the given criteria
deleteWhere :: forall a m. (PersistEntity a, PersistEntityBackend a ~ SqlBackend, MonadSqlBackend m, HasCallStack) => [Filter a] -> m ()

-- | Execute an Esqueleto DELETE query
deleteCount :: forall m. (MonadSqlBackend m, HasCallStack) => SqlQuery () -> m Int64

-- | Commit the current transaction and begin a new one
transactionSave :: forall m. (MonadSqlBackend m, HasCallStack) => m ()

-- | Commit the current transaction and begin a new one
transactionSaveWithIsolation :: forall m. (MonadSqlBackend m, HasCallStack) => IsolationLevel -> m ()

-- | Roll back the current transaction and begin a new one
transactionUndo :: forall m. (MonadSqlBackend m, HasCallStack) => m ()

-- | Roll back the current transaction and begin a new one
transactionUndoWithIsolation :: forall m. (MonadSqlBackend m, HasCallStack) => IsolationLevel -> m ()

-- | Renders a <a>SqlQuery</a> to <a>Text</a> along with the list of
--   <a>PersistValue</a>s that would be supplied to the database for
--   <tt>?</tt> placeholders
renderQueryDelete :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => SqlQuery a -> m (Text, [PersistValue])

-- | Renders a <a>SqlQuery</a> to <a>Text</a> along with the list of
--   <a>PersistValue</a>s that would be supplied to the database for
--   <tt>?</tt> placeholders
renderQueryInsertInto :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => SqlQuery a -> m (Text, [PersistValue])

-- | Renders a <a>SqlQuery</a> to <a>Text</a> along with the list of
--   <a>PersistValue</a>s that would be supplied to the database for
--   <tt>?</tt> placeholders
renderQuerySelect :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => SqlQuery a -> m (Text, [PersistValue])

-- | Renders a <a>SqlQuery</a> to <a>Text</a> along with the list of
--   <a>PersistValue</a>s that would be supplied to the database for
--   <tt>?</tt> placeholders
renderQueryToText :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => Mode -> SqlQuery a -> m (Text, [PersistValue])

-- | Renders a <a>SqlQuery</a> to <a>Text</a> along with the list of
--   <a>PersistValue</a>s that would be supplied to the database for
--   <tt>?</tt> placeholders
renderQueryUpdate :: forall a r m. (SqlSelect a r, MonadSqlBackend m, HasCallStack) => SqlQuery a -> m (Text, [PersistValue])

module Database.Persist.Sql.Lifted.Query.Aggregate

-- | <tt>GROUP BY</tt> clause. You can enclose multiple columns in a tuple.
--   
--   <pre>
--   select $ <a>from</a> \(foo `<a>InnerJoin</a>` bar) -&gt; do
--     <a>on</a> (foo <a>^.</a> FooBarId <a>==.</a> bar <a>^.</a> BarId)
--     <a>groupBy</a> (bar <a>^.</a> BarId, bar <a>^.</a> BarName)
--     return (bar <a>^.</a> BarId, bar <a>^.</a> BarName, countRows)
--   </pre>
--   
--   With groupBy you can sort by aggregate functions, like so (we used
--   <tt>let</tt> to restrict the more general <a>countRows</a> to
--   <tt>SqlSqlExpr (Value Int)</tt> to avoid ambiguity---the second use of
--   <a>countRows</a> has its type restricted by the <tt>:: Int</tt>
--   below):
--   
--   <pre>
--   r &lt;- select $ <a>from</a> \(foo `<a>InnerJoin</a>` bar) -&gt; do
--     <a>on</a> (foo <a>^.</a> FooBarId <a>==.</a> bar <a>^.</a> BarId)
--     <a>groupBy</a> $ bar <a>^.</a> BarName
--     let countRows' = <a>countRows</a>
--     <a>orderBy</a> [<a>asc</a> countRows']
--     return (bar <a>^.</a> BarName, countRows')
--   forM_ r $ \(<a>Value</a> name, <a>Value</a> count) -&gt; do
--     print name
--     print (count :: Int)
--   </pre>
--   
--   <h3>Need more columns?</h3>
--   
--   The <a>ToSomeValues</a> class is defined for <a>SqlExpr</a> and tuples
--   of <a>SqlExpr</a>s. We only have definitions for up to 8 elements in a
--   tuple right now, so it's possible that you may need to have more than
--   8 elements.
--   
--   For example, consider a query with a <a>groupBy</a> call like this:
--   
--   <pre>
--   groupBy (e0, e1, e2, e3, e4, e5, e6, e7)
--   </pre>
--   
--   This is the biggest you can get with a single tuple. However, you can
--   easily nest the tuples to add more:
--   
--   <pre>
--   groupBy ((e0, e1, e2, e3, e4, e5, e6, e7), e8, e9)
--   </pre>
groupBy :: ToSomeValues a => a -> SqlQuery ()

-- | An alias for <a>groupBy</a> that avoids conflict with the term from
--   <a>Data.List</a> <a>groupBy</a>.
groupBy_ :: ToSomeValues a => a -> SqlQuery ()

-- | <tt>HAVING</tt>.
having :: SqlExpr (Value Bool) -> SqlQuery ()

module Database.Persist.Sql.Lifted.Query.CommonTableExpressions

-- | <tt>WITH</tt> clause used to introduce a <a>Common Table Expression
--   (CTE)</a>. CTEs are supported in most modern SQL engines and can be
--   useful in performance tuning. In Esqueleto, CTEs should be used as a
--   subquery memoization tactic. When writing plain SQL, CTEs are
--   sometimes used to organize the SQL code, in Esqueleto, this is better
--   achieved through function that return <a>SqlQuery</a> values.
--   
--   <pre>
--   select $ do
--   cte &lt;- with subQuery
--   cteResult &lt;- from cte
--   where_ $ cteResult ...
--   pure cteResult
--   </pre>
--   
--   <b>WARNING</b>: In some SQL engines using a CTE can diminish
--   performance. In these engines the CTE is treated as an optimization
--   fence. You should always verify that using a CTE will in fact improve
--   your performance over a regular subquery.
--   
--   Notably, in PostgreSQL prior to version 12, CTEs are always fully
--   calculated, which can potentially significantly pessimize queries. As
--   of PostgreSQL 12, non-recursive and side-effect-free queries may be
--   inlined and optimized accordingly if not declared
--   <tt>MATERIALIZED</tt> to get the previous behaviour. See <a>the
--   PostgreSQL CTE documentation</a>, section Materialization, for more
--   information. To use a <tt>MATERIALIZED</tt> query in Esquelto, see
--   functions <tt>withMaterialized</tt> and
--   <tt>withRecursiveMaterialized</tt>.
--   
--   <i>Since: 3.4.0.0</i>
with :: (ToAlias a, ToAliasReference a, SqlSelect a r) => SqlQuery a -> SqlQuery (From a)

-- | <tt>WITH</tt> <tt>RECURSIVE</tt> allows one to make a recursive
--   subquery, which can reference itself. Like <tt>WITH</tt>, this is
--   supported in most modern SQL engines. Useful for hierarchical,
--   self-referential data, like a tree of data.
--   
--   <pre>
--   select $ do
--   cte &lt;- withRecursive
--            (do
--                person &lt;- from $ table @Person
--                where_ $ person ^. PersonId ==. val personId
--                pure person
--            )
--            unionAll_
--            (\self -&gt; do
--                (p :&amp; f :&amp; p2 :&amp; pSelf) &lt;- from self
--                         `innerJoin` $ table @Follow
--                         `on` (\(p :&amp; f) -&gt;
--                                 p ^. PersonId ==. f ^. FollowFollower)
--                         `innerJoin` $ table @Person
--                         `on` (\(p :&amp; f :&amp; p2) -&gt;
--                                 f ^. FollowFollowed ==. p2 ^. PersonId)
--                         `leftJoin` self
--                         `on` (\(_ :&amp; _ :&amp; p2 :&amp; pSelf) -&gt;
--                                 just (p2 ^. PersonId) ==. pSelf ?. PersonId)
--                where_ $ isNothing (pSelf ?. PersonId)
--                groupBy (p2 ^. PersonId)
--                pure p2
--            )
--   from cte
--   </pre>
--   
--   <i>Since: 3.4.0.0</i>
withRecursive :: (ToAlias a, ToAliasReference a, SqlSelect a r) => SqlQuery a -> UnionKind -> (From a -> SqlQuery a) -> SqlQuery (From a)

module Database.Persist.Sql.Lifted.Query.Core

-- | SQL backend for <tt>esqueleto</tt> using <a>SqlPersistT</a>.
data () => SqlQuery a

-- | <tt>WHERE</tt> clause: restrict the query's result.
where_ :: SqlExpr (Value Bool) -> SqlQuery ()

-- | <tt>LIMIT</tt>. Limit the number of returned rows.
limit :: Int64 -> SqlQuery ()

-- | <tt>OFFSET</tt>. Usually used with <a>limit</a>.
offset :: Int64 -> SqlQuery ()

-- | <tt>DISTINCT</tt>. Change the current <tt>SELECT</tt> into <tt>SELECT
--   DISTINCT</tt>. For example:
--   
--   <pre>
--   select $ distinct $
--     <a>from</a> \foo -&gt; do
--     ...
--   </pre>
--   
--   Note that this also has the same effect:
--   
--   <pre>
--   select $
--     <a>from</a> \foo -&gt; do
--     distinct (return ())
--     ...
--   </pre>
distinct :: SqlQuery a -> SqlQuery a

-- | <tt>DISTINCT ON</tt>. Change the current <tt>SELECT</tt> into
--   <tt>SELECT DISTINCT ON (SqlExpressions)</tt>. For example:
--   
--   <pre>
--   select $
--     <a>from</a> \foo -&gt;
--     <a>distinctOn</a> [<a>don</a> (foo ^. FooName), <a>don</a> (foo ^. FooState)] $ do
--     ...
--   </pre>
--   
--   You can also chain different calls to <a>distinctOn</a>. The above is
--   equivalent to:
--   
--   <pre>
--   select $
--     <a>from</a> \foo -&gt;
--     <a>distinctOn</a> [<a>don</a> (foo ^. FooName)] $
--     <a>distinctOn</a> [<a>don</a> (foo ^. FooState)] $ do
--     ...
--   </pre>
--   
--   Each call to <a>distinctOn</a> adds more SqlExpressions. Calls to
--   <a>distinctOn</a> override any calls to <a>distinct</a>.
--   
--   Note that PostgreSQL requires the SqlExpressions on <tt>DISTINCT
--   ON</tt> to be the first ones to appear on a <tt>ORDER BY</tt>. This is
--   not managed automatically by esqueleto, keeping its spirit of trying
--   to be close to raw SQL.
--   
--   Supported by PostgreSQL only.
distinctOn :: [SqlExpr DistinctOn] -> SqlQuery a -> SqlQuery a

-- | <tt>ORDER BY</tt> clause. See also <a>asc</a> and <a>desc</a>.
--   
--   Multiple calls to <a>orderBy</a> get concatenated on the final query,
--   including <a>distinctOnOrderBy</a>.
orderBy :: [SqlExpr OrderBy] -> SqlQuery ()

-- | Erase an SqlExpression's type so that it's suitable to be used by
--   <a>distinctOn</a>.
don :: SqlExpr (Value a) -> SqlExpr DistinctOn

-- | A convenience function that calls both <a>distinctOn</a> and
--   <a>orderBy</a>. In other words,
--   
--   <pre>
--   <a>distinctOnOrderBy</a> [asc foo, desc bar, desc quux] $ do
--     ...
--   </pre>
--   
--   is the same as:
--   
--   <pre>
--   <a>distinctOn</a> [don foo, don  bar, don  quux] $ do
--     <a>orderBy</a>  [asc foo, desc bar, desc quux]
--     ...
--   </pre>
distinctOnOrderBy :: [SqlExpr OrderBy] -> SqlQuery a -> SqlQuery a

-- | Project an SqlExpression that may be null, guarding against null
--   cases.
withNonNull :: PersistField typ => SqlExpr (Value (Maybe typ)) -> (SqlExpr (Value typ) -> SqlQuery a) -> SqlQuery a

module Database.Persist.Sql.Lifted.Query.Locking

-- | Add a locking clause to the query. Please read <a>LockingKind</a>
--   documentation and your RDBMS manual. Unsafe since not all locking
--   clauses are implemented for every RDBMS
--   
--   If multiple calls to <a>locking</a> are made on the same query, the
--   last one is used.
locking :: LockingKind -> SqlQuery ()

-- | Different kinds of locking clauses supported by <a>locking</a>.
--   
--   Note that each RDBMS has different locking support. The constructors
--   of this datatype specify only the <i>syntax</i> of the locking
--   mechanism, not its <i>semantics</i>. For example, even though both
--   MySQL and PostgreSQL support <a>ForUpdate</a>, there are no guarantees
--   that they will behave the same.
data () => LockingKind

-- | <tt>FOR UPDATE</tt> syntax. Supported by MySQL, Oracle and PostgreSQL.
ForUpdate :: LockingKind

-- | <tt>FOR UPDATE SKIP LOCKED</tt> syntax. Supported by MySQL, Oracle and
--   PostgreSQL.
ForUpdateSkipLocked :: LockingKind

-- | <tt>FOR SHARE</tt> syntax. Supported by PostgreSQL.
ForShare :: LockingKind

-- | <tt>LOCK IN SHARE MODE</tt> syntax. Supported by MySQL.
LockInShareMode :: LockingKind

module Database.Persist.Sql.Lifted.Query.SetOperations

-- | <tt>UNION</tt> SQL set operation. Can be used as an infix function
--   between <a>SqlQuery</a> values.
union_ :: Union_ a => a

-- | <tt>UNION</tt> <tt>ALL</tt> SQL set operation. Can be used as an infix
--   function between <a>SqlQuery</a> values.
unionAll_ :: UnionAll_ a => a

-- | <tt>EXCEPT</tt> SQL set operation. Can be used as an infix function
--   between <a>SqlQuery</a> values.
except_ :: (ToSqlSetOperation a a', ToSqlSetOperation b a') => a -> b -> SqlSetOperation a'

-- | <tt>INTERSECT</tt> SQL set operation. Can be used as an infix function
--   between <a>SqlQuery</a> values.
intersect_ :: (ToSqlSetOperation a a', ToSqlSetOperation b a') => a -> b -> SqlSetOperation a'

module Database.Persist.Sql.Lifted.Query.Update

-- | <tt>SET</tt> clause used on <tt>UPDATE</tt>s. Note that while it's not
--   a type error to use this function on a <tt>SELECT</tt>, it will most
--   certainly result in a runtime error.
set :: PersistEntity val => SqlExpr (Entity val) -> [SqlExpr (Entity val) -> SqlExpr Update] -> SqlQuery ()

module Database.Persist.Sql.Lifted.Query

-- | SQL backend for <tt>esqueleto</tt> using <a>SqlPersistT</a>.
data () => SqlQuery a

-- | <tt>WHERE</tt> clause: restrict the query's result.
where_ :: SqlExpr (Value Bool) -> SqlQuery ()

-- | <tt>GROUP BY</tt> clause. You can enclose multiple columns in a tuple.
--   
--   <pre>
--   select $ <a>from</a> \(foo `<a>InnerJoin</a>` bar) -&gt; do
--     <a>on</a> (foo <a>^.</a> FooBarId <a>==.</a> bar <a>^.</a> BarId)
--     <a>groupBy</a> (bar <a>^.</a> BarId, bar <a>^.</a> BarName)
--     return (bar <a>^.</a> BarId, bar <a>^.</a> BarName, countRows)
--   </pre>
--   
--   With groupBy you can sort by aggregate functions, like so (we used
--   <tt>let</tt> to restrict the more general <a>countRows</a> to
--   <tt>SqlSqlExpr (Value Int)</tt> to avoid ambiguity---the second use of
--   <a>countRows</a> has its type restricted by the <tt>:: Int</tt>
--   below):
--   
--   <pre>
--   r &lt;- select $ <a>from</a> \(foo `<a>InnerJoin</a>` bar) -&gt; do
--     <a>on</a> (foo <a>^.</a> FooBarId <a>==.</a> bar <a>^.</a> BarId)
--     <a>groupBy</a> $ bar <a>^.</a> BarName
--     let countRows' = <a>countRows</a>
--     <a>orderBy</a> [<a>asc</a> countRows']
--     return (bar <a>^.</a> BarName, countRows')
--   forM_ r $ \(<a>Value</a> name, <a>Value</a> count) -&gt; do
--     print name
--     print (count :: Int)
--   </pre>
--   
--   <h3>Need more columns?</h3>
--   
--   The <a>ToSomeValues</a> class is defined for <a>SqlExpr</a> and tuples
--   of <a>SqlExpr</a>s. We only have definitions for up to 8 elements in a
--   tuple right now, so it's possible that you may need to have more than
--   8 elements.
--   
--   For example, consider a query with a <a>groupBy</a> call like this:
--   
--   <pre>
--   groupBy (e0, e1, e2, e3, e4, e5, e6, e7)
--   </pre>
--   
--   This is the biggest you can get with a single tuple. However, you can
--   easily nest the tuples to add more:
--   
--   <pre>
--   groupBy ((e0, e1, e2, e3, e4, e5, e6, e7), e8, e9)
--   </pre>
groupBy :: ToSomeValues a => a -> SqlQuery ()

-- | An alias for <a>groupBy</a> that avoids conflict with the term from
--   <a>Data.List</a> <a>groupBy</a>.
groupBy_ :: ToSomeValues a => a -> SqlQuery ()

-- | <tt>HAVING</tt>.
having :: SqlExpr (Value Bool) -> SqlQuery ()

-- | <tt>LIMIT</tt>. Limit the number of returned rows.
limit :: Int64 -> SqlQuery ()

-- | <tt>OFFSET</tt>. Usually used with <a>limit</a>.
offset :: Int64 -> SqlQuery ()

-- | <tt>DISTINCT</tt>. Change the current <tt>SELECT</tt> into <tt>SELECT
--   DISTINCT</tt>. For example:
--   
--   <pre>
--   select $ distinct $
--     <a>from</a> \foo -&gt; do
--     ...
--   </pre>
--   
--   Note that this also has the same effect:
--   
--   <pre>
--   select $
--     <a>from</a> \foo -&gt; do
--     distinct (return ())
--     ...
--   </pre>
distinct :: SqlQuery a -> SqlQuery a

-- | <tt>DISTINCT ON</tt>. Change the current <tt>SELECT</tt> into
--   <tt>SELECT DISTINCT ON (SqlExpressions)</tt>. For example:
--   
--   <pre>
--   select $
--     <a>from</a> \foo -&gt;
--     <a>distinctOn</a> [<a>don</a> (foo ^. FooName), <a>don</a> (foo ^. FooState)] $ do
--     ...
--   </pre>
--   
--   You can also chain different calls to <a>distinctOn</a>. The above is
--   equivalent to:
--   
--   <pre>
--   select $
--     <a>from</a> \foo -&gt;
--     <a>distinctOn</a> [<a>don</a> (foo ^. FooName)] $
--     <a>distinctOn</a> [<a>don</a> (foo ^. FooState)] $ do
--     ...
--   </pre>
--   
--   Each call to <a>distinctOn</a> adds more SqlExpressions. Calls to
--   <a>distinctOn</a> override any calls to <a>distinct</a>.
--   
--   Note that PostgreSQL requires the SqlExpressions on <tt>DISTINCT
--   ON</tt> to be the first ones to appear on a <tt>ORDER BY</tt>. This is
--   not managed automatically by esqueleto, keeping its spirit of trying
--   to be close to raw SQL.
--   
--   Supported by PostgreSQL only.
distinctOn :: [SqlExpr DistinctOn] -> SqlQuery a -> SqlQuery a

-- | <tt>ORDER BY</tt> clause. See also <a>asc</a> and <a>desc</a>.
--   
--   Multiple calls to <a>orderBy</a> get concatenated on the final query,
--   including <a>distinctOnOrderBy</a>.
orderBy :: [SqlExpr OrderBy] -> SqlQuery ()

-- | Erase an SqlExpression's type so that it's suitable to be used by
--   <a>distinctOn</a>.
don :: SqlExpr (Value a) -> SqlExpr DistinctOn

-- | A convenience function that calls both <a>distinctOn</a> and
--   <a>orderBy</a>. In other words,
--   
--   <pre>
--   <a>distinctOnOrderBy</a> [asc foo, desc bar, desc quux] $ do
--     ...
--   </pre>
--   
--   is the same as:
--   
--   <pre>
--   <a>distinctOn</a> [don foo, don  bar, don  quux] $ do
--     <a>orderBy</a>  [asc foo, desc bar, desc quux]
--     ...
--   </pre>
distinctOnOrderBy :: [SqlExpr OrderBy] -> SqlQuery a -> SqlQuery a

-- | <tt>SET</tt> clause used on <tt>UPDATE</tt>s. Note that while it's not
--   a type error to use this function on a <tt>SELECT</tt>, it will most
--   certainly result in a runtime error.
set :: PersistEntity val => SqlExpr (Entity val) -> [SqlExpr (Entity val) -> SqlExpr Update] -> SqlQuery ()

-- | Project an SqlExpression that may be null, guarding against null
--   cases.
withNonNull :: PersistField typ => SqlExpr (Value (Maybe typ)) -> (SqlExpr (Value typ) -> SqlQuery a) -> SqlQuery a

-- | Add a locking clause to the query. Please read <a>LockingKind</a>
--   documentation and your RDBMS manual. Unsafe since not all locking
--   clauses are implemented for every RDBMS
--   
--   If multiple calls to <a>locking</a> are made on the same query, the
--   last one is used.
locking :: LockingKind -> SqlQuery ()

-- | Different kinds of locking clauses supported by <a>locking</a>.
--   
--   Note that each RDBMS has different locking support. The constructors
--   of this datatype specify only the <i>syntax</i> of the locking
--   mechanism, not its <i>semantics</i>. For example, even though both
--   MySQL and PostgreSQL support <a>ForUpdate</a>, there are no guarantees
--   that they will behave the same.
data () => LockingKind

-- | <tt>FOR UPDATE</tt> syntax. Supported by MySQL, Oracle and PostgreSQL.
ForUpdate :: LockingKind

-- | <tt>FOR UPDATE SKIP LOCKED</tt> syntax. Supported by MySQL, Oracle and
--   PostgreSQL.
ForUpdateSkipLocked :: LockingKind

-- | <tt>FOR SHARE</tt> syntax. Supported by PostgreSQL.
ForShare :: LockingKind

-- | <tt>LOCK IN SHARE MODE</tt> syntax. Supported by MySQL.
LockInShareMode :: LockingKind

-- | <tt>UNION</tt> SQL set operation. Can be used as an infix function
--   between <a>SqlQuery</a> values.
union_ :: Union_ a => a

-- | <tt>UNION</tt> <tt>ALL</tt> SQL set operation. Can be used as an infix
--   function between <a>SqlQuery</a> values.
unionAll_ :: UnionAll_ a => a

-- | <tt>EXCEPT</tt> SQL set operation. Can be used as an infix function
--   between <a>SqlQuery</a> values.
except_ :: (ToSqlSetOperation a a', ToSqlSetOperation b a') => a -> b -> SqlSetOperation a'

-- | <tt>INTERSECT</tt> SQL set operation. Can be used as an infix function
--   between <a>SqlQuery</a> values.
intersect_ :: (ToSqlSetOperation a a', ToSqlSetOperation b a') => a -> b -> SqlSetOperation a'

-- | <tt>WITH</tt> clause used to introduce a <a>Common Table Expression
--   (CTE)</a>. CTEs are supported in most modern SQL engines and can be
--   useful in performance tuning. In Esqueleto, CTEs should be used as a
--   subquery memoization tactic. When writing plain SQL, CTEs are
--   sometimes used to organize the SQL code, in Esqueleto, this is better
--   achieved through function that return <a>SqlQuery</a> values.
--   
--   <pre>
--   select $ do
--   cte &lt;- with subQuery
--   cteResult &lt;- from cte
--   where_ $ cteResult ...
--   pure cteResult
--   </pre>
--   
--   <b>WARNING</b>: In some SQL engines using a CTE can diminish
--   performance. In these engines the CTE is treated as an optimization
--   fence. You should always verify that using a CTE will in fact improve
--   your performance over a regular subquery.
--   
--   Notably, in PostgreSQL prior to version 12, CTEs are always fully
--   calculated, which can potentially significantly pessimize queries. As
--   of PostgreSQL 12, non-recursive and side-effect-free queries may be
--   inlined and optimized accordingly if not declared
--   <tt>MATERIALIZED</tt> to get the previous behaviour. See <a>the
--   PostgreSQL CTE documentation</a>, section Materialization, for more
--   information. To use a <tt>MATERIALIZED</tt> query in Esquelto, see
--   functions <tt>withMaterialized</tt> and
--   <tt>withRecursiveMaterialized</tt>.
--   
--   <i>Since: 3.4.0.0</i>
with :: (ToAlias a, ToAliasReference a, SqlSelect a r) => SqlQuery a -> SqlQuery (From a)

-- | <tt>WITH</tt> <tt>RECURSIVE</tt> allows one to make a recursive
--   subquery, which can reference itself. Like <tt>WITH</tt>, this is
--   supported in most modern SQL engines. Useful for hierarchical,
--   self-referential data, like a tree of data.
--   
--   <pre>
--   select $ do
--   cte &lt;- withRecursive
--            (do
--                person &lt;- from $ table @Person
--                where_ $ person ^. PersonId ==. val personId
--                pure person
--            )
--            unionAll_
--            (\self -&gt; do
--                (p :&amp; f :&amp; p2 :&amp; pSelf) &lt;- from self
--                         `innerJoin` $ table @Follow
--                         `on` (\(p :&amp; f) -&gt;
--                                 p ^. PersonId ==. f ^. FollowFollower)
--                         `innerJoin` $ table @Person
--                         `on` (\(p :&amp; f :&amp; p2) -&gt;
--                                 f ^. FollowFollowed ==. p2 ^. PersonId)
--                         `leftJoin` self
--                         `on` (\(_ :&amp; _ :&amp; p2 :&amp; pSelf) -&gt;
--                                 just (p2 ^. PersonId) ==. pSelf ?. PersonId)
--                where_ $ isNothing (pSelf ?. PersonId)
--                groupBy (p2 ^. PersonId)
--                pure p2
--            )
--   from cte
--   </pre>
--   
--   <i>Since: 3.4.0.0</i>
withRecursive :: (ToAlias a, ToAliasReference a, SqlSelect a r) => SqlQuery a -> UnionKind -> (From a -> SqlQuery a) -> SqlQuery (From a)

module Database.Persist.Sql.Lifted.Update

-- | Updating a database entity.
--   
--   Persistent users use combinators to create these.
data () => Update record

-- | Assign a field a value.
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   updateAge :: MonadIO m =&gt; ReaderT SqlBackend m ()
--   updateAge = updateWhere [UserName ==. "SPJ" ] [UserAge =. 45]
--   </pre>
--   
--   Similar to <a>updateWhere</a> which is shown in the above example you
--   can use other functions present in the module
--   <a>Database.Persist.Class</a>. Note that the first parameter of
--   <a>updateWhere</a> is [<a>Filter</a> val] and second parameter is
--   [<a>Update</a> val]. By comparing this with the type of <a>==.</a> and
--   <a>=.</a>, you can see that they match up in the above usage.
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+--------+
--   |id   |name |age     |
--   +-----+-----+--------+
--   |1    |SPJ  |40 -&gt; 45|
--   +-----+-----+--------+
--   |2    |Simon|41      |
--   +-----+-----+--------+
--   </pre>
(=.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Update v
infixr 3 =.

-- | Assign a field by addition (<tt>+=</tt>).
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   addAge :: MonadIO m =&gt; ReaderT SqlBackend m ()
--   addAge = updateWhere [UserName ==. "SPJ" ] [UserAge +=. 1]
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+---------+
--   |id   |name |age      |
--   +-----+-----+---------+
--   |1    |SPJ  |40 -&gt; 41 |
--   +-----+-----+---------+
--   |2    |Simon|41       |
--   +-----+-----+---------+
--   </pre>
(+=.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Update v
infixr 3 +=.

-- | Assign a field by subtraction (<tt>-=</tt>).
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   subtractAge :: MonadIO m =&gt; ReaderT SqlBackend m ()
--   subtractAge = updateWhere [UserName ==. "SPJ" ] [UserAge -=. 1]
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+---------+
--   |id   |name |age      |
--   +-----+-----+---------+
--   |1    |SPJ  |40 -&gt; 39 |
--   +-----+-----+---------+
--   |2    |Simon|41       |
--   +-----+-----+---------+
--   </pre>
(-=.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Update v
infixr 3 -=.

-- | Assign a field by multiplication (<tt>*=</tt>).
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   multiplyAge :: MonadIO m =&gt; ReaderT SqlBackend m ()
--   multiplyAge = updateWhere [UserName ==. "SPJ" ] [UserAge *=. 2]
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+--------+
--   |id   |name |age     |
--   +-----+-----+--------+
--   |1    |SPJ  |40 -&gt; 80|
--   +-----+-----+--------+
--   |2    |Simon|41      |
--   +-----+-----+--------+
--   </pre>
(*=.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Update v
infixr 3 *=.

-- | Assign a field by division (<tt>/=</tt>).
--   
--   <h3>Examples</h3>
--   
--   <pre>
--   divideAge :: MonadIO m =&gt; ReaderT SqlBackend m ()
--   divideAge = updateWhere [UserName ==. "SPJ" ] [UserAge /=. 2]
--   </pre>
--   
--   The above query when applied on <a>dataset-1</a>, will produce this:
--   
--   <pre>
--   +-----+-----+---------+
--   |id   |name |age      |
--   +-----+-----+---------+
--   |1    |SPJ  |40 -&gt; 20 |
--   +-----+-----+---------+
--   |2    |Simon|41       |
--   +-----+-----+---------+
--   </pre>
(/=.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Update v
infixr 3 /=.