Database.Beam.Migrate.Simple

Utility functions for common use cases

Documentation

autoMigrate :: (Database be db, MonadFail m) => BeamMigrationBackend be m -> CheckedDatabaseSettings be db -> m ()

Given a BeamMigrationBackend, attempt to automatically bring the current database up-to-date with the given CheckedDatabaseSettings. Fails (via fail) if this involves an irreversible migration (one that may result in data loss).

simpleSchema :: Database be db => ActionProvider be -> CheckedDatabaseSettings be db -> Maybe [BeamSqlBackendSyntax be]

Attempt to find a SQL schema given an ActionProvider and a checked database. Returns Nothing if no schema could be found, which usually means you have chosen the wrong ActionProvider, or the backend you're using is buggy.

simpleMigration :: (MonadBeam be m, Database be db) => (forall a. handle -> m a -> IO a) -> BeamMigrationBackend be m -> handle -> CheckedDatabaseSettings be db -> IO (Maybe [BeamSqlBackendSyntax be])

Given a migration backend, a handle to a database, and a checked database, attempt to find a schema. This should always return Just, unless the backend has incomplete migrations support.

BeamMigrationBackends can usually be found in a module named Database.Beam.Backend.Migrate with the namemigrationBackend

runSimpleMigration :: MonadBeam be m => (forall a. hdl -> m a -> IO a) -> hdl -> [BeamSqlBackendSyntax be] -> IO ()

Run a sequence of commands on a database

backendMigrationScript :: BeamSqlBackend be => (BeamSqlBackendSyntax be -> String) -> Migration be a -> String

Given a function to convert a command to a String, produce a script that will execute the given migration. Usually, the function you provide eventually calls displaySyntax to rendere the command.

data VerificationResult

Result type for verifySchema

Constructors

VerificationSucceeded

VerificationFailed [SomeDatabasePredicate]

Instances

Show VerificationResult

Defined in Database.Beam.Migrate.Simple

Methods

showsPrec :: Int -> VerificationResult -> ShowS

show :: VerificationResult -> String

showList :: [VerificationResult] -> ShowS

verifySchema :: (Database be db, MonadBeam be m) => BeamMigrationBackend be m -> CheckedDatabaseSettings be db -> m VerificationResult

Verify that the given, beam database matches the actual schema. On success, returns VerificationSucceeded, on failure, returns VerificationFailed and a list of missing predicates.

newtype IgnorePredicates

Selects a class of predicates to ignore if detected (e.g. metadata tables for migrations, other schemas, etc.).

Constructors

IgnorePredicates

Fields

• unIgnorePredicates :: SomeDatabasePredicate -> Any

Instances

Semigroup IgnorePredicates

Defined in Database.Beam.Migrate.Simple

Methods

(<>) :: IgnorePredicates -> IgnorePredicates -> IgnorePredicates

sconcat :: NonEmpty IgnorePredicates -> IgnorePredicates

stimes :: Integral b => b -> IgnorePredicates -> IgnorePredicates

Monoid IgnorePredicates

Defined in Database.Beam.Migrate.Simple

Methods

mempty :: IgnorePredicates

mappend :: IgnorePredicates -> IgnorePredicates -> IgnorePredicates

mconcat :: [IgnorePredicates] -> IgnorePredicates

data CheckResult

Result type for checkSchema

Constructors

CheckResult

Fields

• missingPredicates :: HashSet SomeDatabasePredicate

  Expected predicates from the CheckedDatabaseSettings which were not found in the live database

• unexpectedPredicates :: HashSet SomeDatabasePredicate

  Predicates found in the live database which are not present in the CheckedDatabaseSettings and are not ignored

Instances

Eq CheckResult

Defined in Database.Beam.Migrate.Simple

Methods

(==) :: CheckResult -> CheckResult -> Bool

(/=) :: CheckResult -> CheckResult -> Bool

Show CheckResult

Defined in Database.Beam.Migrate.Simple

Methods

showsPrec :: Int -> CheckResult -> ShowS

show :: CheckResult -> String

showList :: [CheckResult] -> ShowS

ignoreTables :: (QualifiedName -> Bool) -> IgnorePredicates

Ignore predicates relating to tables matching the given name predicate.

ignoreAll :: IgnorePredicates

Ignore any unknown predicates. This probably only makes sense to use if you are only querying and not writing to the database.

checkSchema :: (Database be db, Monad m) => BeamMigrationBackend be m -> CheckedDatabaseSettings be db -> IgnorePredicates -> m CheckResult

Checks the given database settings against the live database. This is similar to verifySchema, but detects and returns unknown predicates that are true about the live database (e.g. unknown tables, fields, etc.).

createSchema :: (Database be db, MonadFail m) => BeamMigrationBackend be m -> CheckedDatabaseSettings be db -> m ()

Given a CheckedDatabaseSettings and a BeamMigrationBackend, attempt to create the schema from scratch in the current database.

May fail if we cannot find a schema

data BringUpToDateHooks m

Constructors

BringUpToDateHooks

Fields

• runIrreversibleHook :: m Bool

  Called before we're about to run an irreversible migration step. Return True to run the step, or False to abort immediately.

• startStepHook :: Int -> Text -> m ()

  Called at the beginning of each step with the step index and description

• endStepHook :: Int -> Text -> m ()

  Called at the end of each step with the step index and description

• runCommandHook :: Int -> String -> m ()

  Called before a command is about to run. The first argument is the step index and the second is a string representing the command about to be run.

• queryFailedHook :: m ()

  Called when a query fails

• discontinuousMigrationsHook :: Int -> m ()

  Called when the migration log has a discontinuity at the supplied index

• logMismatchHook :: Int -> Text -> Text -> m ()

  The migration log at the given index is not what was expected. The first text is the actual commit id, the second, the expected

• databaseAheadHook :: Int -> m ()

  The database is ahead of the given migrations. The parameter supplies the number of entries passed the given migrations the database has.

defaultUpToDateHooks :: MonadFail m => BringUpToDateHooks m

Default set of BringUpToDateHooks. Refuses to run irreversible migrations, and fails in case of error, using fail.

bringUpToDate :: (Database be db, MonadFail m, HasDataTypeCreatedCheck (BeamMigrateSqlBackendDataTypeSyntax be)) => BeamMigrationBackend be m -> MigrationSteps be () (CheckedDatabaseSettings be db) -> m (Maybe (CheckedDatabaseSettings be db))

Equivalent to calling bringUpToDateWithHooks with defaultUpToDateHooks.

Tries to bring the database up to date, using the database log and the given MigrationSteps. Fails if the migration is irreversible, or an error occurs.

bringUpToDateWithHooks :: forall db be m. (Database be db, MonadFail m, HasDataTypeCreatedCheck (BeamMigrateSqlBackendDataTypeSyntax be)) => BringUpToDateHooks m -> BeamMigrationBackend be m -> MigrationSteps be () (CheckedDatabaseSettings be db) -> m (Maybe (CheckedDatabaseSettings be db))

Check for the beam-migrate log. If it exists, use it and the supplied migrations to bring the database up-to-date. Otherwise, create the log and run all migrations.

Accepts a set of hooks that can be used to customize behavior. See the documentation for BringUpToDateHooks for more information. Calling this with defaultUpToDateHooks is the same as using bringUpToDate.

haskellSchema :: (MonadBeam be m, MonadFail m) => BeamMigrationBackend be m -> m String

Given a BeamMigrationBackend, get a string representing a Haskell module that would be a good starting point for further development.

For example, for a postgres database named chinook

import Database.Beam.Migrate.Simple
import Database.Beam.Postgres (runBeamPostgres)
import Database.Beam.Postgres.Migrate (migrationBackend)
import Database.PostgreSQL.Simple

getSchema :: IO String
getSchema = do pg <- connectPostgreSQL
               runBeamPostgres pg (haskellSchema migrationBackend)

Backends that have a migration backend typically export it under the module name Database.Beam.Backend.Migrate.

module Database.Beam.Migrate.Actions

module Database.Beam.Migrate.Types