-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | An implementation of relational database "migrations"
--   
--   A library and program for the creation, management, and installation
--   of schema updates (called <i>migrations</i>) for a relational
--   database. In particular, this package lets the migration author
--   express explicit dependencies between migrations and the management
--   tool automatically installs or reverts migrations accordingly, using
--   transactions for safety. This package is written to support any
--   HDBC-supported database, although at present only PostgreSQL is fully
--   supported. To get started, see the included <a>README</a> and
--   <a>MOO.TXT</a> files and the usage output for the <a>moo</a> command.
@package dbmigrations
@version 0.8


-- | This module types and functions for representing a dependency graph of
--   arbitrary objects and functions for querying such graphs to get
--   dependency and reverse dependency information.
module Database.Schema.Migrations.Dependencies

-- | <a>Dependable</a> objects supply a representation of their
--   identifiers, and a list of other objects upon which they depend.
class (Eq a, Ord a) => Dependable a
depsOf :: Dependable a => a -> [String]
depId :: Dependable a => a -> String

-- | A <a>DependencyGraph</a> represents a collection of objects together
--   with a graph of their dependency relationships. This is intended to be
--   used with instances of <a>Dependable</a>.
data DependencyGraph a
DG :: [(a, Int)] -> [(String, Int)] -> Gr String String -> DependencyGraph a

-- | A mapping of <a>Dependable</a> objects to their graph vertex indices.
depGraphObjectMap :: DependencyGraph a -> [(a, Int)]

-- | A mapping of <a>Dependable</a> object identifiers to their graph
--   vertex indices.
depGraphNameMap :: DependencyGraph a -> [(String, Int)]

-- | A directed <a>Gr</a> (graph) of the <a>Dependable</a> objects'
--   dependency relationships, with <a>String</a> vertex and edge labels.
depGraph :: DependencyGraph a -> Gr String String

-- | Build a dependency graph from a list of <a>Dependable</a>s. Return the
--   graph on success or return an error message if the graph cannot be
--   constructed (e.g., if the graph contains a cycle).
mkDepGraph :: Dependable a => [a] -> Either String (DependencyGraph a)

-- | Given a dependency graph and an ID, return the IDs of objects that the
--   object depends on. IDs are returned with least direct dependencies
--   first (i.e., the apply order).
dependencies :: Dependable d => DependencyGraph d -> String -> [String]

-- | Given a dependency graph and an ID, return the IDs of objects that
--   depend on it. IDs are returned with least direct reverse dependencies
--   first (i.e., the revert order).
reverseDependencies :: Dependable d => DependencyGraph d -> String -> [String]
instance Show a => Show (DependencyGraph a)
instance Eq a => Eq (DependencyGraph a)

module Database.Schema.Migrations.Migration
data Migration
Migration :: UTCTime -> String -> Maybe String -> String -> Maybe String -> [String] -> Migration
mTimestamp :: Migration -> UTCTime
mId :: Migration -> String
mDesc :: Migration -> Maybe String
mApply :: Migration -> String
mRevert :: Migration -> Maybe String
mDeps :: Migration -> [String]
class Monad m => MonadMigration m
getCurrentTime :: MonadMigration m => m UTCTime
newMigration :: MonadMigration m => String -> m Migration
instance Eq Migration
instance Show Migration
instance Ord Migration
instance MonadMigration IO
instance Dependable Migration

module Database.Schema.Migrations.Backend

-- | A Backend represents a database engine backend such as MySQL or
--   SQLite. A Backend supplies relatively low-level functions for
--   inspecting the backend's state, applying migrations, and reverting
--   migrations. A Backend also supplies the migration necessary to
--   <a>bootstrap</a> a backend so that it can track which migrations are
--   installed.
class Monad m => Backend b m
getBootstrapMigration :: Backend b m => b -> m Migration
isBootstrapped :: Backend b m => b -> m Bool
applyMigration :: Backend b m => b -> Migration -> m ()
revertMigration :: Backend b m => b -> Migration -> m ()
getMigrations :: Backend b m => b -> m [String]

-- | Backend instances should use this as the name of the migration
--   returned by getBootstrapMigration; this migration is special because
--   it cannot be reverted.
rootMigrationName :: String


-- | This module provides an abstraction for a <i>migration store</i>, a
--   facility in which <a>Migration</a>s can be stored and from which they
--   can be loaded. This module also provides functions for taking
--   <a>Migration</a>s from a store and converting them into the
--   appropriate intermediate types for use with the rest of this library.
module Database.Schema.Migrations.Store

-- | A type class for types which represent a storage facility (and a monad
--   context in which to operate on the store). A MigrationStore is a
--   facility in which new migrations can be created, and from which
--   existing migrations can be loaded.
class Monad m => MigrationStore s m where fullMigrationName _ name = return name
loadMigration :: MigrationStore s m => s -> String -> m (Maybe Migration)
saveMigration :: MigrationStore s m => s -> Migration -> m ()
getMigrations :: MigrationStore s m => s -> m [String]
fullMigrationName :: MigrationStore s m => s -> String -> m String

-- | A type for types of validation errors for migration maps.
data MapValidationError

-- | A migration claims a dependency on a migration that does not exist.
DependencyReferenceError :: String -> String -> MapValidationError

-- | An error was encountered when constructing the dependency graph for
--   this store.
DependencyGraphError :: String -> MapValidationError
data StoreData
StoreData :: MigrationMap -> DependencyGraph Migration -> StoreData
storeDataMapping :: StoreData -> MigrationMap
storeDataGraph :: StoreData -> DependencyGraph Migration

-- | A mapping from migration name to <a>Migration</a>. This is exported
--   for testing purposes, but you'll want to interface with this through
--   the encapsulating <a>StoreData</a> type.
type MigrationMap = Map String Migration

-- | Load migrations from the specified <a>MigrationStore</a>, validate the
--   loaded migrations, and return errors or a <a>MigrationMap</a> on
--   success. Generally speaking, this will be the first thing you should
--   call once you have constructed a <a>MigrationStore</a>.
loadMigrations :: MigrationStore s m => s -> m (Either [MapValidationError] StoreData)

-- | A convenience function for extracting the list of <a>Migration</a>s
--   extant in the specified <a>StoreData</a>.
storeMigrations :: StoreData -> [Migration]

-- | A convenience function for looking up a <a>Migration</a> by name in
--   the specified <a>StoreData</a>.
storeLookup :: StoreData -> String -> Maybe Migration

-- | Create a <a>DependencyGraph</a> from a <a>MigrationMap</a>; returns
--   Left if the dependency graph cannot be constructed (e.g., due to a
--   dependency cycle) or Right on success. Generally speaking, you won't
--   want to use this directly; use <a>loadMigrations</a> instead.
depGraphFromMapping :: MigrationMap -> Either String (DependencyGraph Migration)

-- | Validate a migration map. Returns zero or more validation errors.
validateMigrationMap :: MigrationMap -> [MapValidationError]

-- | Validate a single migration. Looks up the migration's dependencies in
--   the specified <a>MigrationMap</a> and returns a
--   <a>MapValidationError</a> for each one that does not exist in the map.
validateSingleMigration :: MigrationMap -> Migration -> [MapValidationError]
instance Eq MapValidationError
instance Show MapValidationError


-- | This module provides a type for interacting with a filesystem-backed
--   <a>MigrationStore</a>.
module Database.Schema.Migrations.Filesystem
data FilesystemStore
FSStore :: FilePath -> FilesystemStore
storePath :: FilesystemStore -> FilePath

-- | Given a store and migration name, read and parse the associated
--   migration and return the migration if successful. Otherwise return a
--   parsing error message.
migrationFromFile :: FilesystemStore -> String -> IO (Either String Migration)

-- | Given a filesystem path, read and parse the file as a migration return
--   the <a>Migration</a> if successful. Otherwise return a parsing error
--   message.
migrationFromPath :: FilePath -> IO (Either String Migration)
instance Typeable FilesystemStoreError
instance Show FilesystemStoreError
instance MonadIO m => MigrationStore FilesystemStore m
instance Exception FilesystemStoreError

module Database.Schema.Migrations.Backend.HDBC
instance IConnection conn => Backend conn IO


-- | This module provides a high-level interface for the rest of this
--   library.
module Database.Schema.Migrations

-- | Create a new migration and store it in the <a>MigrationStore</a>, with
--   some of its fields initially set to defaults.
createNewMigration :: (MonadMigration m, MigrationStore s m) => s -> String -> [String] -> m (Either String Migration)

-- | Given a <a>Backend</a>, ensure that the backend is ready for use by
--   bootstrapping it. This entails installing the appropriate database
--   elements to track installed migrations. If the backend is already
--   bootstrapped, this has no effect.
ensureBootstrappedBackend :: Backend b m => b -> m ()

-- | Given a migration mapping computed from a MigrationStore, a backend,
--   and a migration to apply, return a list of migrations to apply, in
--   order.
migrationsToApply :: Backend b m => StoreData -> b -> Migration -> m [Migration]

-- | Given a migration mapping computed from a MigrationStore, a backend,
--   and a migration to revert, return a list of migrations to revert, in
--   order.
migrationsToRevert :: Backend b m => StoreData -> b -> Migration -> m [Migration]

-- | Given a <a>Backend</a> and a <a>MigrationMap</a>, query the backend
--   and return a list of migration names which are available in the
--   <a>MigrationMap</a> but which are not installed in the <a>Backend</a>.
missingMigrations :: Backend b m => b -> StoreData -> m [String]