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


-- | Tools for maintaining a database
--   
--   Tools for maintaining a database
@package refurb
@version 0.3.0.2


-- | Module containing externally useful types for Refurb, most notably the
--   <a>Migration</a> type.
module Refurb.Types

-- | Structure with connection information for connecting to the database.
data ConnInfo
ConnInfo :: Text -> Word16 -> Text -> Text -> Text -> ConnInfo

-- | Hostname or IP address of the PostgreSQL server.
[connHost] :: ConnInfo -> Text

-- | Port number the PostgreSQL server is running on (usually
--   <tt>5432</tt>).
[connPort] :: ConnInfo -> Word16

-- | What user to connect to the database as.
[connUser] :: ConnInfo -> Text

-- | What password to connect to the database with.
[connPassword] :: ConnInfo -> Text

-- | What database in the PostgreSQL server to attach to.
[connDbName] :: ConnInfo -> Text

-- | Given a <a>ConnInfo</a> make up the real connection string to pass
--   when connecting to the database. Includes password, so never log this.
connInfoAsConnString :: ConnInfo -> ByteString

-- | Given a <a>ConnInfo</a> make up the log-safe connection string to show
--   to humans, which omits the password.
connInfoAsLogString :: ConnInfo -> Text

-- | Enumeration of the types of migration that are known about.
data MigrationType

-- | Migration that updates the schema of the database and should be run
--   everywhere.
MigrationSchema :: MigrationType

-- | Migration that installs or replaces data for testing purposes and
--   should never be run in production.
MigrationSeedData :: MigrationType

-- | Constraint for actions run in the context of a migration, with access
--   to underlying IO, PostgreSQL connection, and logging.
type MonadMigration m = (MonadBaseControl IO m, MonadMask m, MonadReader Connection m, MonadLogger m)

-- | Data type of a migration, with its key, type, and actions.
data Migration
Migration :: Text -> Text -> MigrationType -> (forall m. MonadMigration m => Maybe (m ())) -> (forall m. MonadMigration m => m ()) -> Migration

-- | Schema for the migration to run in, which also qualifies the migration
--   key."
[_migrationSchema] :: Migration -> Text

-- | Unique key to identify this migration among all known migrations.
--   Never reuse keys, as they're the only link between the stored
--   migration log and known migrations.
[_migrationKey] :: Migration -> Text

-- | What type of migration this is.
[_migrationType] :: Migration -> MigrationType

-- | Optional action to execute before the primary execution to verify
--   preconditions.
[_migrationCheck] :: Migration -> forall m. MonadMigration m => Maybe (m ())

-- | Main migration action, such as creating tables or updating data.
[_migrationExecute] :: Migration -> forall m. MonadMigration m => m ()
migrationSchema :: Lens' Migration Text
migrationKey :: Lens' Migration Text
migrationType :: Lens' Migration MigrationType
migrationCheck :: forall m_aebP. MonadMigration m_aebP => Getter Migration (Maybe (m_aebP ()))
migrationExecute :: forall m_aec4. MonadMigration m_aec4 => Getter Migration (m_aec4 ())

-- | The fully qualified key of the migration, schema.key
migrationQualifiedKey :: Migration -> Text

-- | Helper to construct a <a>MigrationSchema</a> type <a>Migration</a>
--   with the given execution action and no check action.
schemaMigration :: Text -> Text -> (forall m. MonadMigration m => m ()) -> Migration

-- | Helper to construct a <a>MigrationSeedData</a> type <a>Migration</a>
--   with the given execution action and no check action.
seedDataMigration :: Text -> Text -> (forall m. MonadMigration m => m ()) -> Migration

-- | Attach a check function to a <a>Migration</a>.
withCheck :: Migration -> (forall m. MonadMigration m => m ()) -> Migration
instance GHC.Show.Show Refurb.Types.MigrationType
instance GHC.Classes.Eq Refurb.Types.MigrationType


-- | Utilities for writing migrations.
module Refurb.MigrationUtils

-- | Simple quasiquoter which just makes it easier to embed literal chunks
--   of SQL in migrations.
--   
--   For example:
--   
--   <pre>
--   createStuffIndex :: MonadMigration m =&gt; m ()
--   createStuffIndex =
--     execute_
--       [qqSql|
--         create index stuff_index
--           on stuff (things)
--           where is_what_we_want_to_index = <tt>t</tt>
--       |]
--   </pre>
qqSql :: QuasiQuoter

-- | Quasiquoter which takes a block of literal SQL and converts it into a
--   list of <a>Query</a> values, e.g. to pass to <a>executeSeries_</a>. A
--   semicolon at the beginning or end of a line (sans whitespace)
--   separates SQL statements.
--   
--   For example:
--   
--   <pre>
--   createStuff :: MonadMigration m =&gt; m ()
--   createStuff =
--     executeSeries_ [qqSqls|
--       create sequence stuff_seq;
--       create table stuff
--         ( id bigint not null primary key default nextval(<tt>stuff_seq</tt>)
--         );
--       |]
--   </pre>
qqSqls :: QuasiQuoter

-- | Execute some parameterized SQL against the database connection. Wraps
--   <a>execute</a> using the <a>MonadMigration</a> reader to get the
--   connection.
execute :: (MonadMigration m, ToRow q) => Query -> q -> m Int64

-- | Execute some parameterized SQL against the database connection. Wraps
--   <a>executeMany</a> using the <a>MonadMigration</a> reader to get the
--   connection.
executeMany :: (MonadMigration m, ToRow q) => Query -> [q] -> m Int64

-- | Execute some fixed SQL against the database connection. Wraps
--   <a>execute_</a> using the <a>MonadMigration</a> reader to get the
--   connection.
execute_ :: MonadMigration m => Query -> m Int64

-- | Execute a series of fixed SQL statements against the database
--   connection. Equivalent to `traverse_ (void . execute_)`
executeSeries_ :: MonadMigration m => [Query] -> m ()

-- | Run a parameterized query against the database connection. Wraps
--   <a>query</a> using the <a>MonadMigration</a> reader to get the
--   connection.
query :: (MonadMigration m, ToRow q, FromRow r) => Query -> q -> m [r]

-- | Run a fixed query against the database connection. Wraps <a>query_</a>
--   using the <a>MonadMigration</a> reader to get the connection.
query_ :: (MonadMigration m, FromRow r) => Query -> m [r]

-- | Run an Opaleye query against the database connection. Wraps
--   <a>runSelect</a> using the <a>MonadMigration</a> reader to get the
--   connection.
runQuery :: (MonadMigration m, Default Unpackspec columns columns, Default FromFields columns haskells) => Select columns -> m [haskells]

-- | Run an Opaleye <a>runInsert</a> against the database connection.
runInsertMany :: MonadMigration m => Table columns columns' -> [columns] -> m Int64

-- | Run an Opaleye <a>runUpdate</a> against the database connection.
runUpdate :: MonadMigration m => Table columnsW columnsR -> (columnsR -> columnsW) -> (columnsR -> Field SqlBool) -> m Int64

-- | Run an Opaleye <a>runDelete</a> against the database connection.
runDelete :: MonadMigration m => Table columnsW columnsR -> (columnsR -> Field SqlBool) -> m Int64

-- | Check if a schema exists using the <tt>information_schema</tt> views.
doesSchemaExist :: MonadMigration m => Text -> m Bool

-- | Check if a table exists in a schema using the
--   <tt>information_schema</tt> views.
doesTableExist :: MonadMigration m => Text -> Text -> m Bool

-- | Check if a column exists in a schema on a table using the
--   <tt>information_schema</tt> views.
doesColumnExist :: MonadMigration m => Text -> Text -> Text -> m Bool


-- | Module containing definition of and functions for maintaining the
--   in-database state storage for Refurb.
module Refurb.Store

-- | Result of running a migration, either success or failure.
data MigrationResult
MigrationSuccess :: MigrationResult
MigrationFailure :: MigrationResult
data PGMigrationResult
type FId = (:->) "id" Int32
type FIdMay = (:->) "id" (Maybe Int32)
type CId = (:->) "id" (Field SqlInt4)
type CIdMay = (:->) "id" (Maybe (Field SqlInt4))
type FQualifiedKey = (:->) "qualified_key" Text
type CQualifiedKey = (:->) "qualified_key" (Field SqlText)
type FApplied = (:->) "applied" UTCTime
type CApplied = (:->) "applied" (Field SqlTimestamptz)
type FOutput = (:->) "output" Text
type COutput = (:->) "output" (Field SqlText)
type FResult = (:->) "result" MigrationResult
type CResult = (:->) "result" (Field PGMigrationResult)
type FDuration = (:->) "duration" Double
type CDuration = (:->) "duration" (Field SqlFloat8)
type FProdSystem = (:->) "prod_system" Bool
type CProdSystem = (:->) "prod_system" (Field SqlBool)
cProdSystem :: forall f_aqs5 rs_aqs6. (Functor f_aqs5, (∈) CProdSystem rs_aqs6) => (Field SqlBool -> f_aqs5 (Field SqlBool)) -> Record rs_aqs6 -> f_aqs5 (Record rs_aqs6)
fProdSystem :: forall f_aqs3 rs_aqs4. (Functor f_aqs3, (∈) FProdSystem rs_aqs4) => (Bool -> f_aqs3 Bool) -> Record rs_aqs4 -> f_aqs3 (Record rs_aqs4)
cDuration :: forall f_aqs1 rs_aqs2. (Functor f_aqs1, (∈) CDuration rs_aqs2) => (Field SqlFloat8 -> f_aqs1 (Field SqlFloat8)) -> Record rs_aqs2 -> f_aqs1 (Record rs_aqs2)
fDuration :: forall f_aqrZ rs_aqs0. (Functor f_aqrZ, (∈) FDuration rs_aqs0) => (Double -> f_aqrZ Double) -> Record rs_aqs0 -> f_aqrZ (Record rs_aqs0)
cResult :: forall f_aqrX rs_aqrY. (Functor f_aqrX, (∈) CResult rs_aqrY) => (Field PGMigrationResult -> f_aqrX (Field PGMigrationResult)) -> Record rs_aqrY -> f_aqrX (Record rs_aqrY)
fResult :: forall f_aqrV rs_aqrW. (Functor f_aqrV, (∈) FResult rs_aqrW) => (MigrationResult -> f_aqrV MigrationResult) -> Record rs_aqrW -> f_aqrV (Record rs_aqrW)
cOutput :: forall f_aqrT rs_aqrU. (Functor f_aqrT, (∈) COutput rs_aqrU) => (Field SqlText -> f_aqrT (Field SqlText)) -> Record rs_aqrU -> f_aqrT (Record rs_aqrU)
fOutput :: forall f_aqrR rs_aqrS. (Functor f_aqrR, (∈) FOutput rs_aqrS) => (Text -> f_aqrR Text) -> Record rs_aqrS -> f_aqrR (Record rs_aqrS)
cApplied :: forall f_aqrP rs_aqrQ. (Functor f_aqrP, (∈) CApplied rs_aqrQ) => (Field SqlTimestamptz -> f_aqrP (Field SqlTimestamptz)) -> Record rs_aqrQ -> f_aqrP (Record rs_aqrQ)
fApplied :: forall f_aqrN rs_aqrO. (Functor f_aqrN, (∈) FApplied rs_aqrO) => (UTCTime -> f_aqrN UTCTime) -> Record rs_aqrO -> f_aqrN (Record rs_aqrO)
cQualifiedKey :: forall f_aqrL rs_aqrM. (Functor f_aqrL, (∈) CQualifiedKey rs_aqrM) => (Field SqlText -> f_aqrL (Field SqlText)) -> Record rs_aqrM -> f_aqrL (Record rs_aqrM)
fQualifiedKey :: forall f_aqrJ rs_aqrK. (Functor f_aqrJ, (∈) FQualifiedKey rs_aqrK) => (Text -> f_aqrJ Text) -> Record rs_aqrK -> f_aqrJ (Record rs_aqrK)
cIdMay :: forall f_aqrH rs_aqrI. (Functor f_aqrH, (∈) CIdMay rs_aqrI) => (Maybe (Field SqlInt4) -> f_aqrH (Maybe (Field SqlInt4))) -> Record rs_aqrI -> f_aqrH (Record rs_aqrI)
cId :: forall f_aqrF rs_aqrG. (Functor f_aqrF, (∈) CId rs_aqrG) => (Field SqlInt4 -> f_aqrF (Field SqlInt4)) -> Record rs_aqrG -> f_aqrF (Record rs_aqrG)
fIdMay :: forall f_aqrD rs_aqrE. (Functor f_aqrD, (∈) FIdMay rs_aqrE) => (Maybe Int32 -> f_aqrD (Maybe Int32)) -> Record rs_aqrE -> f_aqrD (Record rs_aqrE)
fId :: forall f_aqrB rs_aqrC. (Functor f_aqrB, (∈) FId rs_aqrC) => (Int32 -> f_aqrB Int32) -> Record rs_aqrC -> f_aqrB (Record rs_aqrC)
cProdSystem_ :: Proxy CProdSystem
fProdSystem_ :: Proxy FProdSystem
cDuration_ :: Proxy CDuration
fDuration_ :: Proxy FDuration
cResult_ :: Proxy CResult
fResult_ :: Proxy FResult
cOutput_ :: Proxy COutput
fOutput_ :: Proxy FOutput
cApplied_ :: Proxy CApplied
fApplied_ :: Proxy FApplied
cQualifiedKey_ :: Proxy CQualifiedKey
fQualifiedKey_ :: Proxy FQualifiedKey
cIdMay_ :: Proxy CIdMay
cId_ :: Proxy CId
fIdMay_ :: Proxy FIdMay
fId_ :: Proxy FId

-- | Fields of a migration log entry in memory fetched from the database
--   (with ID)
type MigrationLog = '[FId, FQualifiedKey, FApplied, FOutput, FResult, FDuration]

-- | Fields of a migration log entry to insert in the database (with the ID
--   column optional)
type MigrationLogW = '[FIdMay, FQualifiedKey, FApplied, FOutput, FResult, FDuration]

-- | Columns of a migration log when reading from the database (with ID)
type MigrationLogColsR = '[CId, CQualifiedKey, CApplied, COutput, CResult, CDuration]

-- | Columns of a migration log when inserting into the database (with ID
--   column optional)
type MigrationLogColsW = '[CIdMay, CQualifiedKey, CApplied, COutput, CResult, CDuration]

-- | Fields of the Refurb config in memory
type RefurbConfig = '[FProdSystem]

-- | Columns of the Refurb config in the database
type RefurbConfigCols = '[CProdSystem]

-- | The migration log table which records all executed migrations and
--   their results
migrationLog :: Table (Record MigrationLogColsW) (Record MigrationLogColsR)

-- | The refurb config table which controls whether this database is
--   considered a production one or not
refurbConfig :: Table (Record RefurbConfigCols) (Record RefurbConfigCols)

-- | Test to see if the schema seems to be installed by looking for an
--   existing refurb_config table
isSchemaPresent :: (MonadBaseControl IO m, MonadMask m, MonadLogger m) => Connection -> m Bool

-- | Check if this database is configured as a production database by
--   reading the refurb config table
isProdSystem :: (MonadBaseControl IO m, MonadLogger m) => Connection -> m Bool

-- | Create the refurb schema elements. Will fail if they already exist.
initializeSchema :: (MonadBaseControl IO m, MonadLogger m) => Connection -> m ()

-- | Read the migration log and stitch it together with the expected
--   migration list, forming a list in the same order as the known
--   migrations but with <a>These</a> representing whether the migration
--   log for the known migration is present or not.
--   
--   <ul>
--   <li><tt><a>This</a> migration</tt> represents a known migration that
--   has no log entry.</li>
--   <li><tt><a>That</a> migrationLog</tt> represents an unknown migration
--   that was applied in the past.</li>
--   <li><tt><a>These</a> migration migrationLog</tt> represents a
--   migration that has an attempted application in the log.</li>
--   </ul>
readMigrationStatus :: (MonadBaseControl IO m, MonadLogger m) => Connection -> [Migration] -> SelectArr (Record MigrationLogColsR) () -> m [These Migration (Record MigrationLog)]
instance Opaleye.Internal.PGTypes.IsSqlType Refurb.Store.PGMigrationResult
instance Opaleye.Internal.RunQuery.DefaultFromField Refurb.Store.PGMigrationResult Refurb.Store.MigrationResult
instance Data.Profunctor.Product.Default.Class.Default Opaleye.Internal.Constant.ToFields Refurb.Store.MigrationResult (Opaleye.Internal.Column.Field Refurb.Store.PGMigrationResult)
instance Database.PostgreSQL.Simple.FromField.FromField Refurb.Store.MigrationResult
instance GHC.Show.Show Refurb.Store.MigrationResult
instance GHC.Classes.Eq Refurb.Store.MigrationResult


-- | Module with <tt>optparse-applicative</tt> parsers for and datatypes to
--   represent the command line arguments.
module Refurb.Cli

-- | Newtype wrapper for the <tt>--execute</tt> boolean (<tt>True</tt> if
--   given, <tt>False</tt> if omitted)
newtype GoNoGo
GoNoGo :: Bool -> GoNoGo

-- | Newtype wrapper for the <tt>--backup-first</tt> option to the
--   <tt>migrate</tt> command.
newtype PreMigrationBackup
PreMigrationBackup :: FilePath -> PreMigrationBackup

-- | Newtype wrapper for the <tt>--seed</tt> boolean (<tt>True</tt> if
--   given, <tt>False</tt> if omitted)
newtype InstallSeedData
InstallSeedData :: Bool -> InstallSeedData

-- | The various top level commands that can be requested by the user
data Command

-- | Migrate the database or show what migrations would be applied,
--   possibly backing up beforehand.
CommandMigrate :: GoNoGo -> Maybe PreMigrationBackup -> InstallSeedData -> Command

-- | Show the migration status.
CommandShowLog :: Command

-- | Show status of a particular migration with its log output.
CommandShowMigration :: FQualifiedKey -> Command

-- | Back up the database.
CommandBackup :: FilePath -> Command

-- | Option parser for the <tt>migrate</tt> command
commandMigrateParser :: ParserInfo Command

-- | Option parser for the <tt>show-log</tt> command
commandShowLogParser :: ParserInfo Command

-- | Option parser for the <tt>show-migration</tt> command
commandShowMigrationParser :: ParserInfo Command

-- | Option parser for the <tt>backup</tt> command
commandBackupParser :: ParserInfo Command

-- | Structure holding the parsed command line arguments and options.
data Opts
Opts :: Bool -> Bool -> FilePath -> Command -> Opts

-- | Whether to turn on debug logging to the console
[debug] :: Opts -> Bool

-- | Whether to colorize console output
[colorize] :: Opts -> Bool

-- | The configuration file where (presumably) the database connection
--   information is stored
[configFile] :: Opts -> FilePath

-- | Which command the user chose and the options for that command
[command] :: Opts -> Command

-- | Parser for the command line arguments
optsParser :: ParserInfo Opts
instance GHC.Show.Show Refurb.Cli.GoNoGo
instance GHC.Classes.Eq Refurb.Cli.GoNoGo
instance GHC.Show.Show Refurb.Cli.PreMigrationBackup
instance GHC.Classes.Eq Refurb.Cli.PreMigrationBackup
instance GHC.Show.Show Refurb.Cli.InstallSeedData
instance GHC.Classes.Eq Refurb.Cli.InstallSeedData
instance GHC.Show.Show Refurb.Cli.Command
instance GHC.Classes.Eq Refurb.Cli.Command


-- | Module containing shared types and functions used for implementing the
--   various commands.
module Refurb.Run.Internal

-- | Reader context for all command execution which contains the command
--   line options, database connection and connection information, and
--   known migrations.
data Context
Context :: Opts -> Connection -> ConnInfo -> [Migration] -> Context

-- | The <a>Opts</a> structure parsed from the command line by
--   <tt>Refurb.Cli</tt>.
[contextOptions] :: Context -> Opts

-- | The open database <a>Connection</a>.
[contextDbConn] :: Context -> Connection

-- | The information used to connect to the database, required for running
--   command line tools like <tt>pg_dump</tt> against the same database.
[contextDbConnInfo] :: Context -> ConnInfo

-- | The known migrations passed in to <a>refurbMain</a>.
[contextMigrations] :: Context -> [Migration]

-- | Constraint of actions for command execution, including access to the
--   <a>Context</a>, logging, and underlying IO.
type MonadRefurb m = (MonadBaseControl IO m, MonadFail m, MonadMask m, MonadReader Context m, MonadLogger m, MonadLoggerIO m)

-- | Given the configuration implicitly available to <a>MonadRefurb</a>,
--   produce a function which possibly strips ANSI colorization from a
--   <a>Doc</a> if the user requested colorless output.
optionallyColorM :: MonadRefurb m => m (Doc -> Doc)

-- | Given the configuration implicitly available to <a>MonadRefurb</a>,
--   produce a function which emits a <a>Doc</a> on stdout that is colored
--   unless the user requested colorless output.
optionallyColoredM :: MonadRefurb m => m (Doc -> m ())

-- | Produce a colorized <a>Doc</a> with <tt>success</tt> or
--   <tt>failure</tt>, based on which <a>MigrationResult</a> value was
--   passed.
migrationResultDoc :: MigrationResult -> Doc

module Refurb.Run.Info

-- | Given a migration status as read by <a>readMigrationStatus</a>, pretty
--   print that information as a table on stdout.
showMigrationStatus :: (MonadRefurb m, MonoTraversable t, Element t ~ These Migration (Record MigrationLog)) => t -> m ()

-- | Implement the <tt>show-log</tt> command by reading the entire
--   migration log and displaying it with <a>showMigrationStatus</a>.
showLog :: MonadRefurb m => m ()

-- | Implement the <tt>show-migration</tt> command by reading migration log
--   pertaining to the given migration key and displaying it with
--   <a>showMigrationStatus</a> plus its log output.
showMigration :: MonadRefurb m => FQualifiedKey -> m ()

module Refurb.Run.Backup

-- | Handle the <tt>backup</tt> command by calling <tt>pg_dump</tt> to save
--   a database backup.
backup :: MonadRefurb m => FilePath -> m ()

module Refurb.Run.Migrate

-- | Helper which produces the standard prefix <a>Doc</a> for a given
--   migration: <tt>migration key: </tt> with color.
migrationPrefixDoc :: Migration -> Doc

-- | Implement the <tt>migrate</tt> command by verifying that seed data is
--   only applied to non-production databases, reading the migration
--   status, and determining from that status which migrations to apply. If
--   the user requested execution of migrations, delegate to
--   <a>applyMigrations</a> to actually do the work.
migrate :: (MonadUnliftIO m, MonadRefurb m) => GoNoGo -> Maybe PreMigrationBackup -> InstallSeedData -> m ()

-- | Given a pre-vetted list of <a>Migration</a> structures to apply to the
--   database, iterate through them and run their check actions (if any)
--   followed by execution actions with log output captured.
applyMigrations :: (MonadUnliftIO m, MonadRefurb m) => [Migration] -> m ()

-- | Format a <a>Loc</a> in the way we want for logging output -
--   <tt>package:module filename:line:column</tt>
locLogString :: Loc -> LogStr

-- | Format the current timestamp in the way we want for logging output -
--   <tt>yyyy-mm-dd hh:mm:ss.SSS</tt>
nowLogString :: IO LogStr


-- | Top level module of Refurb along which re-exports the library portion
--   of Refurb (<a>Types</a> and <a>MigrationUtils</a>)
module Refurb

-- | Main entry point for refurbishing.
--   
--   In <tt>refurb readDatabaseConnectionString migrations</tt>,
--   <tt>readDatabaseConnectionString</tt> is a function taking the
--   configuration file path from the command line and yielding a pair of
--   actual and loggable connection strings, and <tt>migrations</tt> is a
--   list of <a>Migration</a> records to consider.
--   
--   For example:
--   
--   <pre>
--   module Main where
--   
--   import Refurb (<a>Migration</a>, <a>MonadMigration</a>, <a>execute_</a>, <a>schemaMigration</a>, refurbMain)
--   
--   migrations :: [<a>Migration</a>]
--   migrations =
--     [ schemaMigration "create-my-table" createMyTable
--     ]
--   
--   createMyTable :: MonadMigration m =&gt; m ()
--   createMyTable =
--     void $ execute_ "create table my_table (...)"
--   
--   main :: IO ()
--   main = refurbMain readDatabaseConnInfo migrations
--   </pre>
refurbMain :: (FilePath -> IO ConnInfo) -> [Migration] -> IO ()