Type-safe, non-relational, multi-backend persistence.

Version on this page:
LTS Haskell 22.17:
Stackage Nightly 2024-04-20:
Latest on Hackage:

See all snapshots persistent-template appears in

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

Module documentation for


Provides Template Haskell helpers for persistent. For more information, see the chapter in the Yesod book.

code organization

The TH.hs module contains code generators. persistent-template uses EntityDefs that it gets from the quasi-quoter. The quasi-quoter is in persistent Quasi.hs Similarly mant of the types come from the persistent library

Development tips

To get a better idea of what code you’re generating, you can output the content of Template Haskell expressions to a file:

stack test persistent-template --ghc-options='-ddump-splices -ddump-to-file'

The output will be in the .stack-work directory. The exact path will depend on your specific setup, but if you search for files ending in .dump-splices you’ll find the output (find .stack-work -type f -name '*.dump-splices')

If you make changes to the generated code, it is highly recommended to compare the output with your changes to output from master (even better if this diff is included in your PR!). Seemingly small changes can have dramatic changes on the generated code.

For example, embedding an EntityDef in a function that was called for every field of that Entity made the number of generated lines O(N^2) for that function—very bad!


Unreleased changes

  • Require extensions in a more friendly manner. #1030
  • Specify a strategy for all deriving clauses, which avoids the -Wmissing-deriving-strategy warning introduced in GHC 8.8.2. #1030

  • Fix the mkPersist function to not require importing the classes explicitly. #1027

  • Fix the test-suite for persistent-template. #1023


  • Add fieldError to the export list of Database.Persist.TH #1008


  • Small optimization/code cleanup to generated Template Haskell code size, by slimming the implementation of to/fromPersistValue for Entities. #1014


  • Reduces the amount of code generated by Template Haskell. The amount of code generated for a certain function was O(N^2) with respect to the number of fields on a given Entity. This change shows dramatic improvements in benchmarks for compiling Persistent models. #
  • Drops support for GHC 8.0, so that DerivingStrategies can be used by persistent-template
  • persistent-template now requires DerivingStrategies, GeneralizedNewtypeDeriving, and StandaloneDeriving to be enabled in the file where Persistent entities are created
  • Fixes a long-standing issue where persistent-template would fail when DeriveAnyClass was enabled (See #578)
  • #1002


  • Remove an overlapping instance for Lift a. #998


  • Update module documentation for Database.Persist.TH to better describe the purpose of the module #968
  • Support template-haskell-2.15 #959


  • Expose the knot tying logic of parseReferences so that users can build migrations from independently define entities at runtime #932


  • Add the mkEntityDefList function to work around #902. #904


  • Depends on persistent-2.10.0 which provides the OnlyOneUniqueKey and AtLeastOneUniqueKey classes. Automatically generates instances for these classes based on how many unique keys the entity definition gets. This changes requires UndecidableInstances to be enabled on each module that generates entity definitions. #885
  • Removed deprecated sqlOnlySettings. Please use sqlSettings instead. #894



  • Slight improvement to the error message when a Persistent field can’t be parsed from database results


  • Exposed parseReferences to allow custom QuasiQuoters


  • Fix incorrect ToJSON/FromJSON instance generation for generic backends

Allow non-null self-references in a list

  • Allow composite Primary keys for tables that contain nullable fields.
  • Support foreign keys to non-integer ids

  • fix GHC 7.8 bug when a field name is “type”

  • fix a bad Eq instance /= definition for Key when mpsGenetric=True

  • workaround TH bug in GHC 7.10


  • read/write typeclass split


  • aeson 0.11
  • transformers 0.5


support http-api-data for url serialization

By default explicitly use Int64 for foreign key references. This avoids confusion on a 32 bit system.

Support foreign key references to composite primary keys

Support for monad-control 1.0