Type-safe, multi-backend data serialization.

Version on this page:
LTS Haskell 22.11:
Stackage Nightly 2024-02-22:
Latest on Hackage:

See all snapshots persistent appears in

MIT licensed by Michael Snoyman
This version can be pinned in stack with:persistent-,4735


Type-safe, data serialization. You must use a specific backend in order to make this useful. For more information, see the chapter in the Yesod book.


Changelog for persistent

  • Fix a bug where an empty entity definition would break parsing of EntityDefs. #1176

  • Docs/Bugs fixes #1153
    • Fix documentation on FieldDef.fieldAttrs.
    • Postgresql backend: Add a space in cascade clause of generated SQL.

  • Foreign Key improvements #1121

    • It is now supported to refer to a table with an auto generated Primary Kay
    • It is now supported to refer to non-primary fields, using the keyword References
    • It is now supported to have cascade options for simple/single-field Foreign Keys
  • Introduces a breaking change to the internal function mkColumns, which can now be passed a record of functions to override its default behavior. #996

  • Added explicit forall notation to make most API functions play nice when using TypeApplications. (e.g. instead of selectList @_ @_ @User [] [], you can now write selectList @User [] []) #1006

  • #1060

    • The QuasiQuoter now supports OnDelete and OnUpdate cascade options.
  • #1044

    • Field and constraint labels generated by TH can now be customized.
    • mpsPrefixFields is deprecated in favor of using these customisation functions.
  • #1032

    • Instance for Natural is removed. See OverflowNatural for a replacement and rationale on why.
  • #1063

    • A new class member keyFromRecordM allows you to construct a Key record from a record if it was defined with Primary.
  • #1036

    • The method entityIdFromJSON that is used to parse entities now correctly works for entities that define a custom Primary key.
  • #856

    • Modify upsertBy to use backend-specific implementation (if any).
  • #1066

    • You can set a column’s sql=id for a non Id column.
  • Fix a bug where unsafe migration error messages were being shown using Show prior to printing, resulting in less helpful output. #1080

  • #1087

    • RawSql now has tuple instances up to GHC’s max tuple size (62)
  • #1076

    • Loc is now imported from monad-logger as opposed to template-haskell. Removes template-haskell as an explicit dependency.
  • #1114

    • Remove unnecessary deriving of Typeable.
  • #1128

    • Remove Monad constraint on entityDef
  • #1127

    • Remove deriving of Show for uniques. Users that need a Show instance can put a standalone deriving instance:

      deriving stock instance Show (Unique User)
  • #1131

    • Add an exists function to the PersistQueryRead type class.
  • #1117

    • Allow parsing UTCTimes from sqlite with the format “%F %T%Q” as well, instead of only “%FT%T%Q”.
  • #1140

    • A new function checkUniqueUpdateable allows you to check uniqueness constraints on an entity update without having to update it.
  • #1142

    • Deprecate hasCompositeKey in favor of hasCustomPrimaryKey and hasCompositePrimaryKey functions.
  • #1098

    • Add support for configuring the number of stripes and idle timeout for connection pools
      • For functions that do not specify an idle timeout, the default has been bumped to 600 seconds.
        • This change is based off the experience of two production codebases. See #775
      • Add a new type ConnectionPoolConfig to configure the number of connections in a pool, their idle timeout, and stripe size.
      • Add defaultConnectionPoolConfig to create a ConnectionPoolConfig
      • Add createSqlPoolWithConfig and withSqlPoolWithConfig, which take this new data type
  • #1122, #1152

    • Adds a new constructor, PersistLiteral ByteString to PersistValue to support unescaped SQL literals.

      • Obviously, this is highly unsafe, and you should never use it with user input.
    • Adds a new field, cGenerated :: Maybe Text to Column for backend-specific support of generated columns.

      • Express generated fields in the Persistent DSL
          fieldOne Text Maybe
          fieldTwo Text Maybe
          fieldThree Text Maybe generated=COALESCE(field_one,field_two)
      • Support for MySQL >= 5.7. (No version checking is performed! Using this feature with older versions of MySQL will cause runtime SQL exceptions!)
      • Support for Postgresql >= 12. (No version checking is performed! Using this feature with older versions of Postgresql will cause runtime SQL exceptions!)
      • Support for SQLite >= 3.31 (same caveat applies; support added in #1152 )
  • #1151

    • Allow OverloadedLabels to be used with the EntityField type.

  • #1041
    • Explicit foreign keys can now reference tables with custom sql name
    • Add qualified names to the stock classes list.

  • #1024
    • Add the ability to do documentation comments in entity definition syntax. Unfortunately, TemplateHaskell cannot add documentation comments, so this can’t be used to add Haddocks to entities.
    • Add Haddock explainers for some of the supported entity syntax in Database.Persist.Quasi


  • Add the EntityWithPrefix type to allow users to specify a custom prefix for raw SQL queries. #1018
  • Added Acquire based API to Database.Persist.Sql for working with connections/pools in monads which aren’t MonadUnliftIO. #984


  • Log exceptions when closing a connection fails. See point 1 in yesod #1635. #978


  • Added support for GHC 8.8 about MonadFail changes #976


  • Added runMigrationQuiet and runMigrationUnsafeQuiet to Database.Persist.Sql.Migration as safer alternatives to runMigrationSilent. #971 This functions as workaround/fix for: #966, #948, #640, and #474
  • Added RawSql instances for 9, 10, 11 and 12-column results. #961


  • Added constraint= attribute to allow users to specify foreign reference constraint names.


  • Added two type classes OnlyOneUniqueKey and AtLeastOneUniqueKey. These classes are used as constraints on functions that expect a certain amount of unique keys. They are defined automatically as part of the persistent-template’s generation. #885
  • Add the entityComments field to the EntityDef datatype, and fieldComments fields to the FieldDef datatype. The QuasiQuoter does not currently know how to add documentation comments to these types, but it can be expanded later. #865
  • Expose the SqlReadT and SqlWriteT constructors. #887
  • Remove deprecated Connection type synonym. Please use SqlBackend instead. #894
  • Remove deprecated SqlPersist type synonym. Please use SqlPersistT instead. #894
  • Alter the type of connUpsertSql to take a list of unique definitions. This paves the way for more efficient upsert implementations. #895


  • Add documentation for the Migration type and some helpers. #860


  • Fix #847: SQL error with putMany on Sqlite when Entity has no unique index.


  • Added support for SQL isolation levels to via SqlBackend. [#812]
  • Move Database.Persist.Sql.Raw.QQ to a separate persistent-qq package #827
  • Fix 832: repsertMany now matches mapM_ (uncurry repsert) and is atomic for supported sql back-ends.


  • Added support for sql= to the unique constraints quasi-quoter so that users can specify the database names of the constraints.


  • DRY-ed up and exposed several util functions in Database.Persist.Sql.Util.
    • Upstream-ed updatePersistValue, mkUpdateText, and commaSeparated from Database.Persist.MySQL.
    • De-duplicated updatePersistValue from various Database.Persist.Sql.Orphan.* modules.
  • Batching enhancements to reduce db round-trips.
    • Added getMany and repsertMany for batched get and repsert.
    • Added putMany with a default/slow implementation. SqlBackend’s that support native UPSERT should override this for batching enhancements.
    • Updated insertEntityMany to replace slow looped usage with batched execution.
  • See #770


  • Switch from MonadBaseControl to MonadUnliftIO
  • Reapplies #723, which was reverted in version 2.7.3.

  • Improve error messages when failing to parse database results into Persistent records. #741
  • A handful of fromPersistField implementations called error instead of returning a Left Text. All of the implementations were changed to return Left. #741
  • Improve error message when a SQL insert fails with a custom primary key #757


  • Reverts #723, which generalized functions using the BackendCompatible class. These changes were an accidental breaking change.
  • Recommend the PersistDbSpecific docs if someone gets an error about converting from PersistDbSpecific


  • Many of the functions have been generalized using the BackendCompatible class. #723
    • This change was an accidental breaking change and was reverted in 2.7.3.
    • These change will be released in a future version of Persistent with a major version bump.
  • Add raw sql quasi quoters #717


  • Added an insertUniqueEntity function #718
  • Added BackendCompatible class #701


  • Fix upsert behavior #613
  • Atomic upsert query fixed for arithmatic operations #662
  • Haddock and test coverage improved for upsert


  • Fix edge case for \<-. [Nothing]
  • Introduce connMaxParams
  • Add ‘getJustEntity’ and ‘insertRecord’ convenience function
  • Minor Haddock improvment


  • Add connUpsertSql type for providing backend-specific upsert sql support.


  • read/write typeclass split
  • add insertOrGet convenience function to PersistUnique

  • Documentation updates #515


  • Workaround for side-exiting transformers in runSqlConn #516


  • PersistField instance for Natural
  • better oracle support in odbc


  • Add liftSqlPersistMPool function
  • support http-api-data for url serialization


  • Migration failure message with context
  • Fix insertKey for composite keys


  • Add a RawSql instance for Key. This allows selecting primary keys using functions like rawSql. #407
  • SqlBackend support for an optimized insertMany


Important! If persistent-template is not upgraded to you might need to make sure Int64 is in scope for your model declarations.

  • add showMigration function
  • explicitly use Int64 for foreign key references


Add dbIdColumnsEsc to Sql.Utils. Used in persistent-postgresql


  • Fix getBy with a primary key. #342


  • Break self-referencing cycles in the entity declarations


  • Error with Doubles without a decimal part #378
  • runSqlPool does not perform timeout checks.

  • One extra feature for #939: use logDebugN instead

Parse UTCTime in 8601 format #339

Support for monad-control 1.0