persistent-2.14.6.3: Type-safe, multi-backend data serialization.

Safe Haskell | None
Language | Haskell2010

Database.Persist.Sql.Migration

Contents

- Types
- Using a `Migration`
- Utilities for constructing migrations
- If something goes wrong...

Description

This module documents tools and utilities for running SQL migrations.

A `Migration` is (currently) an alias for a `WriterT` of

Synopsis

- type Migration = WriterT [Text] (WriterT CautiousMigration (ReaderT SqlBackend IO)) ()
- type CautiousMigration = [(Bool, Sql)]
- type Sql = Text
- showMigration :: forall (m :: Type -> Type). (HasCallStack, MonadIO m) => Migration -> ReaderT SqlBackend m [Text]
- parseMigration :: forall (m :: Type -> Type). (HasCallStack, MonadIO m) => Migration -> ReaderT SqlBackend m (Either [Text] CautiousMigration)
- parseMigration' :: forall (m :: Type -> Type). (HasCallStack, MonadIO m) => Migration -> ReaderT SqlBackend m CautiousMigration
- printMigration :: forall (m :: Type -> Type). (HasCallStack, MonadIO m) => Migration -> ReaderT SqlBackend m ()
- getMigration :: forall (m :: Type -> Type). (MonadIO m, HasCallStack) => Migration -> ReaderT SqlBackend m [Sql]
- runMigration :: forall (m :: Type -> Type). MonadIO m => Migration -> ReaderT SqlBackend m ()
- runMigrationQuiet :: forall (m :: Type -> Type). MonadIO m => Migration -> ReaderT SqlBackend m [Text]
- runMigrationSilent :: forall (m :: Type -> Type). MonadUnliftIO m => Migration -> ReaderT SqlBackend m [Text]
- runMigrationUnsafe :: forall (m :: Type -> Type). MonadIO m => Migration -> ReaderT SqlBackend m ()
- runMigrationUnsafeQuiet :: forall (m :: Type -> Type). (HasCallStack, MonadIO m) => Migration -> ReaderT SqlBackend m [Text]
- migrate :: [EntityDef] -> EntityDef -> Migration
- reportErrors :: [Text] -> Migration
- reportError :: Text -> Migration
- addMigrations :: CautiousMigration -> Migration
- addMigration :: Bool -> Sql -> Migration
- runSqlCommand :: SqlPersistT IO () -> Migration
- newtype PersistUnsafeMigrationException = PersistUnsafeMigrationException [(Bool, Sql)]

# Types

type Migration = WriterT [Text] (WriterT CautiousMigration (ReaderT SqlBackend IO)) () #

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.

type CautiousMigration = [(Bool, Sql)] #

A list of SQL operations, marked with a safety flag. If the `Bool` is `True`, then the operation is *unsafe* - it might be destructive, or otherwise not idempotent. If the `Bool` is `False`, then the operation is *safe*, and can be run repeatedly without issues.

type Sql = Text #

# Using a `Migration`

showMigration :: forall (m :: Type -> Type). (HasCallStack, MonadIO m) => Migration -> ReaderT SqlBackend m [Text] #

Convert a `Migration` to a list of `Text` values corresponding to their `Sql` statements.

parseMigration :: forall (m :: Type -> Type). (HasCallStack, MonadIO m) => Migration -> ReaderT SqlBackend m (Either [Text] CautiousMigration) #

Given a `Migration`, this parses it and returns either a list of errors associated with the migration or a list of migrations to do.

parseMigration' :: forall (m :: Type -> Type). (HasCallStack, MonadIO m) => Migration -> ReaderT SqlBackend m CautiousMigration #

Like `parseMigration`, but instead of returning the value in an `Either` value, it calls `error` on the error values.

printMigration :: forall (m :: Type -> Type). (HasCallStack, MonadIO m) => Migration -> ReaderT SqlBackend m () #

Prints a migration.

getMigration :: forall (m :: Type -> Type). (MonadIO m, HasCallStack) => Migration -> ReaderT SqlBackend m [Sql] #

Return all of the `Sql` values associated with the given migration. Calls `error` if there's a parse error on any migration.

runMigration :: forall (m :: Type -> Type). MonadIO m => Migration -> ReaderT SqlBackend m () #

Runs a migration. If the migration fails to parse or if any of the migrations are unsafe, then this throws a `PersistUnsafeMigrationException`.

runMigrationQuiet :: forall (m :: Type -> Type). MonadIO m => Migration -> ReaderT SqlBackend m [Text] #

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

Since: 2.10.2

runMigrationSilent :: forall (m :: Type -> Type). MonadUnliftIO m => Migration -> ReaderT SqlBackend m [Text] #

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!

runMigrationUnsafe :: forall (m :: Type -> Type). MonadIO m => Migration -> ReaderT SqlBackend m () #

Like `runMigration`, but this will perform the unsafe database migrations instead of erroring out.

runMigrationUnsafeQuiet :: forall (m :: Type -> Type). (HasCallStack, MonadIO m) => Migration -> ReaderT SqlBackend m [Text] #

Same as `runMigrationUnsafe`, but returns a list of the SQL commands executed instead of printing them to stderr.

Since: 2.10.2

migrate :: [EntityDef] -> EntityDef -> Migration #

Given a list of old entity definitions and a new `EntityDef` in `val`, this creates a `Migration` to update the old list of definitions with the new one.

# Utilities for constructing migrations

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, 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

reportErrors :: [Text] -> Migration #

Report multiple errors in a `Migration`.

Since: 2.9.2

reportError :: Text -> Migration #

Report a single error in a `Migration`.

Since: 2.9.2

addMigrations :: CautiousMigration -> Migration #

Add a `CautiousMigration` (aka a `[(`Bool`, `Text`)]`) to the migration plan.

Since: 2.9.2

addMigration #

Arguments

:: Bool | Is the migration unsafe to run? (eg a destructive or non-idempotent update on the schema). If `True`, the migration is *unsafe*, and will need to be run manually later. If `False`, the migration is *safe*, and can be run any number of times.
-> Sql | A `Text` value representing the command to run on the database.
-> Migration |

Add a migration to the migration plan.

Since: 2.9.2

runSqlCommand :: SqlPersistT IO () -> Migration #

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";" []

Since: 2.13.0.0

# If something goes wrong...

newtype PersistUnsafeMigrationException #

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.

Since: 2.11.1.0

Constructors

PersistUnsafeMigrationException [(Bool, Sql)] |

#### Instances

Instances details

Exception PersistUnsafeMigrationException # |
Instance details Defined in Database.Persist.Sql.Migration Methods toException :: PersistUnsafeMigrationException -> SomeException # fromException :: SomeException -> Maybe PersistUnsafeMigrationException # displayException :: PersistUnsafeMigrationException -> String # backtraceDesired :: PersistUnsafeMigrationException -> Bool #
Show PersistUnsafeMigrationException # | This `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.
Instance details Defined in Database.Persist.Sql.Migration Methods showsPrec :: Int -> PersistUnsafeMigrationException -> ShowS # show :: PersistUnsafeMigrationException -> String # showList :: [PersistUnsafeMigrationException] -> ShowS #