beam-migrate-0.5.0.0: SQL DDL support and migrations support library for Beam

Safe HaskellNone
LanguageHaskell2010

Database.Beam.Migrate.Simple

Description

Utility functions for common use cases

Synopsis

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.

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.).

data CheckResult Source #

Result type for checkSchema

Constructors

CheckResult 

Fields

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.