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


-- | A pure haskell backend for the persistent library using MySQL database server.
--   
--   This package contains a backend for persistent using the MySQL
--   database server. Internally it uses the <tt>mysql-haskell</tt> package
--   in order to access the database. See README.md for more.
--   
--   This package supports only MySQL 5.1 and above. However, it has been
--   tested only on MySQL 5.5. Only the InnoDB storage engine is officially
--   supported.
--   
--   Known problems:
--   
--   <ul>
--   <li>This package does not support statements inside other
--   statements.</li>
--   </ul>
@package persistent-mysql-haskell
@version 0.4.1


-- | A MySQL backend for <tt>persistent</tt>.
module Database.Persist.MySQL

-- | Create a MySQL connection pool and run the given action. The pool is
--   properly released after the action finishes using it. Note that you
--   should not use the given <a>ConnectionPool</a> outside the action
--   since it may be already been released.
withMySQLPool :: (MonadLogger m, MonadUnliftIO m, IsSqlBackend backend) => MySQLConnectInfo -> Int -> (Pool backend -> m a) -> m a

-- | Same as <a>withMySQLPool</a>, but instead of opening a pool of
--   connections, only one connection is opened.
withMySQLConn :: (MonadUnliftIO m, MonadLogger m, IsSqlBackend backend) => MySQLConnectInfo -> (backend -> m a) -> m a

-- | Create a MySQL connection pool. Note that it's your responsibility to
--   properly close the connection pool when unneeded. Use
--   <a>withMySQLPool</a> for automatic resource control.
createMySQLPool :: (MonadUnliftIO m, MonadLogger m, IsSqlBackend backend) => MySQLConnectInfo -> Int -> m (Pool backend)

-- | MySQL connection information.
data MySQLConnectInfo

-- | Public constructor for <tt>MySQLConnectInfo</tt>.
mkMySQLConnectInfo :: HostName -> ByteString -> ByteString -> ByteString -> MySQLConnectInfo

-- | Update port number for <tt>MySQLConnectInfo</tt>.
setMySQLConnectInfoPort :: PortNumber -> MySQLConnectInfo -> MySQLConnectInfo

-- | Update character set for <tt>MySQLConnectInfo</tt>.
setMySQLConnectInfoCharset :: Word8 -> MySQLConnectInfo -> MySQLConnectInfo

-- | Information required to connect to a MySQL database using
--   <tt>persistent</tt>'s generic facilities. These values are the same
--   that are given to <a>withMySQLPool</a>.
data MySQLConf

-- | Public constructor for <tt>MySQLConf</tt>.
mkMySQLConf :: MySQLConnectInfo -> Int -> MySQLConf

-- | Mock a migration even when the database is not present. This function
--   will mock the migration for a database even when the actual database
--   isn't already present in the system.
mockMigration :: Migration -> IO ()

-- | MySQL specific <tt>upsert_</tt>. This will prevent multiple queries,
--   when one will do. The record will be inserted into the database. In
--   the event that the record already exists in the database, the record
--   will have the relevant updates performed.
insertOnDuplicateKeyUpdate :: (backend ~ PersistEntityBackend record, PersistEntity record, MonadIO m, PersistStore backend, BackendCompatible SqlBackend backend) => record -> [Update record] -> ReaderT backend m ()

-- | Do a bulk insert on the given records in the first parameter. In the
--   event that a key conflicts with a record currently in the database,
--   the second and third parameters determine what will happen.
--   
--   The second parameter is a list of fields to copy from the original
--   value. This allows you to specify which fields to copy from the record
--   you're trying to insert into the database to the preexisting row.
--   
--   The third parameter is a list of updates to perform that are
--   independent of the value that is provided. You can use this to
--   increment a counter value. These updates only occur if the original
--   record is present in the database.
--   
--   <h3><b>More details on <a>HandleUpdateCollision</a> usage</b></h3>
--   
--   The <tt>[<a>HandleUpdateCollision</a>]</tt> parameter allows you to
--   specify which fields (and under which conditions) will be copied from
--   the inserted rows. For a brief example, consider the following data
--   model and existing data set:
--   
--   <pre>
--   Item
--     name        Text
--     description Text
--     price       Double Maybe
--     quantity    Int Maybe
--   
--     Primary name
--   </pre>
--   
--   <pre>
--   items:
--   +------+-------------+-------+----------+
--   | name | description | price | quantity |
--   +------+-------------+-------+----------+
--   | foo  | very good   |       |    3     |
--   | bar  |             |  3.99 |          |
--   +------+-------------+-------+----------+
--   </pre>
--   
--   This record type has a single natural key on <tt>itemName</tt>. Let's
--   suppose that we download a CSV of new items to store into the
--   database. Here's our CSV:
--   
--   <pre>
--   name,description,price,quantity
--   foo,,2.50,6
--   bar,even better,,5
--   yes,wow,,
--   </pre>
--   
--   We parse that into a list of Haskell records:
--   
--   <pre>
--   records =
--     [ Item { itemName = "foo", itemDescription = ""
--            , itemPrice = Just 2.50, itemQuantity = Just 6
--            }
--     , Item "bar" "even better" Nothing (Just 5)
--     , Item "yes" "wow" Nothing Nothing
--     ]
--   </pre>
--   
--   The new CSV data is partial. It only includes <b>updates</b> from the
--   upstream vendor. Our CSV library parses the missing description field
--   as an empty string. We don't want to override the existing
--   description. So we can use the <a>copyUnlessEmpty</a> function to say:
--   "Don't update when the value is empty."
--   
--   Likewise, the new row for <tt>bar</tt> includes a quantity, but no
--   price. We do not want to overwrite the existing price in the database
--   with a <tt>NULL</tt> value. So we can use <a>copyUnlessNull</a> to
--   only copy the existing values in.
--   
--   The final code looks like this: <tt>
--   <a>insertManyOnDuplicateKeyUpdate</a> records [ <a>copyUnlessEmpty</a>
--   ItemDescription , <a>copyUnlessNull</a> ItemPrice ,
--   <a>copyUnlessNull</a> ItemQuantity ] [] </tt>
--   
--   Once we run that code on the datahase, the new data set looks like
--   this:
--   
--   <pre>
--   items:
--   +------+-------------+-------+----------+
--   | name | description | price | quantity |
--   +------+-------------+-------+----------+
--   | foo  | very good   |  2.50 |    6     |
--   | bar  | even better |  3.99 |    5     |
--   | yes  | wow         |       |          |
--   +------+-------------+-------+----------+
--   </pre>
insertManyOnDuplicateKeyUpdate :: forall record backend m. (backend ~ PersistEntityBackend record, BackendCompatible SqlBackend backend, PersistEntity record, MonadIO m) => [record] -> [HandleUpdateCollision record] -> [Update record] -> ReaderT backend m ()

-- | This type is used to determine how to update rows using MySQL's
--   <tt>INSERT ... ON DUPLICATE KEY UPDATE</tt> functionality, exposed via
--   <a>insertManyOnDuplicateKeyUpdate</a> in this library.
data HandleUpdateCollision record

-- | <i>Deprecated: The type SomeField is deprecated. Use the type
--   HandleUpdateCollision instead, and use the function copyField instead
--   of the data constructor.</i>

-- | An alias for <a>HandleUpdateCollision</a>. The type previously was
--   only used to copy a single value, but was expanded to be handle more
--   complex queries.

-- | <i>Deprecated: The type SomeField is deprecated. Use the type
--   HandleUpdateCollision instead, and use the function copyField instead
--   of the data constructor.</i>
type SomeField = HandleUpdateCollision

-- | Copy the field directly from the record.
copyField :: PersistField typ => EntityField record typ -> HandleUpdateCollision record

-- | Copy the field into the database only if the value in the
--   corresponding record is non-<tt>NULL</tt>.
--   
--   @since 2.6.2
copyUnlessNull :: PersistField typ => EntityField record (Maybe typ) -> HandleUpdateCollision record

-- | Copy the field into the database only if the value in the
--   corresponding record is non-empty, where "empty" means the Monoid
--   definition for <a>mempty</a>. Useful for <a>Text</a>, <a>String</a>,
--   <tt>ByteString</tt>, etc.
--   
--   The resulting <a>HandleUpdateCollision</a> type is useful for the
--   <a>insertManyOnDuplicateKeyUpdate</a> function.
--   
--   @since 2.6.2
copyUnlessEmpty :: (Monoid typ, PersistField typ) => EntityField record typ -> HandleUpdateCollision record

-- | Copy the field into the database only if the field is not equal to the
--   provided value. This is useful to avoid copying weird nullary data
--   into the database.
--   
--   The resulting <a>HandleUpdateCollision</a> type is useful for the
--   <a>insertManyOnDuplicateKeyUpdate</a> function.
--   
--   @since 2.6.2
copyUnlessEq :: PersistField typ => EntityField record typ -> typ -> HandleUpdateCollision record

-- | Set TLS ClientParams for <tt>MySQLConnectInfo</tt>.
setMySQLConnectInfoTLS :: ClientParams -> MySQLConnectInfo -> MySQLConnectInfo

-- | The whole point of TLS is that: a peer should have already trusted
--   some certificates, which can be used for validating other peer's
--   certificates. if the certificates sent by other side form a chain. and
--   one of them is issued by one of <a>TrustedCAStore</a>, Then the peer
--   will be trusted.
data TrustedCAStore :: *

-- | provided by your operating system.
SystemCAStore :: TrustedCAStore

-- | provided by <a>Mozilla</a>.
MozillaCAStore :: TrustedCAStore

-- | provided by your self, the CA file can contain multiple certificates.
CustomCAStore :: FilePath -> TrustedCAStore

-- | make a simple tls <a>ClientParams</a> that will validate server and
--   use tls connection without providing client's own certificate.
--   suitable for connecting server which don't validate clients.
--   
--   we defer setting of <a>clientServerIdentification</a> to connecting
--   phase.
--   
--   Note, tls's default validating method require server has v3
--   certificate. you can use openssl's V3 extension to issue such a
--   certificate. or change <a>ClientParams</a> before connecting.
makeClientParams :: TrustedCAStore -> IO ClientParams

-- | make a simple tls <a>ClientParams</a> that will validate server and
--   use tls connection while providing client's own certificate as well.
--   suitable for connecting server which validate clients.
--   
--   Also only accept v3 certificate.
makeClientParams' :: FilePath -> [FilePath] -> FilePath -> TrustedCAStore -> IO ClientParams

-- | Extract connection configs from <a>MySQLConf</a> @since 0.4.1
myConnInfo :: MySQLConf -> MySQLConnectInfo

-- | Extract connection pool size from <a>MySQLConf</a> @since 0.4.1
myPoolSize :: MySQLConf -> Int
instance GHC.Show.Show Database.Persist.MySQL.MySQLConf
instance GHC.Show.Show Database.Persist.MySQL.MySQLConnectInfo
instance Data.Aeson.Types.FromJSON.FromJSON Database.Persist.MySQL.MySQLConf
instance Database.Persist.Class.PersistConfig.PersistConfig Database.Persist.MySQL.MySQLConf
instance Database.MySQL.Query.QueryParam Database.Persist.MySQL.P
