-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Type-safe, non-relational, multi-backend persistence. -- -- This library provides just the general interface and helper functions. -- You must use a specific backend in order to make this useful. @package persistent @version 0.6.1 module Database.Persist.TH.Library apE :: Either x (y -> z) -> Either x y -> Either x z module Database.Persist.Util nullable :: [String] -> Bool deprecate :: String -> a -> a -- | API for database actions. The API deals with fields and entities. In -- SQL, a field corresponds to a column, and should be a single -- non-composite value. An entity corresponds to a SQL table, so an -- entity is a collection of fields. module Database.Persist.Base -- | A raw value which can be stored in any backend and can be marshalled -- to and from a PersistField. data PersistValue PersistText :: Text -> PersistValue PersistByteString :: ByteString -> PersistValue PersistInt64 :: Int64 -> PersistValue PersistDouble :: Double -> PersistValue PersistBool :: Bool -> PersistValue PersistDay :: Day -> PersistValue PersistTimeOfDay :: TimeOfDay -> PersistValue PersistUTCTime :: UTCTime -> PersistValue PersistNull :: PersistValue PersistList :: [PersistValue] -> PersistValue PersistMap :: [(Text, PersistValue)] -> PersistValue -- | intended especially for MongoDB backend PersistObjectId :: ByteString -> PersistValue -- | A SQL data type. Naming attempts to reflect the underlying Haskell -- datatypes, eg SqlString instead of SqlVarchar. Different SQL databases -- may have different translations for these types. data SqlType SqlString :: SqlType SqlInt32 :: SqlType -- | FIXME 8-byte integer; should be renamed SqlInt64 SqlInteger :: SqlType SqlReal :: SqlType SqlBool :: SqlType SqlDay :: SqlType SqlTime :: SqlType SqlDayTime :: SqlType SqlBlob :: SqlType -- | A value which can be marshalled to and from a PersistValue. class PersistField a toPersistValue :: PersistField a => a -> PersistValue fromPersistValue :: PersistField a => PersistValue -> Either String a sqlType :: PersistField a => a -> SqlType isNullable :: PersistField a => a -> Bool -- | A single database entity. For example, if writing a blog application, -- a blog entry would be an entry, containing fields such as title and -- content. class PersistEntity val where { data family EntityField val :: * -> *; data family Unique val :: ((* -> *) -> * -> *) -> *; } persistColumnDef :: PersistEntity val => EntityField val typ -> ColumnDef entityDef :: PersistEntity val => val -> EntityDef toPersistFields :: PersistEntity val => val -> [SomePersistField] fromPersistValues :: PersistEntity val => [PersistValue] -> Either String val halfDefined :: PersistEntity val => val persistUniqueToFieldNames :: PersistEntity val => Unique val backend -> [String] persistUniqueToValues :: PersistEntity val => Unique val backend -> [PersistValue] persistUniqueKeys :: PersistEntity val => val -> [Unique val backend] class (MonadIO (b m), MonadIO m, Monad (b m), Monad m) => PersistBackend b m insert :: (PersistBackend b m, PersistEntity val) => val -> b m (Key b val) replace :: (PersistBackend b m, PersistEntity val) => Key b val -> val -> b m () update :: (PersistBackend b m, PersistEntity val) => Key b val -> [Update val] -> b m () updateWhere :: (PersistBackend b m, PersistEntity val) => [Filter val] -> [Update val] -> b m () delete :: (PersistBackend b m, PersistEntity val) => Key b val -> b m () deleteBy :: (PersistBackend b m, PersistEntity val) => Unique val b -> b m () deleteWhere :: (PersistBackend b m, PersistEntity val) => [Filter val] -> b m () get :: (PersistBackend b m, PersistEntity val) => Key b val -> b m (Maybe val) getBy :: (PersistBackend b m, PersistEntity val) => Unique val b -> b m (Maybe (Key b val, val)) selectEnum :: (PersistBackend b m, PersistEntity val) => [Filter val] -> [SelectOpt val] -> Enumerator (Key b val, val) (b m) a selectFirst :: (PersistBackend b m, PersistEntity val) => [Filter val] -> [SelectOpt val] -> b m (Maybe (Key b val, val)) selectKeys :: (PersistBackend b m, PersistEntity val) => [Filter val] -> Enumerator (Key b val) (b m) a count :: (PersistBackend b m, PersistEntity val) => [Filter val] -> b m Int data PersistFilter Eq :: PersistFilter Ne :: PersistFilter Gt :: PersistFilter Lt :: PersistFilter Ge :: PersistFilter Le :: PersistFilter In :: PersistFilter NotIn :: PersistFilter BackendSpecificFilter :: String -> PersistFilter data PersistUpdate Assign :: PersistUpdate Add :: PersistUpdate Subtract :: PersistUpdate Multiply :: PersistUpdate Divide :: PersistUpdate data SelectOpt v Asc :: (EntityField v typ) -> SelectOpt v Desc :: (EntityField v typ) -> SelectOpt v OffsetBy :: Int -> SelectOpt v LimitTo :: Int -> SelectOpt v data SomePersistField SomePersistField :: a -> SomePersistField -- | Call select but return the result as a list. selectList :: (PersistEntity val, PersistBackend b m) => [Filter val] -> [SelectOpt val] -> b m [(Key b val, val)] -- | Insert a value, checking for conflicts with any unique constraints. If -- a duplicate exists in the database, it is returned as Left. -- Otherwise, the new Key is returned as Right. insertBy :: (PersistEntity v, PersistBackend b m) => v -> b m (Either (Key b v, v) (Key b v)) -- | A modification of getBy, which takes the PersistEntity -- itself instead of a Unique value. Returns a value matching -- one of the unique keys. This function makes the most sense on -- entities with a single Unique constructor. getByValue :: (PersistEntity v, PersistBackend b m) => v -> b m (Maybe (Key b v, v)) -- | Same as get, but for a non-null (not Maybe) foreign key Unsafe unless -- your database is enforcing that the foreign key is valid getJust :: (PersistBackend b m, PersistEntity val, Show (Key b val)) => Key b val -> b m val belongsTo :: (PersistBackend b m, PersistEntity ent1, PersistEntity ent2) => (ent1 -> Maybe (Key b ent2)) -> ent1 -> b m (Maybe ent2) -- | same as belongsTo, but uses getJust and therefore is -- similarly unsafe belongsToJust :: (PersistBackend b m, PersistEntity ent1, PersistEntity ent2) => (ent1 -> Key b ent2) -> ent1 -> b m ent2 -- | Check whether there are any conflicts for unique keys with this entity -- and existing entities in the database. -- -- Returns True if the entity would be unique, and could thus -- safely be inserted; returns False on a conflict. checkUnique :: (PersistEntity val, PersistBackend b m) => val -> b m Bool class PersistEntity a => DeleteCascade a b deleteCascade :: (DeleteCascade a b, PersistBackend b m) => Key b a -> b m () deleteCascadeWhere :: (DeleteCascade a b, PersistBackend b m) => [Filter a] -> b m () data PersistException -- | Generic Exception PersistError :: String -> PersistException PersistMarshalError :: String -> PersistException PersistInvalidField :: String -> PersistException PersistForeignConstraintUnmet :: String -> PersistException PersistMongoDBError :: String -> PersistException PersistMongoDBUnsupported :: String -> PersistException data Update v Update :: EntityField v typ -> typ -> PersistUpdate -> Update v updateField :: Update v -> EntityField v typ updateValue :: Update v -> typ updateUpdate :: Update v -> PersistUpdate updateFieldName :: PersistEntity v => Update v -> String -- | Filters which are available for select, updateWhere -- and deleteWhere. Each filter constructor specifies the field -- being filtered on, the type of comparison applied (equals, not equals, -- etc) and the argument for the comparison. data Filter v Filter :: EntityField v typ -> Either typ [typ] -> PersistFilter -> Filter v filterField :: Filter v -> EntityField v typ filterValue :: Filter v -> Either typ [typ] filterFilter :: Filter v -> PersistFilter -- | convenient for internal use, not needed for the API FilterAnd :: [Filter v] -> Filter v FilterOr :: [Filter v] -> Filter v newtype Key backend entity Key :: PersistValue -> Key backend entity unKey :: Key backend entity -> PersistValue data EntityDef EntityDef :: String -> [String] -> [ColumnDef] -> [UniqueDef] -> [String] -> EntityDef entityName :: EntityDef -> String entityAttribs :: EntityDef -> [String] entityColumns :: EntityDef -> [ColumnDef] entityUniques :: EntityDef -> [UniqueDef] entityDerives :: EntityDef -> [String] type ColumnName = String type ColumnType = String data ColumnDef ColumnDef :: ColumnName -> ColumnType -> [String] -> ColumnDef columnName :: ColumnDef -> ColumnName columnType :: ColumnDef -> ColumnType columnAttribs :: ColumnDef -> [String] data UniqueDef UniqueDef :: String -> [ColumnName] -> UniqueDef uniqueName :: UniqueDef -> String uniqueColumns :: UniqueDef -> [ColumnName] fst3 :: (t, t1, t2) -> t snd3 :: (t, t1, t2) -> t1 third3 :: (t, t1, t2) -> t2 limitOffsetOrder :: PersistEntity val => [SelectOpt val] -> (Int, Int, [SelectOpt val]) instance Typeable PersistException instance Typeable PersistValue instance Typeable SqlType instance Show PersistException instance Show PersistValue instance Read PersistValue instance Eq PersistValue instance Ord PersistValue instance Show SqlType instance Read SqlType instance Eq SqlType instance Show (Key backend entity) instance Read (Key backend entity) instance Eq (Key backend entity) instance Ord (Key backend entity) instance PersistField (Key backend entity) instance Show ColumnDef instance Show UniqueDef instance Show EntityDef instance Read PersistFilter instance Show PersistFilter instance Read PersistUpdate instance Show PersistUpdate instance Enum PersistUpdate instance Bounded PersistUpdate instance PersistField PersistValue instance PersistField SomePersistField instance PersistField a => PersistField (Maybe a) instance PersistField UTCTime instance PersistField TimeOfDay instance PersistField Day instance PersistField Bool instance PersistField Double instance PersistField Word64 instance PersistField Word32 instance PersistField Word16 instance PersistField Word8 instance PersistField Int64 instance PersistField Int32 instance PersistField Int16 instance PersistField Int8 instance PersistField Int instance PersistField Html instance PersistField Text instance PersistField ByteString instance PersistField String instance SinglePiece PersistValue instance Error PersistException instance Exception PersistException module Database.Persist.Quasi -- | Parses a quasi-quoted syntax into a list of entity definitions. parse :: String -> [EntityDef] -- | Code that is only needed for writing GenericSql backends. module Database.Persist.GenericSql.Internal data Connection Connection :: (Text -> IO Statement) -> (RawName -> [RawName] -> Either Text (Text, Text)) -> IORef (Map Text Statement) -> IO () -> (forall v. PersistEntity v => (Text -> IO Statement) -> v -> IO (Either [Text] [(Bool, Text)])) -> ((Text -> IO Statement) -> IO ()) -> ((Text -> IO Statement) -> IO ()) -> ((Text -> IO Statement) -> IO ()) -> (RawName -> String) -> String -> Connection prepare :: Connection -> Text -> IO Statement insertSql :: Connection -> RawName -> [RawName] -> Either Text (Text, Text) stmtMap :: Connection -> IORef (Map Text Statement) close :: Connection -> IO () migrateSql :: Connection -> forall v. PersistEntity v => (Text -> IO Statement) -> v -> IO (Either [Text] [(Bool, Text)]) begin :: Connection -> (Text -> IO Statement) -> IO () commitC :: Connection -> (Text -> IO Statement) -> IO () rollbackC :: Connection -> (Text -> IO Statement) -> IO () escapeName :: Connection -> RawName -> String noLimit :: Connection -> String data Statement Statement :: IO () -> IO () -> ([PersistValue] -> IO ()) -> (forall a m. MonadControlIO m => [PersistValue] -> (RowPopper m -> m a) -> m a) -> Statement finalize :: Statement -> IO () reset :: Statement -> IO () execute :: Statement -> [PersistValue] -> IO () withStmt :: Statement -> forall a m. MonadControlIO m => [PersistValue] -> (RowPopper m -> m a) -> m a withSqlConn :: MonadControlIO m => IO Connection -> (Connection -> m a) -> m a withSqlPool :: MonadControlIO m => IO Connection -> Int -> (Pool Connection -> m a) -> m a type RowPopper m = m (Maybe [PersistValue]) -- | Create the list of columns for the given entity. mkColumns :: PersistEntity val => val -> ([Column], [UniqueDef']) data Column Column :: RawName -> Bool -> SqlType -> Maybe String -> (Maybe (RawName, RawName)) -> Column cName :: Column -> RawName cNull :: Column -> Bool cType :: Column -> SqlType cDefault :: Column -> Maybe String cReference :: Column -> (Maybe (RawName, RawName)) type UniqueDef' = (RawName, [RawName]) refName :: RawName -> RawName -> RawName tableColumns :: EntityDef -> [(RawName, String, [String])] rawFieldName :: ColumnDef -> RawName rawTableName :: EntityDef -> RawName newtype RawName RawName :: String -> RawName unRawName :: RawName -> String filterClause :: PersistEntity val => Bool -> Connection -> [Filter val] -> String filterClauseNoWhere :: PersistEntity val => Bool -> Connection -> [Filter val] -> String getFieldName :: EntityDef -> String -> RawName dummyFromFilts :: [Filter v] -> v orderClause :: PersistEntity val => Bool -> Connection -> SelectOpt val -> String getFiltsValues :: PersistEntity val => Connection -> [Filter val] -> [PersistValue] instance Eq RawName instance Ord RawName module Database.Persist.GenericSql.Raw withStmt :: MonadControlIO m => Text -> [PersistValue] -> (RowPopper (SqlPersist m) -> SqlPersist m a) -> SqlPersist m a execute :: MonadIO m => Text -> [PersistValue] -> SqlPersist m () newtype SqlPersist m a SqlPersist :: ReaderT Connection m a -> SqlPersist m a unSqlPersist :: SqlPersist m a -> ReaderT Connection m a getStmt' :: Connection -> Text -> IO Statement getStmt :: MonadIO m => Text -> SqlPersist m Statement instance Monad m => Monad (SqlPersist m) instance MonadIO m => MonadIO (SqlPersist m) instance MonadTrans SqlPersist instance Functor m => Functor (SqlPersist m) instance Applicative m => Applicative (SqlPersist m) instance MonadControlIO m => MonadControlIO (SqlPersist m) instance MonadPlus m => MonadPlus (SqlPersist m) -- | This is a helper module for creating SQL backends. Regular users do -- not need to use this module. module Database.Persist.GenericSql newtype SqlPersist m a SqlPersist :: ReaderT Connection m a -> SqlPersist m a unSqlPersist :: SqlPersist m a -> ReaderT Connection m a data Connection type ConnectionPool = Pool Connection data Statement runSqlConn :: MonadControlIO m => SqlPersist m a -> Connection -> m a runSqlPool :: MonadControlIO m => SqlPersist m a -> Pool Connection -> m a type Migration m = WriterT [Text] (WriterT CautiousMigration m) () parseMigration :: Monad m => Migration m -> m (Either [Text] CautiousMigration) parseMigration' :: Monad m => Migration m -> m (CautiousMigration) printMigration :: MonadControlIO m => Migration (SqlPersist m) -> SqlPersist m () getMigration :: MonadControlIO m => Migration (SqlPersist m) -> SqlPersist m [Sql] runMigration :: MonadControlIO m => Migration (SqlPersist m) -> SqlPersist m () -- | Same as runMigration, but returns a list of the SQL commands -- executed instead of printing them to stderr. runMigrationSilent :: MonadControlIO m => Migration (SqlPersist m) -> SqlPersist m [Text] runMigrationUnsafe :: MonadControlIO m => Migration (SqlPersist m) -> SqlPersist m () migrate :: (MonadControlIO m, PersistEntity val) => val -> Migration (SqlPersist m) -- | Perform a database commit. commit :: MonadIO m => SqlPersist m () -- | Perform a database rollback. rollback :: MonadIO m => SqlPersist m () newtype Key backend entity Key :: PersistValue -> Key backend entity unKey :: Key backend entity -> PersistValue instance MonadControlIO m => PersistBackend SqlPersist m instance SinglePiece (Key SqlPersist entity) module Database.Persist.Join class PersistBackend b m => RunJoin a b m where { type family Result a; } runJoin :: RunJoin a b m => a -> b m (Result a) data SelectOneMany backend one many SelectOneMany :: [Filter one] -> [SelectOpt one] -> [Filter many] -> [SelectOpt many] -> ([Key backend one] -> Filter many) -> (many -> Key backend one) -> Bool -> SelectOneMany backend one many somFilterOne :: SelectOneMany backend one many -> [Filter one] somOrderOne :: SelectOneMany backend one many -> [SelectOpt one] somFilterMany :: SelectOneMany backend one many -> [Filter many] somOrderMany :: SelectOneMany backend one many -> [SelectOpt many] somFilterKeys :: SelectOneMany backend one many -> [Key backend one] -> Filter many somGetKey :: SelectOneMany backend one many -> many -> Key backend one somIncludeNoMatch :: SelectOneMany backend one many -> Bool selectOneMany :: ([Key backend one] -> Filter many) -> (many -> Key backend one) -> SelectOneMany backend one many instance (PersistEntity one, PersistEntity many, Ord (Key backend one), PersistBackend backend monad) => RunJoin (SelectOneMany backend one many) backend monad module Database.Persist.Join.Sql class RunJoin a runJoin :: (RunJoin a, MonadControlIO m) => a -> SqlPersist m (Result a) instance (PersistEntity one, PersistEntity many, Eq (Key SqlPersist one)) => RunJoin (SelectOneMany SqlPersist one many) module Database.Persist -- | A value which can be marshalled to and from a PersistValue. class PersistField a toPersistValue :: PersistField a => a -> PersistValue fromPersistValue :: PersistField a => PersistValue -> Either String a sqlType :: PersistField a => a -> SqlType isNullable :: PersistField a => a -> Bool -- | A single database entity. For example, if writing a blog application, -- a blog entry would be an entry, containing fields such as title and -- content. class PersistEntity val where { data family EntityField val :: * -> *; data family Unique val :: ((* -> *) -> * -> *) -> *; } persistColumnDef :: PersistEntity val => EntityField val typ -> ColumnDef entityDef :: PersistEntity val => val -> EntityDef toPersistFields :: PersistEntity val => val -> [SomePersistField] fromPersistValues :: PersistEntity val => [PersistValue] -> Either String val halfDefined :: PersistEntity val => val persistUniqueToFieldNames :: PersistEntity val => Unique val backend -> [String] persistUniqueToValues :: PersistEntity val => Unique val backend -> [PersistValue] persistUniqueKeys :: PersistEntity val => val -> [Unique val backend] class (MonadIO (b m), MonadIO m, Monad (b m), Monad m) => PersistBackend b m insert :: (PersistBackend b m, PersistEntity val) => val -> b m (Key b val) replace :: (PersistBackend b m, PersistEntity val) => Key b val -> val -> b m () update :: (PersistBackend b m, PersistEntity val) => Key b val -> [Update val] -> b m () updateWhere :: (PersistBackend b m, PersistEntity val) => [Filter val] -> [Update val] -> b m () delete :: (PersistBackend b m, PersistEntity val) => Key b val -> b m () deleteBy :: (PersistBackend b m, PersistEntity val) => Unique val b -> b m () deleteWhere :: (PersistBackend b m, PersistEntity val) => [Filter val] -> b m () get :: (PersistBackend b m, PersistEntity val) => Key b val -> b m (Maybe val) getBy :: (PersistBackend b m, PersistEntity val) => Unique val b -> b m (Maybe (Key b val, val)) selectEnum :: (PersistBackend b m, PersistEntity val) => [Filter val] -> [SelectOpt val] -> Enumerator (Key b val, val) (b m) a selectFirst :: (PersistBackend b m, PersistEntity val) => [Filter val] -> [SelectOpt val] -> b m (Maybe (Key b val, val)) selectKeys :: (PersistBackend b m, PersistEntity val) => [Filter val] -> Enumerator (Key b val) (b m) a count :: (PersistBackend b m, PersistEntity val) => [Filter val] -> b m Int newtype Key backend entity Key :: PersistValue -> Key backend entity unKey :: Key backend entity -> PersistValue -- | Call select but return the result as a list. selectList :: (PersistEntity val, PersistBackend b m) => [Filter val] -> [SelectOpt val] -> b m [(Key b val, val)] -- | Insert a value, checking for conflicts with any unique constraints. If -- a duplicate exists in the database, it is returned as Left. -- Otherwise, the new Key is returned as Right. insertBy :: (PersistEntity v, PersistBackend b m) => v -> b m (Either (Key b v, v) (Key b v)) -- | Same as get, but for a non-null (not Maybe) foreign key Unsafe unless -- your database is enforcing that the foreign key is valid getJust :: (PersistBackend b m, PersistEntity val, Show (Key b val)) => Key b val -> b m val belongsTo :: (PersistBackend b m, PersistEntity ent1, PersistEntity ent2) => (ent1 -> Maybe (Key b ent2)) -> ent1 -> b m (Maybe ent2) -- | same as belongsTo, but uses getJust and therefore is -- similarly unsafe belongsToJust :: (PersistBackend b m, PersistEntity ent1, PersistEntity ent2) => (ent1 -> Key b ent2) -> ent1 -> b m ent2 -- | A modification of getBy, which takes the PersistEntity -- itself instead of a Unique value. Returns a value matching -- one of the unique keys. This function makes the most sense on -- entities with a single Unique constructor. getByValue :: (PersistEntity v, PersistBackend b m) => v -> b m (Maybe (Key b v, v)) -- | Check whether there are any conflicts for unique keys with this entity -- and existing entities in the database. -- -- Returns True if the entity would be unique, and could thus -- safely be inserted; returns False on a conflict. checkUnique :: (PersistEntity val, PersistBackend b m) => val -> b m Bool data Update v Update :: EntityField v typ -> typ -> PersistUpdate -> Update v updateField :: Update v -> EntityField v typ updateValue :: Update v -> typ updateUpdate :: Update v -> PersistUpdate data SelectOpt v Asc :: (EntityField v typ) -> SelectOpt v Desc :: (EntityField v typ) -> SelectOpt v OffsetBy :: Int -> SelectOpt v LimitTo :: Int -> SelectOpt v -- | Filters which are available for select, updateWhere -- and deleteWhere. Each filter constructor specifies the field -- being filtered on, the type of comparison applied (equals, not equals, -- etc) and the argument for the comparison. data Filter v Filter :: EntityField v typ -> Either typ [typ] -> PersistFilter -> Filter v filterField :: Filter v -> EntityField v typ filterValue :: Filter v -> Either typ [typ] filterFilter :: Filter v -> PersistFilter -- | convenient for internal use, not needed for the API FilterAnd :: [Filter v] -> Filter v FilterOr :: [Filter v] -> Filter v (=., /=., *=., -=., +=.) :: PersistField typ => EntityField v typ -> typ -> Update v -- | assign a field a value -- -- assign a field by addition (+=) -- -- assign a field by subtraction (-=) -- -- assign a field by multiplication (*=) -- -- assign a field by division (/=) (==., >=., >., <=., <., !=.) :: PersistField typ => EntityField v typ -> typ -> Filter v (<-., /<-.) :: PersistField typ => EntityField v typ -> [typ] -> Filter v -- | In -- -- NotIn (||.) :: [Filter v] -> [Filter v] -> [Filter v]