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


-- | An implementation of relational database "migrations"
--   
@package dbmigrations
@version 0.9


-- | 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 :: Maybe UTCTime -> String -> Maybe String -> String -> Maybe String -> [String] -> Migration
mTimestamp :: Migration -> Maybe UTCTime
mId :: Migration -> String
mDesc :: Migration -> Maybe String
mApply :: Migration -> String
mRevert :: Migration -> Maybe String
mDeps :: Migration -> [String]
newMigration :: String -> Migration
instance Eq Migration
instance Show Migration
instance Ord Migration
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
--   "bootstrap" a backend so that it can track which migrations are
--   installed.
data Backend
Backend :: IO Migration -> IO Bool -> (Migration -> IO ()) -> (Migration -> IO ()) -> IO [String] -> IO () -> IO () -> IO () -> Backend

-- | The migration necessary to bootstrap a database with this connection
--   interface. This might differ slightly from one backend to another.
getBootstrapMigration :: Backend -> IO Migration

-- | Returns whether the backend has been bootstrapped. A backend has been
--   bootstrapped if is capable of tracking which migrations have been
--   installed; the "bootstrap migration" provided by getBootstrapMigration
--   should suffice to bootstrap the backend.
isBootstrapped :: Backend -> IO Bool

-- | Apply the specified migration on the backend. applyMigration does NOT
--   assume control of the transaction, since it expects the transaction to
--   (possibly) cover more than one applyMigration operation. The caller is
--   expected to call commit at the appropriate time. If the application
--   fails, the underlying SqlError is raised and a manual rollback may be
--   necessary; for this, see withTransaction from HDBC.
applyMigration :: Backend -> Migration -> IO ()

-- | Revert the specified migration from the backend and record this action
--   in the table which tracks installed migrations. revertMigration does
--   NOT assume control of the transaction, since it expects the
--   transaction to (possibly) cover more than one revertMigration
--   operation. The caller is expected to call commit at the appropriate
--   time. If the revert fails, the underlying SqlError is raised and a
--   manual rollback may be necessary; for this, see withTransaction from
--   HDBC. If the specified migration does not supply a revert instruction,
--   this has no effect other than bookkeeping.
revertMigration :: Backend -> Migration -> IO ()

-- | Returns a list of installed migration names from the backend.
getMigrations :: Backend -> IO [String]

-- | Commit changes to the backend.
commitBackend :: Backend -> IO ()

-- | Revert changes made to the backend since the current transaction
--   began.
rollbackBackend :: Backend -> IO ()

-- | Disconnect from the backend.
disconnectBackend :: Backend -> IO ()

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

-- | The type of migration storage facilities. A MigrationStore is a
--   facility in which new migrations can be created, and from which
--   existing migrations can be loaded.
data MigrationStore
MigrationStore :: (String -> IO (Either String Migration)) -> (Migration -> IO ()) -> IO [String] -> (String -> IO String) -> MigrationStore

-- | Load a migration from the store.
loadMigration :: MigrationStore -> String -> IO (Either String Migration)

-- | Save a migration to the store.
saveMigration :: MigrationStore -> Migration -> IO ()

-- | Return a list of all available migrations' names.
getMigrations :: MigrationStore -> IO [String]

-- | Return the full representation of a given migration name; mostly for
--   filesystem stores, where the full representation includes the store
--   path.
fullMigrationName :: MigrationStore -> String -> IO 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

-- | The specified migration is invalid.
InvalidMigration :: 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 -> IO (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 FilesystemStoreSettings
FSStore :: FilePath -> FilesystemStoreSettings
storePath :: FilesystemStoreSettings -> 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 :: FilesystemStoreSettings -> 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)
filesystemStore :: FilesystemStoreSettings -> MigrationStore
instance Typeable FilesystemStoreError
instance Show FilesystemStoreError
instance Exception FilesystemStoreError

module Database.Schema.Migrations.Backend.HDBC

-- | General Backend constructor for all HDBC connection implementations.
hdbcBackend :: IConnection conn => conn -> Backend


-- | 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>.
createNewMigration :: MigrationStore -> Migration -> IO (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 -> IO ()

-- | 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 :: StoreData -> Backend -> Migration -> IO [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 :: StoreData -> Backend -> Migration -> IO [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 -> StoreData -> IO [String]

module Moo.Core

-- | The monad in which the application runs.
type AppT a = ReaderT AppState IO a

-- | The type of actions that are invoked to handle specific commands
type CommandHandler = StoreData -> AppT ()

-- | Application state which can be accessed by any command handler.
data AppState
AppState :: CommandOptions -> Command -> [String] -> [String] -> MigrationStore -> DbConnDescriptor -> String -> StoreData -> AppState
_appOptions :: AppState -> CommandOptions
_appCommand :: AppState -> Command
_appRequiredArgs :: AppState -> [String]
_appOptionalArgs :: AppState -> [String]
_appStore :: AppState -> MigrationStore
_appDatabaseConnStr :: AppState -> DbConnDescriptor
_appDatabaseType :: AppState -> String
_appStoreData :: AppState -> StoreData
type ShellEnvironment = [(String, String)]
data Configuration
Configuration :: String -> String -> FilePath -> Configuration
_connectionString :: Configuration -> String
_databaseType :: Configuration -> String
_migrationStorePath :: Configuration -> FilePath
loadConfiguration :: Maybe FilePath -> IO (Either String Configuration)
fromShellEnvironment :: ShellEnvironment -> Maybe Configuration
fromConfigurator :: Config -> IO (Maybe Configuration)

-- | CommandOptions are those options that can be specified at the command
--   prompt to modify the behavior of a command.
data CommandOptions
CommandOptions :: Maybe String -> Bool -> Bool -> CommandOptions
_configFilePath :: CommandOptions -> Maybe String
_test :: CommandOptions -> Bool
_noAsk :: CommandOptions -> Bool

-- | A command has a name, a number of required arguments' labels, a number
--   of optional arguments' labels, and an action to invoke.
data Command
Command :: String -> [String] -> [String] -> [String] -> String -> CommandHandler -> Command
_cName :: Command -> String
_cRequired :: Command -> [String]
_cOptional :: Command -> [String]
_cAllowedOptions :: Command -> [String]
_cDescription :: Command -> String
_cHandler :: Command -> CommandHandler

-- | ConfigOptions are those options read from configuration file
data ConfigData
ConfigData :: String -> String -> String -> ConfigData
_dbTypeStr :: ConfigData -> String
_dbConnStr :: ConfigData -> String
_fileStorePath :: ConfigData -> String
newtype DbConnDescriptor
DbConnDescriptor :: String -> DbConnDescriptor

-- | The values of DBM_DATABASE_TYPE and their corresponding connection
--   factory functions.
databaseTypes :: [(String, String -> IO Backend)]
envDatabaseType :: String
envDatabaseName :: String
envStoreName :: String

module Moo.CommandUtils
apply :: Migration -> StoreData -> Backend -> Bool -> IO [Migration]
confirmCreation :: String -> [String] -> IO Bool
interactiveAskDeps :: StoreData -> IO [String]
lookupMigration :: StoreData -> String -> IO Migration
revert :: Migration -> StoreData -> Backend -> IO [Migration]
withBackend :: (Backend -> IO a) -> AppT a
makeBackend :: String -> DbConnDescriptor -> IO Backend
instance Eq AskDepsChoice

module Moo.CommandHandlers
newCommand :: CommandHandler
upgradeCommand :: CommandHandler
upgradeListCommand :: CommandHandler
reinstallCommand :: CommandHandler
listCommand :: CommandHandler
applyCommand :: CommandHandler
revertCommand :: CommandHandler
testCommand :: CommandHandler


-- | This module defines the MOO command interface, the commnad line
--   options parser, and helpers to manipulate the Command data structure.
module Moo.CommandInterface

-- | The available commands; used to dispatch from the command line and
--   used to generate usage output. |The available commands; used to
--   dispatch from the command line and used to generate usage output.
commands :: [Command]
commandOptionUsage :: String
findCommand :: String -> Maybe Command
getCommandArgs :: [String] -> IO (CommandOptions, [String])
usageString :: Command -> String

module Moo.Main
mainWithConf :: Args -> Configuration -> IO ()
data Configuration
Configuration :: String -> String -> FilePath -> Configuration
_connectionString :: Configuration -> String
_databaseType :: Configuration -> String
_migrationStorePath :: Configuration -> FilePath
type Args = [String]
usage :: IO a
usageSpecific :: Command -> IO a
procArgs :: Args -> IO (Command, CommandOptions, [String])