Copyright | (c) 2011 MailRank, Inc. |
---|---|
License | BSD3 |
Maintainer | Paul Rouse <pyr@doynton.org> |
Stability | experimental |
Portability | portable |
Safe Haskell | None |
Language | Haskell98 |
A low-level client library for the MySQL database, implemented as
bindings to the C mysqlclient
API.
The C library is thread-safe, but uses thread-local state. Therefore,
if these bindings are used in a multi-threaded program, "bound" threads
should be used (see Control.Concurrent). In addition, explicit calls
to initLibrary
, and possibly initThread
and endThread
may be needed
in a multi-threaded program.
- data ConnectInfo = ConnectInfo {}
- data SSLInfo = SSLInfo {}
- type Seconds = Word
- data Protocol
- data Option
- = ConnectTimeout Seconds
- | Compress
- | NamedPipe
- | InitCommand ByteString
- | ReadDefaultFile FilePath
- | ReadDefaultGroup ByteString
- | CharsetDir FilePath
- | CharsetName String
- | LocalInFile Bool
- | Protocol Protocol
- | SharedMemoryBaseName ByteString
- | ReadTimeout Seconds
- | WriteTimeout Seconds
- | UseRemoteConnection
- | UseEmbeddedConnection
- | GuessConnection
- | ClientIP ByteString
- | SecureAuth Bool
- | ReportDataTruncation Bool
- | Reconnect Bool
- | SSLVerifyServerCert Bool
- | FoundRows
- | IgnoreSIGPIPE
- | IgnoreSpace
- | Interactive
- | LocalFiles
- | MultiResults
- | MultiStatements
- | NoSchema
- defaultConnectInfo :: ConnectInfo
- defaultSSLInfo :: SSLInfo
- data Connection
- data Result
- data Type
- data Row
- data MySQLError
- connect :: ConnectInfo -> IO Connection
- close :: Connection -> IO ()
- autocommit :: Connection -> Bool -> IO ()
- ping :: Connection -> IO ()
- changeUser :: Connection -> String -> String -> Maybe String -> IO ()
- selectDB :: Connection -> String -> IO ()
- setCharacterSet :: Connection -> String -> IO ()
- threadId :: Connection -> IO Word
- serverInfo :: Connection -> IO String
- hostInfo :: Connection -> IO String
- protocolInfo :: Connection -> IO Word
- characterSet :: Connection -> IO String
- sslCipher :: Connection -> IO (Maybe String)
- serverStatus :: Connection -> IO String
- query :: Connection -> ByteString -> IO ()
- insertID :: Connection -> IO Word64
- escape :: Connection -> ByteString -> IO ByteString
- fieldCount :: Either Connection Result -> IO Int
- affectedRows :: Connection -> IO Int64
- isResultValid :: Result -> IO Bool
- freeResult :: Result -> IO ()
- storeResult :: Connection -> IO Result
- useResult :: Connection -> IO Result
- fetchRow :: Result -> IO [Maybe ByteString]
- fetchFields :: Result -> IO [Field]
- dataSeek :: Result -> Int64 -> IO ()
- rowSeek :: Result -> Row -> IO Row
- rowTell :: Result -> IO Row
- nextResult :: Connection -> IO Bool
- commit :: Connection -> IO ()
- rollback :: Connection -> IO ()
- clientInfo :: String
- clientVersion :: Word
- initLibrary :: IO ()
- initThread :: IO ()
- endThread :: IO ()
Licensing
Important licensing note: This library is BSD-licensed under the terms of the MySQL FOSS License Exception http://www.mysql.com/about/legal/licensing/foss-exception/.
Since this library links against the GPL-licensed mysqlclient
library, a non-open-source application that uses it may be
subject to the terms of the GPL.
data ConnectInfo Source
ConnectInfo | |
|
defaultConnectInfo :: ConnectInfo Source
Default information for setting up a connection.
Defaults are as follows:
- Server on
localhost
- User
root
- No password
- Database
test
- Character set
utf8
Use as in the following example:
connect defaultConnectInfo { connectHost = "db.example.com" }
defaultSSLInfo :: SSLInfo Source
Default (empty) information for setting up an SSL connection.
data Connection Source
Connection to a MySQL database.
Column types supported by MySQL.
data MySQLError Source
The constructors of MySQLError
are not currently exported, but they
have a consistent set of field names which are exported. These fields are:
errFunction :: String errNumber :: Int errMessage :: String
Connection management
connect :: ConnectInfo -> IO Connection Source
Connect to a database.
close :: Connection -> IO () Source
Close a connection, and mark any outstanding Result
as
invalid.
autocommit :: Connection -> Bool -> IO () Source
Turn autocommit on or off.
By default, MySQL runs with autocommit mode enabled. In this mode, as soon as you modify a table, MySQL stores your modification permanently.
ping :: Connection -> IO () Source
changeUser :: Connection -> String -> String -> Maybe String -> IO () Source
selectDB :: Connection -> String -> IO () Source
setCharacterSet :: Connection -> String -> IO () Source
Connection information
threadId :: Connection -> IO Word Source
serverInfo :: Connection -> IO String Source
hostInfo :: Connection -> IO String Source
protocolInfo :: Connection -> IO Word Source
characterSet :: Connection -> IO String Source
serverStatus :: Connection -> IO String Source
Querying
query :: Connection -> ByteString -> IO () Source
insertID :: Connection -> IO Word64 Source
Return the value generated for an AUTO_INCREMENT
column by the
previous INSERT
or UPDATE
statement.
See http://dev.mysql.com/doc/refman/5.5/en/mysql-insert-id.html
Escaping
escape :: Connection -> ByteString -> IO ByteString Source
Results
fieldCount :: Either Connection Result -> IO Int Source
Return the number of fields (columns) in a result.
- If
Left
Connection
, returns the number of columns for the most recent query on the connection. - For
Right
Result
, returns the number of columns in each row of this result.
The number of columns may legitimately be zero.
affectedRows :: Connection -> IO Int64 Source
Working with results
isResultValid :: Result -> IO Bool Source
Check whether a Result
is still valid, i.e. backed by a live
MYSQL_RES
value.
freeResult :: Result -> IO () Source
Immediately free the MYSQL_RES
value associated with this
Result
, and mark the Result
as invalid.
storeResult :: Connection -> IO Result Source
Retrieve a complete result.
Any previous outstanding Result
is first marked as invalid.
useResult :: Connection -> IO Result Source
Initiate a row-by-row retrieval of a result.
Any previous outstanding Result
is first marked as invalid.
fetchFields :: Result -> IO [Field] Source
Multiple results
nextResult :: Connection -> IO Bool Source
Transactions
commit :: Connection -> IO () Source
Commit the current transaction.
rollback :: Connection -> IO () Source
Roll back the current transaction.
General information
Concurrency
initLibrary :: IO () Source
Call mysql_library_init
A single-threaded program can rely on an implicit initialisation done
when making the first connection, but a multi-threaded one should call
initLibrary
separately, and it should be done before other threads
might call into this library, since this function is not thread-safe.
See https://ro-che.info/articles/2015-04-17-safe-concurrent-mysql-haskell
and https://dev.mysql.com/doc/refman/5.7/en/c-api-threaded-clients.html
for details.
initThread :: IO () Source
Call mysql_thread_init
Again a single-threaded program does not need to call this explicitly. Even
in a multi-threaded one, if each connection is made, used, and destroyed
in a single thread, it is sufficient to rely on the connect
call to do
an implicit thread initialisation. But in other cases, for example when
using a connection pool, each thread requires explicit initialisation.
See https://ro-che.info/articles/2015-04-17-safe-concurrent-mysql-haskell
and https://dev.mysql.com/doc/refman/5.7/en/c-api-threaded-clients.html
for details.
Call mysql_thread_end
This is needed at thread exit to avoid a memory leak, except when using
a non-debug build of at least version 5.7.9 of the MySQL library.
See https://dev.mysql.com/doc/refman/5.7/en/mysql-thread-end.html.
The threads in question are the OS threads, so calling this function
is likely to be important when using large numbers of bound threads (see
Control.Concurrent). Unbound threads - those created with forkIO
and
friends - share a small number of OS threads, so in those it is hard to
call this function safely, and there is little benefit in doing so, but in
any case using this library in unbound threads is not recommended (see
https://ro-che.info/articles/2015-04-17-safe-concurrent-mysql-haskell).