insert package:persistent

Create a new record in the database, returning an automatically created key (in SQL an auto-increment id).

Example usage

Using schema-1 and dataset-1, let's insert a new user John.

insertJohn :: MonadIO m => ReaderT SqlBackend m (Key User)
insertJohn = insert $ User "John" 30

johnId <- insertJohn

The above query when applied on dataset-1, will produce this:

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

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

With schema-2 and dataset-1, we have following lines of code:

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

First three lines return Left because there're duplicates in given record's uniqueness constraints. While the last line returns a new key as Right.

Like insert, but returns the complete Entity.

Example usage

With schema-1 and dataset-1,

insertHaskellEntity :: MonadIO m => ReaderT SqlBackend m (Entity User)
insertHaskellEntity = insertEntity $ User "Haskell" 81

haskellEnt <- insertHaskellEntity

The above query when applied on dataset-1, will produce this:

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

Same as insertMany_, but takes an Entity instead of just a record. Useful when migrating data from one entity to another and want to preserve ids. The MongoDB, PostgreSQL, SQLite and MySQL backends insert all records in one database query.

Example usage

With schema-1 and dataset-1,

insertUserEntityMany :: MonadIO m => ReaderT SqlBackend m ()
insertUserEntityMany = insertEntityMany [SnakeEntity, EvaEntity]

The above query when applied on dataset-1, will produce this:

+-----+------+-----+
|id   |name  |age  |
+-----+------+-----+
|1    |SPJ   |40   |
+-----+------+-----+
|2    |Simon |41   |
+-----+------+-----+
|3    |Snake |38   |
+-----+------+-----+
|4    |Eva   |38   |
+-----+------+-----+

Create a new record in the database using the given key.

Example usage

With schema-1 and dataset-1,

insertAliceKey :: MonadIO m => Key User -> ReaderT SqlBackend m ()
insertAliceKey key = insertKey key $ User "Alice" 20

insertAliceKey $ UserKey {unUserKey = SqlBackendKey {unSqlBackendKey = 3}}

The above query when applied on dataset-1, will produce this:

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

Create multiple records in the database and return their Keys. If you don't need the inserted Keys, use insertMany_. The MongoDB and PostgreSQL backends insert all records and retrieve their keys in one database query. The SQLite and MySQL backends use the slow, default implementation of mapM insert.

Example usage

with schema-1 and dataset-1,

insertUsers :: MonadIO m => ReaderT SqlBackend m [Key User]
insertUsers = insertMany [User "John" 30, User "Nick" 32, User "Jane" 20]

userIds <- insertUsers

The above query when applied on dataset-1, will produce this:

+-----+------+-----+
|id   |name  |age  |
+-----+------+-----+
|1    |SPJ   |40   |
+-----+------+-----+
|2    |Simon |41   |
+-----+------+-----+
|3    |John  |30   |
+-----+------+-----+
|4    |Nick  |32   |
+-----+------+-----+
|5    |Jane  |20   |
+-----+------+-----+

Same as insertMany, but doesn't return any Keys. The MongoDB, PostgreSQL, SQLite and MySQL backends insert all records in one database query.

Example usage

With schema-1 and dataset-1,

insertUsers_ :: MonadIO m => ReaderT SqlBackend m ()
insertUsers_ = insertMany_ [User "John" 30, User "Nick" 32, User "Jane" 20]

The above query when applied on dataset-1, will produce this:

+-----+------+-----+
|id   |name  |age  |
+-----+------+-----+
|1    |SPJ   |40   |
+-----+------+-----+
|2    |Simon |41   |
+-----+------+-----+
|3    |John  |30   |
+-----+------+-----+
|4    |Nick  |32   |
+-----+------+-----+
|5    |Jane  |20   |
+-----+------+-----+

Like insertEntity but just returns the record instead of Entity.

Example usage

With schema-1 and dataset-1,

insertDaveRecord :: MonadIO m => ReaderT SqlBackend m User
insertDaveRecord = insertRecord $ User "Dave" 50

dave <- insertDaveRecord

The above query when applied on dataset-1, will produce this:

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

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

Example usage

With schema-1 and dataset-1, we try to insert the following two records:

linusId <- insertUnique $ User "Linus" 48
spjId   <- insertUnique $ User "SPJ" 90

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

Linus's record was inserted to dataset-1, while SPJ wasn't because SPJ already exists in dataset-1.

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

Example usage

We use schema-2 and dataset-1 here.

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

mSpjEnt <- insertUniqueSpjEntity

The above query results Nothing as SPJ already exists.

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

mAlexaEnt <- insertUniqueSpjEntity

Because there's no such unique keywords of the given record, the above query when applied on dataset-1, will produce this:

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

Same as insertUnique but doesn't return a Key.

Example usage

With schema-1 and dataset-1, we try to insert the following two records:

linusId <- insertUnique_ $ User "Linus" 48
spjId   <- insertUnique_ $ User "SPJ" 90

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

Linus's record was inserted to dataset-1, while SPJ wasn't because SPJ already exists in dataset-1.

Same as insert, but doesn't return a Key.

Example usage

with schema-1 and dataset-1,

insertJohn :: MonadIO m => ReaderT SqlBackend m (Key User)
insertJohn = insert_ $ User "John" 30

The above query when applied on dataset-1, will produce this:

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

A type class which is used to witness that a type is safe to insert into the database without providing a primary key. The TemplateHaskell function mkPersist will generate instances of this class for any entity that it works on. If the entity has a default primary key, then it provides a regular instance. If the entity has a Primary natural key, then this works fine. But if the entity has an Id column with no default=, then this does a TypeError and forces the user to use insertKey.

SQL for inserting many rows and returning their primary keys, for backends that support this functionality. If Nothing, rows will be inserted one-at-a-time using connInsertSql.

This function generates the SQL and values necessary for performing an insert against the database.

Returns a list of escaped field names and "?" placeholder values for performing inserts. This does not include generated columns. Does not include generated columns.

Make a list PersistValue suitable for database inserts. Pairs nicely with the function mkInsertPlaceholders. Does not include generated columns.

This function generates the SQL and values necessary for performing an insert against the database.

Set the connInsertManySql field on the SqlBackend. This should only be used by the database backend library to provide an efficient implementation of a bulk insert function. If this is not set, a slow default will be used.

Put a new statement into the cache. An immediate lookup of the statement MUST return the inserted statement for the given cache key. Depending on the implementation, the statement cache MAY choose to evict other statements from the cache within this function.