Database.MySQL.Base

This module provide common MySQL operations,

NOTEs on Exceptions: This package use Exception to deal with unexpected situations, but you shouldn't try to catch them if you don't have a recovery plan, for example: there's no meaning to catch a ERRException during authentication unless you want to try different passwords. By using this library you will meet:

• NetworkException: underline network is broken.
• UnconsumedResultSet: you should consume previous resultset before sending new command.
• ERRException: you receive a ERR packet when you shouldn't.
• UnexpectedPacket: you receive a unexpected packet when you shouldn't.
• DecodePacketException: there's a packet we can't decode.
• WrongParamsCount: you're giving wrong number of params to renderParams.

Both UnexpectedPacket and DecodePacketException may indicate a bug of this library rather your code, so please report!

Setting up and control connection

data MySQLConn

data ConnectInfo

Everything you need to establish a MySQL connection.

You may want some helpers in System.IO.Streams.TLS to setup TLS connection.

Constructors

ConnectInfo

Fields

ciHost :: HostName

ciPort :: PortNumber

ciDatabase :: ByteString

ciUser :: ByteString

ciPassword :: ByteString

ciTLSInfo :: Maybe (ClientParams, String)

If ClientParams and subject name are provided, TLS connection will be used.

Instances

Show ConnectInfo

defaultConnectInfo :: ConnectInfo

A simple ConnectInfo targeting localhost with user=root and empty password.

connect :: ConnectInfo -> IO MySQLConn

Establish a MySQL connection.

connectDetail :: ConnectInfo -> IO (Greeting, MySQLConn)

Establish a MySQL connection with Greeting back, so you can find server's version .etc.

close :: MySQLConn -> IO ()

Close a MySQL connection.

ping :: MySQLConn -> IO OK

Send a COM_PING.

direct query

execute :: MySQLConn -> Query -> [MySQLValue] -> IO OK

Execute a MySQL query with parameters which don't return a resultSet.

The query may contain placeholders ?, for filling up parameters, the parameters will be escaped before get filled into the query, please DO NOT enable NO_BACKSLASH_ESCAPES, and you should consider using prepared statement if this's not an one shot query.

execute_ :: MySQLConn -> Query -> IO OK

Execute a MySQL query which don't return a resultSet.

query_ :: MySQLConn -> Query -> IO ([ColumnDef], InputStream [MySQLValue])

Execute a MySQL query which return a resultSet.

query :: MySQLConn -> Query -> [MySQLValue] -> IO ([ColumnDef], InputStream [MySQLValue])

Execute a MySQL query which return a result-set with parameters.

Note that you must fully consumed the result-set before start a new query on the same MySQLConn, or an UnconsumedResultSet will be thrown. if you want to skip the result-set, use skipToEof.

prepared query statement

prepareStmt :: MySQLConn -> Query -> IO StmtID

Ask MySQL to prepare a query statement.

prepareStmtDetail :: MySQLConn -> Query -> IO (StmtPrepareOK, [ColumnDef], [ColumnDef])

Ask MySQL to prepare a query statement.

All details from COM_STMT_PREPARE Response are returned: the StmtPrepareOK packet, params's ColumnDef, table's ColumnDef.

executeStmt :: MySQLConn -> StmtID -> [MySQLValue] -> IO OK

Execute prepared query statement with parameters, expecting no resultset.

queryStmt :: MySQLConn -> StmtID -> [MySQLValue] -> IO ([ColumnDef], InputStream [MySQLValue])

Execute prepared query statement with parameters, expecting resultset.

Rules about UnconsumedResultSet applied here too.

closeStmt :: MySQLConn -> StmtID -> IO ()

Ask MySQL to closed a query statement.

resetStmt :: MySQLConn -> StmtID -> IO ()

Ask MySQL to reset a query statement, all previous resultset will be cleared.

MySQL protocol

module Database.MySQL.Protocol.Auth

module Database.MySQL.Protocol.Command

module Database.MySQL.Protocol.ColumnDef

module Database.MySQL.Protocol.Packet

module Database.MySQL.Protocol.MySQLValue

helpers

newtype Query

Query string type borrowed from mysql-simple.

This type is intended to make it difficult to construct a SQL query by concatenating string fragments, as that is an extremely common way to accidentally introduce SQL injection vulnerabilities into an application.

This type is an instance of IsString, so the easiest way to construct a query is to enable the OverloadedStrings language extension and then simply write the query in double quotes.

The underlying type is a ByteString, and literal Haskell strings that contain Unicode characters will be correctly transformed to UTF-8.

Constructors

Query

Fields

fromQuery :: ByteString

Instances

Eq Query

Ord Query

Read Query

Show Query

IsString Query

renderParams :: Query -> [MySQLValue] -> Query

command :: MySQLConn -> Command -> IO OK

Send a Command which don't return a resultSet.

skipToEof :: InputStream a -> IO ()