Documentation

Queries against Unique keys (other than the id Key).

Please read the general Persistent documentation to learn how to create Unique keys.

Using this with an Entity without a Unique key leads to undefined behavior. A few of these functions require a single Unique, so using an Entity with multiple Uniques is also undefined. In these cases persistent's goal is to throw an exception as soon as possible, but persistent is still transitioning to that.

SQL backends automatically create uniqueness constraints, but for MongoDB you must manually place a unique index on a field to have a uniqueness constraint.

Some functions in this module (insertUnique, insertBy, and replaceUnique) first query the unique indexes to check for conflicts. You could instead optimistically attempt to perform the operation (e.g. replace instead of replaceUnique). However,

• there is some fragility to trying to catch the correct exception and determing the column of failure;
• an exception will automatically abort the current SQL transaction.

This class is used to ensure that upsert is only called on records that have a single Unique key. The quasiquoter automatically generates working instances for appropriate records, and generates TypeError instances for records that have 0 or multiple unique keys.

Since: 2.10.0

Given a proxy for a PersistEntity record, this returns the sole UniqueDef for that entity.

Since: 2.13.0.0

This class is used to ensure that functions requring at least one unique key are not called with records that have 0 unique keys. The quasiquoter automatically writes working instances for appropriate entities, and generates TypeError instances for records that have 0 unique keys.

Since: 2.10.0

Given a proxy for a record that has an instance of AtLeastOneUniqueKey, this returns a NonEmpty list of the UniqueDefs for that entity.

Since: 2.10.0

This is an error message. It is used when writing instances of OnlyOneUniqueKey for an entity that has no unique keys.

Since: 2.10.0

This is an error message. It is used when an entity has multiple unique keys, and the function expects a single unique key.

Since: 2.10.0

A modification of getBy, which takes the PersistEntity itself instead of a Unique record. Returns a record matching one of the unique keys. This function makes the most sense on entities with a single Unique constructor.

Example usage

mSpjEnt <- getBySpjValue

+----+------+-----+
| id | name | age |
+----+------+-----+
|  1 | SPJ  |  40 |
+----+------+-----+

Retrieve a record from the database using the given unique keys. It will attempt to find a matching record for each Unique in the list, and returns the first one that has a match.

Returns Nothing if you provide an empty list ('[]') or if no value matches in the database.

Since: 2.10.0

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.

Example usage

l1 <- insertBy $ User "SPJ" 20
l2 <- insertBy $ User "XXX" 41
l3 <- insertBy $ User "SPJ" 40
r1 <- insertBy $ User "XXX" 100

Like insertEntity, but returns Nothing when the record couldn't be inserted because of a uniqueness constraint.

Example usage

insertUniqueSpjEntity :: MonadIO m => ReaderT SqlBackend m (Maybe (Entity User))
insertUniqueSpjEntity = insertUniqueEntity $ User "SPJ" 50

mSpjEnt <- insertUniqueSpjEntity

insertUniqueAlexaEntity :: MonadIO m => ReaderT SqlBackend m (Maybe (Entity User))
insertUniqueAlexaEntity = insertUniqueEntity $ User "Alexa" 3

mAlexaEnt <- insertUniqueSpjEntity

+----+-------+-----+
| id | name  | age |
+----+-------+-----+
|  1 | SPJ   |  40 |
+----+-------+-----+
|  2 | Simon |  41 |
+----+-------+-----+
|  3 | Alexa |   3 |
+----+-------+-----+

Since: 2.7.1

Attempt to replace the record of the given key with the given new record. First query the unique fields to make sure the replacement maintains uniqueness constraints.

Return Nothing if the replacement was made. If uniqueness is violated, return a Just with the Unique violation

Since: 1.2.2.0

Check whether there are any conflicts for unique keys with this entity and existing entities in the database.

Returns Nothing if the entity would be unique, and could thus safely be inserted. on a conflict returns the conflicting key

Example usage

mAlanConst <- checkUnique $ User "Alan" 70

mSpjConst <- checkUnique $ User "SPJ" 60

Check whether there are any conflicts for unique keys with this entity and existing entities in the database.

Returns Nothing if the entity would stay unique, and could thus safely be updated. on a conflict returns the conflicting key

This is similar to checkUnique, except it's useful for updating - when the particular entity already exists, it would normally conflict with itself. This variant ignores those conflicts

Example usage

mAlanConst <- checkUnique $ User "Alan" 70

mSpjConst <- checkUnique $ User "SPJ" 60

Since: 2.11.0.0

Return the single unique key for a record.

Example usage

onlySimonConst :: MonadIO m => ReaderT SqlBackend m (Unique User)
onlySimonConst = onlyUnique $ User "Simon" 999

mSimonConst <- onlySimonConst

The slow but generic upsertBy implementation for any PersistUniqueRead. * Lookup corresponding entities (if any) getBy. * If the record exists, update using updateGet. * If it does not exist, insert using insertEntity. @since 2.11

The slow but generic putMany implementation for any PersistUniqueRead. * Lookup corresponding entities (if any) for each record using getByValue * For pre-existing records, issue a replace for each old key and new record * For new records, issue a bulk insertMany_

This function returns a list of PersistValue that correspond to the Unique keys on that record. This is useful for comparing two records for equality only on the basis of their Unique keys.