-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Low-level binding to SQLite3. Includes UTF8 and BLOB support. -- -- This package is not very different from the other SQLite3 bindings out -- there, but it fixes a few deficiencies I was finding. It is not as -- complete as bindings-sqlite3, but is slightly higher-level, in that it -- supports marshalling of data values to and from the database. In -- particular, it supports strings encoded as UTF8, and BLOBs represented -- as ByteStrings. -- -- Release history: -- -- @package direct-sqlite @version 2.2.1 module Database.SQLite3.Bindings.Types -- | http://www.sqlite.org/c3ref/sqlite3.html -- -- CDatabase = sqlite3 data CDatabase -- | http://www.sqlite.org/c3ref/stmt.html -- -- CStatement = sqlite3_stmt data CStatement -- | http://www.sqlite.org/c3ref/c_abort.html newtype CError CError :: CInt -> CError -- | Note that this is a partial function. If the error code is invalid, or -- perhaps introduced in a newer version of SQLite but this library has -- not been updated to support it, the result is undefined. -- -- To be clear, if decodeError fails, it is undefined -- behavior, not an exception you can handle. -- -- Therefore, do not use direct-sqlite with a different version of SQLite -- than the one bundled (currently, 3.7.13). If you do, ensure that -- decodeError and decodeColumnType are still exhaustive. decodeError :: CError -> Error data Error -- | Successful result ErrorOK :: Error -- | SQL error or missing database ErrorError :: Error -- | Internal logic error in SQLite ErrorInternal :: Error -- | Access permission denied ErrorPermission :: Error -- | Callback routine requested an abort ErrorAbort :: Error -- | The database file is locked ErrorBusy :: Error -- | A table in the database is locked ErrorLocked :: Error -- | A malloc() failed ErrorNoMemory :: Error -- | Attempt to write a readonly database ErrorReadOnly :: Error -- | Operation terminated by sqlite3_interrupt() ErrorInterrupt :: Error -- | Some kind of disk I/O error occurred ErrorIO :: Error -- | The database disk image is malformed ErrorCorrupt :: Error -- | Unknown opcode in sqlite3_file_control() ErrorNotFound :: Error -- | Insertion failed because database is full ErrorFull :: Error -- | Unable to open the database file ErrorCan'tOpen :: Error -- | Database lock protocol error ErrorProtocol :: Error -- | Database is empty ErrorEmpty :: Error -- | The database schema changed ErrorSchema :: Error -- | String or BLOB exceeds size limit ErrorTooBig :: Error -- | Abort due to constraint violation ErrorConstraint :: Error -- | Data type mismatch ErrorMismatch :: Error -- | Library used incorrectly ErrorMisuse :: Error -- | Uses OS features not supported on host ErrorNoLargeFileSupport :: Error -- | Authorization denied ErrorAuthorization :: Error -- | Auxiliary database format error ErrorFormat :: Error -- | 2nd parameter to sqlite3_bind out of range ErrorRange :: Error -- | File opened that is not a database file ErrorNotADatabase :: Error -- | sqlite3_step() has another row ready ErrorRow :: Error -- | sqlite3_step() has finished executing ErrorDone :: Error -- | http://www.sqlite.org/c3ref/c_blob.html newtype CColumnType CColumnType :: CInt -> CColumnType -- | Note that this is a partial function. See decodeError for more -- information. decodeColumnType :: CColumnType -> ColumnType data ColumnType IntegerColumn :: ColumnType FloatColumn :: ColumnType TextColumn :: ColumnType BlobColumn :: ColumnType NullColumn :: ColumnType -- | Index of a parameter in a parameterized query. Parameter indices start -- from 1. -- -- When a query is prepared, SQLite allocates an array indexed -- from 1 to the highest parameter index. For example: -- -- 
--   >Right stmt <- prepare conn "SELECT ?1, ?5, ?3, ?"
--   >bindParameterCount stmt
--   ParamIndex 6
--
-- -- This will allocate an array indexed from 1 to 6 (? takes the -- highest preceding index plus one). The array is initialized with null -- values. When you bind a parameter with bindSQLData, it assigns -- a new value to one of these indices. -- -- See http://www.sqlite.org/lang_expr.html#varparam for the -- syntax of parameter placeholders, and how parameter indices are -- assigned. newtype ParamIndex ParamIndex :: CInt -> ParamIndex -- | Index of a column in a result set. Column indices start from 0. newtype ColumnIndex ColumnIndex :: CInt -> ColumnIndex -- | Number of columns in a result set. type ColumnCount = ColumnIndex newtype CNumBytes CNumBytes :: CInt -> CNumBytes -- | http://www.sqlite.org/c3ref/c_static.html -- -- Ptr CDestructor = sqlite3_destructor_type data CDestructor c_SQLITE_TRANSIENT :: Ptr CDestructor instance Eq Error instance Show Error instance Eq ColumnType instance Show ColumnType instance Eq ParamIndex instance Ord ParamIndex instance Enum ParamIndex instance Num ParamIndex instance Real ParamIndex instance Integral ParamIndex instance Eq ColumnIndex instance Ord ColumnIndex instance Enum ColumnIndex instance Num ColumnIndex instance Real ColumnIndex instance Integral ColumnIndex instance Eq CNumBytes instance Ord CNumBytes instance Show CNumBytes instance Enum CNumBytes instance Num CNumBytes instance Real CNumBytes instance Integral CNumBytes instance Show CError instance Show CColumnType instance Show ColumnIndex instance Show ParamIndex module Database.SQLite3.Bindings -- | http://www.sqlite.org/c3ref/open.html -- -- This sets the 'Ptr CDatabase' even on failure. c_sqlite3_open :: CString -> Ptr (Ptr CDatabase) -> IO CError -- | http://www.sqlite.org/c3ref/close.html c_sqlite3_close :: Ptr CDatabase -> IO CError -- | http://www.sqlite.org/c3ref/errcode.html c_sqlite3_errmsg :: Ptr CDatabase -> IO CString c_sqlite3_exec :: Ptr CDatabase -> CString -> FunPtr (CExecCallback a) -> Ptr a -> Ptr CString -> IO CError type CExecCallback a = Ptr a -> ColumnCount -> Ptr CString -> Ptr CString -> CInt -- | A couple important things to know about callbacks from Haskell code: -- -- mkCExecCallback :: CExecCallback a -> IO (FunPtr (CExecCallback a)) -- | http://www.sqlite.org/c3ref/prepare.html -- -- If the query contains no SQL statements, this returns -- SQLITE_OK and sets the Ptr CStatement -- to null. c_sqlite3_prepare_v2 :: Ptr CDatabase -> CString -> CNumBytes -> Ptr (Ptr CStatement) -> Ptr CString -> IO CError -- | http://www.sqlite.org/c3ref/db_handle.html c_sqlite3_db_handle :: Ptr CStatement -> IO (Ptr CDatabase) -- | http://www.sqlite.org/c3ref/step.html c_sqlite3_step :: Ptr CStatement -> IO CError -- | http://www.sqlite.org/c3ref/reset.html -- -- Warning: If the most recent c_sqlite3_step call failed, -- this will return the corresponding error code. c_sqlite3_reset :: Ptr CStatement -> IO CError -- | http://www.sqlite.org/c3ref/finalize.html -- -- Warning: If the most recent c_sqlite3_step call failed, -- this will return the corresponding error code. c_sqlite3_finalize :: Ptr CStatement -> IO CError -- | http://www.sqlite.org/c3ref/clear_bindings.html -- -- A look at the source reveals that this function always returns -- SQLITE_OK. c_sqlite3_clear_bindings :: Ptr CStatement -> IO CError -- | http://www.sqlite.org/c3ref/bind_parameter_count.html -- -- This returns the index of the largest (rightmost) parameter, which is -- not necessarily the number of parameters. If numbered parameters like -- ?5 are used, there may be gaps in the list. c_sqlite3_bind_parameter_count :: Ptr CStatement -> IO ParamIndex -- | http://www.sqlite.org/c3ref/bind_parameter_name.html c_sqlite3_bind_parameter_name :: Ptr CStatement -> ParamIndex -> IO CString -- | http://www.sqlite.org/c3ref/column_count.html c_sqlite3_column_count :: Ptr CStatement -> IO ColumnCount c_sqlite3_bind_blob :: Ptr CStatement -> ParamIndex -> Ptr a -> CNumBytes -> Ptr CDestructor -> IO CError c_sqlite3_bind_text :: Ptr CStatement -> ParamIndex -> CString -> CNumBytes -> Ptr CDestructor -> IO CError c_sqlite3_bind_double :: Ptr CStatement -> ParamIndex -> Double -> IO CError c_sqlite3_bind_int64 :: Ptr CStatement -> ParamIndex -> Int64 -> IO CError c_sqlite3_bind_null :: Ptr CStatement -> ParamIndex -> IO CError c_sqlite3_column_type :: Ptr CStatement -> ColumnIndex -> IO CColumnType c_sqlite3_column_bytes :: Ptr CStatement -> ColumnIndex -> IO CNumBytes c_sqlite3_column_blob :: Ptr CStatement -> ColumnIndex -> IO (Ptr a) c_sqlite3_column_int64 :: Ptr CStatement -> ColumnIndex -> IO Int64 c_sqlite3_column_double :: Ptr CStatement -> ColumnIndex -> IO Double c_sqlite3_column_text :: Ptr CStatement -> ColumnIndex -> IO CString -- | http://sqlite.org/c3ref/free.html c_sqlite3_free :: Ptr a -> IO () -- | This API is a slightly lower-level version of Database.SQLite3. -- Namely: -- -- module Database.SQLite3.Direct -- | http://www.sqlite.org/c3ref/open.html open :: Utf8 -> IO (Either (Error, Utf8) Database) -- | http://www.sqlite.org/c3ref/close.html close :: Database -> IO (Either Error ()) -- | http://www.sqlite.org/c3ref/errcode.html errmsg :: Database -> IO Utf8 exec :: Database -> Utf8 -> IO (Either (Error, Utf8) ()) -- | http://www.sqlite.org/c3ref/prepare.html -- -- If the query contains no SQL statements, this returns Right -- Nothing. prepare :: Database -> Utf8 -> IO (Either Error (Maybe Statement)) -- | http://www.sqlite.org/c3ref/db_handle.html getStatementDatabase :: Statement -> IO Database -- | http://www.sqlite.org/c3ref/step.html step :: Statement -> IO (Either Error StepResult) -- | http://www.sqlite.org/c3ref/reset.html -- -- Warning: -- -- reset :: Statement -> IO (Either Error ()) -- | http://www.sqlite.org/c3ref/finalize.html -- -- Warning: If the most recent step call failed, this will -- return the corresponding error. finalize :: Statement -> IO (Either Error ()) -- | http://www.sqlite.org/c3ref/clear_bindings.html -- -- Set all parameters in the prepared statement to null. clearBindings :: Statement -> IO () -- | http://www.sqlite.org/c3ref/bind_parameter_count.html -- -- This returns the index of the largest (rightmost) parameter. Note that -- this is not necessarily the number of parameters. If numbered -- parameters like ?5 are used, there may be gaps in the list. -- -- See ParamIndex for more information. bindParameterCount :: Statement -> IO ParamIndex -- | http://www.sqlite.org/c3ref/bind_parameter_name.html bindParameterName :: Statement -> ParamIndex -> IO (Maybe Utf8) -- | http://www.sqlite.org/c3ref/column_count.html columnCount :: Statement -> IO ColumnCount bindInt64 :: Statement -> ParamIndex -> Int64 -> IO (Either Error ()) bindDouble :: Statement -> ParamIndex -> Double -> IO (Either Error ()) bindText :: Statement -> ParamIndex -> Utf8 -> IO (Either Error ()) bindBlob :: Statement -> ParamIndex -> ByteString -> IO (Either Error ()) bindNull :: Statement -> ParamIndex -> IO (Either Error ()) columnType :: Statement -> ColumnIndex -> IO ColumnType columnInt64 :: Statement -> ColumnIndex -> IO Int64 columnDouble :: Statement -> ColumnIndex -> IO Double columnText :: Statement -> ColumnIndex -> IO Utf8 columnBlob :: Statement -> ColumnIndex -> IO ByteString newtype Database Database :: (Ptr CDatabase) -> Database newtype Statement Statement :: (Ptr CStatement) -> Statement data ColumnType IntegerColumn :: ColumnType FloatColumn :: ColumnType TextColumn :: ColumnType BlobColumn :: ColumnType NullColumn :: ColumnType data StepResult Row :: StepResult Done :: StepResult data Error -- | Successful result ErrorOK :: Error -- | SQL error or missing database ErrorError :: Error -- | Internal logic error in SQLite ErrorInternal :: Error -- | Access permission denied ErrorPermission :: Error -- | Callback routine requested an abort ErrorAbort :: Error -- | The database file is locked ErrorBusy :: Error -- | A table in the database is locked ErrorLocked :: Error -- | A malloc() failed ErrorNoMemory :: Error -- | Attempt to write a readonly database ErrorReadOnly :: Error -- | Operation terminated by sqlite3_interrupt() ErrorInterrupt :: Error -- | Some kind of disk I/O error occurred ErrorIO :: Error -- | The database disk image is malformed ErrorCorrupt :: Error -- | Unknown opcode in sqlite3_file_control() ErrorNotFound :: Error -- | Insertion failed because database is full ErrorFull :: Error -- | Unable to open the database file ErrorCan'tOpen :: Error -- | Database lock protocol error ErrorProtocol :: Error -- | Database is empty ErrorEmpty :: Error -- | The database schema changed ErrorSchema :: Error -- | String or BLOB exceeds size limit ErrorTooBig :: Error -- | Abort due to constraint violation ErrorConstraint :: Error -- | Data type mismatch ErrorMismatch :: Error -- | Library used incorrectly ErrorMisuse :: Error -- | Uses OS features not supported on host ErrorNoLargeFileSupport :: Error -- | Authorization denied ErrorAuthorization :: Error -- | Auxiliary database format error ErrorFormat :: Error -- | 2nd parameter to sqlite3_bind out of range ErrorRange :: Error -- | File opened that is not a database file ErrorNotADatabase :: Error -- | sqlite3_step() has another row ready ErrorRow :: Error -- | sqlite3_step() has finished executing ErrorDone :: Error -- | A ByteString containing UTF8-encoded text with no NUL -- characters. newtype Utf8 Utf8 :: ByteString -> Utf8 -- | Index of a parameter in a parameterized query. Parameter indices start -- from 1. -- -- When a query is prepared, SQLite allocates an array indexed -- from 1 to the highest parameter index. For example: -- -- 
--   >Right stmt <- prepare conn "SELECT ?1, ?5, ?3, ?"
--   >bindParameterCount stmt
--   ParamIndex 6
--
-- -- This will allocate an array indexed from 1 to 6 (? takes the -- highest preceding index plus one). The array is initialized with null -- values. When you bind a parameter with bindSQLData, it assigns -- a new value to one of these indices. -- -- See http://www.sqlite.org/lang_expr.html#varparam for the -- syntax of parameter placeholders, and how parameter indices are -- assigned. newtype ParamIndex ParamIndex :: CInt -> ParamIndex -- | Index of a column in a result set. Column indices start from 0. newtype ColumnIndex ColumnIndex :: CInt -> ColumnIndex -- | Number of columns in a result set. type ColumnCount = ColumnIndex instance Eq Database instance Show Database instance Eq Statement instance Show Statement instance Eq StepResult instance Show StepResult instance Eq Utf8 instance Show Utf8 instance IsString Utf8 module Database.SQLite3 -- | http://www.sqlite.org/c3ref/open.html open :: Text -> IO Database -- | http://www.sqlite.org/c3ref/close.html close :: Database -> IO () -- | Execute zero or more SQL statements delimited by semicolons. exec :: Database -> Text -> IO () -- | http://www.sqlite.org/c3ref/prepare.html -- -- Unlike exec, prepare only executes the first statement, -- and ignores subsequent statements. -- -- If the query string contains no SQL statements, this fails. prepare :: Database -> Text -> IO Statement -- | http://www.sqlite.org/c3ref/step.html step :: Statement -> IO StepResult -- | http://www.sqlite.org/c3ref/reset.html -- -- Note that in the C API, sqlite3_reset returns an error code -- if the most recent sqlite3_step indicated an error. We do not -- replicate that behavior here. reset never throws an exception. reset :: Statement -> IO () -- | http://www.sqlite.org/c3ref/finalize.html -- -- Like reset, finalize never throws an exception. finalize :: Statement -> IO () -- | http://www.sqlite.org/c3ref/clear_bindings.html -- -- Set all parameters in the prepared statement to null. clearBindings :: Statement -> IO () -- | http://www.sqlite.org/c3ref/bind_parameter_count.html -- -- This returns the index of the largest (rightmost) parameter. Note that -- this is not necessarily the number of parameters. If numbered -- parameters like ?5 are used, there may be gaps in the list. -- -- See ParamIndex for more information. bindParameterCount :: Statement -> IO ParamIndex -- | http://www.sqlite.org/c3ref/bind_parameter_name.html -- -- Return the N-th SQL parameter name. -- -- Named parameters are returned as-is. E.g. ":v" is returned as Just -- ":v". Unnamed parameters, however, are converted to -- Nothing. -- -- Note that the parameter index starts at 1, not 0. bindParameterName :: Statement -> ParamIndex -> IO (Maybe Text) -- | http://www.sqlite.org/c3ref/column_count.html columnCount :: Statement -> IO ColumnCount -- | If the index is not between 1 and bindParameterCount inclusive, -- this fails with ErrorRange. Otherwise, it succeeds, even if the -- query skips this index by using numbered parameters. -- -- Example: -- -- 
--   > stmt <- prepare conn "SELECT ?1, ?3, ?5"
--   > bindSQLData stmt 1 (SQLInteger 1)
--   > bindSQLData stmt 2 (SQLInteger 2)
--   > bindSQLData stmt 6 (SQLInteger 6)
--   *** Exception: SQLite3 returned ErrorRange while attempting to perform bind int64.
--   > step stmt >> columns stmt
--   [SQLInteger 1,SQLNull,SQLNull]
--
bindSQLData :: Statement -> ParamIndex -> SQLData -> IO () -- | Convenience function for binding values to all parameters. This will -- fail if the list has the wrong number of parameters. bind :: Statement -> [SQLData] -> IO () bindInt :: Statement -> ParamIndex -> Int -> IO () bindInt64 :: Statement -> ParamIndex -> Int64 -> IO () bindDouble :: Statement -> ParamIndex -> Double -> IO () bindText :: Statement -> ParamIndex -> Text -> IO () bindBlob :: Statement -> ParamIndex -> ByteString -> IO () bindNull :: Statement -> ParamIndex -> IO () column :: Statement -> ColumnIndex -> IO SQLData columns :: Statement -> IO [SQLData] columnType :: Statement -> ColumnIndex -> IO ColumnType columnInt64 :: Statement -> ColumnIndex -> IO Int64 columnDouble :: Statement -> ColumnIndex -> IO Double -- | This will throw a DecodeError if the datum contains invalid -- UTF-8. If this behavior is undesirable, you can use columnText -- from Database.SQLite3.Direct, which does not perform conversion -- to Text. columnText :: Statement -> ColumnIndex -> IO Text columnBlob :: Statement -> ColumnIndex -> IO ByteString data Database data Statement data SQLData SQLInteger :: !Int64 -> SQLData SQLFloat :: !Double -> SQLData SQLText :: !Text -> SQLData SQLBlob :: !ByteString -> SQLData SQLNull :: SQLData -- | Exception thrown when SQLite3 reports an error. -- -- direct-sqlite may throw other types of exceptions if you misuse the -- API. data SQLError SQLError :: !Error -> Text -> Text -> SQLError -- | Error code returned by API call sqlError :: SQLError -> !Error -- | Text describing the error sqlErrorDetails :: SQLError -> Text -- | Indicates what action produced this error, e.g. exec "SELECT * -- FROM foo" sqlErrorContext :: SQLError -> Text data ColumnType IntegerColumn :: ColumnType FloatColumn :: ColumnType TextColumn :: ColumnType BlobColumn :: ColumnType NullColumn :: ColumnType data StepResult Row :: StepResult Done :: StepResult data Error -- | Successful result ErrorOK :: Error -- | SQL error or missing database ErrorError :: Error -- | Internal logic error in SQLite ErrorInternal :: Error -- | Access permission denied ErrorPermission :: Error -- | Callback routine requested an abort ErrorAbort :: Error -- | The database file is locked ErrorBusy :: Error -- | A table in the database is locked ErrorLocked :: Error -- | A malloc() failed ErrorNoMemory :: Error -- | Attempt to write a readonly database ErrorReadOnly :: Error -- | Operation terminated by sqlite3_interrupt() ErrorInterrupt :: Error -- | Some kind of disk I/O error occurred ErrorIO :: Error -- | The database disk image is malformed ErrorCorrupt :: Error -- | Unknown opcode in sqlite3_file_control() ErrorNotFound :: Error -- | Insertion failed because database is full ErrorFull :: Error -- | Unable to open the database file ErrorCan'tOpen :: Error -- | Database lock protocol error ErrorProtocol :: Error -- | Database is empty ErrorEmpty :: Error -- | The database schema changed ErrorSchema :: Error -- | String or BLOB exceeds size limit ErrorTooBig :: Error -- | Abort due to constraint violation ErrorConstraint :: Error -- | Data type mismatch ErrorMismatch :: Error -- | Library used incorrectly ErrorMisuse :: Error -- | Uses OS features not supported on host ErrorNoLargeFileSupport :: Error -- | Authorization denied ErrorAuthorization :: Error -- | Auxiliary database format error ErrorFormat :: Error -- | 2nd parameter to sqlite3_bind out of range ErrorRange :: Error -- | File opened that is not a database file ErrorNotADatabase :: Error -- | sqlite3_step() has another row ready ErrorRow :: Error -- | sqlite3_step() has finished executing ErrorDone :: Error -- | Index of a parameter in a parameterized query. Parameter indices start -- from 1. -- -- When a query is prepared, SQLite allocates an array indexed -- from 1 to the highest parameter index. For example: -- -- 
--   >Right stmt <- prepare conn "SELECT ?1, ?5, ?3, ?"
--   >bindParameterCount stmt
--   ParamIndex 6
--
-- -- This will allocate an array indexed from 1 to 6 (? takes the -- highest preceding index plus one). The array is initialized with null -- values. When you bind a parameter with bindSQLData, it assigns -- a new value to one of these indices. -- -- See http://www.sqlite.org/lang_expr.html#varparam for the -- syntax of parameter placeholders, and how parameter indices are -- assigned. newtype ParamIndex ParamIndex :: CInt -> ParamIndex -- | Index of a column in a result set. Column indices start from 0. newtype ColumnIndex ColumnIndex :: CInt -> ColumnIndex -- | Number of columns in a result set. type ColumnCount = ColumnIndex instance Typeable SQLData instance Typeable SQLError instance Eq SQLData instance Show SQLData instance Exception SQLError instance Show SQLError