Database.HDBC.MySQL

HDBC-mysql-0.7.1.0: MySQL driver for HDBC

Copyright | Copyright (c) 2009-2010 Chris Waterson
License | LGPL
Maintainer | bos@serpentine.com
Stability | experimental
Portability | GHC
Safe Haskell | None
Language | Haskell2010

Database.HDBC.MySQL

Description

This module provides a MySQL driver for the HDBC database interface. To use it, invoke the `connectMySQL` method to create an `Database.HDBC.IConnection` that you can use to interact with a MySQL database. Use the `defaultMySQLConnectInfo`, overriding the default values as necessary.

    import Control.Monad
    import Database.HDBC
    import Database.HDBC.MySQL

    main = do
      rows <- withRTSSignalsBlocked $ do
        conn <- connectMySQL defaultMySQLConnectInfo {
                  mysqlHost     = "db1.example.com",
                  mysqlUser     = "scott",
                  mysqlPassword = "tiger"
                }
        quickQuery' conn "SELECT 1 + 1" []
      forM_ rows $ \row -> putStrLn $ show row

There are some important caveats to note about this driver.

- RTS signals. If you are writing an application that links against GHC's threaded runtime (as most server-side applications do), you must use `withRTSSignalsBlocked` to defend the `mysqlclient` library against the signals the RTS uses, or you may experience crashes.
- 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, it is up to you to make sure that you use a MySQL engine that supports transactions.
- Dates and times. MySQL does not store time zone information in `DATETIME` or `TIMESTAMP` 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.

Synopsis

- data MySQLConnectInfo = MySQLConnectInfo {
  - mysqlHost :: String
  - mysqlUser :: String
  - mysqlPassword :: String
  - mysqlDatabase :: String
  - mysqlPort :: Int
  - mysqlUnixSocket :: String
  - mysqlGroup :: Maybe String
  }
- data Connection
- connectMySQL :: MySQLConnectInfo -> IO Connection
- defaultMySQLConnectInfo :: MySQLConnectInfo
- withRTSSignalsBlocked :: IO a -> IO a

# Documentation

data MySQLConnectInfo

Connection information to use with connectMySQL.

You must either supply a host and port, or the full path to a Unix socket.

Constructors

MySQLConnectInfo |
Fields mysqlHost :: String The server's hostname; e.g., `"db1.example.com"` mysqlUser :: String The MySQL username to use for login; e.g., `"scott"` mysqlPassword :: String The MySQL password to use for login; e.g., `"tiger"` mysqlDatabase :: String the "default" database name; e.g., `"emp"` mysqlPort :: Int The port on which to connect to the server; e.g., `3306` mysqlUnixSocket :: String The absolute path of the server's Unix socket; e.g., `"/var/lib/mysql.sock"` mysqlGroup :: Maybe String The group name in my.cnf from which it reads options; e.g., `"test"`

data Connection

Instances

IConnection Connection |

connectMySQL :: MySQLConnectInfo -> IO Connection

Connects to a MySQL database using the specified connection information.

defaultMySQLConnectInfo :: MySQLConnectInfo

Typical connection information, meant to be overridden partially, for example:

    connectMySQL defaultMySQLConnectInfo { mysqlHost = "db1" }

In particular, the default values are `"127.0.0.1"` as the host, `3306` as the port, `"root"` as the user, no password, and `"test"` as the default database.

withRTSSignalsBlocked :: IO a -> IO a

Execute an `IO` action with signals used by GHC's runtime signals blocked. The `mysqlclient` 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 `-threaded` option).

This function blocks `SIGALRM` and `SIGVTALRM`, 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:

     SqlError {
       seState = "",
       seNativeError = 2003,
       seErrorMsg = "Can't connect to MySQL server on 'localhost' (4)"
     }