Remove Coercible abiilty for SqlExpr.

changelog.md

@@ -1,3 +1,11 @@
+3.6.0.0
+=======
+- @parsonsmatt
+    - [#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.
+
 3.5.14.0
 ========
 - @parsonsmatt

esqueleto.cabal

@@ -2,7 +2,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.
                 .

src/Database/Esqueleto/Experimental/ToAliasReference.hs

@@ -5,7 +5,6 @@
 module Database.Esqueleto.Experimental.ToAliasReference
     where
 
-import Data.Coerce
 import Database.Esqueleto.Internal.Internal hiding (From, from, on)
 import Database.Esqueleto.Internal.PersistentImport
 
@@ -31,7 +30,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/Internal/Internal.hs

@@ -1,4 +1,5 @@
 {-# LANGUAGE CPP #-}
+{-# LANGUAGE RoleAnnotations #-}
 {-# LANGUAGE DeriveFunctor #-}
 {-# LANGUAGE DataKinds #-}
 {-# LANGUAGE TypeOperators #-}
@@ -63,7 +64,7 @@
 import Data.Kind (Type)
 import qualified Data.List as List
 import qualified Data.Map.Strict as Map
 import qualified Data.Monoid as Monoid
 import Data.Proxy (Proxy(..))
 import Data.Set (Set)
 import qualified Data.Set as Set
@@ -73,7 +74,7 @@
 import Data.Typeable (Typeable)
 import Database.Esqueleto.Internal.ExprParser (TableAccess(..), parseOnExpr)
 import Database.Esqueleto.Internal.PersistentImport
 import Database.Persist (EntityNameDB(..), FieldNameDB(..), SymbolToField(..))
 import qualified Database.Persist
 import Database.Persist.Sql.Util
        ( entityColumnCount
@@ -126,7 +127,7 @@
     maybelize
         :: PreprocessedFrom (SqlExpr (Entity a))
         -> PreprocessedFrom (SqlExpr (Maybe (Entity a)))
-    maybelize (PreprocessedFrom e f') = PreprocessedFrom (coerce e) f'
+    maybelize (PreprocessedFrom e f') = PreprocessedFrom (veryUnsafeCoerceSqlExpr e) f'
 
 -- | (Internal) Do a @JOIN@.
 fromJoin
@@ -367,7 +368,7 @@
 --
 -- @since 2.2.4
 don :: SqlExpr (Value a) -> SqlExpr DistinctOn
-don = coerce
+don = veryUnsafeCoerceSqlExpr
 
 -- | A convenience function that calls both 'distinctOn' and
 -- 'orderBy'.  In other words,
@@ -1433,7 +1434,7 @@
     unique = finalR uniqueConstructor
     -- there must be a better way to get the constrain name from a unique, make this not a list search
     filterF = (==) (persistUniqueToFieldNames unique) . uniqueFields
     uniqueDef = head . filter filterF . getEntityUniques . entityDef $ proxy
 
 -- | Render updates to be use in a SET clause for a given sql backend.
 --
@@ -2340,12 +2341,12 @@
 entityAsValue
     :: SqlExpr (Entity val)
     -> SqlExpr (Value (Entity val))
-entityAsValue = coerce
+entityAsValue = veryUnsafeCoerceSqlExpr
 
 entityAsValueMaybe
     :: SqlExpr (Maybe (Entity val))
     -> SqlExpr (Value (Maybe (Entity val)))
-entityAsValueMaybe = coerce
+entityAsValueMaybe = veryUnsafeCoerceSqlExpr
 
 -- | An expression on the SQL backend.
 --
@@ -2357,6 +2358,34 @@
 -- interpolated by the SQL backend.
 data SqlExpr a = ERaw SqlExprMeta (NeedParens -> IdentInfo -> (TLB.Builder, [PersistValue]))
 
+type role SqlExpr nominal
+
+-- | The type @'SqlExpr' a@ represents a SQL expression that evaluates to
+-- a value that can be parsed in Haskell to an @a@. There are often many
+-- underlying SQL values that can parse exactly. The function
+-- 'veryUnsafeCoerceSqlExpr' allows you to change this type.
+--
+-- There is no guarantee that the result works! To be safe, you want to provide
+-- a local helper function that calls this at a tested type.
+--
+-- As an example, you may know that two types share an identical SQL
+-- representation, and can be parsed exactly the same way. Perhaps you have
+-- a @data SomeEnum@ which you represent as a @TEXT@ in Postgres, and you
+-- want to treat it as a @TEXT@. You could define a top-level
+-- type-restricted alias to this which allows this to be done safely:
+--
+-- @
+--  enumToText :: SqlExpr (Value SomeEnum) -> SqlExpr (Value Text)
+--  enumToText = veryUnsafeCoerceSqlExpr
+-- @
+--
+-- Note that this is fragile: if you change the encoding of 'SomeEnum' to
+-- be anything other than 'Text', then your code will fail at runtime.
+--
+-- @since 3.6.0.0
+veryUnsafeCoerceSqlExpr :: SqlExpr a -> SqlExpr b
+veryUnsafeCoerceSqlExpr (ERaw m k) = ERaw m k
+
 -- | Folks often want the ability to promote a Haskell function into the
 -- 'SqlExpr' expression language - and naturally reach for 'fmap'.
 -- Unfortunately, this is impossible. We cannot send *functions* to the
@@ -2826,14 +2855,20 @@
 -- | (Internal) Coerce a value's type from 'SqlExpr (Value a)' to
 -- 'SqlExpr (Value b)'.  You should /not/ use this function
 -- unless you know what you're doing!
+--
+-- This is an alias for 'veryUnsafeCoerceSqlExpr' with the type fixed to
+-- 'Value'.
 veryUnsafeCoerceSqlExprValue :: SqlExpr (Value a) -> SqlExpr (Value b)
-veryUnsafeCoerceSqlExprValue = coerce
+veryUnsafeCoerceSqlExprValue = veryUnsafeCoerceSqlExpr
 
 
 -- | (Internal) Coerce a value's type from 'SqlExpr (ValueList
 -- a)' to 'SqlExpr (Value a)'.  Does not work with empty lists.
+--
+-- This is an alias for 'veryUnsafeCoerceSqlExpr', with the type fixed to
+-- 'ValueList' and 'Value'.
 veryUnsafeCoerceSqlExprValueList :: SqlExpr (ValueList a) -> SqlExpr (Value a)
-veryUnsafeCoerceSqlExprValueList = coerce
+veryUnsafeCoerceSqlExprValueList = veryUnsafeCoerceSqlExpr
 
 
 ----------------------------------------------------------------------
@@ -3257,7 +3292,7 @@
                 first (("SELECT DISTINCT ON (" <>) . (<> ") "))
                 $ uncommas' (processExpr <$> exprs)
       where
-        processExpr e = materializeExpr info (coerce e :: SqlExpr (Value a))
+        processExpr e = materializeExpr info (veryUnsafeCoerceSqlExpr e :: SqlExpr (Value a))
     withCols v = v <> sqlSelectCols info ret
     plain    v = (v, [])
 
@@ -3513,7 +3548,7 @@
 
 -- | You may return a possibly-@NULL@ 'Entity' from a 'select' query.
 instance PersistEntity a => SqlSelect (SqlExpr (Maybe (Entity a))) (Maybe (Entity a)) where
-    sqlSelectCols info e = sqlSelectCols info (coerce e :: SqlExpr (Entity a))
+    sqlSelectCols info e = sqlSelectCols info (veryUnsafeCoerceSqlExpr e :: SqlExpr (Entity a))
     sqlSelectColCount = sqlSelectColCount . fromEMaybe
       where
         fromEMaybe :: Proxy (SqlExpr (Maybe e)) -> Proxy (SqlExpr e)