Safe Haskell	Safe-Inferred
Language	Haskell2010

Database.Beam.Migrate.Simple

Description

Utility functions for common use cases

Synopsis

autoMigrate :: (Database be db, MonadFail m) => BeamMigrationBackend be m -> CheckedDatabaseSettings be db -> m ()
simpleSchema :: Database be db => ActionProvider be -> CheckedDatabaseSettings be db -> Maybe [BeamSqlBackendSyntax be]
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])
runSimpleMigration :: MonadBeam be m => (forall a. hdl -> m a -> IO a) -> hdl -> [BeamSqlBackendSyntax be] -> IO ()
backendMigrationScript :: BeamSqlBackend be => (BeamSqlBackendSyntax be -> String) -> Migration be a -> String
data VerificationResult
- = VerificationSucceeded
- | VerificationFailed [SomeDatabasePredicate]
verifySchema :: (Database be db, MonadBeam be m) => BeamMigrationBackend be m -> CheckedDatabaseSettings be db -> m VerificationResult
newtype IgnorePredicates = IgnorePredicates {
- unIgnorePredicates :: SomeDatabasePredicate -> Any
}
data CheckResult = CheckResult {
- missingPredicates :: HashSet SomeDatabasePredicate
- unexpectedPredicates :: HashSet SomeDatabasePredicate
}
ignoreTables :: (QualifiedName -> Bool) -> IgnorePredicates
ignoreAll :: IgnorePredicates
checkSchema :: (Database be db, Monad m) => BeamMigrationBackend be m -> CheckedDatabaseSettings be db -> IgnorePredicates -> m CheckResult
createSchema :: (Database be db, MonadFail m) => BeamMigrationBackend be m -> CheckedDatabaseSettings be db -> m ()
data BringUpToDateHooks m = BringUpToDateHooks {
- runIrreversibleHook :: m Bool
- startStepHook :: Int -> Text -> m ()
- endStepHook :: Int -> Text -> m ()
- runCommandHook :: Int -> String -> m ()
- queryFailedHook :: m ()
- discontinuousMigrationsHook :: Int -> m ()
- logMismatchHook :: Int -> Text -> Text -> m ()
- databaseAheadHook :: Int -> m ()
}
defaultUpToDateHooks :: MonadFail m => BringUpToDateHooks m
bringUpToDate :: (Database be db, MonadFail m, HasDataTypeCreatedCheck (BeamMigrateSqlBackendDataTypeSyntax be)) => BeamMigrationBackend be m -> MigrationSteps be () (CheckedDatabaseSettings be db) -> m (Maybe (CheckedDatabaseSettings be db))
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))
haskellSchema :: (MonadBeam be m, MonadFail m) => BeamMigrationBackend be m -> m String
module Database.Beam.Migrate.Actions
module Database.Beam.Migrate.Types

Documentation

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

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] Source #

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]) Source #

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 () Source #

Run a sequence of commands on a database

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

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 Source #

Result type for verifySchema

Constructors

VerificationSucceeded
VerificationFailed [SomeDatabasePredicate]

Instances

Instances details

Show VerificationResult Source #
Instance details 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 Source #

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 Source #

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

Instances details

Monoid IgnorePredicates Source #
Instance details Defined in Database.Beam.Migrate.Simple Methods mempty :: IgnorePredicates # mappend :: IgnorePredicates -> IgnorePredicates -> IgnorePredicates # mconcat :: [IgnorePredicates] -> IgnorePredicates #
Semigroup IgnorePredicates Source #
Instance details Defined in Database.Beam.Migrate.Simple Methods (<>) :: IgnorePredicates -> IgnorePredicates -> IgnorePredicates # sconcat :: NonEmpty IgnorePredicates -> IgnorePredicates # stimes :: Integral b => b -> IgnorePredicates -> IgnorePredicates #

data CheckResult Source #

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

Instances details

Show CheckResult Source #
Instance details Defined in Database.Beam.Migrate.Simple Methods showsPrec :: Int -> CheckResult -> ShowS # show :: CheckResult -> String # showList :: [CheckResult] -> ShowS #
Eq CheckResult Source #
Instance details Defined in Database.Beam.Migrate.Simple Methods (==) :: CheckResult -> CheckResult -> Bool # (/=) :: CheckResult -> CheckResult -> Bool #

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

Ignore predicates relating to tables matching the given name predicate.

ignoreAll :: IgnorePredicates Source #

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 Source #

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 () Source #

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 Source #

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 Source #

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)) Source #

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)) Source #

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 Source #

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