HDBC-2.1.1: Haskell Database ConnectivitySource codeContentsIndex
MaintainerJohn Goerzen <jgoerzen@complete.org>

Types for HDBC.


Written by John Goerzen, jgoerzen@complete.org

class IConnection conn where
disconnect :: conn -> IO ()
commit :: conn -> IO ()
rollback :: conn -> IO ()
prepare :: conn -> String -> IO Statement
clone :: conn -> IO conn
hdbcDriverName :: conn -> String
hdbcClientVer :: conn -> String
proxiedClientName :: conn -> String
proxiedClientVer :: conn -> String
dbServerVer :: conn -> String
dbTransactionSupport :: conn -> Bool
getTables :: conn -> IO [String]
data Statement = Statement {
execute :: [SqlValue] -> IO Integer
finish :: IO ()
fetchRow :: IO (Maybe [SqlValue])
getColumnNames :: IO [String]
originalQuery :: String
describeResult :: IO [(String, SqlColDesc)]
data SqlError = SqlError {
seState :: String
seNativeError :: Int
seErrorMsg :: String
nToSql :: Integral a => a -> SqlValue
iToSql :: Int -> SqlValue
posixToSql :: POSIXTime -> SqlValue
fromSql :: Convertible SqlValue a => SqlValue -> a
safeFromSql :: Convertible SqlValue a => SqlValue -> ConvertResult a
toSql :: Convertible a SqlValue => a -> SqlValue
data SqlValue
= SqlString String
| SqlByteString ByteString
| SqlWord32 Word32
| SqlWord64 Word64
| SqlInt32 Int32
| SqlInt64 Int64
| SqlInteger Integer
| SqlChar Char
| SqlBool Bool
| SqlDouble Double
| SqlRational Rational
| SqlLocalDate Day
| SqlLocalTimeOfDay TimeOfDay
| SqlZonedLocalTimeOfDay TimeOfDay TimeZone
| SqlLocalTime LocalTime
| SqlZonedTime ZonedTime
| SqlUTCTime UTCTime
| SqlDiffTime NominalDiffTime
| SqlEpochTime Integer
| SqlTimeDiff Integer
| SqlNull
data ConnWrapper = forall conn . IConnection conn => ConnWrapper conn
class IConnection conn whereSource

Main database handle object.

An IConnection object is created by specific functions in the module for an individual database. That is, the connect function -- which creates this object -- is not standardized through the HDBC interface.

A connection is closed by a call to disconnect.

A call to commit is required to make sure that your changes get committed to the database. In other words, HDBC has no support for autocommit, which we consider an outdated notion.

disconnect :: conn -> IO ()Source

Disconnect from the remote database.

You do not need to explicitly close an IConnection object, but you may do so if you so desire. If you don't, the object will disconnect from the database in a sane way when it is garbage-collected. However, a disconnection may raise an error, so you are encouraged to explicitly call disconnect. Also, garbage collection may not run when the program terminates, and some databases really like an explicit disconnect.

So, bottom line is, you're best off calling disconnect directly, but the world won't end if you forget.

This function discards any data not committed already. Database driver implementators should explicitly call rollback if their databases don't do this automatically on disconnect.

Bad Things (TM) could happen if you call this while you have Statements active. In more precise language, the results in such situations are undefined and vary by database. So don't do it.

commit :: conn -> IO ()Source

Commit any pending data to the database.

Required to make any changes take effect.

rollback :: conn -> IO ()Source
Roll back to the state the database was in prior to the last commit or rollback.
run :: conn -> String -> [SqlValue] -> IO IntegerSource
Execute a single SQL query. Returns the number of rows modified (see execute for details). The second parameter is a list of replacement values, if any.
prepare :: conn -> String -> IO StatementSource

Prepares a statement for execution.

Question marks in the statement will be replaced by positional parameters in a later call to execute.

Please note that, depending on the database and the driver, errors in your SQL may be raised either here or by execute. Make sure you handle exceptions both places if necessary.

clone :: conn -> IO connSource

Create a new Connection object, pointed at the same server as this object is. This will generally establish a separate physical connection.

When you wish to establish multiple connections to a single server, the correct way to do so is to establish the first connection with the driver-specific connection function, and then clone it for each additional connection.

This can be important when a database doesn't provide much thread support itself, and the HDBC driver module must serialize access to a particular database.

This can also be a handy utility function whenever you need a separate connection to whatever database you are connected to already.

hdbcDriverName :: conn -> StringSource
The name of the HDBC driver module for this connection. Ideally would be the same as the database name portion of the Cabal package name. For instance, "sqlite3" or "odbc". This is the layer that is bound most tightly to HDBC.
hdbcClientVer :: conn -> StringSource
The version of the C (or whatever) client library that the HDBC driver module is bound to. The meaning of this is driver-specific. For an ODBC or similar proxying driver, this should be the version of the ODBC library, not the eventual DB client driver.
proxiedClientName :: conn -> StringSource
In the case of a system such as ODBC, the name of the database client/server in use, if available. For others, identical to hdbcDriverName.
proxiedClientVer :: conn -> StringSource
In the case of a system such as ODBC, the version of the database client in use, if available. For others, identical to hdbcClientVer. This is the next layer out past the HDBC driver.
dbServerVer :: conn -> StringSource
The version of the database server, if available.
dbTransactionSupport :: conn -> BoolSource

Whether or not the current database supports transactions. If False, then commit and rollback should be expected to raise errors.

MySQL is the only commonly-used database that is known to not support transactions entirely. Please see the MySQL notes in the ODBC driver for more information.

getTables :: conn -> IO [String]Source

The names of all tables accessible by the current connection, excluding special meta-tables (system tables).




Obtain information about the columns in a specific table. The String in the result set is the column name.



show/hide Instances
data Statement Source
execute :: [SqlValue] -> IO Integer



For SELECT queries, you will always get 0.





This is most useful for non-SELECT statements.

finish :: IO ()Abort a query in progress -- usually not needed.
fetchRow :: IO (Maybe [SqlValue])Fetches one row from the DB. Returns Nothing if there are no more rows. Will automatically call finish when the last row is read.
getColumnNames :: IO [String]




originalQuery :: StringThe original query that this Statement was prepared with.
describeResult :: IO [(String, SqlColDesc)]





data SqlError Source



seState :: String
seNativeError :: Int
seErrorMsg :: String
show/hide Instances
nToSql :: Integral a => a -> SqlValueSource
Converts any Integral type to a SqlValue by using toInteger.
iToSql :: Int -> SqlValueSource
Convenience function for using numeric literals in your program.
posixToSql :: POSIXTime -> SqlValueSource
fromSql :: Convertible SqlValue a => SqlValue -> aSource

Conversions to and from SqlValues and standard Haskell types.


toSql :: Convertible a SqlValue => a -> SqlValueSource
data SqlValue Source









Here are some notes about conversion:

  • Fractions of a second are not preserved on time values
  • There is no safeToSql because toSql never fails.

















  • Both are NULL





SqlString String
SqlByteString ByteString
SqlWord32 Word32
SqlWord64 Word64
SqlInt32 Int32
SqlInt64 Int64
SqlInteger Integer
SqlChar Char
SqlBool Bool
SqlDouble Double
SqlRational Rational
SqlLocalDate DayLocal YYYY-MM-DD (no timezone)
SqlLocalTimeOfDay TimeOfDayLocal HH:MM:SS (no timezone)
SqlZonedLocalTimeOfDay TimeOfDay TimeZoneLocal HH:MM:SS -HHMM. Converts to and from (TimeOfDay, TimeZone).
SqlLocalTime LocalTimeLocal YYYY-MM-DD HH:MM:SS (no timezone)
SqlZonedTime ZonedTimeLocal YYYY-MM-DD HH:MM:SS -HHMM. Considered equal if both convert to the same UTC time.
SqlPOSIXTime POSIXTimeTime as seconds since midnight Jan 1 1970 UTC. Integer rendering as for SqlDiffTime.
SqlEpochTime IntegerDEPRECATED Representation of ClockTime or CalendarTime. Use SqlPOSIXTime instead.
SqlTimeDiff IntegerDEPRECATED Representation of TimeDiff. Use SqlDiffTime instead.
SqlNullNULL in SQL or Nothing in Haskell
show/hide Instances
Eq SqlValue
Show SqlValue
Typeable SqlValue
Convertible Bool SqlValue
Convertible Char SqlValue
Convertible Double SqlValue
Convertible Int SqlValue
Convertible Int32 SqlValue
Convertible Int64 SqlValue
Convertible Integer SqlValue
Convertible Rational SqlValue
Convertible Word32 SqlValue
Convertible Word64 SqlValue
Convertible String SqlValue
Convertible ByteString SqlValue
Convertible ByteString SqlValue
Convertible ClockTime SqlValue
Convertible CalendarTime SqlValue
Convertible TimeDiff SqlValue
Convertible LocalTime SqlValue
Convertible ZonedTime SqlValue
Convertible TimeOfDay SqlValue
Convertible UTCTime SqlValue
Convertible NominalDiffTime SqlValue
Convertible Day SqlValue
Convertible DiffTime SqlValue
Convertible SqlValue Bool
Convertible SqlValue Char
Convertible SqlValue Double
Convertible SqlValue Int
Convertible SqlValue Int32
Convertible SqlValue Int64
Convertible SqlValue Integer
Convertible SqlValue Rational
Convertible SqlValue Word32
Convertible SqlValue Word64
Convertible SqlValue String
Convertible SqlValue ByteString
Convertible SqlValue ByteString
Convertible SqlValue ClockTime
Convertible SqlValue CalendarTime
Convertible SqlValue TimeDiff
Convertible SqlValue LocalTime
Convertible SqlValue ZonedTime
Convertible SqlValue TimeOfDay
Convertible SqlValue UTCTime
Convertible SqlValue NominalDiffTime
Convertible SqlValue Day
Convertible SqlValue DiffTime
Convertible SqlValue a => Convertible SqlValue (Maybe a)
Convertible SqlValue (TimeOfDay, TimeZone)
Convertible a SqlValue => Convertible (Maybe a) SqlValue
Convertible (TimeOfDay, TimeZone) SqlValue
data ConnWrapper Source

Sometimes, it is annoying to use typeclasses with Haskell's type system. In those situations, you can use a ConnWrapper. You can create one with:

let wrapped = ConnWrapper iconn

You can then use this directly, since a ConnWrapper is also an IConnection. However, you will not be able to use private database functions on it.

Or, you can use withWConn.

forall conn . IConnection conn => ConnWrapper conn
show/hide Instances

Unwrap a ConnWrapper and pass the embedded IConnection to a function. Example:

Produced by Haddock version 2.7.2