Squeather.Internal

Documentation

data C'sqlite3

SQLite3 database handle

data C'sqlite3_stmt

SQLite3 statement handle

data C'void

Void

data Database

Database handle. To create a database handle, use open. After creating and using the handle, be sure to clean it up using close as this is not done automatically. Consider using bracket to make allocation and cleanup exception-safe.

Constructors

Database

Fields

• dbPtr :: Ptr C'sqlite3
• dbFilename :: Text

  Used only for error messages.

Instances

Eq Database

Defined in Squeather.Internal

Methods

(==) :: Database -> Database -> Bool

(/=) :: Database -> Database -> Bool

Ord Database

Defined in Squeather.Internal

Methods

compare :: Database -> Database -> Ordering

(<) :: Database -> Database -> Bool

(<=) :: Database -> Database -> Bool

(>) :: Database -> Database -> Bool

(>=) :: Database -> Database -> Bool

max :: Database -> Database -> Database

min :: Database -> Database -> Database

Show Database

Defined in Squeather.Internal

Methods

showsPrec :: Int -> Database -> ShowS

show :: Database -> String

showList :: [Database] -> ShowS

data Statement

Statement handle. To create a statement handle, use prepare. After creating and using a Statement, be sure to clean it up using finalize as this is not done automatically. Consider using bracket to make allocation and cleanup exception-safe.

Constructors

Statement

Fields

• stmtPtr :: Ptr C'sqlite3_stmt
• stmtSql :: Text

  SQL used to make the statement

• stmtDb :: Database

  Database used to make this statement

Instances

Eq Statement

Defined in Squeather.Internal

Methods

(==) :: Statement -> Statement -> Bool

(/=) :: Statement -> Statement -> Bool

Ord Statement

Defined in Squeather.Internal

Methods

compare :: Statement -> Statement -> Ordering

(<) :: Statement -> Statement -> Bool

(<=) :: Statement -> Statement -> Bool

(>) :: Statement -> Statement -> Bool

(>=) :: Statement -> Statement -> Bool

max :: Statement -> Statement -> Statement

min :: Statement -> Statement -> Statement

Show Statement

Defined in Squeather.Internal

Methods

showsPrec :: Int -> Statement -> ShowS

show :: Statement -> String

showList :: [Statement] -> ShowS

data SqueatherErrorFlag

Errors produced by the Squeather library (as opposed to being caused directly by the underlying SQLite3 C library.)

Constructors

ParameterNotFound

Named parameter for SQL statement not found

ExecFailed

The exec function found an error string

IntConversion

Failed to convert an Int to a CInt or vice-versa because the values were out of range.

UnknownColumnType CInt

sqlite3_column_type returned a type Squeather didn't identify.

UnknownSqliteError CInt

SQLite returned an error code that is uknown to Squeather.

IncompleteBackup

A backup was started, but it did not finish running.

Bug

These failures should never happen and indicate a bug in Squeather.

ColumnNameNull Int

The call to sqlite3_column_name returned a null pointer.

Instances

Eq SqueatherErrorFlag

Defined in Squeather.Internal

Methods

(==) :: SqueatherErrorFlag -> SqueatherErrorFlag -> Bool

(/=) :: SqueatherErrorFlag -> SqueatherErrorFlag -> Bool

Ord SqueatherErrorFlag

Defined in Squeather.Internal

Methods

compare :: SqueatherErrorFlag -> SqueatherErrorFlag -> Ordering

(<) :: SqueatherErrorFlag -> SqueatherErrorFlag -> Bool

(<=) :: SqueatherErrorFlag -> SqueatherErrorFlag -> Bool

(>) :: SqueatherErrorFlag -> SqueatherErrorFlag -> Bool

(>=) :: SqueatherErrorFlag -> SqueatherErrorFlag -> Bool

max :: SqueatherErrorFlag -> SqueatherErrorFlag -> SqueatherErrorFlag

min :: SqueatherErrorFlag -> SqueatherErrorFlag -> SqueatherErrorFlag

Show SqueatherErrorFlag

Defined in Squeather.Internal

Methods

showsPrec :: Int -> SqueatherErrorFlag -> ShowS

show :: SqueatherErrorFlag -> String

showList :: [SqueatherErrorFlag] -> ShowS

data Error

Exceptions. Squeather indicates all errors (even those arising from possible bugs) by throwing exceptions of this type.

Constructors

Error

Fields

• errorContext :: Text

  Gives a context where this error occured, such as a SELECT query or a filename passed to open.

• errorFlag :: Either ErrorFlag SqueatherErrorFlag

  Either the error flag returned by SQLite library, or the flag produced by this library.

• errorText :: Text

  The text description of the error, as returned by SQLite or as created by Squeather.

• errorFilename :: Text

  The filename of the database giving rise to the error.

Instances

Eq Error

Defined in Squeather.Internal

Methods

(==) :: Error -> Error -> Bool

(/=) :: Error -> Error -> Bool

Ord Error

Defined in Squeather.Internal

Methods

compare :: Error -> Error -> Ordering

(<) :: Error -> Error -> Bool

(<=) :: Error -> Error -> Bool

(>) :: Error -> Error -> Bool

(>=) :: Error -> Error -> Bool

max :: Error -> Error -> Error

min :: Error -> Error -> Error

Show Error

Defined in Squeather.Internal

Methods

showsPrec :: Int -> Error -> ShowS

show :: Error -> String

showList :: [Error] -> ShowS

Exception Error

Defined in Squeather.Internal

Methods

toException :: Error -> SomeException

fromException :: SomeException -> Maybe Error

displayException :: Error -> String

sqlite3_extended_result_codes

Arguments

:: Ptr C'sqlite3

-> Int

On or off

-> IO CInt

https://www.sqlite.org/c3ref/extended_result_codes.html

sqlite3_open_v2

Arguments

:: Ptr CChar

Database filename, UTF-8

-> Ptr (Ptr C'sqlite3)

OUT: SQLite db handle

-> CInt

Flags

-> Ptr CChar

VFS module to use

-> IO CInt

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

sqlite3_errmsg :: Ptr C'sqlite3 -> IO (Ptr CChar)

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

readUtf8 :: Ptr CChar -> IO Text

Reads a UTF-8 text.

writeUtf8 :: Text -> (Ptr CChar -> IO a) -> IO a

Writes a UTF-8 text for foreign function use.

writeUtf8Len :: Text -> ((Ptr CChar, Int) -> IO a) -> IO a

Like writeUtf8 but instead returns a CStringLen.

checkError

Arguments

:: Database

-> Text

Context

-> CInt

-> IO ()

Checks SQLite return code. Throws an exception if the code is an error. Otherwise, returns successfully. Do not use this function if checking the return code from a function such as sqlite3_step; instead, use checkStepError.

checkStepError

Arguments

:: Database

-> Text

Context

-> CInt

-> IO StepResult

Like checkError but for use when using sqlite3_step.

open

Arguments

:: Text

Database filename

-> IO Database

Opens a new Database. The openFlags are used.

openWithFlags

Arguments

:: OpenFlags

-> Text

Database filename

-> IO Database

Opens a new Database, with settings specified with openFlags.

sqlite3_prepare_v2

Arguments

:: Ptr C'sqlite3

Database handle

-> Ptr CChar

SQL Statement, UTF-8

-> CInt

Length of SQL statement in bytes

-> Ptr (Ptr C'sqlite3_stmt)

OUT Statement handle

-> Ptr (Ptr CChar)

OUT unused portion of input statement

-> IO CInt

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

prepare

Arguments

:: Database

Database handle

-> Text

SQL Statement, UTF-8

-> IO Statement

Prepares a statement. The corresponding C SQLite function allows you to pass in a multi-statement SQL text, and retrieve the unused portion for later use. Squeather does not allow this. Squeather will prepare only the first statement.

sqlite3_bind_parameter_index

Arguments

:: Ptr C'sqlite3_stmt

Statement

-> Ptr CChar

Parameter name

-> IO CInt

The index of the parameter. Returns 0 if no matching parameter is found.

https://www.sqlite.org/c3ref/bind_parameter_index.html

getParameterIndex

Arguments

:: Statement

-> Text

Look up the parameter with this name.

-> IO CInt

Gets the index of the parameter that has the given name. Throws an Error with ParameterNotFound if the given parameter name does not exist for this statement.

sqlite3_bind_blob

Arguments

:: Ptr C'sqlite3_stmt

-> CInt

Index

-> Ptr a

Blob

-> CInt

Length

-> FunPtr (Ptr a -> IO ())

Callback to dispose of the blob. Use SQLITE_STATIC if the blob is in static, unmanaged space and does not need to be freed. Use SQLITE_TRANSIENT to have SQLite make its own private copy of the data immediately.

-> IO CInt

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

bindBlob

Arguments

:: Statement

-> Text

Parameter name

-> ByteString

Blob

-> IO ()

sqlite3_bind_double

Arguments

:: Ptr C'sqlite3_stmt

-> CInt

Index

-> Double

Double to bind

-> IO CInt

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

bindDouble

Arguments

:: Statement

-> Text

Parameter name

-> Double

-> IO ()

sqlite3_bind_int64

Arguments

:: Ptr C'sqlite3_stmt

-> CInt

Index

-> Int64

-> IO CInt

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

bindInt64

Arguments

:: Statement

-> Text

Parameter name

-> Int64

-> IO ()

sqlite3_bind_null

Arguments

:: Ptr C'sqlite3_stmt

-> CInt

Index

-> IO CInt

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

bindNull

Arguments

:: Statement

-> Text

Parameter name

-> IO ()

sqlite3_bind_text

Arguments

:: Ptr C'sqlite3_stmt

-> CInt

Index

-> Ptr CChar

UTF-8 text

-> CInt

Length

-> FunPtr (Ptr a -> IO ())

Callback to dispose of the string. Use SQLITE_STATIC if the string is in static, unmanaged space and does not need to be freed. Use SQLITE_TRANSIENT to have SQLite make its own private copy of the data immediately.

-> IO CInt

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

bindText

Arguments

:: Statement

-> Text

Parameter name

-> Text

Text to bind

-> IO ()

bindSqlData

Arguments

:: Statement

-> Text

Parameter name

-> SQLData

-> IO ()

Binds a parameter with given SQL data to the given Statement.

sqlite3_step :: Ptr C'sqlite3_stmt -> IO CInt

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

step :: Statement -> IO StepResult

Evaluate a prepared statement. Returns Row if the Statement has returned a row of data. In that case, use column or columns to get individual columns or all columns, respectively. Returns Done if there is no data to retrieve. In that case, step should not be called again without first calling reset.

sqlite3_column_count :: Ptr C'sqlite3_stmt -> IO CInt

The number of columns returned by the prepared statement. Can be zero. However, just because this routine returns a positive number does not mean that data will be returned. A SELECT statement will always return a postive column count, but a particular query might return no rows.

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

sqlite3_column_bytes

Arguments

:: Ptr C'sqlite3_stmt

-> CInt

Column index

-> IO CInt

Number of bytes in the column

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

sqlite3_column_type

Arguments

:: Ptr C'sqlite3_stmt

-> CInt

Index

-> IO CInt

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

sqlite3_column_blob

Arguments

:: Ptr C'sqlite3_stmt

-> CInt

Index

-> IO (Ptr a)

Pointer to result

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

sqlite3_column_double

Arguments

:: Ptr C'sqlite3_stmt

-> CInt

Index

-> IO Double

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

sqlite3_column_int64

Arguments

:: Ptr C'sqlite3_stmt

-> CInt

Index

-> IO Int64

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

sqlite3_column_text

Arguments

:: Ptr C'sqlite3_stmt

-> CInt

Index

-> IO (Ptr CUChar)

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

column

Arguments

:: Statement

-> Int

Index

-> IO SQLData

Retrieves a column with a given index from the Statement. Assumes that step was already called and that it returned Row.

columnCount :: Statement -> IO Int

The number of columns that a given Statement will return. Works regardless of whether step has been applied or not; however, just because this returns a positive value does not mean that step will ever actually return a Row.

columns :: Statement -> IO [SQLData]

Return all available columns, in order, from a Statement on which step returned Row. You should already have applied step.

allRows :: Statement -> IO [[SQLData]]

Retrieves all remaining rows from a Statement. Applies step for you for as many times as needed.

bindParams :: Statement -> [(Text, SQLData)] -> IO ()

Bind multiple named parameters to a Statement.

execute

Arguments

:: Database

-> Text

SQL text

-> IO [[SQLData]]

All SQL data from the query.

Execute a query without any parameters. Executes only one query - there is no need to terminate it with a semicolon, although you can. If you use a semicolon-separated list of queries, only the first query will be run. There is no way to use SQL parameters; for that you will need executeNamed.

executeNamed

Arguments

:: Database

-> Text

SQL text

-> [(Text, SQLData)]

Pairs, where each Text is a named parameter and each SQLData is the corresponding data to bind to that parameter. This page describes the different parameter syntax that is allowed. Squeather makes no effort to support the plain ? syntax. Note that the leading mark (?, :, @, or $) is part of the parameter name and must appear as part of the Text.

-> IO [[SQLData]]

All SQL data from the query.

Execute a query with named parameters. Executes only one query - there is no need to terminate it with a semicolon, although you can. If you use a semicolon-separated list of queries, only the first query will be run.

executeNamedWithColumns

Arguments

:: Database

-> Text

SQL text

-> [(Text, SQLData)]

Pairs, where each Text is a named parameter and each SQLData is the corresponding data to bind to that parameter. This page describes the different parameter syntax that is allowed. Squeather makes no effort to support the plain ? syntax. Note that the leading mark (?, :, @, or $) is part of the parameter name and must appear as part of the Text.

-> IO ([Text], [[SQLData]])

The column names, and all SQL data from the query.

Like executeNamed but also returns the names of the columns in addition to the SQL results.

sqlite3_reset :: Ptr C'sqlite3_stmt -> IO CInt

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

reset :: Statement -> IO ()

Resets a Statement so it may be re-executed. Does not clear bindings. In SQLite, sqlite3_reset returns an error code if the most recent step statement returned an error. reset does not do this. It does not check the error code returned by sqlite3_reset.

sqlite3_clear_bindings :: Ptr C'sqlite3_stmt -> IO CInt

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

clearBindings :: Statement -> IO ()

Clears all bindings on the Statement.

sqlite3_finalize :: Ptr C'sqlite3_stmt -> IO CInt

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

finalize :: Statement -> IO ()

Finalize a statement. Frees up resources the statement used. Any use of the statement after finalization can result in undefined and undesirable behavior. In the SQLite library, this returns an error code if the most recent evaluation of the statement failed. This function does not replicate that behavior; it does not check the return result of sqlite3_finalize. (In general such behvaior is not necessary; if the previous action caused a failure, it should already have thrown an exception.)

sqlite3_close :: Ptr C'sqlite3 -> IO CInt

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

sqlite3_close_v2 :: Ptr C'sqlite3 -> IO CInt

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

close :: Database -> IO ()

Closes and cleans up a database handle.

type ExecCallback a

Arguments

 = Ptr a

The fourth argument of sqlite3_exec is passed through here.

-> CInt

The number of columns in the result

-> Ptr (Ptr CChar)

An array of pointers to strings obtained as if from sqlite3_column_text

-> Ptr (Ptr CChar)

An array of pointers to strings where each entry represents the name of the corresponding result column as obtained from sqlite3_column_name

-> IO CInt

The function should return zero if successful. If it returns non-zero, then SQLITE_ABORT will be thrown without involking the callback again and without running any more SQL statements.

The type of the callback from sqlite3_exec. This callback is invoked for every row of data.

sqlite3_exec

Arguments

:: Ptr C'sqlite3

-> Ptr CChar

SQL

-> FunPtr (ExecCallback a)

Callback. Pass nullFunPtr if you do not with to use a callback.

-> Ptr a

Passed to callback for every row

-> Ptr (Ptr CChar)

If there is a failure, the error message is written here. If there is no failure, nullPtr is written here.

-> IO CInt

https://www.sqlite.org/c3ref/exec.html

sqlite3_free :: Ptr a -> IO ()

https://www.sqlite.org/c3ref/free.html

exec

Arguments

:: Database

-> Text

SQL to be evaluated. Multiple, semicolon-separated statements will be executed.

-> IO ()

Evaluate one or more SQL statements. There is no way to obtain the results; for that you will need execute or executeNamed. There is no way to use SQL parameters; for that you will need executeNamed.

sqlite3_last_insert_rowid :: Ptr C'sqlite3 -> IO Int64

https://www.sqlite.org/c3ref/last_insert_rowid.html

lastInsertRowId :: Database -> IO Int64

Get the rowid of the most recent successful INSERT.

intToCInt

Arguments

:: Text

Context. For error messages only.

-> Text

Database filename. For error messages only.

-> Int

-> IO CInt

Convert from an Int to a CInt. Makes sure the conversion fits in the space allotted. Throws an exception if it doesn't fit.

intFromCInt

Arguments

:: Text

Context. For error messages only.

-> Text

Database filename. For error messages only.

-> CInt

-> IO Int

Convert from an CInt to a Int. Makes sure the conversion fits in the space allotted. Throws an exception if it doesn't fit.

sqliteVersion :: String

Returns a string which is the version number for SQLite used to build this library. SQLite is embedded into the library, so the only way to change the SQLite version is to recompile the library.

openFlags :: OpenFlags

Default settings for OpenFlags, where the writeMode is ReadWrite Create, fullMutex is True, and all other flags are set to False.

data C'sqlite3_backup

sqlite3_backup_init

Arguments

:: Ptr C'sqlite3

Destination database handle

-> Ptr CChar

Destination database name - main for the main database, temp for the temporary database, or the name specified after the AS keyword in an ATTACH statement for an attached database.

-> Ptr C'sqlite3

Source database handle

-> Ptr CChar

Source database name

-> IO (Ptr C'sqlite3_backup)

Returns pointer to backup object

https://www.sqlite.org/c3ref/backup_finish.html

sqlite3_backup_step

Arguments

:: Ptr C'sqlite3_backup

-> CInt

Number of pages. If negative, copy all remaining source pages.

-> IO CInt

Returns error code

https://www.sqlite.org/c3ref/backup_finish.html

sqlite3_backup_finish

Arguments

:: Ptr C'sqlite3_backup

-> IO CInt

Returns error code

https://www.sqlite.org/c3ref/backup_finish.html

sqlite3_backup_remaining

Arguments

:: Ptr C'sqlite3_backup

-> IO CInt

Returns number of pages remaining to be backed up

https://www.sqlite.org/c3ref/backup_finish.html

sqlite3_backup_pagecount

Arguments

:: Ptr C'sqlite3_backup

-> IO CInt

Returns number of pages in source database

https://www.sqlite.org/c3ref/backup_finish.html

data Source

Backup source

Constructors

Source

Fields

• sourceConnection :: Database
• sourceName :: Text

  The name for the source database. Use main for the main database, temp for the temporary database, or the name specified after the AS keyword in an ATTACH statement for an attached database.

Instances

Eq Source

Defined in Squeather.Internal

Methods

(==) :: Source -> Source -> Bool

(/=) :: Source -> Source -> Bool

Ord Source

Defined in Squeather.Internal

Methods

compare :: Source -> Source -> Ordering

(<) :: Source -> Source -> Bool

(<=) :: Source -> Source -> Bool

(>) :: Source -> Source -> Bool

(>=) :: Source -> Source -> Bool

max :: Source -> Source -> Source

min :: Source -> Source -> Source

Show Source

Defined in Squeather.Internal

Methods

showsPrec :: Int -> Source -> ShowS

show :: Source -> String

showList :: [Source] -> ShowS

data Destination

Backup destination

Constructors

Destination

Fields

• destConnection :: Database
• destName :: Text

  The name for the destination database. Use main for the main database, temp for the temporary database, or the name specified after the AS keyword in an ATTACH statement for an attached database.

Instances

Eq Destination

Defined in Squeather.Internal

Methods

(==) :: Destination -> Destination -> Bool

(/=) :: Destination -> Destination -> Bool

Ord Destination

Defined in Squeather.Internal

Methods

compare :: Destination -> Destination -> Ordering

(<) :: Destination -> Destination -> Bool

(<=) :: Destination -> Destination -> Bool

(>) :: Destination -> Destination -> Bool

(>=) :: Destination -> Destination -> Bool

max :: Destination -> Destination -> Destination

min :: Destination -> Destination -> Destination

Show Destination

Defined in Squeather.Internal

Methods

showsPrec :: Int -> Destination -> ShowS

show :: Destination -> String

showList :: [Destination] -> ShowS

backup :: Source -> Destination -> IO ()

Use the SQLite backup API to copy the content of one database to another. Can be used to safely copy databases while they are in use, or to copy in-memory databases to or from persistent files.

sqlite3_changes :: Ptr C'sqlite3 -> IO CInt

https://www.sqlite.org/c3ref/changes.html

changes :: Database -> IO Int

Count the number of rows modified by the most recent INSERT, UPDATE, or DELETE statement.

sqlite3_column_name :: Ptr C'sqlite3_stmt -> CInt -> IO (Ptr CChar)

columnName

Arguments

:: Statement

-> Int

Index. The leftmost column is 0.

-> IO Text

Gets the name of a column. The name is the value of the AS clause if it exists, or is an undefined string otherwise.

columnNames :: Statement -> IO [Text]

Gets all column names, in order.