-- 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 mysql-haskell 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:
--
--
-- - This package does not support statements inside other
-- statements.
--
@package persistent-mysql-haskell
@version 0.4.2
-- | A MySQL backend for persistent.
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 ConnectionPool 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 withMySQLPool, 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
-- withMySQLPool for automatic resource control.
createMySQLPool :: (MonadUnliftIO m, MonadLogger m, IsSqlBackend backend) => MySQLConnectInfo -> Int -> m (Pool backend)
-- | MySQL connection information.
data MySQLConnectInfo
-- | Public constructor for MySQLConnectInfo.
mkMySQLConnectInfo :: HostName -> ByteString -> ByteString -> ByteString -> MySQLConnectInfo
-- | Update port number for MySQLConnectInfo.
setMySQLConnectInfoPort :: PortNumber -> MySQLConnectInfo -> MySQLConnectInfo
-- | Update character set for MySQLConnectInfo.
setMySQLConnectInfoCharset :: Word8 -> MySQLConnectInfo -> MySQLConnectInfo
-- | Information required to connect to a MySQL database using
-- persistent's generic facilities. These values are the same
-- that are given to withMySQLPool.
data MySQLConf
-- | Public constructor for MySQLConf.
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 upsert_. 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.
--
--
--
-- The [HandleUpdateCollision] 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:
--
--
-- Item
-- name Text
-- description Text
-- price Double Maybe
-- quantity Int Maybe
--
-- Primary name
--
--
--
-- items:
-- +------+-------------+-------+----------+
-- | name | description | price | quantity |
-- +------+-------------+-------+----------+
-- | foo | very good | | 3 |
-- | bar | | 3.99 | |
-- +------+-------------+-------+----------+
--
--
-- This record type has a single natural key on itemName. Let's
-- suppose that we download a CSV of new items to store into the
-- database. Here's our CSV:
--
--
-- name,description,price,quantity
-- foo,,2.50,6
-- bar,even better,,5
-- yes,wow,,
--
--
-- We parse that into a list of Haskell records:
--
--
-- records =
-- [ Item { itemName = "foo", itemDescription = ""
-- , itemPrice = Just 2.50, itemQuantity = Just 6
-- }
-- , Item "bar" "even better" Nothing (Just 5)
-- , Item "yes" "wow" Nothing Nothing
-- ]
--
--
-- The new CSV data is partial. It only includes updates 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 copyUnlessEmpty function to say:
-- "Don't update when the value is empty."
--
-- Likewise, the new row for bar includes a quantity, but no
-- price. We do not want to overwrite the existing price in the database
-- with a NULL value. So we can use copyUnlessNull to
-- only copy the existing values in.
--
-- The final code looks like this:
-- insertManyOnDuplicateKeyUpdate records [ copyUnlessEmpty
-- ItemDescription , copyUnlessNull ItemPrice ,
-- copyUnlessNull ItemQuantity ] []
--
-- Once we run that code on the datahase, the new data set looks like
-- this:
--
--
-- items:
-- +------+-------------+-------+----------+
-- | name | description | price | quantity |
-- +------+-------------+-------+----------+
-- | foo | very good | 2.50 | 6 |
-- | bar | even better | 3.99 | 5 |
-- | yes | wow | | |
-- +------+-------------+-------+----------+
--
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
-- INSERT ... ON DUPLICATE KEY UPDATE functionality, exposed via
-- insertManyOnDuplicateKeyUpdate in this library.
data HandleUpdateCollision record
-- | Deprecated: The type SomeField is deprecated. Use the type
-- HandleUpdateCollision instead, and use the function copyField instead
-- of the data constructor.
-- | An alias for HandleUpdateCollision. The type previously was
-- only used to copy a single value, but was expanded to be handle more
-- complex queries.
-- | Deprecated: The type SomeField is deprecated. Use the type
-- HandleUpdateCollision instead, and use the function copyField instead
-- of the data constructor.
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-NULL.
--
-- @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 mempty. Useful for Text, String,
-- ByteString, etc.
--
-- The resulting HandleUpdateCollision type is useful for the
-- insertManyOnDuplicateKeyUpdate 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 HandleUpdateCollision type is useful for the
-- insertManyOnDuplicateKeyUpdate function.
--
-- @since 2.6.2
copyUnlessEq :: PersistField typ => EntityField record typ -> typ -> HandleUpdateCollision record
-- | Set TLS ClientParams for MySQLConnectInfo.
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 TrustedCAStore, Then the peer
-- will be trusted.
data TrustedCAStore
-- | provided by your operating system.
SystemCAStore :: TrustedCAStore
-- | provided by Mozilla.
MozillaCAStore :: TrustedCAStore
-- | provided by your self, the CA file can contain multiple certificates.
CustomCAStore :: FilePath -> TrustedCAStore
-- | make a simple tls ClientParams 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 clientServerIdentification 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 ClientParams before connecting.
makeClientParams :: TrustedCAStore -> IO ClientParams
-- | make a simple tls ClientParams 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 MySQLConf @since 0.4.1
myConnInfo :: MySQLConf -> MySQLConnectInfo
-- | Extract connection pool size from MySQLConf @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