:: a typeCtrl KGHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27
Modulepersistent-2.14.6.3Haskell2010
This module documents tools and utilities for running SQL migrations.
A Migration is a four level monad stack consisting of:
WriterT [Text] representing a log of errors in the migrations.
WriterT CautiousMigration representing a list of migrations to
run, along with whether or not they are safe.
ReaderT SqlBackend, aka the SqlPersistT transformer for
database interop.
IO for arbitrary IO.
Given a Migration, this parses it and returns either a list of errors associated with the migration or a list of migrations to do.
Like parseMigration, but instead of returning the value in an Either value, it calls error on the error values.
Prints a migration.
Runs a migration. If the migration fails to parse or if any of the migrations are unsafe, then this throws a PersistUnsafeMigrationException.
Same as runMigration, but does not report the individual migrations on stderr. Instead it returns a list of the executed SQL commands.
This is a safer/more robust alternative to runMigrationSilent, but may be less silent for some persistent implementations, most notably persistent-postgresql
Same as runMigration, but returns a list of the SQL commands executed instead of printing them to stderr.
This function silences the migration by remapping stderr. As a result, it is not thread-safe and can clobber output from other parts of the program. This implementation method was chosen to also silence postgresql migration output on stderr, but is not recommended!
Like runMigration, but this will perform the unsafe database migrations instead of erroring out.
Same as runMigrationUnsafe, but returns a list of the SQL commands executed instead of printing them to stderr.
While migrate is capable of creating a Migration for you, it's not the only way you can write migrations. You can use these utilities to write extra steps in your migrations.
As an example, let's say we want to enable the citext extension on
postgres as part of our migrations.
share [mkPersist sqlSettings, Database.Persist.TH.mkMigration "migrateAll"] ...
migration :: Migration
migration = do
runSqlCommand $
rawExecute_ "CREATE EXTENSION IF NOT EXISTS "citext";"
migrateAll
For raw commands, you can also just write addMigration:
migration :: Migration
migration = do
addMigration "CREATE EXTENSION IF NOT EXISTS "citext";"
migrateAll
Report multiple errors in a Migration.
Report a single error in a Migration.
Add a CautiousMigration (aka a [(Bool, Text)]) to the
migration plan.
addMigration Add a migration to the migration plan.
Run an action against the database during a migration. Can be useful for eg creating Postgres extensions:
runSqlCommand $ rawExecute "CREATE EXTENSION IF NOT EXISTS "uuid-ossp";" []
An exception indicating that Persistent refused to run some unsafe migrations. Contains a list of pairs where the Bool tracks whether the migration was unsafe (True means unsafe), and the Sql is the sql statement for the migration.
Show PersistUnsafeMigrationExceptionDefined in persistent-2.14.6.3 · Database.Persist.Sql.MigrationThis Show instance renders an error message suitable for printing to the console. This is a little dodgy, but since GHC uses Show instances when displaying uncaught exceptions, we have little choice.
Exception PersistUnsafeMigrationExceptionDefined in persistent-2.14.6.3 · Database.Persist.Sql.Migration