Safe Haskell | Safe-Infered |
---|
Database.Persist
Contents
- 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))
- class PersistStore b m => PersistQuery b m where
- update :: PersistEntity val => Key b val -> [Update val] -> b m ()
- updateWhere :: PersistEntity val => [Filter val] -> [Update val] -> b m ()
- deleteWhere :: PersistEntity val => [Filter val] -> b m ()
- selectSource :: (PersistEntity val, PersistEntityBackend val ~ b) => [Filter val] -> [SelectOpt val] -> Source (ResourceT (b m)) (Entity val)
- selectFirst :: (PersistEntity val, PersistEntityBackend val ~ b) => [Filter val] -> [SelectOpt val] -> b m (Maybe (Entity val))
- selectKeys :: PersistEntity val => [Filter val] -> Source (ResourceT (b m)) (Key b val)
- count :: PersistEntity val => [Filter val] -> b m Int
- newtype Key backend entity = Key {}
- data Entity entity = Entity {
- entityKey :: Key (PersistEntityBackend entity) entity
- entityVal :: entity
- insertBy :: (PersistEntity v, PersistStore b m, PersistUnique b m, b ~ PersistEntityBackend v) => v -> b m (Either (Entity v) (Key b 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
- getByValue :: (PersistEntity v, PersistUnique b m, PersistEntityBackend v ~ b) => v -> b m (Maybe (Entity v))
- checkUnique :: (PersistEntityBackend val ~ b, PersistEntity val, PersistUnique b m) => val -> b m Bool
- selectList :: (PersistEntity val, PersistQuery b m, PersistEntityBackend val ~ b) => [Filter val] -> [SelectOpt val] -> b m [Entity val]
- deleteCascadeWhere :: (DeleteCascade a b m, PersistQuery b m) => [Filter a] -> b m ()
- data SelectOpt v
- = forall typ . Asc (EntityField v typ)
- | forall typ . Desc (EntityField v typ)
- | OffsetBy Int
- | LimitTo Int
- data Filter v
- = forall typ . PersistField typ => Filter {
- filterField :: EntityField v typ
- filterValue :: Either typ [typ]
- filterFilter :: PersistFilter
- | FilterAnd [Filter v]
- | FilterOr [Filter v]
- = forall typ . PersistField typ => Filter {
- (=.), (/=.), (*=.), (-=.), (+=.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Update v
- (==.), (>=.), (>.), (<=.), (<.), (!=.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Filter v
- (<-.), (/<-.) :: forall v typ. PersistField typ => EntityField v typ -> [typ] -> Filter v
- (||.) :: forall v. [Filter v] -> [Filter v] -> [Filter v]
Documentation
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 |
class PersistStore b m => PersistQuery b m where
Methods
update :: PersistEntity val => Key b val -> [Update val] -> b m ()
Update individual fields on a specific record.
updateWhere :: PersistEntity val => [Filter val] -> [Update val] -> b m ()
Update individual fields on any record matching the given criterion.
deleteWhere :: PersistEntity val => [Filter val] -> b m ()
Delete all records matching the given criterion.
selectSource :: (PersistEntity val, PersistEntityBackend val ~ b) => [Filter val] -> [SelectOpt val] -> Source (ResourceT (b m)) (Entity val)
Get all records matching the given criterion in the specified order. Returns also the identifiers.
selectFirst :: (PersistEntity val, PersistEntityBackend val ~ b) => [Filter val] -> [SelectOpt val] -> b m (Maybe (Entity val))
get just the first record for the criterion
selectKeys :: PersistEntity val => [Filter val] -> Source (ResourceT (b m)) (Key b val)
Get the Key
s of all records matching the given criterion.
count :: PersistEntity val => [Filter val] -> b m Int
The total number of records fulfilling the given criterion.
Instances
(MonadThrow m, MonadIO m, MonadUnsafeIO m, MonadBaseControl IO m) => PersistQuery SqlPersist m |
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
|
insertBy :: (PersistEntity v, PersistStore b m, PersistUnique b m, b ~ PersistEntityBackend v) => v -> b m (Either (Entity v) (Key b v))
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
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.
checkUnique :: (PersistEntityBackend val ~ b, PersistEntity val, PersistUnique b m) => val -> b m Bool
selectList :: (PersistEntity val, PersistQuery b m, PersistEntityBackend val ~ b) => [Filter val] -> [SelectOpt val] -> b m [Entity val]
Call select
but return the result as a list.
deleteCascadeWhere :: (DeleteCascade a b m, PersistQuery b m) => [Filter a] -> b m ()
data SelectOpt v
Constructors
forall typ . Asc (EntityField v typ) | |
forall typ . Desc (EntityField v typ) | |
OffsetBy Int | |
LimitTo Int |
data Filter 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.
Constructors
forall typ . PersistField typ => Filter | |
Fields
| |
FilterAnd [Filter v] | convenient for internal use, not needed for the API |
FilterOr [Filter v] |
query combinators
(=.), (/=.), (*=.), (-=.), (+=.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Update v
assign a field a value
(==.), (>=.), (>.), (<=.), (<.), (!=.) :: forall v typ. PersistField typ => EntityField v typ -> typ -> Filter v
(<-.), (/<-.) :: forall v typ. PersistField typ => EntityField v typ -> [typ] -> Filter v
In