Deprecation Cycles for 3.6 (#412)

* Deprecate ilike outside of Postgres

* lol

* Deprecation Cycling

* wow okay cool

* oh woops

changelog.md

@@ -1,6 +1,25 @@
 3.6.0.0
 =======
 - @parsonsmatt
+    - [#412](https://github.com/bitemyapp/esqueleto/pull/412)
+        - The `random_` and `rand` functions (deprecated in 2.6.0) have been
+          removed. Please refer to the database specific ones (ie
+          `Database.Esqueleto.PostgreSQL` etc)
+        - The `sub_select` function (deprecated in 3.2.0) has been removed.
+          Please use the safer variants like `subSelect`, `subSelectMaybe`, etc.
+        - The `ToAliasT` and `ToAliasReferenceT` types has been removed after having been deprecated in 3.4.0.1.
+        - The `Union` type (deprecated in 3.4) was removed. Please use `union_`
+          instead.
+        - The `UnionAll` type (deprecated in 3.4) was removed. Please use
+          `unionAll_` instead.
+        - The `Except` type  (deprecated in 3.4) was removed. Please use
+          `except_` instead.
+        - The `Intersect` type  (deprecated in 3.4) was removed. Please use
+          `intersect_` instead.
+        - The `SubQuery` type (deprecated in 3.4) was removed. You do not need
+          to tag subqueries to use them in `from` clauses.
+        - The `SelectQuery` type (deprecated in 3.4) was removed. You do not
+          need to tag `SqlQuery` values with `SelectQuery`.
     - [#287](https://github.com/bitemyapp/esqueleto/pull/278)
         - Deprecate `distinctOn` and `distinctOnOrderBy`. Use the variants
           defined in `PostgreSQL` module instead. The signature has changed, but

src/Database/Esqueleto.hs

@@ -51,14 +51,14 @@ module Database.Esqueleto {-# WARNING "This module will switch over to the Exper
     -- $gettingstarted
 
     -- * @esqueleto@'s Language
-    where_, on, groupBy, orderBy, rand, asc, desc, limit, offset
+    where_, on, groupBy, orderBy, asc, desc, limit, offset
              , distinct, distinctOn, don, distinctOnOrderBy, having, locking
-             , sub_select, (^.), (?.)
+             , (^.), (?.)
              , val, isNothing, just, nothing, joinV, withNonNull
              , countRows, count, countDistinct
              , not_, (==.), (>=.), (>.), (<=.), (<.), (!=.), (&&.), (||.)
              , between, (+.), (-.), (/.), (*.)
-             , random_, round_, ceiling_, floor_
+             , round_, ceiling_, floor_
              , min_, max_, sum_, avg_, castNum, castNumM
              , coalesce, coalesceDefault
              , lower_, upper_, trim_, ltrim_, rtrim_, length_, left_, right_

src/Database/Esqueleto/Experimental.hs

@@ -22,7 +22,6 @@ module Database.Esqueleto.Experimental
       from
     , table
     , Table(..)
-    , SubQuery(..)
     , selectQuery
 
     -- ** Joins
@@ -40,14 +39,9 @@ module Database.Esqueleto.Experimental
       -- ** Set Operations
       -- $sql-set-operations
     , union_
-    , Union(..)
     , unionAll_
-    , UnionAll(..)
     , except_
-    , Except(..)
     , intersect_
-    , Intersect(..)
-    , pattern SelectQuery
 
       -- ** Common Table Expressions
     , with
@@ -57,9 +51,7 @@ module Database.Esqueleto.Experimental
     , From(..)
     , ToMaybe(..)
     , ToAlias(..)
-    , ToAliasT
     , ToAliasReference(..)
-    , ToAliasReferenceT
     , ToSqlSetOperation(..)
     , SqlSelect
 
@@ -68,7 +60,6 @@ module Database.Esqueleto.Experimental
     , groupBy
     , groupBy_
     , orderBy
-    , rand
     , asc
     , desc
     , limit
@@ -81,7 +72,6 @@ module Database.Esqueleto.Experimental
     , having
     , locking
 
-    , sub_select
     , (^.)
     , (?.)
 
@@ -113,7 +103,6 @@ module Database.Esqueleto.Experimental
     , (/.)
     , (*.)
 
-    , random_
     , round_
     , ceiling_
     , floor_

src/Database/Esqueleto/Experimental/From.hs

@@ -98,10 +98,6 @@ table = From $ do
                )
 
 
-{-# DEPRECATED SubQuery "/Since: 3.4.0.0/ - It is no longer necessary to tag 'SqlQuery' values with @SubQuery@" #-}
-newtype SubQuery a = SubQuery a
-instance (SqlSelect a r, ToAlias a, ToAliasReference a) => ToFrom (SubQuery (SqlQuery a)) a where
-    toFrom (SubQuery q) = selectQuery q
 instance (SqlSelect a r, ToAlias a, ToAliasReference a) => ToFrom (SqlQuery a) a where
     toFrom = selectQuery
 

src/Database/Esqueleto/Experimental/From/SqlSetOperation.hs

@@ -74,11 +74,6 @@ mkSetOperation operation lhs rhs = SqlSetOperation $ \p -> do
     (_, rightClause) <- unSqlSetOperation (toSqlSetOperation rhs) p
     pure (leftValue, \info -> leftClause info <> (operation, mempty) <> rightClause info)
 
-{-# DEPRECATED Union "/Since: 3.4.0.0/ - Use the 'union_' function instead of the 'Union' data constructor" #-}
-data Union a b = a `Union` b
-instance ToSqlSetOperation a a' => ToSqlSetOperation (Union a a) a' where
-    toSqlSetOperation (Union a b) = union_ a b
-
 -- | Overloaded @union_@ function to support use in both 'SqlSetOperation'
 -- and 'withRecursive'
 --
@@ -102,30 +97,10 @@ instance (ToSqlSetOperation a c, ToSqlSetOperation b c, res ~ SqlSetOperation c)
   => UnionAll_ (a -> b -> res) where
     unionAll_ = mkSetOperation " UNION ALL "
 
-{-# DEPRECATED UnionAll "/Since: 3.4.0.0/ - Use the 'unionAll_' function instead of the 'UnionAll' data constructor" #-}
-data UnionAll a b = a `UnionAll` b
-instance ToSqlSetOperation a a' => ToSqlSetOperation (UnionAll a a) a' where
-    toSqlSetOperation (UnionAll a b) = unionAll_ a b
-
-{-# DEPRECATED Except "/Since: 3.4.0.0/ - Use the 'except_' function instead of the 'Except' data constructor" #-}
-data Except a b = a `Except` b
-instance ToSqlSetOperation a a' => ToSqlSetOperation (Except a a) a' where
-    toSqlSetOperation (Except a b) = except_ a b
-
 -- | @EXCEPT@ SQL set operation. Can be used as an infix function between 'SqlQuery' values.
 except_ :: (ToSqlSetOperation a a', ToSqlSetOperation b a') => a -> b -> SqlSetOperation a'
 except_ = mkSetOperation " EXCEPT "
 
-{-# DEPRECATED Intersect "/Since: 3.4.0.0/ - Use the 'intersect_' function instead of the 'Intersect' data constructor" #-}
-data Intersect a b = a `Intersect` b
-instance ToSqlSetOperation a a' => ToSqlSetOperation (Intersect a a) a' where
-    toSqlSetOperation (Intersect a b) = intersect_ a b
-
 -- | @INTERSECT@ SQL set operation. Can be used as an infix function between 'SqlQuery' values.
 intersect_ :: (ToSqlSetOperation a a', ToSqlSetOperation b a') => a -> b -> SqlSetOperation a'
 intersect_ = mkSetOperation " INTERSECT "
-
-{-# DEPRECATED SelectQuery "/Since: 3.4.0.0/ - It is no longer necessary to tag 'SqlQuery' values with @SelectQuery@" #-}
-pattern SelectQuery :: p -> p
-pattern SelectQuery a = a
-

src/Database/Esqueleto/Experimental/ToAlias.hs

@@ -8,9 +8,6 @@ module Database.Esqueleto.Experimental.ToAlias
 import Database.Esqueleto.Internal.Internal hiding (From, from, on)
 import Database.Esqueleto.Internal.PersistentImport
 
-{-# DEPRECATED ToAliasT "This type alias doesn't do anything. Please delete it. Will be removed in the next release." #-}
-type ToAliasT a = a
-
 -- Tedious tuple magic
 class ToAlias a where
     toAlias :: a -> SqlQuery a

src/Database/Esqueleto/Experimental/ToAliasReference.hs

@@ -8,9 +8,6 @@ module Database.Esqueleto.Experimental.ToAliasReference
 import Database.Esqueleto.Internal.Internal hiding (From, from, on)
 import Database.Esqueleto.Internal.PersistentImport
 
-{-# DEPRECATED ToAliasReferenceT "This type alias doesn't do anything. Please delete it. Will be removed in the next release." #-}
-type ToAliasReferenceT a = a
-
 -- more tedious tuple magic
 class ToAliasReference a where
     toAliasReference :: Ident -> a -> SqlQuery a

src/Database/Esqueleto/Internal/Internal.hs

@@ -406,12 +406,6 @@ distinctOnOrderBy exprs act =
 
 {-# DEPRECATED distinctOnOrderBy "This function is deprecated, as it is only supported in Postgresql. Please use the function defined in `Database.Esqueleto.PostgreSQL` instead." #-}
 
--- | @ORDER BY random()@ clause.
---
--- @since 1.3.10
-rand :: SqlExpr OrderBy
-rand = ERaw noMeta $ \_ _ -> ("RANDOM()", [])
-
 -- | @HAVING@.
 --
 -- @since 1.2.2
@@ -435,29 +429,6 @@ locking kind = putLocking $ LegacyLockingClause kind
 putLocking :: LockingClause -> SqlQuery ()
 putLocking clause = Q $ W.tell mempty { sdLockingClause = clause }
 
-{-#
-  DEPRECATED
-    sub_select
-    "sub_select \n \
-sub_select is an unsafe function to use. If used with a SqlQuery that \n \
-returns 0 results, then it may return NULL despite not mentioning Maybe \n \
-in the return type. If it returns more than 1 result, then it will throw a \n \
-SQL error.\n\n Instead, consider using one of the following alternatives: \n \
-- subSelect: attaches a LIMIT 1 and the Maybe return type, totally safe.  \n \
-- subSelectMaybe: Attaches a LIMIT 1, useful for a query that already \n \
-  has a Maybe in the return type. \n \
-- subSelectCount: Performs a count of the query - this is always safe. \n \
-- subSelectUnsafe: Performs no checks or guarantees. Safe to use with \n \
-  countRows and friends."
-  #-}
--- | Execute a subquery @SELECT@ in an SqlExpression.  Returns a
--- simple value so should be used only when the @SELECT@ query
--- is guaranteed to return just one row.
---
--- Deprecated in 3.2.0.
-sub_select :: PersistField a => SqlQuery (SqlExpr (Value a)) -> SqlExpr (Value a)
-sub_select         = sub SELECT
-
 -- | Execute a subquery @SELECT@ in a 'SqlExpr'. The query passed to this
 -- function will only return a single result - it has a @LIMIT 1@ passed in to
 -- the query to make it safe, and the return type is 'Maybe' to indicate that
@@ -891,9 +862,6 @@ not_ v = ERaw noMeta (const $ first ("NOT " <>) . x)
 between :: PersistField a => SqlExpr (Value a) -> (SqlExpr (Value a), SqlExpr (Value a)) -> SqlExpr (Value Bool)
 a `between` (b, c) = a >=. b &&. a <=. c
 
-random_  :: (PersistField a, Num a) => SqlExpr (Value a)
-random_  = unsafeSqlValue "RANDOM()"
-
 round_   :: (PersistField a, Num a, PersistField b, Num b) => SqlExpr (Value a) -> SqlExpr (Value b)
 round_   = unsafeSqlFunction "ROUND"
 
@@ -1001,12 +969,15 @@ like    = unsafeSqlBinOp    " LIKE "
 
 -- | @ILIKE@ operator (case-insensitive @LIKE@).
 --
--- Supported by PostgreSQL only.
+-- Supported by PostgreSQL only. Deprecated in version 3.6.0 in favor of the
+-- version available from "Database.Esqueleto.PostgreSQL".
 --
 -- @since 2.2.3
 ilike :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s) -> SqlExpr (Value Bool)
 ilike   = unsafeSqlBinOp    " ILIKE "
 
+{-# DEPRECATED ilike "Since 3.6.0: `ilike` is only supported on Postgres. Please import it from 'Database.Esqueleto.PostgreSQL." #-}
+
 -- | The string @'%'@.  May be useful while using 'like' and
 -- concatenation ('concat_' or '++.', depending on your
 -- database).  Note that you always have to type the parenthesis,
@@ -1019,13 +990,19 @@ ilike   = unsafeSqlBinOp    " ILIKE "
 (%)     = unsafeSqlValue    "'%'"
 
 -- | The @CONCAT@ function with a variable number of
--- parameters.  Supported by MySQL and PostgreSQL.
+-- parameters.  Supported by MySQL and PostgreSQL. SQLite supports this in
+-- versions after 3.44.0, and @persistent-sqlite@ supports this in versions
+-- @2.13.3.0@ and after.
 concat_ :: SqlString s => [SqlExpr (Value s)] -> SqlExpr (Value s)
 concat_ = unsafeSqlFunction "CONCAT"
 
 -- | The @||@ string concatenation operator (named after
 -- Haskell's '++' in order to avoid naming clash with '||.').
+--
 -- Supported by SQLite and PostgreSQL.
+--
+-- MySQL support requires setting the SQL mode to @PIPES_AS_CONCAT@ or @ANSI@
+-- - see <https://stackoverflow.com/a/24777235 this StackOverflow answer>.
 (++.) :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s) -> SqlExpr (Value s)
 (++.)   = unsafeSqlBinOp    " || "
 
@@ -1172,13 +1149,13 @@ field /=. expr = setAux field (\ent -> ent ^. field /. expr)
 --        'from' $ \\p -> do
 --        'where_' (p '^.' PersonName '==.' 'val' \"Mike\"))
 --      'then_'
---        ('sub_select' $
+--        ('subSelect' $
 --        'from' $ \\v -> do
 --        let sub =
 --                'from' $ \\c -> do
 --                'where_' (c '^.' PersonName '==.' 'val' \"Mike\")
 --                return (c '^.' PersonFavNum)
---        'where_' (v '^.' PersonFavNum >. 'sub_select' sub)
+--        'where_' ('just' (v '^.' PersonFavNum) >. 'subSelect' sub)
 --        return $ 'count' (v '^.' PersonName) +. 'val' (1 :: Int)) ]
 --    ('else_' $ 'val' (-1))
 -- @
@@ -1244,10 +1221,6 @@ case_ = unsafeSqlCase
 toBaseId :: ToBaseId ent => SqlExpr (Value (Key ent)) -> SqlExpr (Value (Key (BaseEnt ent)))
 toBaseId = veryUnsafeCoerceSqlExprValue
 
-{-# DEPRECATED random_ "Since 2.6.0: `random_` is not uniform across all databases! Please use a specific one such as 'Database.Esqueleto.PostgreSQL.random_', 'Database.Esqueleto.MySQL.random_', or 'Database.Esqueleto.SQLite.random_'" #-}
-
-{-# DEPRECATED rand "Since 2.6.0: `rand` ordering function is not uniform across all databases! To avoid accidental partiality it will be removed in the next major version." #-}
-
 -- Fixity declarations
 infixl 9 ^.
 infixl 7 *., /.

src/Database/Esqueleto/Legacy.hs

@@ -52,14 +52,14 @@ module Database.Esqueleto.Legacy
     -- $gettingstarted
 
     -- * @esqueleto@'s Language
-    where_, on, groupBy, orderBy, rand, asc, desc, limit, offset
+    where_, on, groupBy, orderBy, asc, desc, limit, offset
              , distinct, distinctOn, don, distinctOnOrderBy, having, locking
-             , sub_select, (^.), (?.)
+             , (^.), (?.)
              , val, isNothing, just, nothing, joinV, withNonNull
              , countRows, count, countDistinct
              , not_, (==.), (>=.), (>.), (<=.), (<.), (!=.), (&&.), (||.)
              , between, (+.), (-.), (/.), (*.)
-             , random_, round_, ceiling_, floor_
+             , round_, ceiling_, floor_
              , min_, max_, sum_, avg_, castNum, castNumM
              , coalesce, coalesceDefault
              , lower_, upper_, trim_, ltrim_, rtrim_, length_, left_, right_

src/Database/Esqueleto/PostgreSQL.hs

@@ -38,6 +38,7 @@ module Database.Esqueleto.PostgreSQL
     , forKeyShareOf
     , filterWhere
     , values
+    , ilike
     , distinctOn
     , distinctOnOrderBy
     , withMaterialized
@@ -72,7 +73,7 @@ import Database.Esqueleto.Experimental.From.SqlSetOperation
 import Database.Esqueleto.Experimental.ToAlias
 import Database.Esqueleto.Experimental.ToAliasReference
 import Database.Esqueleto.Internal.Internal hiding
-       (From(..), distinctOn, distinctOnOrderBy, from, on, random_)
+       (From(..), ilike, distinctOn, distinctOnOrderBy, from, on, random_)
 import Database.Esqueleto.Internal.PersistentImport hiding
        (uniqueFields, upsert, upsertBy)
 import Database.Persist (ConstraintNameDB(..), EntityNameDB(..))
@@ -661,6 +662,12 @@ forKeyShareOf :: LockableEntity a => a -> OnLockedBehavior -> SqlQuery ()
 forKeyShareOf lockableEntities onLockedBehavior =
   putLocking $ PostgresLockingClauses [PostgresLockingKind PostgresForKeyShare (Just $ LockingOfClause lockableEntities) onLockedBehavior]
 
+-- | @ILIKE@ operator (case-insensitive @LIKE@).
+--
+-- @since 2.2.3
+ilike :: SqlString s => SqlExpr (Value s) -> SqlExpr (Value s) -> SqlExpr (Value Bool)
+ilike   = unsafeSqlBinOp    " ILIKE "
+
 -- | @WITH@ @MATERIALIZED@ clause is used to introduce a
 -- [Common Table Expression (CTE)](https://en.wikipedia.org/wiki/Hierarchical_and_recursive_queries_in_SQL#Common_table_expression)
 -- with the MATERIALIZED keyword. The MATERIALIZED keyword is only supported in PostgreSQL >= version 12.