Safe Haskell | None |
---|---|
Language | Haskell2010 |
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
- control loading of extensions
- Result statistics
- Create custom SQL functions
- Create custom collations
- Interrupting a long-running query
- Incremental blob I/O
- Online Backup API
- Types
Description
This API is a slightly lower-level version of Database.SQLite3 . Namely:
Synopsis
- open :: Utf8 -> IO ( Either ( Error , Utf8 ) Database )
- close :: Database -> IO ( Either Error ())
- errcode :: Database -> IO Error
- errmsg :: Database -> IO Utf8
- setTrace :: Database -> Maybe ( Utf8 -> IO ()) -> IO ()
- getAutoCommit :: Database -> IO Bool
- setSharedCacheEnabled :: Bool -> IO ( Either Error ())
- exec :: Database -> Utf8 -> IO ( Either ( Error , Utf8 ) ())
- execWithCallback :: Database -> Utf8 -> ExecCallback -> IO ( Either ( Error , Utf8 ) ())
- type ExecCallback = ColumnCount -> [ Utf8 ] -> [ Maybe Utf8 ] -> IO ()
- prepare :: Database -> Utf8 -> IO ( Either Error ( Maybe Statement ))
- getStatementDatabase :: Statement -> IO Database
- step :: Statement -> IO ( Either Error StepResult )
- stepNoCB :: Statement -> IO ( Either Error StepResult )
- reset :: Statement -> IO ( Either Error ())
- finalize :: Statement -> IO ( Either Error ())
- clearBindings :: Statement -> IO ()
- statementSql :: Statement -> IO ( Maybe Utf8 )
- bindParameterCount :: Statement -> IO ParamIndex
- bindParameterName :: Statement -> ParamIndex -> IO ( Maybe Utf8 )
- bindParameterIndex :: Statement -> Utf8 -> IO ( Maybe ParamIndex )
- columnCount :: Statement -> IO ColumnCount
- columnName :: Statement -> ColumnIndex -> IO ( Maybe Utf8 )
- 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 ())
- bindZeroBlob :: Statement -> ParamIndex -> Int -> 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
- setLoadExtensionEnabled :: Database -> Bool -> IO ( Either Error ())
- lastInsertRowId :: Database -> IO Int64
- changes :: Database -> IO Int
- totalChanges :: Database -> IO Int
- createFunction :: Database -> Utf8 -> Maybe ArgCount -> Bool -> ( FuncContext -> FuncArgs -> IO ()) -> IO ( Either Error ())
- createAggregate :: Database -> Utf8 -> Maybe ArgCount -> a -> ( FuncContext -> FuncArgs -> a -> IO a) -> ( FuncContext -> a -> IO ()) -> IO ( Either Error ())
- deleteFunction :: Database -> Utf8 -> Maybe ArgCount -> IO ( Either Error ())
- funcArgCount :: FuncArgs -> ArgCount
- funcArgType :: FuncArgs -> ArgIndex -> IO ColumnType
- funcArgInt64 :: FuncArgs -> ArgIndex -> IO Int64
- funcArgDouble :: FuncArgs -> ArgIndex -> IO Double
- funcArgText :: FuncArgs -> ArgIndex -> IO Utf8
- funcArgBlob :: FuncArgs -> ArgIndex -> IO ByteString
- funcResultInt64 :: FuncContext -> Int64 -> IO ()
- funcResultDouble :: FuncContext -> Double -> IO ()
- funcResultText :: FuncContext -> Utf8 -> IO ()
- funcResultBlob :: FuncContext -> ByteString -> IO ()
- funcResultZeroBlob :: FuncContext -> Int -> IO ()
- funcResultNull :: FuncContext -> IO ()
- getFuncContextDatabase :: FuncContext -> IO Database
- createCollation :: Database -> Utf8 -> ( Utf8 -> Utf8 -> Ordering ) -> IO ( Either Error ())
- deleteCollation :: Database -> Utf8 -> IO ( Either Error ())
- interrupt :: Database -> IO ()
- blobOpen :: Database -> Utf8 -> Utf8 -> Utf8 -> Int64 -> Bool -> IO ( Either Error Blob )
- blobClose :: Blob -> IO ( Either Error ())
- blobReopen :: Blob -> Int64 -> IO ( Either Error ())
- blobBytes :: Blob -> IO Int
- blobRead :: Blob -> Int -> Int -> IO ( Either Error ByteString )
- blobReadBuf :: Blob -> Ptr a -> Int -> Int -> IO ( Either Error ())
- blobWrite :: Blob -> ByteString -> Int -> IO ( Either Error ())
- backupInit :: Database -> Utf8 -> Database -> Utf8 -> IO ( Either Error Backup )
- backupFinish :: Backup -> IO ( Either Error ())
- backupStep :: Backup -> Int -> IO ( Either Error BackupStepResult )
- backupRemaining :: Backup -> IO Int
- backupPagecount :: Backup -> IO Int
- newtype Database = Database ( Ptr CDatabase )
- newtype Statement = Statement ( Ptr CStatement )
-
data
ColumnType
- = IntegerColumn
- | FloatColumn
- | TextColumn
- | BlobColumn
- | NullColumn
- newtype FuncContext = FuncContext ( Ptr CContext )
- data FuncArgs = FuncArgs CArgCount ( Ptr ( Ptr CValue ))
- data Blob = Blob Database ( Ptr CBlob )
- data Backup = Backup Database ( Ptr CBackup )
- data StepResult
-
data
BackupStepResult
- = BackupOK
- | BackupDone
-
data
Error
- = ErrorOK
- | ErrorError
- | ErrorInternal
- | ErrorPermission
- | ErrorAbort
- | ErrorBusy
- | ErrorLocked
- | ErrorNoMemory
- | ErrorReadOnly
- | ErrorInterrupt
- | ErrorIO
- | ErrorCorrupt
- | ErrorNotFound
- | ErrorFull
- | ErrorCan'tOpen
- | ErrorProtocol
- | ErrorEmpty
- | ErrorSchema
- | ErrorTooBig
- | ErrorConstraint
- | ErrorMismatch
- | ErrorMisuse
- | ErrorNoLargeFileSupport
- | ErrorAuthorization
- | ErrorFormat
- | ErrorRange
- | ErrorNotADatabase
- | ErrorNotice
- | ErrorWarning
- | ErrorRow
- | ErrorDone
- newtype Utf8 = Utf8 ByteString
- newtype ParamIndex = ParamIndex Int
- newtype ColumnIndex = ColumnIndex Int
- type ColumnCount = ColumnIndex
- newtype ArgCount = ArgCount Int
- type ArgIndex = ArgCount
Connection management
setTrace :: Database -> Maybe ( Utf8 -> IO ()) -> IO () Source #
https://www.sqlite.org/c3ref/profile.html
Enable/disable tracing of SQL execution. Tracing can be disabled
by setting
Nothing
as the logger callback.
Warning: If the logger callback throws an exception, your whole program will crash. Enable only for debugging!
getAutoCommit :: Database -> IO Bool Source #
https://www.sqlite.org/c3ref/get_autocommit.html
Return
True
if the connection is in autocommit mode, or
False
if a
transaction started with
BEGIN
is still active.
Be warned that some errors roll back the transaction automatically,
and that
ROLLBACK
will throw an error if no transaction is active.
Use
getAutoCommit
to avoid such an error:
autocommit <-getAutoCommit
connwhen
(not autocommit) $exec
conn "ROLLBACK"
setSharedCacheEnabled :: Bool -> IO ( Either Error ()) Source #
https://www.sqlite.org/c3ref/enable_shared_cache.html
Enable or disable shared cache for all future connections.
Simple query execution
execWithCallback :: Database -> Utf8 -> ExecCallback -> IO ( Either ( Error , Utf8 ) ()) Source #
Like
exec
, but invoke the callback for each result row.
If the callback throws an exception, it will be rethrown by
execWithCallback
.
type ExecCallback Source #
Arguments
= ColumnCount |
Number of columns, which is the number of items in the following lists. This will be the same for every row. |
-> [ Utf8 ] |
List of column names. This will be the same for every row. |
-> [ Maybe Utf8 ] |
List of column values, as returned by
|
-> IO () |
Statement management
prepare :: Database -> Utf8 -> IO ( Either Error ( Maybe Statement )) Source #
https://www.sqlite.org/c3ref/prepare.html
If the query contains no SQL statements, this returns
.
Right
Nothing
stepNoCB :: Statement -> IO ( Either Error StepResult ) Source #
https://www.sqlite.org/c3ref/step.html
Faster step for statements that don't callback to Haskell functions (e.g. by using custom SQL functions).
reset :: Statement -> IO ( Either Error ()) Source #
https://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 #
https://www.sqlite.org/c3ref/finalize.html
Warning:
If the most recent
step
call failed,
this will return the corresponding error.
clearBindings :: Statement -> IO () Source #
https://www.sqlite.org/c3ref/clear_bindings.html
Set all parameters in the prepared statement to null.
statementSql :: Statement -> IO ( Maybe Utf8 ) Source #
https://www.sqlite.org/c3ref/sql.html
Return a copy of the original SQL text used to compile the statement.
Parameter and column information
bindParameterCount :: Statement -> IO ParamIndex Source #
https://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 #
bindParameterIndex :: Statement -> Utf8 -> IO ( Maybe ParamIndex ) Source #
columnName :: Statement -> ColumnIndex -> IO ( Maybe Utf8 ) Source #
Binding values to a prepared statement
bindDouble :: Statement -> ParamIndex -> Double -> IO ( Either Error ()) Source #
bindBlob :: Statement -> ParamIndex -> ByteString -> IO ( Either Error ()) Source #
bindZeroBlob :: Statement -> ParamIndex -> Int -> IO ( Either Error ()) Source #
Reading the result row
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 #
control loading of extensions
setLoadExtensionEnabled :: Database -> Bool -> IO ( Either Error ()) Source #
https://www.sqlite.org/c3ref/enable_load_extension.html
Enable or disable extension loading.
Result statistics
changes :: Database -> IO Int Source #
https://www.sqlite.org/c3ref/changes.html
Return the number of rows that were changed, inserted, or deleted
by the most recent
INSERT
,
DELETE
, or
UPDATE
statement.
totalChanges :: Database -> IO Int Source #
https://www.sqlite.org/c3ref/total_changes.html
Return the total number of row changes caused by
INSERT
,
DELETE
,
or
UPDATE
statements since the
Database
was opened.
Create custom SQL functions
Arguments
:: Database | |
-> Utf8 |
Name of the function. |
-> Maybe ArgCount |
Number of arguments.
|
-> Bool |
Is the function deterministic? |
-> ( FuncContext -> FuncArgs -> IO ()) |
Implementation of the function. |
-> IO ( Either Error ()) |
https://sqlite.org/c3ref/create_function.html
Create a custom SQL function or redefine the behavior of an existing function.
Arguments
:: Database | |
-> Utf8 |
Name of the function. |
-> Maybe ArgCount |
Number of arguments. |
-> a |
Initial aggregate state. |
-> ( FuncContext -> FuncArgs -> a -> IO a) |
Process one row and update the aggregate state. |
-> ( FuncContext -> a -> IO ()) |
Called after all rows have been processed. Can be used to construct the returned value from the aggregate state. |
-> IO ( Either Error ()) |
Like
createFunction
except that it creates an aggregate function.
deleteFunction :: Database -> Utf8 -> Maybe ArgCount -> IO ( Either Error ()) Source #
Delete an SQL function (scalar or aggregate).
Extract function arguments
funcArgCount :: FuncArgs -> ArgCount Source #
funcArgType :: FuncArgs -> ArgIndex -> IO ColumnType Source #
funcArgBlob :: FuncArgs -> ArgIndex -> IO ByteString Source #
Set the result of a function
funcResultInt64 :: FuncContext -> Int64 -> IO () Source #
funcResultDouble :: FuncContext -> Double -> IO () Source #
funcResultText :: FuncContext -> Utf8 -> IO () Source #
funcResultBlob :: FuncContext -> ByteString -> IO () Source #
funcResultZeroBlob :: FuncContext -> Int -> IO () Source #
funcResultNull :: FuncContext -> IO () Source #
Create custom collations
Interrupting a long-running query
interrupt :: Database -> IO () Source #
https://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
.
Incremental blob I/O
Arguments
:: Database | |
-> Utf8 |
The symbolic name of the database (e.g. "main"). |
-> Utf8 |
The table name. |
-> Utf8 |
The column name. |
-> Int64 |
The
|
-> Bool |
Open the blob for read-write. |
-> IO ( Either Error Blob ) |
https://www.sqlite.org/c3ref/blob_open.html
Open a blob for incremental I/O.
Online Backup API
Types
data ColumnType Source #
Constructors
IntegerColumn | |
FloatColumn | |
TextColumn | |
BlobColumn | |
NullColumn |
Instances
Eq ColumnType Source # | |
Defined in Database.SQLite3.Bindings.Types Methods (==) :: ColumnType -> ColumnType -> Bool Source # (/=) :: ColumnType -> ColumnType -> Bool Source # |
|
Show ColumnType Source # | |
Defined in Database.SQLite3.Bindings.Types |
|
FFIType ColumnType CColumnType Source # | |
Defined in Database.SQLite3.Bindings.Types |
newtype FuncContext Source #
The context in which a custom SQL function is executed.
Constructors
FuncContext ( Ptr CContext ) |
Instances
Eq FuncContext Source # | |
Defined in Database.SQLite3.Direct Methods (==) :: FuncContext -> FuncContext -> Bool Source # (/=) :: FuncContext -> FuncContext -> Bool Source # |
|
Show FuncContext Source # | |
Defined in Database.SQLite3.Direct |
The arguments of a custom SQL function.
The type of blob handles used for incremental blob I/O
Results and errors
data StepResult Source #
Instances
Eq StepResult Source # | |
Defined in Database.SQLite3.Direct Methods (==) :: StepResult -> StepResult -> Bool Source # (/=) :: StepResult -> StepResult -> Bool Source # |
|
Show StepResult Source # | |
Defined in Database.SQLite3.Direct |
data BackupStepResult Source #
Constructors
BackupOK |
There are still more pages to be copied. |
BackupDone |
All pages were successfully copied. |
Instances
Eq BackupStepResult Source # | |
Defined in Database.SQLite3.Direct Methods (==) :: BackupStepResult -> BackupStepResult -> Bool Source # (/=) :: BackupStepResult -> BackupStepResult -> Bool Source # |
|
Show BackupStepResult Source # | |
Defined in Database.SQLite3.Direct |
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
|
ErrorReadOnly |
Attempt to write a readonly database |
ErrorInterrupt |
Operation terminated by
|
ErrorIO |
Some kind of disk I/O error occurred |
ErrorCorrupt |
The database disk image is malformed |
ErrorNotFound |
Unknown opcode in
|
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 |
ErrorNotice |
Notifications from sqlite3_log() |
ErrorWarning |
Warnings from sqlite3_log() |
ErrorRow |
|
ErrorDone |
|
Special types
A
ByteString
containing UTF8-encoded text with no NUL characters.
Constructors
Utf8 ByteString |
newtype ParamIndex Source #
Index of a parameter in a parameterized query. Parameter indices start from 1.
When a query is
prepare
d, 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 https://www.sqlite.org/lang_expr.html#varparam for the syntax of parameter placeholders, and how parameter indices are assigned.
Constructors
ParamIndex Int |
Instances
newtype ColumnIndex Source #
Index of a column in a result set. Column indices start from 0.
Constructors
ColumnIndex Int |
Instances
type ColumnCount = ColumnIndex Source #
Number of columns in a result set.
Number of arguments of a user defined SQL function.