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

Safe Haskell | None

Database.Persist.Types

Synopsis

- data Checkmark
  - = Active
  - | Inactive
- data IsNullable
  - = Nullable !WhyNullable
  - | NotNullable
- data WhyNullable
  - = ByMaybeAttr
  - | ByNullableAttr
- data EntityDef sqlType = EntityDef {
  - entityHaskell :: !HaskellName
  - entityDB :: !DBName
  - entityID :: !DBName
  - entityAttrs :: ![Attr]
  - entityFields :: ![FieldDef sqlType]
  - entityUniques :: ![UniqueDef]
  - entityDerives :: ![Text]
  - entityExtra :: !(Map Text [ExtraLine])
  - entitySum :: !Bool
  }
- type ExtraLine = [Text]
- newtype HaskellName = HaskellName {
  - unHaskellName :: Text
  }
- newtype DBName = DBName {
  - unDBName :: Text
  }
- type Attr = Text
- data FieldType
  - = FTTypeCon (Maybe Text) Text
  - | FTApp FieldType FieldType
  - | FTList FieldType
- data FieldDef sqlType = FieldDef {
  - fieldHaskell :: !HaskellName
  - fieldDB :: !DBName
  - fieldType :: !FieldType
  - fieldSqlType :: !sqlType
  - fieldAttrs :: ![Attr]
  - fieldStrict :: !Bool
  - fieldEmbedded :: Maybe (EntityDef ())
  }
- data UniqueDef = UniqueDef {
  - uniqueHaskell :: !HaskellName
  - uniqueDBName :: !DBName
  - uniqueFields :: ![(HaskellName, DBName)]
  - uniqueAttrs :: ![Attr]
  }
- data PersistException
  - = PersistError Text
  - | PersistMarshalError Text
  - | PersistInvalidField Text
  - | PersistForeignConstraintUnmet Text
  - | PersistMongoDBError Text
  - | PersistMongoDBUnsupported Text
- newtype ZT = ZT ZonedTime
- data PersistValue
  - = PersistText Text
  - | PersistByteString ByteString
  - | PersistInt64 Int64
  - | PersistDouble Double
  - | PersistRational Rational
  - | PersistBool Bool
  - | PersistDay Day
  - | PersistTimeOfDay TimeOfDay
  - | PersistUTCTime UTCTime
  - | PersistZonedTime ZT
  - | PersistNull
  - | PersistList [PersistValue]
  - | PersistMap [(Text, PersistValue)]
  - | PersistObjectId ByteString
- fromPersistValueText :: PersistValue -> Either String Text
- data SqlType
  - = SqlString
  - | SqlInt32
  - | SqlInt64
  - | SqlReal
  - | SqlNumeric Word32 Word32
  - | SqlBool
  - | SqlDay
  - | SqlTime
  - | SqlDayTime
  - | SqlDayTimeZoned
  - | SqlBlob
  - | SqlOther Text
- newtype KeyBackend backend entity = Key {
  - unKey :: PersistValue
  }
- type family KeyEntity key
- data PersistFilter
  - = Eq
  - | Ne
  - | Gt
  - | Lt
  - | Ge
  - | Le
  - | In
  - | NotIn
  - | BackendSpecificFilter Text
- data UpdateGetException = KeyNotFound String
- data PersistUpdate
  - = Assign
  - | Add
  - | Subtract
  - | Multiply
  - | Divide
- data SomePersistField = forall a . PersistField a => SomePersistField a
- data Update v = forall typ . PersistField typ => Update {
  - updateField :: EntityField v typ
  - updateValue :: typ
  - updateUpdate :: PersistUpdate
  }
- data SelectOpt v
  - = forall typ . Asc (EntityField v typ)
  - | forall typ . Desc (EntityField v typ)
  - | OffsetBy Int
  - | LimitTo Int
- type family BackendSpecificFilter b v
- data Filter v
  - = forall typ . PersistField typ => Filter {
    - filterField :: EntityField v typ
    - filterValue :: Either typ [typ]
    - filterFilter :: PersistFilter
    }
  - | FilterAnd [Filter v]
  - | FilterOr [Filter v]
  - | BackendFilter (BackendSpecificFilter (PersistEntityBackend v) v)
- type Key val = KeyBackend (PersistEntityBackend val) val
- data Entity entity = Entity {
  - entityKey :: Key entity
  - entityVal :: entity
  }

# Documentation

data Checkmark

A `Checkmark` should be used as a field type whenever a uniqueness constraint should guarantee that a certain kind of record may appear at most once, but other kinds of records may appear any number of times.

NOTE: You need to mark any `Checkmark` fields as `nullable` (see the following example).

For example, suppose there's a `Location` entity that represents where a user has lived:

     Location
         user    UserId
         name    Text
         current Checkmark nullable

    UniqueLocation user current

The `UniqueLocation` constraint allows any number of `Inactive` `Location`s to be `current`. However, there may be at most one `current` `Location` per user (i.e., either zero or one per user).

This data type works because of the way that SQL treats `NULL`able fields within uniqueness constraints. The SQL standard says that `NULL` values should be considered different, so we represent `Inactive` as SQL `NULL`, thus allowing any number of `Inactive` records. On the other hand, we represent `Active` as `TRUE`, so the uniqueness constraint will disallow more than one `Active` record.

Note: There may be DBMSs that do not respect the SQL standard's treatment of `NULL` values on uniqueness constraints, please check if this data type works before relying on it.

The SQL `BOOLEAN` type is used because it's the smallest data type available. Note that we never use `FALSE`, just `TRUE` and `NULL`. Provides the same behavior `Maybe ()` would if `()` was a valid `PersistField`.

Constructors

Active | When used on a uniqueness constraint, there may be at most one `Active` record.
Inactive | When used on a uniqueness constraint, there may be any number of `Inactive` records.

Instances

Bounded Checkmark |
Enum Checkmark |
Eq Checkmark |
Ord Checkmark |
Read Checkmark |
Show Checkmark |
PathPiece Checkmark |
PersistField Checkmark |
PersistFieldSql Checkmark |

data IsNullable

Constructors

Nullable !WhyNullable |
NotNullable |

Instances

Eq IsNullable |
Show IsNullable |

data WhyNullable

The reason why a field is `nullable` is very important. A field that is nullable because of a `Maybe` tag will have its type changed from `A` to `Maybe A`. OTOH, a field that is nullable because of a `nullable` tag will remain with the same type.

Constructors

ByMaybeAttr |
ByNullableAttr |

Instances

Eq WhyNullable |
Show WhyNullable |

data EntityDef sqlType

Constructors

EntityDef |

Fields

entityHaskell :: !HaskellName
entityDB :: !DBName
entityID :: !DBName
entityAttrs :: ![Attr]
entityFields :: ![FieldDef sqlType]
entityUniques :: ![UniqueDef]
entityDerives :: ![Text]
entityExtra :: !(Map Text [ExtraLine])
entitySum :: !Bool

Instances

Functor EntityDef |
Eq sqlType => Eq (EntityDef sqlType) |
Ord sqlType => Ord (EntityDef sqlType) |
Read sqlType => Read (EntityDef sqlType) |
Show sqlType => Show (EntityDef sqlType) |

type ExtraLine = [Text]

newtype HaskellName

Constructors

HaskellName |

Fields

unHaskellName :: Text

Instances

Eq HaskellName |
Ord HaskellName |
Read HaskellName |
Show HaskellName |

newtype DBName

Constructors

DBName |

Fields

unDBName :: Text

Instances

Eq DBName |
Ord DBName |
Read DBName |
Show DBName |

type Attr = Text

data FieldType

Constructors

FTTypeCon (Maybe Text) Text | Optional module and name.
FTApp FieldType FieldType |
FTList FieldType |

Instances

Eq FieldType |
Ord FieldType |
Read FieldType |
Show FieldType |

data FieldDef sqlType

Constructors

FieldDef |

Fields

fieldHaskell :: !HaskellName

  name of the field

fieldDB :: !DBName
fieldType :: !FieldType
fieldSqlType :: !sqlType
fieldAttrs :: ![Attr]

  user annotations for a field

fieldStrict :: !Bool

  a strict field in the data type. Default: true

fieldEmbedded :: Maybe (EntityDef ())

  indicates that the field uses an embedded entity

Instances

Functor FieldDef |
Eq sqlType => Eq (FieldDef sqlType) |
Ord sqlType => Ord (FieldDef sqlType) |
Read sqlType => Read (FieldDef sqlType) |
Show sqlType => Show (FieldDef sqlType) |

data UniqueDef

Constructors

UniqueDef |

Fields

uniqueHaskell :: !HaskellName
uniqueDBName :: !DBName
uniqueFields :: ![(HaskellName, DBName)]
uniqueAttrs :: ![Attr]

Instances

Eq UniqueDef |
Ord UniqueDef |
Read UniqueDef |
Show UniqueDef |

data PersistException

Constructors

PersistError Text | Generic Exception
PersistMarshalError Text |
PersistInvalidField Text |
PersistForeignConstraintUnmet Text |
PersistMongoDBError Text |
PersistMongoDBUnsupported Text |

Instances

Show PersistException |
Typeable PersistException |
Exception PersistException |
Error PersistException |

newtype ZT

Avoid orphan instances.

Constructors

ZT ZonedTime |

Instances

Eq ZT |
Ord ZT |
Read ZT |
Show ZT |
Typeable ZT |

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 |
PersistRational Rational |
PersistBool Bool |
PersistDay Day |
PersistTimeOfDay TimeOfDay |
PersistUTCTime UTCTime |
PersistZonedTime ZT |
PersistNull |
PersistList [PersistValue] |
PersistMap [(Text, PersistValue)] |
PersistObjectId ByteString | intended especially for MongoDB backend

Instances

Eq PersistValue |
Ord PersistValue |
Read PersistValue |
Show PersistValue |
Typeable PersistValue |
ToJSON PersistValue |
FromJSON PersistValue |
PathPiece PersistValue |
PersistField PersistValue |
PersistFieldSql PersistValue |

fromPersistValueText :: PersistValue -> Either String Text

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 |
SqlInt64 |
SqlReal |
SqlNumeric Word32 Word32 |
SqlBool |
SqlDay |
SqlTime |
SqlDayTime |
SqlDayTimeZoned |
SqlBlob |
SqlOther Text | a backend-specific name

Instances

Eq SqlType |
Ord SqlType |
Read SqlType |
Show SqlType |
Typeable SqlType |

newtype KeyBackend backend entity

Constructors

Key |

Fields

unKey :: PersistValue

Instances

Eq (KeyBackend backend entity) |
Ord (KeyBackend backend entity) |
Read (KeyBackend backend entity) |
Show (KeyBackend backend entity) |
ToJSON (KeyBackend backend entity) |
FromJSON (KeyBackend backend entity) |
PathPiece (KeyBackend SqlBackend entity) |
PersistField (KeyBackend backend entity) |

type family KeyEntity key

data PersistFilter

Constructors

Eq |
Ne |
Gt |
Lt |
Ge |
Le |
In |
NotIn |
BackendSpecificFilter Text |

Instances

Read PersistFilter |
Show PersistFilter |

data UpdateGetException

Constructors

KeyNotFound String |

Instances

Show UpdateGetException |
Typeable UpdateGetException |
Exception UpdateGetException |

data PersistUpdate

Constructors

Assign |
Add |
Subtract |
Multiply |
Divide |

Instances

Bounded PersistUpdate |
Enum PersistUpdate |
Read PersistUpdate |
Show PersistUpdate |

data SomePersistField

Constructors

forall a . PersistField a => SomePersistField a |

Instances

PersistField SomePersistField |

data Update v

Constructors

forall typ . PersistField typ => Update |

Fields

updateField :: EntityField v typ
updateValue :: typ
updateUpdate :: PersistUpdate

data SelectOpt v

Constructors

forall typ . Asc (EntityField v typ) |
forall typ . Desc (EntityField v typ) |
OffsetBy Int |
LimitTo Int |

type family BackendSpecificFilter b v

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

filterField :: EntityField v typ
filterValue :: Either typ [typ]
filterFilter :: PersistFilter

FilterAnd [Filter v] | convenient for internal use, not needed for the API
FilterOr [Filter v] |
BackendFilter (BackendSpecificFilter (PersistEntityBackend v) v) |

type Key val = KeyBackend (PersistEntityBackend val) val

Helper wrapper, equivalent to `Key (PersistEntityBackend val) val`.

Since 1.1.0

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

entityKey :: Key entity
entityVal :: entity

Instances

Eq entity => Eq (Entity entity) |
Ord entity => Ord (Entity entity) |
Read entity => Read (Entity entity) |
Show entity => Show (Entity entity) |
ToJSON e => ToJSON (Entity e) |
FromJSON e => FromJSON (Entity e) |
PersistEntity a => RawSql (Entity a) |