renderQueryToText

changelog.md

@@ -1,6 +1,9 @@
-Unreleased
+Unreleased (3.1.1)
 ========
 
+- @parsonsmatt
+  - [](): Added `renderQueryToText` and related functions.
+
 3.1.0
 =======
 

src/Database/Esqueleto.hs

@@ -86,6 +86,12 @@ module Database.Esqueleto
   , insertSelectCount
   , (<#)
   , (<&>)
+  -- ** Rendering Queries
+  , renderQueryToText
+  , renderQuerySelect
+  , renderQueryUpdate
+  , renderQueryDelete
+  , renderQueryInsertInto
     -- * Internal.Language
   , From
     -- * RDBMS-specific modules

src/Database/Esqueleto/Internal/Internal.hs

@@ -2031,6 +2031,90 @@ toRawSql mode (conn, firstIdentState) query =
       , makeLocking         lockingClause
       ]
 
+-- | Renders a 'SqlQuery' into a 'Text' value along with the list of
+-- 'PersistValue's that would be supplied to the database for @?@ placeholders.
+--
+-- You must ensure that the 'Mode' you pass to this function corresponds with
+-- the actual 'SqlQuery'. If you pass a query that uses incompatible features
+-- (like an @INSERT@ statement with a @SELECT@ mode) then you'll get a weird
+-- result.
+--
+-- @since 3.1.1
+renderQueryToText
+  :: (SqlSelect a r, BackendCompatible SqlBackend backend, Monad m)
+  => Mode
+  -- ^ Whether to render as an 'SELECT', 'DELETE', etc.
+  -> SqlQuery a
+  -- ^ The SQL query you want to render.
+  -> R.ReaderT backend m (T.Text, [PersistValue])
+renderQueryToText mode query = do
+  backend <- R.ask
+  let (builder, pvals) = toRawSql mode (backend, initialIdentState) query
+  pure (builderToText builder, pvals)
+
+-- | Renders a 'SqlQuery' into a 'Text' value along with the list of
+-- 'PersistValue's that would be supplied to the database for @?@ placeholders.
+--
+-- You must ensure that the 'Mode' you pass to this function corresponds with
+-- the actual 'SqlQuery'. If you pass a query that uses incompatible features
+-- (like an @INSERT@ statement with a @SELECT@ mode) then you'll get a weird
+-- result.
+--
+-- @since 3.1.1
+renderQuerySelect
+  :: (SqlSelect a r, BackendCompatible SqlBackend backend, Monad m)
+  => SqlQuery a
+  -- ^ The SQL query you want to render.
+  -> R.ReaderT backend m (T.Text, [PersistValue])
+renderQuerySelect = renderQueryToText SELECT
+
+-- | Renders a 'SqlQuery' into a 'Text' value along with the list of
+-- 'PersistValue's that would be supplied to the database for @?@ placeholders.
+--
+-- You must ensure that the 'Mode' you pass to this function corresponds with
+-- the actual 'SqlQuery'. If you pass a query that uses incompatible features
+-- (like an @INSERT@ statement with a @SELECT@ mode) then you'll get a weird
+-- result.
+--
+-- @since 3.1.1
+renderQueryDelete
+  :: (SqlSelect a r, BackendCompatible SqlBackend backend, Monad m)
+  => SqlQuery a
+  -- ^ The SQL query you want to render.
+  -> R.ReaderT backend m (T.Text, [PersistValue])
+renderQueryDelete = renderQueryToText DELETE
+
+-- | Renders a 'SqlQuery' into a 'Text' value along with the list of
+-- 'PersistValue's that would be supplied to the database for @?@ placeholders.
+--
+-- You must ensure that the 'Mode' you pass to this function corresponds with
+-- the actual 'SqlQuery'. If you pass a query that uses incompatible features
+-- (like an @INSERT@ statement with a @SELECT@ mode) then you'll get a weird
+-- result.
+--
+-- @since 3.1.1
+renderQueryUpdate
+  :: (SqlSelect a r, BackendCompatible SqlBackend backend, Monad m)
+  => SqlQuery a
+  -- ^ The SQL query you want to render.
+  -> R.ReaderT backend m (T.Text, [PersistValue])
+renderQueryUpdate = renderQueryToText UPDATE
+
+-- | Renders a 'SqlQuery' into a 'Text' value along with the list of
+-- 'PersistValue's that would be supplied to the database for @?@ placeholders.
+--
+-- You must ensure that the 'Mode' you pass to this function corresponds with
+-- the actual 'SqlQuery'. If you pass a query that uses incompatible features
+-- (like an @INSERT@ statement with a @SELECT@ mode) then you'll get a weird
+-- result.
+--
+-- @since 3.1.1
+renderQueryInsertInto
+  :: (SqlSelect a r, BackendCompatible SqlBackend backend, Monad m)
+  => SqlQuery a
+  -- ^ The SQL query you want to render.
+  -> R.ReaderT backend m (T.Text, [PersistValue])
+renderQueryInsertInto = renderQueryToText INSERT_INTO
 
 -- | (Internal) Mode of query being converted by 'toRawSql'.
 data Mode =

src/Database/Esqueleto/Internal/Sql.hs

@@ -61,6 +61,11 @@ module Database.Esqueleto.Internal.Sql
   , veryUnsafeCoerceSqlExprValue
   , veryUnsafeCoerceSqlExprValueList
   -- * Helper functions
+  , renderQueryToText
+  , renderQuerySelect
+  , renderQueryUpdate
+  , renderQueryDelete
+  , renderQueryInsertInto
   , makeOrderByNoNewline
   , uncommas'
   , parens

test/Common/Test.hs

@@ -1437,10 +1437,6 @@ testCountingRows run = do
           [Value n] <- select $ from $ return . countKind
           liftIO $ (n :: Int) `shouldBe` expected
 
-
-
-
-
 tests :: Run -> Spec
 tests run = do
   describe "Tests that are common to all backends" $ do
@@ -1460,6 +1456,7 @@ tests run = do
     testMathFunctions run
     testCase run
     testCountingRows run
+    testRenderSql run