Safe Haskell | None |
---|
Database.Persist.Store
Description
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.
- data PersistValue
- data SqlType
- = SqlString
- | SqlInt32
- | SqlInteger
- | SqlReal
- | SqlBool
- | SqlDay
- | SqlTime
- | SqlDayTime
- | SqlBlob
- class PersistField a where
- toPersistValue :: a -> PersistValue
- fromPersistValue :: PersistValue -> Either Text a
- sqlType :: a -> SqlType
- isNullable :: a -> Bool
- class PersistEntity val where
- data EntityField val :: * -> *
- type PersistEntityBackend val :: (* -> *) -> * -> *
- data Unique val :: ((* -> *) -> * -> *) -> *
- persistFieldDef :: EntityField val typ -> FieldDef
- entityDef :: val -> EntityDef
- toPersistFields :: val -> [SomePersistField]
- fromPersistValues :: [PersistValue] -> Either Text val
- halfDefined :: val
- persistUniqueToFieldNames :: Unique val backend -> [(HaskellName, DBName)]
- persistUniqueToValues :: Unique val backend -> [PersistValue]
- persistUniqueKeys :: val -> [Unique val backend]
- persistIdField :: EntityField val (Key (PersistEntityBackend val) val)
- class (MonadBaseControl IO m, MonadBaseControl IO (b m)) => PersistStore b m where
- insert :: PersistEntity val => val -> b m (Key b val)
- insertKey :: PersistEntity val => Key b val -> val -> b m ()
- repsert :: PersistEntity val => Key b val -> val -> b m ()
- replace :: PersistEntity val => Key b val -> val -> b m ()
- delete :: PersistEntity val => Key b val -> b m ()
- get :: PersistEntity val => Key b val -> b m (Maybe val)
- class PersistStore b m => PersistUnique b m where
- getBy :: (PersistEntityBackend val ~ b, PersistEntity val) => Unique val b -> b m (Maybe (Entity val))
- deleteBy :: PersistEntity val => Unique val b -> b m ()
- insertUnique :: (b ~ PersistEntityBackend val, PersistEntity val) => val -> b m (Maybe (Key b val))
- data PersistFilter
- data SomePersistField = forall a . PersistField a => SomePersistField a
- insertBy :: (PersistEntity v, PersistStore b m, PersistUnique b m, b ~ PersistEntityBackend v) => v -> b m (Either (Entity v) (Key b v))
- getByValue :: (PersistEntity v, PersistUnique b m, PersistEntityBackend v ~ b) => v -> b m (Maybe (Entity v))
- getJust :: (PersistStore b m, PersistEntity val, Show (Key b val)) => Key b val -> b m val
- belongsTo :: (PersistStore b m, PersistEntity ent1, PersistEntity ent2) => (ent1 -> Maybe (Key b ent2)) -> ent1 -> b m (Maybe ent2)
- belongsToJust :: (PersistStore b m, PersistEntity ent1, PersistEntity ent2) => (ent1 -> Key b ent2) -> ent1 -> b m ent2
- checkUnique :: (PersistEntityBackend val ~ b, PersistEntity val, PersistUnique b m) => val -> b m Bool
- class PersistEntity a => DeleteCascade a b m where
- deleteCascade :: Key b a -> b m ()
- data PersistException
- newtype Key backend entity = Key {}
- data Entity entity = Entity {
- entityKey :: Key (PersistEntityBackend entity) entity
- entityVal :: entity
- getPersistMap :: PersistValue -> Either Text [(Text, PersistValue)]
- listToJSON :: [PersistValue] -> Text
- mapToJSON :: [(Text, PersistValue)] -> Text
- class PersistConfig c where
- type PersistConfigBackend c :: (* -> *) -> * -> *
- type PersistConfigPool c
- loadConfig :: Value -> Parser c
- applyEnv :: c -> IO c
- createPoolConfig :: c -> IO (PersistConfigPool c)
- runPool :: (MonadBaseControl IO m, MonadIO m) => c -> PersistConfigBackend c m a -> PersistConfigPool c -> m a
Documentation
data PersistValue
A raw value which can be stored in any backend and can be marshalled to
and from a PersistField
.
Constructors
PersistText Text | |
PersistByteString ByteString | |
PersistInt64 Int64 | |
PersistDouble Double | |
PersistBool Bool | |
PersistDay Day | |
PersistTimeOfDay TimeOfDay | |
PersistUTCTime UTCTime | |
PersistNull | |
PersistList [PersistValue] | |
PersistMap [(Text, PersistValue)] | |
PersistObjectId ByteString | intended especially for MongoDB backend |
data SqlType
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.
Constructors
SqlString | |
SqlInt32 | |
SqlInteger | FIXME 8-byte integer; should be renamed SqlInt64 |
SqlReal | |
SqlBool | |
SqlDay | |
SqlTime | |
SqlDayTime | |
SqlBlob |
class PersistField a where
A value which can be marshalled to and from a PersistValue
.
Methods
toPersistValue :: a -> PersistValue
fromPersistValue :: PersistValue -> Either Text a
isNullable :: a -> Bool
Instances
class PersistEntity val where
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.
Associated Types
data EntityField val :: * -> *
Parameters: val and datatype of the field
type PersistEntityBackend val :: (* -> *) -> * -> *
data Unique val :: ((* -> *) -> * -> *) -> *
Unique keys in existence on this entity.
Methods
persistFieldDef :: EntityField val typ -> FieldDef
toPersistFields :: val -> [SomePersistField]
fromPersistValues :: [PersistValue] -> Either Text val
halfDefined :: val
persistUniqueToFieldNames :: Unique val backend -> [(HaskellName, DBName)]
persistUniqueToValues :: Unique val backend -> [PersistValue]
persistUniqueKeys :: val -> [Unique val backend]
persistIdField :: EntityField val (Key (PersistEntityBackend val) val)
class (MonadBaseControl IO m, MonadBaseControl IO (b m)) => PersistStore b m where
Methods
insert :: PersistEntity val => val -> b m (Key b val)
Create a new record in the database, returning an automatically created key (in SQL an auto-increment id).
insertKey :: PersistEntity val => Key b val -> val -> b m ()
Create a new record in the database using the given key.
repsert :: PersistEntity val => Key b val -> val -> b m ()
Put the record in the database with the given key.
Unlike replace
, if a record with the given key does not
exist then a new record will be inserted.
replace :: PersistEntity val => Key b val -> val -> b m ()
Replace the record in the database with the given
key. Note that the result is undefined if such record does
not exist, so you must use insertKey
or repsert
in
these cases.
delete :: PersistEntity val => Key b val -> b m ()
Delete a specific record by identifier. Does nothing if record does not exist.
get :: PersistEntity val => Key b val -> b m (Maybe val)
Get a record by identifier, if available.
Instances
(MonadBaseControl IO m, MonadIO m, MonadThrow m, MonadUnsafeIO m) => PersistStore SqlPersist m |
class PersistStore b m => PersistUnique b m where
Methods
getBy :: (PersistEntityBackend val ~ b, PersistEntity val) => Unique val b -> b m (Maybe (Entity val))
Get a record by unique key, if available. Returns also the identifier.
deleteBy :: PersistEntity val => Unique val b -> b m ()
Delete a specific record by unique key. Does nothing if no record matches.
insertUnique :: (b ~ PersistEntityBackend val, PersistEntity val) => val -> b m (Maybe (Key b val))
Instances
(MonadBaseControl IO m, MonadUnsafeIO m, MonadIO m, MonadThrow m) => PersistUnique SqlPersist m |
data PersistFilter
Instances
insertBy :: (PersistEntity v, PersistStore b m, PersistUnique b m, b ~ PersistEntityBackend v) => v -> b m (Either (Entity v) (Key b v))
getByValue :: (PersistEntity v, PersistUnique b m, PersistEntityBackend v ~ b) => v -> b m (Maybe (Entity 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.
getJust :: (PersistStore b m, PersistEntity val, Show (Key b val)) => Key b val -> b m val
Same as get, but for a non-null (not Maybe) foreign key Unsafe unless your database is enforcing that the foreign key is valid
belongsTo :: (PersistStore b m, PersistEntity ent1, PersistEntity ent2) => (ent1 -> Maybe (Key b ent2)) -> ent1 -> b m (Maybe ent2)
belongsToJust :: (PersistStore b m, PersistEntity ent1, PersistEntity ent2) => (ent1 -> Key b ent2) -> ent1 -> b m ent2
same as belongsTo, but uses getJust
and therefore is similarly unsafe
checkUnique :: (PersistEntityBackend val ~ b, PersistEntity val, PersistUnique b m) => val -> b m Bool
class PersistEntity a => DeleteCascade a b m where
Methods
deleteCascade :: Key b a -> b m ()
data PersistException
Constructors
PersistError Text | Generic Exception |
PersistMarshalError Text | |
PersistInvalidField Text | |
PersistForeignConstraintUnmet Text | |
PersistMongoDBError Text | |
PersistMongoDBUnsupported Text |
data Entity entity
Datatype that represents an entity, with both its key and its Haskell representation.
When using the an SQL-based backend (such as SQLite or
PostgreSQL), an Entity
may take any number of columns
depending on how many fields it has. In order to reconstruct
your entity on the Haskell side, persistent
needs all of
your entity columns and in the right order. Note that you
don't need to worry about this when using persistent
's API
since everything is handled correctly behind the scenes.
However, if you want to issue a raw SQL command that returns
an Entity
, then you have to be careful with the column
order. While you could use SELECT Entity.* WHERE ...
and
that would work most of the time, there are times when the
order of the columns on your database is different from the
order that persistent
expects (for example, if you add a new
field in the middle of you entity definition and then use the
migration code -- persistent
will expect the column to be in
the middle, but your DBMS will put it as the last column).
So, instead of using a query like the one above, you may use
rawSql
(from the
Database.Persist.GenericSql module) with its /entity
selection placeholder/ (a double question mark ??
). Using
rawSql
the query above must be written as SELECT ?? WHERE
..
. Then rawSql
will replace ??
with the list of all
columns that we need from your entity in the right order. If
your query returns two entities (i.e. (Entity backend a,
Entity backend b)
), then you must you use SELECT ??, ??
WHERE ...
, and so on.
Constructors
Entity | |
Fields
|
Helpers
getPersistMap :: PersistValue -> Either Text [(Text, PersistValue)]
listToJSON :: [PersistValue] -> Text
mapToJSON :: [(Text, PersistValue)] -> Text
Config
class PersistConfig c where
Represents a value containing all the configuration options for a specific backend. This abstraction makes it easier to write code that can easily swap backends.
Methods
loadConfig :: Value -> Parser c
Load the config settings from a Value
, most likely taken from a YAML
config file.
Modify the config settings based on environment variables.
createPoolConfig :: c -> IO (PersistConfigPool c)
Create a new connection pool based on the given config settings.
runPool :: (MonadBaseControl IO m, MonadIO m) => c -> PersistConfigBackend c m a -> PersistConfigPool c -> m a
Run a database action by taking a connection from the pool.