persistent-2.6: Type-safe, multi-backend data serialization.

Safe HaskellNone
LanguageHaskell98

Database.Persist.Sql

Contents

Synopsis

Documentation

type Connection = SqlBackend #

Deprecated: Please use SqlBackend instead

Deprecated synonym for SqlBackend.

type SqlPersist = SqlPersistT #

Deprecated: Please use SqlPersistT instead

type Sql = Text #

Although it covers most of the useful cases, persistent's API may not be enough for some of your tasks. May be you need some complex JOIN query, or a database-specific command needs to be issued.

To issue raw SQL queries you could use withStmt, which allows you to do anything you need. However, its API is low-level and you need to parse each row yourself. However, most of your complex queries will have simple results -- some of your entities and maybe a couple of derived columns.

This is where rawSql comes in. Like withStmt, you may issue any SQL query. However, it does all the hard work for you and automatically parses the rows of the result. It may return:

  • An Entity, that which selectList returns. All of your entity's fields are automatically parsed.
  • A Single a, which is a single, raw column of type a. You may use a Haskell type (such as in your entity definitions), for example Single Text or Single Int, or you may get the raw column value with Single PersistValue.
  • A tuple combining any of these (including other tuples). Using tuples allows you to return many entities in one query.

The only difference between issuing SQL queries with rawSql and using other means is that we have an entity selection placeholder, the double question mark ??. It must be used whenever you want to SELECT an Entity from your query. Here's a sample SQL query sampleStmt that may be issued:

SELECT ??, ??
FROM "Person", "Likes", "Object"
WHERE "Person".id = "Likes"."personId"
AND "Object".id = "Likes"."objectId"
AND "Person".name LIKE ?

To use that query, you could say

do results <- rawSql sampleStmt ["%Luke%"]
   forM_ results $
     \( Entity personKey person
      , Entity objectKey object
      ) -> do ...

Note that rawSql knows how to replace the double question marks ?? because of the type of the results.

newtype Single a #

A single column (see rawSql). Any PersistField may be used here, including PersistValue (which does not do any processing).

Constructors

Single 

Fields

Instances

Eq a => Eq (Single a) # 

Methods

(==) :: Single a -> Single a -> Bool #

(/=) :: Single a -> Single a -> Bool #

Ord a => Ord (Single a) # 

Methods

compare :: Single a -> Single a -> Ordering #

(<) :: Single a -> Single a -> Bool #

(<=) :: Single a -> Single a -> Bool #

(>) :: Single a -> Single a -> Bool #

(>=) :: Single a -> Single a -> Bool #

max :: Single a -> Single a -> Single a #

min :: Single a -> Single a -> Single a #

Read a => Read (Single a) # 
Show a => Show (Single a) # 

Methods

showsPrec :: Int -> Single a -> ShowS #

show :: Single a -> String #

showList :: [Single a] -> ShowS #

PersistField a => RawSql (Single a) # 

data SqlBackend #

Constructors

SqlBackend 

Fields

data Statement #

Constructors

Statement 

Fields

type LogFunc = Loc -> LogSource -> LogLevel -> LogStr -> IO () #

readToUnknown :: Monad m => ReaderT SqlReadBackend m a -> ReaderT SqlBackend m a #

Useful for running a read query against a backend with unknown capabilities.

readToWrite :: Monad m => ReaderT SqlReadBackend m a -> ReaderT SqlWriteBackend m a #

Useful for running a read query against a backend with read and write capabilities.

writeToUnknown :: Monad m => ReaderT SqlWriteBackend m a -> ReaderT SqlBackend m a #

Useful for running a write query against an untagged backend with unknown capabilities.

type SqlBackendCanRead backend = (IsSqlBackend backend, PersistQueryRead backend, PersistStoreRead backend, PersistUniqueRead backend) #

A constraint synonym which witnesses that a backend is SQL and can run read queries.

type SqlBackendCanWrite backend = (SqlBackendCanRead backend, PersistQueryWrite backend, PersistStoreWrite backend, PersistUniqueWrite backend) #

A constraint synonym which witnesses that a backend is SQL and can run read and write queries.

type SqlReadT m a = forall backend. SqlBackendCanRead backend => ReaderT backend m a #

Like SqlPersistT but compatible with any SQL backend which can handle read queries.

type SqlWriteT m a = forall backend. SqlBackendCanWrite backend => ReaderT backend m a #

Like SqlPersistT but compatible with any SQL backend which can handle read and write queries.

type IsSqlBackend backend = (IsPersistBackend backend, BaseBackend backend ~ SqlBackend) #

A backend which is a wrapper around SqlBackend.

class RawSql a where #

Class for data types that may be retrived from a rawSql query.

Minimal complete definition

rawSqlCols, rawSqlColCountReason, rawSqlProcessRow

Methods

rawSqlCols :: (DBName -> Text) -> a -> (Int, [Text]) #

Number of columns that this data type needs and the list of substitutions for SELECT placeholders ??.

rawSqlColCountReason :: a -> String #

A string telling the user why the column count is what it is.

rawSqlProcessRow :: [PersistValue] -> Either Text a #

Transform a row of the result into the data type.

Instances

RawSql a => RawSql (Maybe a) #

Since 1.0.1.

(PersistEntity record, (~) * (PersistEntityBackend record) backend, IsPersistBackend backend) => RawSql (Entity record) # 

Methods

rawSqlCols :: (DBName -> Text) -> Entity record -> (Int, [Text]) #

rawSqlColCountReason :: Entity record -> String #

rawSqlProcessRow :: [PersistValue] -> Either Text (Entity record) #

(PersistEntity a, (~) * (PersistEntityBackend a) backend, IsPersistBackend backend) => RawSql (Key a) # 
PersistField a => RawSql (Single a) # 
(RawSql a, RawSql b) => RawSql (a, b) # 

Methods

rawSqlCols :: (DBName -> Text) -> (a, b) -> (Int, [Text]) #

rawSqlColCountReason :: (a, b) -> String #

rawSqlProcessRow :: [PersistValue] -> Either Text (a, b) #

(RawSql a, RawSql b, RawSql c) => RawSql (a, b, c) # 

Methods

rawSqlCols :: (DBName -> Text) -> (a, b, c) -> (Int, [Text]) #

rawSqlColCountReason :: (a, b, c) -> String #

rawSqlProcessRow :: [PersistValue] -> Either Text (a, b, c) #

(RawSql a, RawSql b, RawSql c, RawSql d) => RawSql (a, b, c, d) # 

Methods

rawSqlCols :: (DBName -> Text) -> (a, b, c, d) -> (Int, [Text]) #

rawSqlColCountReason :: (a, b, c, d) -> String #

rawSqlProcessRow :: [PersistValue] -> Either Text (a, b, c, d) #

(RawSql a, RawSql b, RawSql c, RawSql d, RawSql e) => RawSql (a, b, c, d, e) # 

Methods

rawSqlCols :: (DBName -> Text) -> (a, b, c, d, e) -> (Int, [Text]) #

rawSqlColCountReason :: (a, b, c, d, e) -> String #

rawSqlProcessRow :: [PersistValue] -> Either Text (a, b, c, d, e) #

(RawSql a, RawSql b, RawSql c, RawSql d, RawSql e, RawSql f) => RawSql (a, b, c, d, e, f) # 

Methods

rawSqlCols :: (DBName -> Text) -> (a, b, c, d, e, f) -> (Int, [Text]) #

rawSqlColCountReason :: (a, b, c, d, e, f) -> String #

rawSqlProcessRow :: [PersistValue] -> Either Text (a, b, c, d, e, f) #

(RawSql a, RawSql b, RawSql c, RawSql d, RawSql e, RawSql f, RawSql g) => RawSql (a, b, c, d, e, f, g) # 

Methods

rawSqlCols :: (DBName -> Text) -> (a, b, c, d, e, f, g) -> (Int, [Text]) #

rawSqlColCountReason :: (a, b, c, d, e, f, g) -> String #

rawSqlProcessRow :: [PersistValue] -> Either Text (a, b, c, d, e, f, g) #

(RawSql a, RawSql b, RawSql c, RawSql d, RawSql e, RawSql f, RawSql g, RawSql h) => RawSql (a, b, c, d, e, f, g, h) # 

Methods

rawSqlCols :: (DBName -> Text) -> (a, b, c, d, e, f, g, h) -> (Int, [Text]) #

rawSqlColCountReason :: (a, b, c, d, e, f, g, h) -> String #

rawSqlProcessRow :: [PersistValue] -> Either Text (a, b, c, d, e, f, g, h) #

class PersistField a => PersistFieldSql a where #

Minimal complete definition

sqlType

Methods

sqlType :: Proxy a -> SqlType #

Instances

PersistFieldSql Bool # 

Methods

sqlType :: Proxy * Bool -> SqlType #

PersistFieldSql Double # 

Methods

sqlType :: Proxy * Double -> SqlType #

PersistFieldSql Int # 

Methods

sqlType :: Proxy * Int -> SqlType #

PersistFieldSql Int8 # 

Methods

sqlType :: Proxy * Int8 -> SqlType #

PersistFieldSql Int16 # 

Methods

sqlType :: Proxy * Int16 -> SqlType #

PersistFieldSql Int32 # 

Methods

sqlType :: Proxy * Int32 -> SqlType #

PersistFieldSql Int64 # 

Methods

sqlType :: Proxy * Int64 -> SqlType #

PersistFieldSql Rational # 
PersistFieldSql Word # 

Methods

sqlType :: Proxy * Word -> SqlType #

PersistFieldSql Word8 # 

Methods

sqlType :: Proxy * Word8 -> SqlType #

PersistFieldSql Word16 # 

Methods

sqlType :: Proxy * Word16 -> SqlType #

PersistFieldSql Word32 # 

Methods

sqlType :: Proxy * Word32 -> SqlType #

PersistFieldSql Word64 # 

Methods

sqlType :: Proxy * Word64 -> SqlType #

PersistFieldSql ByteString # 
PersistFieldSql String # 

Methods

sqlType :: Proxy * String -> SqlType #

PersistFieldSql Text # 

Methods

sqlType :: Proxy * Text -> SqlType #

PersistFieldSql UTCTime # 
PersistFieldSql Text # 

Methods

sqlType :: Proxy * Text -> SqlType #

PersistFieldSql Natural # 
PersistFieldSql Html # 

Methods

sqlType :: Proxy * Html -> SqlType #

PersistFieldSql TimeOfDay # 
PersistFieldSql Day # 

Methods

sqlType :: Proxy * Day -> SqlType #

PersistFieldSql PersistValue # 
PersistFieldSql Checkmark # 
PersistFieldSql a => PersistFieldSql [a] # 

Methods

sqlType :: Proxy * [a] -> SqlType #

HasResolution a => PersistFieldSql (Fixed a) # 

Methods

sqlType :: Proxy * (Fixed a) -> SqlType #

PersistFieldSql v => PersistFieldSql (IntMap v) # 

Methods

sqlType :: Proxy * (IntMap v) -> SqlType #

(Ord a, PersistFieldSql a) => PersistFieldSql (Set a) # 

Methods

sqlType :: Proxy * (Set a) -> SqlType #

PersistFieldSql a => PersistFieldSql (Vector a) # 

Methods

sqlType :: Proxy * (Vector a) -> SqlType #

(PersistField record, PersistEntity record) => PersistFieldSql (Entity record) # 

Methods

sqlType :: Proxy * (Entity record) -> SqlType #

(PersistFieldSql a, PersistFieldSql b) => PersistFieldSql (a, b) # 

Methods

sqlType :: Proxy * (a, b) -> SqlType #

PersistFieldSql v => PersistFieldSql (Map Text v) # 

Methods

sqlType :: Proxy * (Map Text v) -> SqlType #

runSqlPool :: (MonadBaseControl IO m, IsSqlBackend backend) => ReaderT backend m a -> Pool backend -> m a #

Get a connection from the pool, run the given action, and then return the connection to the pool.

Note: This function previously timed out after 2 seconds, but this behavior was buggy and caused more problems than it solved. Since version 2.1.2, it performs no timeout checks.

withResourceTimeout #

Arguments

:: MonadBaseControl IO m 
=> Int

Timeout period in microseconds

-> Pool a 
-> (a -> m b) 
-> m (Maybe b) 

Like withResource, but times out the operation if resource allocation does not complete within the given timeout period.

Since 2.0.0

runSqlConn :: (MonadBaseControl IO m, IsSqlBackend backend) => ReaderT backend m a -> backend -> m a #

runSqlPersistM :: IsSqlBackend backend => ReaderT backend (NoLoggingT (ResourceT IO)) a -> backend -> IO a #

runSqlPersistMPool :: IsSqlBackend backend => ReaderT backend (NoLoggingT (ResourceT IO)) a -> Pool backend -> IO a #

liftSqlPersistMPool :: (MonadIO m, IsSqlBackend backend) => ReaderT backend (NoLoggingT (ResourceT IO)) a -> Pool backend -> m a #

withSqlPool #

Arguments

:: (MonadIO m, MonadLogger m, MonadBaseControl IO m, IsSqlBackend backend) 
=> (LogFunc -> IO backend)

create a new connection

-> Int

connection count

-> (Pool backend -> m a) 
-> m a 

createSqlPool :: (MonadIO m, MonadLogger m, MonadBaseControl IO m, IsSqlBackend backend) => (LogFunc -> IO backend) -> Int -> m (Pool backend) #

withSqlConn :: (MonadIO m, MonadBaseControl IO m, MonadLogger m, IsSqlBackend backend) => (LogFunc -> IO backend) -> (backend -> m a) -> m a #

close' :: IsSqlBackend backend => backend -> IO () #

runMigrationSilent :: (MonadBaseControl IO m, MonadIO m) => Migration -> ReaderT SqlBackend m [Text] #

Same as runMigration, but returns a list of the SQL commands executed instead of printing them to stderr.

toSqlKey :: ToBackendKey SqlBackend record => Int64 -> Key record #

fromSqlKey :: ToBackendKey SqlBackend record => Key record -> Int64 #

getFieldName :: forall record typ m backend. (PersistEntity record, PersistEntityBackend record ~ SqlBackend, IsSqlBackend backend, Monad m) => EntityField record typ -> ReaderT backend m Text #

get the SQL string for the field that an EntityField represents Useful for raw SQL queries

Your backend may provide a more convenient fieldName function which does not operate in a Monad

getTableName :: forall record m backend. (PersistEntity record, PersistEntityBackend record ~ SqlBackend, IsSqlBackend backend, Monad m) => record -> ReaderT backend m Text #

get the SQL string for the table that a PeristEntity represents Useful for raw SQL queries

Your backend may provide a more convenient tableName function which does not operate in a Monad

tableDBName :: PersistEntity record => record -> DBName #

useful for a backend to implement tableName by adding escaping

fieldDBName :: forall record typ. PersistEntity record => EntityField record typ -> DBName #

useful for a backend to implement fieldName by adding escaping

rawExecute #

Arguments

:: MonadIO m 
=> Text

SQL statement, possibly with placeholders.

-> [PersistValue]

Values to fill the placeholders.

-> ReaderT SqlBackend m () 

Execute a raw SQL statement

rawExecuteCount #

Arguments

:: (MonadIO m, IsSqlBackend backend) 
=> Text

SQL statement, possibly with placeholders.

-> [PersistValue]

Values to fill the placeholders.

-> ReaderT backend m Int64 

Execute a raw SQL statement and return the number of rows it has modified.

rawSql #

Arguments

:: (RawSql a, MonadIO m) 
=> Text

SQL statement, possibly with placeholders.

-> [PersistValue]

Values to fill the placeholders.

-> ReaderT SqlBackend m [a] 

Execute a raw SQL statement and return its results as a list.

If you're using Entitys (which is quite likely), then you must use entity selection placeholders (double question mark, ??). These ?? placeholders are then replaced for the names of the columns that we need for your entities. You'll receive an error if you don't use the placeholders. Please see the Entitys documentation for more details.

You may put value placeholders (question marks, ?) in your SQL query. These placeholders are then replaced by the values you pass on the second parameter, already correctly escaped. You may want to use toPersistValue to help you constructing the placeholder values.

Since you're giving a raw SQL statement, you don't get any guarantees regarding safety. If rawSql is not able to parse the results of your query back, then an exception is raised. However, most common problems are mitigated by using the entity selection placeholder ??, and you shouldn't see any error at all if you're not using Single.

Some example of rawSql based on this schema:

share [mkPersist sqlSettings, mkMigrate "migrateAll"] [persistLowerCase|
Person
    name String
    age Int Maybe
    deriving Show
BlogPost
    title String
    authorId PersonId
    deriving Show
|]

Examples based on the above schema:

getPerson :: MonadIO m => ReaderT SqlBackend m [Entity Person]
getPerson = rawSql "select ?? from person where name=?" [PersistText "john"]

getAge :: MonadIO m => ReaderT SqlBackend m [Single Int]
getAge = rawSql "select person.age from person where name=?" [PersistText "john"]

getAgeName :: MonadIO m => ReaderT SqlBackend m [(Single Int, Single Text)]
getAgeName = rawSql "select person.age, person.name from person where name=?" [PersistText "john"]

getPersonBlog :: MonadIO m => ReaderT SqlBackend m [(Entity Person, Entity BlogPost)]
getPersonBlog = rawSql "select ??,?? from person,blog_post where person.id = blog_post.author_id" []

Minimal working program for PostgreSQL backend based on the above concepts:

{-# LANGUAGE EmptyDataDecls             #-}
{-# LANGUAGE FlexibleContexts           #-}
{-# LANGUAGE GADTs                      #-}
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
{-# LANGUAGE MultiParamTypeClasses      #-}
{-# LANGUAGE OverloadedStrings          #-}
{-# LANGUAGE QuasiQuotes                #-}
{-# LANGUAGE TemplateHaskell            #-}
{-# LANGUAGE TypeFamilies               #-}

import           Control.Monad.IO.Class  (liftIO)
import           Control.Monad.Logger    (runStderrLoggingT)
import           Database.Persist
import           Control.Monad.Reader
import           Data.Text
import           Database.Persist.Sql
import           Database.Persist.Postgresql
import           Database.Persist.TH

share [mkPersist sqlSettings, mkMigrate "migrateAll"] [persistLowerCase|
Person
    name String
    age Int Maybe
    deriving Show
|]

conn = "host=localhost dbname=new_db user=postgres password=postgres port=5432"

getPerson :: MonadIO m => ReaderT SqlBackend m [Entity Person]
getPerson = rawSql "select ?? from person where name=?" [PersistText "sibi"]

liftSqlPersistMPool y x = liftIO (runSqlPersistMPool y x)

main :: IO ()
main = runStderrLoggingT $ withPostgresqlPool conn 10 $ liftSqlPersistMPool $ do
         runMigration migrateAll
         xs <- getPerson
         liftIO (print xs)

deleteWhereCount :: (PersistEntity val, MonadIO m, PersistEntityBackend val ~ SqlBackend, IsSqlBackend backend) => [Filter val] -> ReaderT backend m Int64 #

Same as deleteWhere, but returns the number of rows affected.

Since 1.1.5

updateWhereCount :: (PersistEntity val, MonadIO m, SqlBackend ~ PersistEntityBackend val, IsSqlBackend backend) => [Filter val] -> [Update val] -> ReaderT backend m Int64 #

Same as updateWhere, but returns the number of rows affected.

Since 1.1.5

transactionSave :: MonadIO m => ReaderT SqlBackend m () #

Commit the current transaction and begin a new one.

Since 1.2.0

transactionUndo :: MonadIO m => ReaderT SqlBackend m () #

Roll back the current transaction and begin a new one.

Since 1.2.0

Internal

mkColumns :: [EntityDef] -> EntityDef -> ([Column], [UniqueDef], [ForeignDef]) #

Create the list of columns for the given entity.

decorateSQLWithLimitOffset :: Text -> (Int, Int) -> Bool -> Text -> Text #

Generates sql for limit and offset for postgres, sqlite and mysql.