Version 3.6.0.0

.github/workflows/haskell.yml

@@ -69,6 +69,7 @@ jobs:
             #     mysql database: 'esqutest' # Optional, default value is "test". The specified database which will be create
             #     mysql user: 'travis' # Required if "mysql root password" is empty, default is empty. The superuser for the specified database. Can use secrets, too
             #     mysql password: 'esqutest' # Required if "mysql user" exists. The password for the "mysql user"
+      - run: sudo apt-get update && sudo apt-get install -y libpcre3-dev
       - run: cabal v2-update
       - run: cabal v2-freeze $CONFIG
       - uses: actions/cache@v4

Makefile

@@ -58,6 +58,7 @@ clean:
 	$(STACK) clean
 
 .PHONY: init-pgsql
+
 init-pgsql:
 	sudo -u postgres -- createuser -s esqutest
 

changelog.md

@@ -1,3 +1,81 @@
+3.6.0.0
+=======
+- @parsonsmatt
+    - [#422](https://github.com/bitemyapp/esqueleto/pull/422)
+        - The instance of `HasField` for `SqlExpr (Maybe (Entity a))` joins
+          `Maybe` values together. This means that if you `leftJoin` a table
+          with a `Maybe` column, the result will be a `SqlExpr (Value (Maybe
+          typ))`, instead of `SqlExpr (Value (Maybe (Maybe typ)))`.
+        - To make this a less breaking change, `joinV` has been given a similar
+          behavior. If the input type to `joinV` is `Maybe (Maybe typ)`, then
+          the result becomes `Maybe typ`. If the input type is `Maybe typ`, then
+          the output is also `Maybe typ`. The `joinV'` function is given as an
+          alternative with monomorphic behavior.
+        - The `just` function is also modified to avoid nesting `Maybe`.
+          Likewise, `just'` is provided to give monomorphic behavior.
+        - `subSelect`, `max_`, `min_`, and `coalesce` were all
+          given `Nullable` output types as well. This should help to reduce the
+          incidence of nested `Maybe`.
+        - The operator `??.` was introduced which can do nested `Maybe`. You may
+          want this if you have type inference issues with `?.` combining
+          `Maybe`.
+    - [#420](https://github.com/bitemyapp/esqueleto/pull/420)
+        - Add a fixity declaration to `?.`
+    - [#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
+          the refactor is straightforward:
+          ```
+              -- old:
+              p <- from $ table
+              distinctOn [don x] $ do
+                  pure p
+
+              -- new:
+              p <- from $ table
+              distinctOn [don x]
+              pure p
+          ```
+    - [#301](https://github.com/bitemyapp/esqueleto/pull/301)
+        - Postgresql `upsert` and `upsertBy` now require a `NonEmpty` list of
+          updates. If you want to provide an empty list of updates, you'll need
+          to use `upsertMaybe` and `upsertMaybeBe` instead. Postgres does not
+          return rows from the database if no updates are performed.
+    - [#413](https://github.com/bitemyapp/esqueleto/pull/413)
+        - The ability to `coerce` `SqlExpr` was removed. Instead, use
+          `veryUnsafeCoerceSqlExpr`. See the documentation on
+          `veryUnsafeCoerceSqlExpr` for safe use example.
+        - `unsafeCeorceSqlExpr` is provided as an option when the underlying
+          Haskell types are coercible. This is still unsafe, as different
+          `PersistFieldSql` instances may be at play.
+    - [#420](https://github.com/bitemyapp/esqueleto/pull/421)
+        - The `LockingKind` constructors are deprecated, and will be removed
+          from non-Internal modules in a future release. Smart constructors
+          replace them, and you may need to import them from a different
+          database-specific module.
+    - [#425](https://github.com/bitemyapp/esqueleto/pull/425)
+        - `fromBaseId` is introduced as the inverse of `toBaseId`.
+        - `toBaseIdMaybe` and `fromBaseIdMaybe` are introduced.
+
 3.5.14.0
 ========
 - @parsonsmatt

esqueleto.cabal

@@ -1,8 +1,7 @@
 cabal-version: 1.12
 
 name:           esqueleto
-
-version:        3.5.14.0
+version:        3.6.0.0
 synopsis:       Type-safe EDSL for SQL queries on persistent backends.
 description:    @esqueleto@ is a bare bones, type-safe EDSL for SQL queries that works with unmodified @persistent@ SQL backends.  Its language closely resembles SQL, so you don't have to learn new concepts, just new syntax, and it's fairly easy to predict the generated SQL and optimize it for your backend. Most kinds of errors committed when writing SQL are caught as compile-time errors---although it is possible to write type-checked @esqueleto@ queries that fail at runtime.
                 .
@@ -53,7 +52,7 @@ library
     hs-source-dirs:
         src/
     build-depends:
-        base >=4.8 && <5.0
+        base >=4.12 && <5.0
       , aeson >=1.0
       , attoparsec >= 0.13 && < 0.15
       , blaze-html

examples/Main.hs

@@ -28,6 +28,7 @@ import Control.Monad.Reader (MonadReader(..), runReaderT)
 import Control.Monad.Trans.Control (MonadBaseControl)
 import Database.Esqueleto.Experimental
 import Database.Persist.Postgresql (ConnectionString, withPostgresqlConn)
+import qualified Database.Persist.Sql as Persistent
 import Database.Persist.TH
        ( mkMigrate
        , mkPersist
@@ -36,7 +37,6 @@ import Database.Persist.TH
        , sqlSettings
        )
 
-
 share [ mkPersist sqlSettings
       , mkMigrate "migrateAll"] [persistLowerCase|
   Person

src/Database/Esqueleto.hs

@@ -51,22 +51,22 @@ 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
+             , (^.), (?.)
+             , val, isNothing, just, just', nothing, joinV, 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_
              , like, ilike, (%), concat_, (++.), castString
              , subList_select, valList, justList
              , in_, notIn, exists, notExists
              , set, (=.), (+=.), (-=.), (*=.), (/=.)
-             , case_, toBaseId
+             , case_, toBaseId, fromBaseId, toBaseIdMaybe, fromBaseIdMaybe
   , subSelect
   , subSelectMaybe
   , subSelectCount
@@ -83,6 +83,8 @@ module Database.Esqueleto {-# WARNING "This module will switch over to the Exper
   , OrderBy
   , DistinctOn
   , LockingKind(..)
+  , forUpdate
+  , forUpdateSkipLocked
   , LockableEntity(..)
   , SqlString
     -- ** Joins

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,18 +51,16 @@ module Database.Esqueleto.Experimental
     , From(..)
     , ToMaybe(..)
     , ToAlias(..)
-    , ToAliasT
     , ToAliasReference(..)
-    , ToAliasReferenceT
     , ToSqlSetOperation(..)
     , SqlSelect
+    , Nullable
 
     -- * The Normal Stuff
     , where_
     , groupBy
     , groupBy_
     , orderBy
-    , rand
     , asc
     , desc
     , limit
@@ -80,8 +72,9 @@ module Database.Esqueleto.Experimental
     , distinctOnOrderBy
     , having
     , locking
+    , forUpdate
+    , forUpdateSkipLocked
 
-    , sub_select
     , (^.)
     , (?.)
 
@@ -113,7 +106,6 @@ module Database.Esqueleto.Experimental
     , (/.)
     , (*.)
 
-    , random_
     , round_
     , ceiling_
     , floor_
@@ -162,6 +154,9 @@ module Database.Esqueleto.Experimental
 
     , case_
     , toBaseId
+    , toBaseIdMaybe
+    , fromBaseId
+    , fromBaseIdMaybe
     , subSelect
     , subSelectMaybe
     , subSelectCount

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 @@
     (_, 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'
 --
@@ -87,7 +82,7 @@
     -- | @UNION@ SQL set operation. Can be used as an infix function between 'SqlQuery' values.
     union_ :: a
 
 instance (ToSqlSetOperation a c, ToSqlSetOperation b c, res ~ SqlSetOperation c)
   => Union_ (a -> b -> res) where
     union_ = mkSetOperation " UNION "
 
@@ -98,34 +93,14 @@
 class UnionAll_ a where
     -- | @UNION@ @ALL@ SQL set operation. Can be used as an infix function between 'SqlQuery' values.
     unionAll_ :: a
 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

@@ -5,13 +5,9 @@
 module Database.Esqueleto.Experimental.ToAliasReference
     where
 
-import Data.Coerce
 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
@@ -31,7 +27,7 @@ instance ToAliasReference (SqlExpr (Entity a)) where
 
 instance ToAliasReference (SqlExpr (Maybe (Entity a))) where
     toAliasReference aliasSource e =
-        coerce <$> toAliasReference aliasSource (coerce e :: SqlExpr (Entity a))
+        veryUnsafeCoerceSqlExpr <$> toAliasReference aliasSource (veryUnsafeCoerceSqlExpr e :: SqlExpr (Entity a))
 
 
 instance (ToAliasReference a, ToAliasReference b) => ToAliasReference (a, b) where

src/Database/Esqueleto/Experimental/ToMaybe.hs

@@ -2,15 +2,14 @@
 {-# LANGUAGE TypeFamilies #-}
 
 module Database.Esqueleto.Experimental.ToMaybe
+    ( module Database.Esqueleto.Experimental.ToMaybe
+    , Nullable
+    )
     where
 
 import Database.Esqueleto.Internal.Internal hiding (From(..), from, on)
 import Database.Esqueleto.Internal.PersistentImport (Entity(..))
 
-type family Nullable a where
-    Nullable (Maybe a) = a
-    Nullable a =  a
-
 class ToMaybe a where
     type ToMaybeT a
     toMaybe :: a -> ToMaybeT a