Database.HDBI.Types

Types for HDBI.

Written by John Goerzen, [e-mail]

Typeclasses

class (Typeable conn, Statement (ConnStatement conn)) => Connection conn where

Typeclass to abstract the working with connection.

Associated Types

type ConnStatement conn :: *

Specific statement for specific connection

Methods

disconnect :: conn -> IO ()

Disconnection from the database. Every opened statement must be finished after this method executed.

begin :: conn -> IO ()

Explicitly start the transaction. Without starting the transaction you can not commit or rollback it. HDBI does not check if transaction started or not, this is the application's resposibility.

This is not recomended to use start by hands, use withTransaction instead

commit :: conn -> IO ()

Explicitly commit started transaction. You must start the transaction before commit

This is not recomended to use commit by hands, use withTransaction instead

rollback :: conn -> IO ()

Rollback the transaction's state. You must start the transaction before rollback

This is not recomended to use rollback by hands, use withTransaction instead

inTransaction :: conn -> IO Bool

Check if current connection is in transaction state. Return True if transaction is started. Each driver implements it with it's own way: some RDBMS has API to check transaction state (like PostgreSQL), some has no (like Sqlite3).

connStatus :: conn -> IO ConnStatus

Return the current status of connection

prepare :: conn -> Query -> IO (ConnStatement conn)

Prepare the statement. Some databases has no feature of preparing statements (PostgreSQL can just prepare named statements), so each driver behaves it's own way.

run :: ToRow row => conn -> Query -> row -> IO ()

Run query and safely finalize statement after that. Has default implementation through execute.

runMany :: ToRow row => conn -> Query -> [row] -> IO ()

Execute query with set of parameters. Has default implementation through executeMany.

runRaw :: conn -> Query -> IO ()

Run raw query. Many databases has an ablility to run a raw queries separated by semicolon. Implementation of this method must use this ability. Has default implementation through run

clone :: conn -> IO conn

Clone the database connection. Return new connection with the same settings

hdbiDriverName :: conn -> String

The name of the HDBI driver module for this connection. Ideally would be the same as the database name portion of the Cabal package name. For instance, "sqlite3" or "postgresql". This is the layer that is bound most tightly to HDBI

dbTransactionSupport :: conn -> Bool

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

Instances

Connection ConnWrapper

class Typeable stmt => Statement stmt where

Statement prepared on database side or just in memory

Methods

execute :: ToRow row => stmt -> row -> IO ()

Execute single query with parameters. In query each parameter must be replaced with ''?'' placeholder. This rule is true for every database, even for PostgreSQL which uses placeholders like ''$1''. Application must ensure that the count of placeholders is equal to count of parameter, it is likely cause an error if it is not.

executeMany :: ToRow row => stmt -> [row] -> IO ()

Execute one query many times with a list of paramters. Has default implementation through execute.

statementStatus :: stmt -> IO StatementStatus

Return the current statement's status.

finish :: stmt -> IO ()

Finish statement and remove database-specific pointer. No any actions may be proceeded after closing the statement, excpet statementStatus which will return StatementFinished and reset.

reset :: stmt -> IO ()

Reset statement to it's initial state, just like after prepare.

fetch :: FromRow row => stmt -> IO (Maybe row)

Fetch next row from the executed statement. Return Nothing when there is no more results acceptable. Each call return next row from the result.

UPDATE INSERT and DELETE queries will likely return Nothing.

NOTE: You still need to explicitly finish the statement after receiving Nothing, unlike with old HDBC interface.

fetchAll :: FromRow row => stmt -> IO (Seq row)

Optional method to strictly fetch all rows from statement. Has default implementation through fetch.

getColumnNames :: stmt -> IO [Text]

Return list of column names of the result.

getColumnsCount :: stmt -> IO Int

Return the number of columns representing the result. Has default implementation through getColumnNames

originalQuery :: stmt -> Query

Return the original query the statement was prepared from.

Instances

Statement StmtWrapper

Data types

newtype Query

safe newtype wrapper for queries. Just lazy Text inside.

Constructors

Query

Fields

unQuery :: Text

Unwrap query to lazy Text

Instances

Eq Query

Data Query

Ord Query

Read Query

Show Query

Typeable Query

IsString Query

Monoid Query

NFData Query

data ConnStatus

Connection status

Constructors

ConnOK

Successfully connected

ConnDisconnected

Successfully disconnected, all statements must be closed at this state

ConnBad

Connection is in some bad state

Instances

Eq ConnStatus

Read ConnStatus

Show ConnStatus

Typeable ConnStatus

data ConnWrapper

Wrapps the specific connection. You can write database-independent code mixing it with database-dependent using castConnection function to cast Wrapper to specific connection type, if you need.

Constructors

forall conn . Connection conn => ConnWrapper conn

Instances

Typeable ConnWrapper

Connection ConnWrapper

data StatementStatus

Statement's status returning by function statementStatus.

Constructors

StatementNew

Newly created statement

StatementExecuted

Expression executed, now you can fetch the rows Statement

StatementFetched

Fetching is done, no more rows can be queried

StatementFinished

Finished, no more actions with this statement

Instances

Eq StatementStatus

Read StatementStatus

Show StatementStatus

Typeable StatementStatus

data StmtWrapper

Wrapper around some specific Statement instance to write database-independent code

Constructors

forall stmt . Statement stmt => StmtWrapper stmt

Instances

Typeable StmtWrapper

Statement StmtWrapper

data SqlError

Error throwing by driver when database operation fails

Constructors

SqlError

Internal database error

Fields

seErrorCode :: String

Low level database-specific error code

seErrorMsg :: String

Error description

Error description from the database client library

SqlDriverError

Driver-specific operational error

Fields

seErrorMsg :: String

Error description

Error description from the database client library

Instances

Eq SqlError

Show SqlError

Typeable SqlError

Exception SqlError

Auxiliary functions

castConnection :: Connection conn => ConnWrapper -> Maybe conn

Cast wrapped connection to the specific connection type using cast of Typeable. You can write database-specific code safely casting wrapped connection to specific type dynamically.

castStatement :: Statement stmt => StmtWrapper -> Maybe stmt

Cast wrapped statement to specific type. You can write database-specific code safely casting wrapped statement to specific type dynamically.

withTransaction :: Connection conn => conn -> IO a -> IO a

Execute some code. If any uncaught exception occurs, run rollback and re-raise it. Otherwise, run commit and return.

This function, therefore, encapsulates the logical property that a transaction is all about: all or nothing.

The Connection object passed in is passed directly to the specified function as a convenience.

This function traps all uncaught exceptions, not just SqlError. Therefore, you will get a rollback for any exception that you don't handle. That's probably what you want anyway.

If there was an error while running rollback, this error will not be reported since the original exception will be propogated back. (You'd probably like to know about the root cause for all of this anyway.) Feedback on this behavior is solicited.

withStatement

Arguments

:: (Connection conn, Statement stmt, stmt ~ ConnStatement conn)

=> conn

Connection

-> Query

Query string

-> (stmt -> IO a)

Action at the statement

-> IO a

Create statement and execute monadic action using it. Safely finalize Statement after action is done.

runFetch :: (Connection con, ToRow params, FromRow row) => con -> Query -> params -> IO (Maybe row)

Run query and return first row

runFetchAll :: (Connection con, ToRow params, FromRow row) => con -> Query -> params -> IO (Seq row)

runFetchOne :: (Connection con, ToRow params, FromSql col) => con -> Query -> params -> IO (Maybe col)