Safe Haskell | None |
---|---|
Language | Haskell2010 |
- 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
This API is a slightly lower-level version of Database.SQLite3. Namely:
- 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)
- 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
- 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
- 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
- | 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 #
http://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 #
http://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 #
= 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 #
http://www.sqlite.org/c3ref/prepare.html
If the query contains no SQL statements, this returns
.Right
Nothing
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.
statementSql :: Statement -> IO (Maybe Utf8) Source #
http://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 #
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 #
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 #
http://www.sqlite.org/c3ref/enable_load_extension.html
Enable or disable extension loading.
Result statistics
changes :: Database -> IO Int Source #
http://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 #
http://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
:: 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 ()) |
http://sqlite.org/c3ref/create_function.html
Create a custom SQL function or redefine the behavior of an existing function.
:: 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 #
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
.
Incremental blob I/O
:: 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
backupStep :: Backup -> Int -> IO (Either Error BackupStepResult) Source #
Types
data ColumnType Source #
newtype FuncContext Source #
The context in which a custom SQL function is executed.
The type of blob handles used for incremental blob I/O
A handle for an online backup process.
Results and errors
data BackupStepResult Source #
BackupOK | There are still more pages to be copied. |
BackupDone | All pages were successfully copied. |
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 |
ErrorRow |
|
ErrorDone |
|
Special types
A ByteString
containing UTF8-encoded text with no NUL characters.
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 http://www.sqlite.org/lang_expr.html#varparam for the syntax of parameter placeholders, and how parameter indices are assigned.
Bounded ParamIndex Source # | Limit min/max bounds to fit into SQLite's native parameter ranges. |
Enum ParamIndex Source # | |
Eq ParamIndex Source # | |
Integral ParamIndex Source # | |
Num ParamIndex Source # | |
Ord ParamIndex Source # | |
Real ParamIndex Source # | |
Show ParamIndex Source # | This just shows the underlying integer, without the data constructor. |
FFIType ParamIndex CParamIndex Source # | |
newtype ColumnIndex Source #
Index of a column in a result set. Column indices start from 0.
Bounded ColumnIndex Source # | Limit min/max bounds to fit into SQLite's native parameter ranges. |
Enum ColumnIndex Source # | |
Eq ColumnIndex Source # | |
Integral ColumnIndex Source # | |
Num ColumnIndex Source # | |
Ord ColumnIndex Source # | |
Real ColumnIndex Source # | |
Show ColumnIndex Source # | This just shows the underlying integer, without the data constructor. |
FFIType ColumnIndex CColumnIndex Source # | |
type ColumnCount = ColumnIndex Source #
Number of columns in a result set.
Number of arguments of a user defined SQL function.