-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Statically checked database access
--   
--   Using Template Haskell and HDBC to do statically checked database
--   access.
@package MetaHDBC
@version 0.1.2

module Database.MetaHDBC.OdbcInferTypes

-- | Asks a ODBC database to infer selected types and placeholder types.
dbInferTypes :: String -> String -> IO ([SqlColDesc], [SqlColDesc])
strictList :: [a] -> IO [a]

module Database.MetaHDBC.Connection
data CachingConnection
CachingConnection :: Connection -> MVar (HashTable String Statement) -> CachingConnection
hdbcConnection :: CachingConnection -> Connection
statementMap :: CachingConnection -> MVar (HashTable String Statement)
cachingConnection :: String -> IO CachingConnection
cachingPrepare :: CachingConnection -> String -> IO Statement

module Database.MetaHDBC.SqlTypeIdExpQ

-- | Given a <a>SqlTypeId</a> it returns a function f which transforms a
--   SqlValue into another type. The return type of f is dependent upon the
--   value of <a>SqlTypeId</a>. The function f is encapsulated in an
--   <a>ExpQ</a>. Also see <a>toSqlTypeId</a>.
fromSqlTypeId :: SqlTypeId -> ExpQ

-- | The opposite of <a>fromSqlTypeId</a> in that it returns a function
--   from a type to <a>SqlValue</a>. Similarly the function is returned in
--   a <a>ExpQ</a>. See <a>fromSqlTypeId</a>.
toSqlTypeId :: SqlTypeId -> ExpQ

-- | Like <a>fromSqlTypeId</a> but also considers if the SqlValue is
--   nullable.
fromSqlColDesc :: SqlColDesc -> ExpQ

-- | Like <a>toSqlTypeId</a> but also considers if the SqlValue is
--   nullable.
toSqlColDesc :: SqlColDesc -> ExpQ

module Database.MetaHDBC.SimpleSqlParser

-- | Parses an extended SQL string. The extionsion is that we allow
--   variable-ids after placeholders (question marks). We return the list
--   of identifiers and the SQL string without the variable-ids. If no
--   variable-id is found after a placeholder, the empty string is returned
--   as variable-id.
simpleSqlParser :: String -> ([String], String)

module Database.MetaHDBC.SqlExpr

-- | Statically typed one-off (not prepared) SQL statement.
runStmt :: String -> String -> ExpQ

-- | Statically typed prepared SQL statement.
prepareStmt :: String -> String -> ExpQ

-- | Makes the query result from prepareStmt or runStmt strict.
strict :: IO [a] -> IO [a]

-- | Common parts for both statements run directly (runStmt) and prepared
--   statements.
data ExprParts
ExprParts :: [Parameter] -> [SqlColDesc] -> String -> Name -> ExprParts

-- | Positional parameters
parameters :: ExprParts -> [Parameter]

-- | Description of values returned from a SQL statement
returnTypes :: ExprParts -> [SqlColDesc]

-- | The SQL expression which is passed on to the database
dbSqlExpr :: ExprParts -> String

-- | Name of the <tt>Connection</tt> parameter.
connectionName :: ExprParts -> Name

-- | Describing a positional parameter
data Parameter
Parameter :: Name -> SqlColDesc -> Bool -> Parameter
parmName :: Parameter -> Name
typeID :: Parameter -> SqlColDesc
isBound :: Parameter -> Bool

-- | Parts used in prepared statements
data PrepareParts
PrepareParts :: ExprParts -> Name -> PrepareParts
exprParts :: PrepareParts -> ExprParts
stmtName :: PrepareParts -> Name
rethrowDoing :: IO a -> String -> IO a

-- | Returns textual information about a query. The returned <a>String</a>
--   is useful as presentation to a user, not for further processing.
sqlInfo :: String -> String -> IO String

-- | Contructs expression-parts. A database is contacting to parse the SQL
--   and infer correct types.
makeExprParts :: String -> String -> Q ExprParts

-- | Constructs a lambda which given a connection and parameters will
--   execute <tt>expr</tt>. See <a>runStmtRHS</a>.
runStmtLHS :: ExprParts -> ExpQ -> ExpQ

-- | Creates an exprresion which runs a SQL statement on a database server.
--   It is expected that the connection variable and parameters has already
--   been bound. See also <a>runStmtLHS</a>.
runStmtRHS :: ExprParts -> ExpQ

-- | Creates parts for a prepared statement. Calls <a>makeExprParts</a>.
makePrepStmtParts :: String -> String -> Q PrepareParts

-- | Lambda for prepared statements.
prepStmtLHS :: PrepareParts -> [StmtQ] -> ExpQ

-- | A StmtQ which prepares a statement on a database.
prepStmtQ :: PrepareParts -> StmtQ

-- | A StmtQ to execute a statement on a database.
execPrepStmtRHS :: PrepareParts -> StmtQ

-- | Creates a StmtQ of type: IO (a1-an -&gt; IO ... ). Where a1-an are the
--   parameters which must be bound.
returnExecPrepStmtLHS :: PrepareParts -> [StmtQ] -> StmtQ


-- | Re-exports MetaHDBC modules and a little part HDBC.ODBC.
module Database.MetaHDBC
cachingConnection :: String -> IO CachingConnection

-- | 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 <a>disconnect</a>. 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 <a>disconnect</a>
--   directly, but the world won't end if you forget.
--   
--   This function discards any data not committed already. Database driver
--   implementators should explicitly call <a>rollback</a> if their
--   databases don't do this automatically on disconnect.
--   
--   Bad Things (TM) could happen if you call this while you have
--   <a>Statement</a>s active. In more precise language, the results in
--   such situations are undefined and vary by database. So don't do it.
disconnect :: IConnection conn => conn -> IO ()

-- | Commit any pending data to the database.
--   
--   Required to make any changes take effect.
commit :: IConnection conn => conn -> IO ()

-- | Roll back to the state the database was in prior to the last
--   <a>commit</a> or <a>rollback</a>.
rollback :: IConnection conn => conn -> IO ()

-- | Connect to an ODBC server.
--   
--   For information on the meaning of the passed string, please see:
--   
--   <a>http://msdn2.microsoft.com/en-us/library/ms715433(VS.85).aspx</a>
--   
--   An example string is:
--   
--   <pre>
--   "DSN=hdbctest1"
--   </pre>
--   
--   This, and all other functions that use ODBC directly or indirectly,
--   can raise SqlErrors just like other HDBC backends. The seErrorMsg
--   field is specified as a String in HDBC. ODBC specifies this data as a
--   list of strings. Therefore, this driver uses show on the data from
--   ODBC. For friendly display, or handling of individual component
--   messages in your code, you can use read on the seErrorMsg field in a
--   context that expects <tt>[String]</tt>.
--   
--   Important note for MySQL users:
--   
--   Unless you are going to use InnoDB tables, you are strongly encouraged
--   to set
--   
--   <pre>
--   Option = 262144
--   </pre>
--   
--   in your odbc.ini (for Unix users), or to disable transaction support
--   in your DSN setup for Windows users.
--   
--   If you fail to do this, the MySQL ODBC driver will incorrectly state
--   that it supports transactions. dbTransactionSupport will incorrectly
--   return True. commit and rollback will then silently fail. This is
--   certainly <i>NOT</i> what you want. It is a bug (or misfeature) in the
--   MySQL driver, not in HDBC.
--   
--   You should ignore this advice if you are using InnoDB tables.
connectODBC :: String -> IO Connection
data Connection :: *