Safe Haskell	None

Database.SQLite3.Direct

Contents

Connection management
Simple query execution
Statement management
Parameter and column information
Binding values to a prepared statement
Reading the result row
Types
- Results and errors
- Special types

Description

This API is a slightly lower-level version of Database.SQLite3. Namely:

It returns errors instead of throwing them.
It only uses cheap conversions. None of these bindings convert from String or Text.

Synopsis

Connection management

open :: Utf8 -> IO (Either (Error, Utf8) Database)Source

http://www.sqlite.org/c3ref/open.html

close :: Database -> IO (Either Error ())Source

http://www.sqlite.org/c3ref/close.html

errmsg :: Database -> IO Utf8 Source

http://www.sqlite.org/c3ref/errcode.html

interrupt :: Database -> IO ()Source

http://www.sqlite.org/c3ref/interrupt.html

Cause any pending operation on the Database handle to stop at its earliest opportunity. This simply sets a flag and returns immediately. It does not wait for the pending operation to finish.

You'll need to compile with -threaded for this to do any good. Without -threaded, FFI calls block the whole RTS, meaning interrupt would never run at the same time as step.

Simple query execution

http://sqlite.org/c3ref/exec.html

exec :: Database -> Utf8 -> IO (Either (Error, Utf8) ())Source

Statement management

prepare :: Database -> Utf8 -> IO (Either Error (Maybe Statement))Source

http://www.sqlite.org/c3ref/prepare.html

If the query contains no SQL statements, this returns Right Nothing.

getStatementDatabase :: Statement -> IO Database Source

http://www.sqlite.org/c3ref/db_handle.html

step :: Statement -> IO (Either Error StepResult)Source

http://www.sqlite.org/c3ref/step.html

reset :: Statement -> IO (Either Error ())Source

http://www.sqlite.org/c3ref/reset.html

Warning:

If the most recent step call failed, this will return the corresponding error.
This does not reset the bindings on a prepared statement. Use clearBindings to do that.

finalize :: Statement -> IO (Either Error ())Source

http://www.sqlite.org/c3ref/finalize.html

Warning: If the most recent step call failed, this will return the corresponding error.

clearBindings :: Statement -> IO ()Source

http://www.sqlite.org/c3ref/clear_bindings.html

Set all parameters in the prepared statement to null.

Parameter and column information

bindParameterCount :: Statement -> IO ParamIndex Source

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.

bindParameterName :: Statement -> ParamIndex -> IO (Maybe Utf8)Source

http://www.sqlite.org/c3ref/bind_parameter_name.html

columnCount :: Statement -> IO ColumnCount Source

http://www.sqlite.org/c3ref/column_count.html

Binding values to a prepared statement

http://www.sqlite.org/c3ref/bind_blob.html

bindInt64 :: Statement -> ParamIndex -> Int64 -> IO (Either Error ())Source

bindDouble :: Statement -> ParamIndex -> Double -> IO (Either Error ())Source

bindText :: Statement -> ParamIndex -> Utf8 -> IO (Either Error ())Source

bindBlob :: Statement -> ParamIndex -> ByteString -> IO (Either Error ())Source

bindNull :: Statement -> ParamIndex -> IO (Either Error ())Source

Reading the result row

http://www.sqlite.org/c3ref/column_blob.html

columnType :: Statement -> ColumnIndex -> IO ColumnType Source

columnInt64 :: Statement -> ColumnIndex -> IO Int64 Source

columnDouble :: Statement -> ColumnIndex -> IO Double Source

columnText :: Statement -> ColumnIndex -> IO Utf8 Source

columnBlob :: Statement -> ColumnIndex -> IO ByteString Source

Types

newtype Database Source

Constructors

Database (Ptr CDatabase)

Instances

Eq Database
Show Database

newtype Statement Source

Constructors

Statement (Ptr CStatement)

Instances

Eq Statement
Show Statement

data ColumnType Source

Constructors

IntegerColumn
FloatColumn
TextColumn
BlobColumn
NullColumn

Instances

Eq ColumnType
Show ColumnType
FFIType ColumnType CColumnType

Results and errors

data StepResult Source

Constructors

Row
Done

Instances

Eq StepResult
Show StepResult

data Error Source

Constructors

ErrorOK	Successful result
ErrorError	SQL error or missing database
ErrorInternal	Internal logic error in SQLite
ErrorPermission	Access permission denied
ErrorAbort	Callback routine requested an abort
ErrorBusy	The database file is locked
ErrorLocked	A table in the database is locked
ErrorNoMemory	A `malloc()` failed
ErrorReadOnly	Attempt to write a readonly database
ErrorInterrupt	Operation terminated by `sqlite3_interrupt()`
ErrorIO	Some kind of disk I/O error occurred
ErrorCorrupt	The database disk image is malformed
ErrorNotFound	Unknown opcode in `sqlite3_file_control()`
ErrorFull	Insertion failed because database is full
ErrorCan'tOpen	Unable to open the database file
ErrorProtocol	Database lock protocol error
ErrorEmpty	Database is empty
ErrorSchema	The database schema changed
ErrorTooBig	String or BLOB exceeds size limit
ErrorConstraint	Abort due to constraint violation
ErrorMismatch	Data type mismatch
ErrorMisuse	Library used incorrectly
ErrorNoLargeFileSupport	Uses OS features not supported on host
ErrorAuthorization	Authorization denied
ErrorFormat	Auxiliary database format error
ErrorRange	2nd parameter to sqlite3_bind out of range
ErrorNotADatabase	File opened that is not a database file
ErrorRow	`sqlite3_step()` has another row ready
ErrorDone	`sqlite3_step()` has finished executing

Instances

Eq Error
Show Error
FFIType Error CError

Special types

newtype Utf8 Source

A ByteString containing UTF8-encoded text with no NUL characters.

Constructors

Utf8 ByteString

Instances

Eq Utf8
Show Utf8
IsString Utf8	fromString = Utf8 . `encodeUtf8` . `pack`

newtype ParamIndex Source

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.

Constructors

ParamIndex Int

Instances

Enum ParamIndex
Eq ParamIndex
Integral ParamIndex
Num ParamIndex
Ord ParamIndex
Real ParamIndex
Show ParamIndex	This just shows the underlying integer, without the data constructor.
FFIType ParamIndex CParamIndex

newtype ColumnIndex Source

Index of a column in a result set. Column indices start from 0.

Constructors

ColumnIndex Int

Instances

Enum ColumnIndex
Eq ColumnIndex
Integral ColumnIndex
Num ColumnIndex
Ord ColumnIndex
Real ColumnIndex
Show ColumnIndex	This just shows the underlying integer, without the data constructor.
FFIType ColumnIndex CColumnIndex

type ColumnCount = ColumnIndex Source

Number of columns in a result set.