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


-- | Manual migrations for the persistent library
--   
--   Manual migrations for the persistent library.
@package persistent-migration
@version 0.2.1


-- | Defines auxiliary data types that can be used in Operations.
module Database.Persist.Migration.Operation.Types

-- | A column identifier, table.column
type ColumnIdentifier = (Text, Text)

-- | Make a ColumnIdentifier displayable.
dotted :: ColumnIdentifier -> Text

-- | The definition for a Column in a SQL database.
data Column
Column :: Text -> SqlType -> [ColumnProp] -> Column
[$sel:colName:Column] :: Column -> Text
[$sel:colType:Column] :: Column -> SqlType
[$sel:colProps:Column] :: Column -> [ColumnProp]

-- | Validate a Column.
validateColumn :: Column -> Either String ()

-- | A property for a <a>Column</a>.
data ColumnProp

-- | Makes a column non-nullable (defaults to nullable)
NotNull :: ColumnProp

-- | Mark this column as a foreign key to the given column
References :: ColumnIdentifier -> ColumnProp

-- | Makes a column auto-incrementing
AutoIncrement :: ColumnProp

-- | Sets the default value for the column. Note that this doesn't matter
--   when inserting data via Haskell; this property only sets the schema in
--   the SQL backend.
--   
--   See <tt>AddColumn</tt> for setting the default value for existing rows
--   in a migration.
--   
--   More info:
--   <a>https://www.yesodweb.com/book/persistent#persistent_attributes</a>
Default :: PersistValue -> ColumnProp

-- | Table constraints in a CREATE query.
data TableConstraint

-- | PRIMARY KEY (col1, col2, ...)
PrimaryKey :: [Text] -> TableConstraint

-- | CONSTRAINT name UNIQUE (col1, col2, ...)
Unique :: Text -> [Text] -> TableConstraint
isPrimaryKey :: TableConstraint -> Bool

-- | Get the columns defined in the given TableConstraint.
getConstraintColumns :: TableConstraint -> [Text]
instance GHC.Classes.Eq Database.Persist.Migration.Operation.Types.ColumnProp
instance GHC.Show.Show Database.Persist.Migration.Operation.Types.ColumnProp
instance GHC.Show.Show Database.Persist.Migration.Operation.Types.Column
instance GHC.Show.Show Database.Persist.Migration.Operation.Types.TableConstraint


-- | Define functions useful for compiling a plan of migration.
module Database.Persist.Migration.Utils.Plan

-- | Given a list of edges and their data and a start/end node, return the
--   shortest path.
--   
--   Errors if no path is found.
getPath :: [(Edge, a)] -> Node -> Node -> Maybe [a]


-- | Defines helper functions for writing SQL queries.
module Database.Persist.Migration.Utils.Sql

-- | Split the given line by commas, ignoring commas within parentheses.
--   
--   <pre>
--   commas "a,b,c" == ["a", "b", "c"]
--   commas "a,b,c (d,e),z" == ["a", "b", "c (d,e)", "z"]
--   commas "a,b,c (d,e,(f,g)),z" == ["a", "b", "c (d,e,(f,g))", "z"]
--   </pre>
commas :: Text -> [Text]

-- | Join the given Text with commas separating each item.
uncommas :: [Text] -> Text

-- | Join the given Text with commas separating each item and quoting them.
uncommas' :: [Text] -> Text

-- | Quote the given Text.
quote :: Text -> Text

-- | A SQL query (with placeholders) and values to replace those
--   placeholders.
data MigrateSql
MigrateSql :: Text -> [PersistValue] -> MigrateSql
[sqlText] :: MigrateSql -> Text
[sqlVals] :: MigrateSql -> [PersistValue]

-- | Execute a SQL query.
executeSql :: MonadIO m => MigrateSql -> SqlPersistT m ()

-- | Create a MigrateSql from the given Text.
pureSql :: Text -> MigrateSql

-- | Map the SQL text with the given function.
mapSql :: (Text -> Text) -> MigrateSql -> MigrateSql

-- | Concatenate the given MigrateSql queries with the given combining
--   function.
concatSql :: ([Text] -> Text) -> [MigrateSql] -> MigrateSql
instance GHC.Show.Show Database.Persist.Migration.Utils.Sql.MigrateSql


-- | Defines the Operation data types.
module Database.Persist.Migration.Operation

-- | An operation that can be migrated.
data Operation
CreateTable :: Text -> [Column] -> [TableConstraint] -> Operation
[name] :: Operation -> Text
[schema] :: Operation -> [Column]
[constraints] :: Operation -> [TableConstraint]
DropTable :: Text -> Operation
[table] :: Operation -> Text
RenameTable :: Text -> Text -> Operation
[from] :: Operation -> Text
[to] :: Operation -> Text
AddConstraint :: Text -> TableConstraint -> Operation
[table] :: Operation -> Text
[constraint] :: Operation -> TableConstraint
DropConstraint :: Text -> Text -> Operation
[table] :: Operation -> Text
[constraintName] :: Operation -> Text
AddColumn :: Text -> Column -> Maybe PersistValue -> Operation
[table] :: Operation -> Text
[column] :: Operation -> Column

-- | The default for existing rows; required if the column is non-nullable
[colDefault] :: Operation -> Maybe PersistValue
RenameColumn :: Text -> Text -> Text -> Operation
[table] :: Operation -> Text
[from] :: Operation -> Text
[to] :: Operation -> Text
DropColumn :: ColumnIdentifier -> Operation
[columnId] :: Operation -> ColumnIdentifier

-- | A custom operation that can be defined manually.
--   
--   RawOperations should primarily use <tt>rawSql</tt> and
--   <tt>rawExecute</tt> from the persistent library. If the operation
--   depends on the backend being run, query <tt>connRDBMS</tt> from the
--   <tt>SqlBackend</tt>:
--   
--   <pre>
--   asks connRDBMS &gt;&gt;= case
--     "sqlite" -&gt; ...
--     _ -&gt; return ()
--   </pre>
RawOperation :: Text -> SqlPersistT IO [MigrateSql] -> Operation
[message] :: Operation -> Text
[rawOp] :: Operation -> SqlPersistT IO [MigrateSql]

-- | Validate that the given Operation is valid.
validateOperation :: Operation -> Either String ()
instance GHC.Show.Show Database.Persist.Migration.Operation.Operation
instance GHC.Show.Show (Database.Persist.Sql.Types.SqlPersistT m a)


-- | Defines <a>MigrateBackend</a>, the data constructor that each SQL
--   backend will need to implement.
module Database.Persist.Migration.Backend

-- | The backend to migrate with.
newtype MigrateBackend
MigrateBackend :: (Operation -> SqlPersistT IO [MigrateSql]) -> MigrateBackend
[getMigrationSql] :: MigrateBackend -> Operation -> SqlPersistT IO [MigrateSql]


-- | Defines a migration framework for the persistent library.
module Database.Persist.Migration.Core

-- | The version of a database. An operation migrates from the given
--   version to another version.
--   
--   The version must be increasing, such that the lowest version is the
--   first version and the highest version is the most up-to-date version.
--   
--   A version represents a version of the database schema. In other words,
--   any set of operations taken to get to version X *MUST* all result in
--   the same database schema.
type Version = Int

-- | The path that an operation takes.
type OperationPath = (Version, Version)

-- | An infix constructor for <a>OperationPath</a>.
(~>) :: Version -> Version -> OperationPath

-- | A migration list that defines operations to manually migrate a
--   database schema.
type Migration = [MigrationPath]

-- | A path representing the operations needed to run to get from one
--   version of the database schema to the next.
data MigrationPath
(:=) :: OperationPath -> [Operation] -> MigrationPath

-- | Get the OperationPath in the MigrationPath.
opPath :: MigrationPath -> OperationPath

-- | Settings to customize migration steps.
newtype MigrateSettings
MigrateSettings :: (Version -> Maybe String) -> MigrateSettings

-- | A function to optionally label certain versions
[$sel:versionToLabel:MigrateSettings] :: MigrateSettings -> Version -> Maybe String

-- | Default migration settings.
defaultSettings :: MigrateSettings

-- | Validate the given migration.
validateMigration :: Migration -> Either String ()

-- | Run the given migration. After successful completion, saves the
--   migration to the database.
runMigration :: MonadIO m => MigrateBackend -> MigrateSettings -> Migration -> SqlPersistT m ()

-- | Get the SQL queries for the given migration.
getMigration :: MonadIO m => MigrateBackend -> MigrateSettings -> Migration -> SqlPersistT m [MigrateSql]
instance GHC.Show.Show Database.Persist.Migration.Core.MigrationPath


-- | Defines a migration framework for the persistent library.
module Database.Persist.Migration

-- | True if the persistent library detects more migrations unaccounted
--   for.
hasMigration :: MonadIO m => Migration -> SqlPersistT m Bool

-- | Fails if the persistent library detects more migrations unaccounted
--   for.
checkMigration :: MonadIO m => Migration -> SqlPersistT m ()

-- | Settings to customize migration steps.
newtype MigrateSettings
MigrateSettings :: (Version -> Maybe String) -> MigrateSettings

-- | A function to optionally label certain versions
[$sel:versionToLabel:MigrateSettings] :: MigrateSettings -> Version -> Maybe String

-- | A path representing the operations needed to run to get from one
--   version of the database schema to the next.
data MigrationPath
(:=) :: OperationPath -> [Operation] -> MigrationPath

-- | A migration list that defines operations to manually migrate a
--   database schema.
type Migration = [MigrationPath]

-- | The path that an operation takes.
type OperationPath = (Version, Version)

-- | The version of a database. An operation migrates from the given
--   version to another version.
--   
--   The version must be increasing, such that the lowest version is the
--   first version and the highest version is the most up-to-date version.
--   
--   A version represents a version of the database schema. In other words,
--   any set of operations taken to get to version X *MUST* all result in
--   the same database schema.
type Version = Int

-- | An infix constructor for <a>OperationPath</a>.
(~>) :: Version -> Version -> OperationPath

-- | Get the OperationPath in the MigrationPath.
opPath :: MigrationPath -> OperationPath

-- | Default migration settings.
defaultSettings :: MigrateSettings

-- | Validate the given migration.
validateMigration :: Migration -> Either String ()

-- | A raw value which can be stored in any backend and can be marshalled
--   to and from a <tt>PersistField</tt>.
data PersistValue
PersistText :: Text -> PersistValue
PersistByteString :: ByteString -> PersistValue
PersistInt64 :: Int64 -> PersistValue
PersistDouble :: Double -> PersistValue
PersistRational :: Rational -> PersistValue
PersistBool :: Bool -> PersistValue
PersistDay :: Day -> PersistValue
PersistTimeOfDay :: TimeOfDay -> PersistValue
PersistUTCTime :: UTCTime -> PersistValue
PersistNull :: PersistValue
PersistList :: [PersistValue] -> PersistValue
PersistMap :: [(Text, PersistValue)] -> PersistValue

-- | Intended especially for MongoDB backend
PersistObjectId :: ByteString -> PersistValue

-- | Intended especially for PostgreSQL backend for text arrays
PersistArray :: [PersistValue] -> PersistValue

-- | This constructor is used to specify some raw literal value for the
--   backend. The <a>LiteralType</a> value specifies how the value should
--   be escaped. This can be used to make special, custom types avaialable
--   in the back end.
PersistLiteral_ :: LiteralType -> ByteString -> PersistValue

-- | This pattern synonym used to be a data constructor on
--   <a>PersistValue</a>, but was changed into a catch-all pattern synonym
--   to allow backwards compatiblity with database types. See the
--   documentation on <a>PersistDbSpecific</a> for more details.
pattern PersistLiteral :: ByteString -> PersistValue

-- | This pattern synonym used to be a data constructor on
--   <a>PersistValue</a>, but was changed into a catch-all pattern synonym
--   to allow backwards compatiblity with database types. See the
--   documentation on <a>PersistDbSpecific</a> for more details.
pattern PersistLiteralEscaped :: ByteString -> PersistValue

-- | This pattern synonym used to be a data constructor for the
--   <a>PersistValue</a> type. It was changed to be a pattern so that
--   JSON-encoded database values could be parsed into their corresponding
--   values. You should not use this, and instead prefer to pattern match
--   on <a>PersistLiteral_</a> directly.
--   
--   If you use this, it will overlap a patern match on the
--   'PersistLiteral_, <a>PersistLiteral</a>, and
--   <a>PersistLiteralEscaped</a> patterns. If you need to disambiguate
--   between these constructors, pattern match on <a>PersistLiteral_</a>
--   directly.
pattern PersistDbSpecific :: ByteString -> PersistValue

-- | A SQL data type. Naming attempts to reflect the underlying Haskell
--   datatypes, eg SqlString instead of SqlVarchar. Different SQL databases
--   may have different translations for these types.
data SqlType
SqlString :: SqlType
SqlInt32 :: SqlType
SqlInt64 :: SqlType
SqlReal :: SqlType
SqlNumeric :: Word32 -> Word32 -> SqlType
SqlBool :: SqlType
SqlDay :: SqlType
SqlTime :: SqlType

-- | Always uses UTC timezone
SqlDayTime :: SqlType
SqlBlob :: SqlType

-- | a backend-specific name
SqlOther :: Text -> SqlType

-- | Execute a raw SQL statement and return its results as a list. If you
--   do not expect a return value, use of <a>rawExecute</a> is recommended.
--   
--   If you're using <a>Entity</a><tt>s</tt> (which is quite likely), then
--   you <i>must</i> use entity selection placeholders (double question
--   mark, <tt>??</tt>). These <tt>??</tt> placeholders are then replaced
--   for the names of the columns that we need for your entities. You'll
--   receive an error if you don't use the placeholders. Please see the
--   <a>Entity</a><tt>s</tt> documentation for more details.
--   
--   You may put value placeholders (question marks, <tt>?</tt>) in your
--   SQL query. These placeholders are then replaced by the values you pass
--   on the second parameter, already correctly escaped. You may want to
--   use <a>toPersistValue</a> to help you constructing the placeholder
--   values.
--   
--   Since you're giving a raw SQL statement, you don't get any guarantees
--   regarding safety. If <a>rawSql</a> is not able to parse the results of
--   your query back, then an exception is raised. However, most common
--   problems are mitigated by using the entity selection placeholder
--   <tt>??</tt>, and you shouldn't see any error at all if you're not
--   using <a>Single</a>.
--   
--   Some example of <a>rawSql</a> based on this schema:
--   
--   <pre>
--   share [mkPersist sqlSettings, mkMigrate "migrateAll"] [persistLowerCase|
--   Person
--       name String
--       age Int Maybe
--       deriving Show
--   BlogPost
--       title String
--       authorId PersonId
--       deriving Show
--   |]
--   </pre>
--   
--   Examples based on the above schema:
--   
--   <pre>
--   getPerson :: MonadIO m =&gt; ReaderT SqlBackend m [Entity Person]
--   getPerson = rawSql "select ?? from person where name=?" [PersistText "john"]
--   
--   getAge :: MonadIO m =&gt; ReaderT SqlBackend m [Single Int]
--   getAge = rawSql "select person.age from person where name=?" [PersistText "john"]
--   
--   getAgeName :: MonadIO m =&gt; ReaderT SqlBackend m [(Single Int, Single Text)]
--   getAgeName = rawSql "select person.age, person.name from person where name=?" [PersistText "john"]
--   
--   getPersonBlog :: MonadIO m =&gt; ReaderT SqlBackend m [(Entity Person, Entity BlogPost)]
--   getPersonBlog = rawSql "select ??,?? from person,blog_post where person.id = blog_post.author_id" []
--   </pre>
--   
--   Minimal working program for PostgreSQL backend based on the above
--   concepts:
--   
--   <pre>
--   {-# LANGUAGE EmptyDataDecls             #-}
--   {-# LANGUAGE FlexibleContexts           #-}
--   {-# LANGUAGE GADTs                      #-}
--   {-# LANGUAGE GeneralizedNewtypeDeriving #-}
--   {-# LANGUAGE MultiParamTypeClasses      #-}
--   {-# LANGUAGE OverloadedStrings          #-}
--   {-# LANGUAGE QuasiQuotes                #-}
--   {-# LANGUAGE TemplateHaskell            #-}
--   {-# LANGUAGE TypeFamilies               #-}
--   
--   import           Control.Monad.IO.Class  (liftIO)
--   import           Control.Monad.Logger    (runStderrLoggingT)
--   import           Database.Persist
--   import           Control.Monad.Reader
--   import           Data.Text
--   import           Database.Persist.Sql
--   import           Database.Persist.Postgresql
--   import           Database.Persist.TH
--   
--   share [mkPersist sqlSettings, mkMigrate "migrateAll"] [persistLowerCase|
--   Person
--       name String
--       age Int Maybe
--       deriving Show
--   |]
--   
--   conn = "host=localhost dbname=new_db user=postgres password=postgres port=5432"
--   
--   getPerson :: MonadIO m =&gt; ReaderT SqlBackend m [Entity Person]
--   getPerson = rawSql "select ?? from person where name=?" [PersistText "sibi"]
--   
--   liftSqlPersistMPool y x = liftIO (runSqlPersistMPool y x)
--   
--   main :: IO ()
--   main = runStderrLoggingT $ withPostgresqlPool conn 10 $ liftSqlPersistMPool $ do
--            runMigration migrateAll
--            xs &lt;- getPerson
--            liftIO (print xs)
--   </pre>
rawSql :: forall a (m :: Type -> Type) backend. (RawSql a, MonadIO m, BackendCompatible SqlBackend backend) => Text -> [PersistValue] -> ReaderT backend m [a]


-- | Defines the migration backend for PostgreSQL.
module Database.Persist.Migration.Postgres

-- | The migration backend for Postgres.
backend :: MigrateBackend

-- | Get a migration with the Postgres backend.
getMigration :: MigrateSettings -> Migration -> SqlPersistT IO [MigrateSql]

-- | Run a migration with the Postgres backend.
runMigration :: MigrateSettings -> Migration -> SqlPersistT IO ()