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


-- | MySQL driver for HDBC
--   
--   This package provides a MySQL driver for HDBC, implemented via
--   bindings to the C <tt>mysqlclient</tt> library.
@package HDBC-mysql
@version 0.7.1.0


-- | This module provides a MySQL driver for the HDBC database interface.
--   To use it, invoke the <a>connectMySQL</a> method to create an
--   <tt>Database.HDBC.IConnection</tt> that you can use to interact with a
--   MySQL database. Use the <a>defaultMySQLConnectInfo</a>, overriding the
--   default values as necessary.
--   
--   <pre>
--   import Control.Monad
--   import Database.HDBC
--   import Database.HDBC.MySQL
--   
--   main = do
--     rows &lt;- <a>withRTSSignalsBlocked</a> $ do
--       conn &lt;- <a>connectMySQL</a> <a>defaultMySQLConnectInfo</a> {
--                 <a>mysqlHost</a>     = "db1.example.com",
--                 <a>mysqlUser</a>     = "scott",
--                 <a>mysqlPassword</a> = "tiger"
--               }
--       <tt>quickQuery'</tt> conn "SELECT 1 + 1" []
--     forM_ rows $ \row -&gt; putStrLn $ show row
--   </pre>
--   
--   There are some important caveats to note about this driver.
--   
--   <ul>
--   <li>RTS signals. If you are writing an application that links against
--   GHC's threaded runtime (as most server-side applications do), you must
--   use <a>withRTSSignalsBlocked</a> to defend the <tt>mysqlclient</tt>
--   library against the signals the RTS uses, or you may experience
--   crashes.</li>
--   <li>Transaction support. The MySQL server supports a variety of
--   backend "engines", only some of which support transactional access
--   (e.g., InnoDB). This driver will report that the database supports
--   transactions. Should you decide to make use of the transactional
--   support in the HDBC API, <i>it is up to you to make sure that you use
--   a MySQL engine that supports transactions</i>.</li>
--   <li>Dates and times. MySQL does not store time zone information in
--   <tt>DATETIME</tt> or <tt>TIMESTAMP</tt> columns: instead, it assumes
--   that all dates are stored in the "server's time zone". At some point
--   in the future, this driver may query for the server's time zone and
--   apply appropriate time zone conversion to these datatypes. For now, it
--   simply treats all times as UTC; i.e., it assumes the server's time
--   zone is UTC.</li>
--   </ul>
module Database.HDBC.MySQL

-- | Connection information to use with connectMySQL.
--   
--   You must either supply a host and port, or the full path to a Unix
--   socket.
data MySQLConnectInfo
MySQLConnectInfo :: String -> String -> String -> String -> Int -> String -> Maybe String -> MySQLConnectInfo

-- | The server's hostname; e.g., <tt>"db1.example.com"</tt>
[mysqlHost] :: MySQLConnectInfo -> String

-- | The MySQL username to use for login; e.g., <tt>"scott"</tt>
[mysqlUser] :: MySQLConnectInfo -> String

-- | The MySQL password to use for login; e.g., <tt>"tiger"</tt>
[mysqlPassword] :: MySQLConnectInfo -> String

-- | the "default" database name; e.g., <tt>"emp"</tt>
[mysqlDatabase] :: MySQLConnectInfo -> String

-- | The port on which to connect to the server; e.g., <tt>3306</tt>
[mysqlPort] :: MySQLConnectInfo -> Int

-- | The absolute path of the server's Unix socket; e.g.,
--   <tt>"/var/lib/mysql.sock"</tt>
[mysqlUnixSocket] :: MySQLConnectInfo -> String

-- | The group name in my.cnf from which it reads options; e.g.,
--   <tt>"test"</tt>
[mysqlGroup] :: MySQLConnectInfo -> Maybe String
data Connection

-- | Connects to a MySQL database using the specified connection
--   information.
connectMySQL :: MySQLConnectInfo -> IO Connection

-- | Typical connection information, meant to be overridden partially, for
--   example:
--   
--   <pre>
--   connectMySQL defaultMySQLConnectInfo { mysqlHost = "db1" }
--   </pre>
--   
--   In particular, the default values are <tt>"127.0.0.1"</tt> as the
--   host, <tt>3306</tt> as the port, <tt>"root"</tt> as the user, no
--   password, and <tt>"test"</tt> as the default database.
defaultMySQLConnectInfo :: MySQLConnectInfo

-- | Execute an <a>IO</a> action with signals used by GHC's runtime signals
--   blocked. The <tt>mysqlclient</tt> C library does not correctly restart
--   system calls if they are interrupted by signals, so many MySQL API
--   calls can unexpectedly fail when called from a Haskell application.
--   This is most likely to occur if you are linking against GHC's threaded
--   runtime (using the <tt>-threaded</tt> option).
--   
--   This function blocks <tt>SIGALRM</tt> and <tt>SIGVTALRM</tt>, runs
--   your action, then unblocks those signals. If you have a series of HDBC
--   calls that may block for a period of time, it may be wise to wrap them
--   in this action. Blocking and unblocking signals is cheap, but not
--   free.
--   
--   Here is an example of an exception that could be avoided by
--   temporarily blocking GHC's runtime signals:
--   
--   <pre>
--   SqlError {
--     seState = "", 
--     seNativeError = 2003, 
--     seErrorMsg = "Can't connect to MySQL server on 'localhost' (4)"
--   }
--   </pre>
withRTSSignalsBlocked :: IO a -> IO a
