-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Mid-Level SQLite client library
--
-- Mid-level SQLite client library, based on postgresql-simple.
--
-- Main documentation: Database.SQLite.Simple
--
-- For more info, browse to http://github.com/nurpax/sqlite-simple
-- for examples & more information.
@package sqlite-simple
@version 0.4.0.0
-- | The Ok type is a simple error handler, basically equivalent to
-- Either [SomeException].
--
-- One of the primary reasons why this type was introduced is that
-- Either SomeException had not been provided an instance for
-- Alternative, and it would have been a bad idea to provide an
-- orphaned instance for a commonly-used type and typeclass included in
-- base.
--
-- Extending the failure case to a list of SomeExceptions enables
-- a more sensible Alternative instance definitions:
-- <|> concatinates the list of exceptions when both cases
-- fail, and empty is defined as 'Errors []'. Though
-- <|> one could pick one of two exceptions, and throw away
-- the other, and have empty provide a generic exception, this
-- avoids cases where empty overrides a more informative exception
-- and allows you to see all the different ways your computation has
-- failed.
module Database.SQLite.Simple.Ok
data Ok a
Errors :: [SomeException] -> Ok a
Ok :: !a -> Ok a
-- | a way to reify a list of exceptions into a single exception
newtype ManyErrors
ManyErrors :: [SomeException] -> ManyErrors
instance Typeable1 Ok
instance Typeable ManyErrors
instance Show a => Show (Ok a)
instance Functor Ok
instance Show ManyErrors
instance Exception ManyErrors
instance Monad Ok
instance MonadPlus Ok
instance Alternative Ok
instance Applicative Ok
instance Eq a => Eq (Ok a)
-- | Internal bits. This interface is less stable and can change at any
-- time. In particular this means that while the rest of the
-- sqlite-simple package endeavors to follow the package versioning
-- policy, this module does not. Also, at the moment there are things in
-- here that aren't particularly internal and are exported elsewhere;
-- these will eventually disappear from this module.
module Database.SQLite.Simple.Internal
-- | Connection to an open database.
data Connection
Connection :: Database -> Connection
-- | A Field represents metadata about a particular field
data Field
Field :: SQLData -> {-# UNPACK #-} !Int -> Field
result :: Field -> SQLData
column :: Field -> {-# UNPACK #-} !Int
newtype Row
Row :: [SQLData] -> Row
rowresult :: Row -> [SQLData]
newtype RowParser a
RP :: ReaderT Row (StateT Int Ok) a -> RowParser a
unRP :: RowParser a -> ReaderT Row (StateT Int Ok) a
gettypename :: SQLData -> ByteString
instance Functor RowParser
instance Applicative RowParser
instance Alternative RowParser
instance Monad RowParser
-- | Top-level module for sqlite-simple.
module Database.SQLite.Simple.Types
-- | A placeholder for the SQL NULL value.
data Null
Null :: Null
-- | A single-value "collection".
--
-- This is useful if you need to supply a single parameter to a SQL
-- query, or extract a single column from a SQL result.
--
-- Parameter example:
--
--
-- query c "select x from scores where x > ?" (Only (42::Int))
--
--
-- Result example:
--
--
-- xs <- query_ c "select id from users"
-- forM_ xs $ \(Only id) -> {- ... -}
--
newtype Only a
Only :: a -> Only a
fromOnly :: Only a -> a
-- | A query string. This type is intended to make it difficult to
-- construct a SQL query by concatenating string fragments, as that is an
-- extremely common way to accidentally introduce SQL injection
-- vulnerabilities into an application.
--
-- This type is an instance of IsString, so the easiest way to
-- construct a query is to enable the OverloadedStrings language
-- extension and then simply write the query in double quotes.
--
--
-- {-# LANGUAGE OverloadedStrings #-}
--
-- import Database.SQLite.Simple
--
-- q :: Query
-- q = "select ?"
--
--
-- The underlying type is a Text, and literal Haskell strings
-- that contain Unicode characters will be correctly transformed to
-- UTF-8.
newtype Query
Query :: Text -> Query
fromQuery :: Query -> Text
-- | A composite type to parse your custom data structures without having
-- to define dummy newtype wrappers every time.
--
--
-- instance FromRow MyData where ...
--
--
--
-- instance FromRow MyData2 where ...
--
--
-- then I can do the following for free:
--
--
-- res <- query' c ...
-- forM res $ \(MyData{..} :. MyData2{..}) -> do
-- ....
--
data (:.) h t
(:.) :: h -> t -> :. h t
instance Typeable Null
instance Typeable Query
instance Typeable1 Only
instance Typeable2 :.
instance Read Null
instance Show Null
instance Eq Query
instance Ord Query
instance Eq a => Eq (Only a)
instance Ord a => Ord (Only a)
instance Read a => Read (Only a)
instance Show a => Show (Only a)
instance Functor Only
instance (Eq h, Eq t) => Eq (h :. t)
instance (Ord h, Ord t) => Ord (h :. t)
instance (Show h, Show t) => Show (h :. t)
instance (Read h, Read t) => Read (h :. t)
instance Monoid Query
instance IsString Query
instance Read Query
instance Show Query
instance Eq Null
-- | The FromField typeclass, for converting a single value in a row
-- returned by a SQL query into a more useful Haskell representation.
--
-- A Haskell numeric type is considered to be compatible with all SQLite
-- numeric types that are less accurate than it. For instance, the
-- Haskell Double type is compatible with the SQLite's 32-bit
-- Int type because it can represent a Int exactly. On
-- the other hand, since a Double might lose precision if
-- representing a 64-bit BigInt, the two are not
-- considered compatible.
module Database.SQLite.Simple.FromField
-- | A type that may be converted from a SQL type.
class FromField a
fromField :: FromField a => FieldParser a
type FieldParser a = Field -> Ok a
-- | Exception thrown if conversion from a SQL value to a Haskell value
-- fails.
data ResultError
-- | The SQL and Haskell types are not compatible.
Incompatible :: String -> String -> String -> ResultError
errSQLType :: ResultError -> String
errHaskellType :: ResultError -> String
errMessage :: ResultError -> String
-- | A SQL NULL was encountered when the Haskell type did not
-- permit it.
UnexpectedNull :: String -> String -> String -> ResultError
errSQLType :: ResultError -> String
errHaskellType :: ResultError -> String
errMessage :: ResultError -> String
-- | The SQL value could not be parsed, or could not be represented as a
-- valid Haskell value, or an unexpected low-level error occurred (e.g.
-- mismatch between metadata and actual data in a row).
ConversionFailed :: String -> String -> String -> ResultError
errSQLType :: ResultError -> String
errHaskellType :: ResultError -> String
errMessage :: ResultError -> String
-- | A Field represents metadata about a particular field
data Field
-- | Return the actual SQL data for a database field. This allows
-- user-defined FromField instances to access the SQL data
-- associated with a field being parsed.
fieldData :: Field -> SQLData
-- | Given one of the constructors from ResultError, the field, and
-- an errMessage, this fills in the other fields in the exception
-- value and returns it in a 'Left . SomeException' constructor.
returnError :: (Typeable a, Exception err) => (String -> String -> String -> err) -> Field -> String -> Ok a
instance Typeable ResultError
instance Eq ResultError
instance Show ResultError
instance FromField Day
instance FromField UTCTime
instance FromField ByteString
instance FromField [Char]
instance FromField Text
instance FromField Bool
instance FromField Double
instance FromField Integer
instance FromField Int64
instance FromField Int
instance FromField Int32
instance FromField Int16
instance FromField Null
instance FromField a => FromField (Maybe a)
instance Exception ResultError
-- | The FromRow typeclass, for converting a row of results returned
-- by a SQL query into a more useful Haskell representation.
--
-- Predefined instances are provided for tuples containing up to ten
-- elements.
module Database.SQLite.Simple.FromRow
-- | A collection type that can be converted from a sequence of fields.
-- Instances are provided for tuples up to 10 elements and lists of any
-- length.
--
-- Note that instances can defined outside of sqlite-simple, which is
-- often useful. For example, here's an instance for a user-defined pair:
--
--
-- data User = User { name :: String, fileQuota :: Int }
--
-- instance FromRow User where
-- fromRow = User <$> field <*> field
--
--
-- The number of calls to field must match the number of fields
-- returned in a single row of the query result. Otherwise, a
-- ConversionFailed exception will be thrown.
--
-- Note the caveats associated with user-defined implementations of
-- fromRow.
class FromRow a
fromRow :: FromRow a => RowParser a
data RowParser a
field :: FromField a => RowParser a
fieldWith :: FieldParser a -> RowParser a
numFieldsRemaining :: RowParser Int
instance (FromRow a, FromRow b) => FromRow (a :. b)
instance FromField a => FromRow [a]
instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h, FromField i, FromField j) => FromRow (a, b, c, d, e, f, g, h, i, j)
instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h, FromField i) => FromRow (a, b, c, d, e, f, g, h, i)
instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h) => FromRow (a, b, c, d, e, f, g, h)
instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g) => FromRow (a, b, c, d, e, f, g)
instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f) => FromRow (a, b, c, d, e, f)
instance (FromField a, FromField b, FromField c, FromField d, FromField e) => FromRow (a, b, c, d, e)
instance (FromField a, FromField b, FromField c, FromField d) => FromRow (a, b, c, d)
instance (FromField a, FromField b, FromField c) => FromRow (a, b, c)
instance (FromField a, FromField b) => FromRow (a, b)
instance FromField a => FromRow (Only a)
-- | The ToField typeclass, for rendering a parameter to an SQLite
-- value to be bound as a SQL query parameter.
module Database.SQLite.Simple.ToField
-- | A type that may be used as a single parameter to a SQL query.
class ToField a
toField :: ToField a => a -> SQLData
instance ToField Day
instance ToField UTCTime
instance ToField Text
instance ToField [Char]
instance ToField Text
instance ToField ByteString
instance ToField ByteString
instance ToField Double
instance ToField Float
instance ToField Word64
instance ToField Word
instance ToField Word32
instance ToField Word16
instance ToField Word8
instance ToField Integer
instance ToField Int64
instance ToField Int
instance ToField Int32
instance ToField Int16
instance ToField Int8
instance ToField Bool
instance ToField Null
instance ToField a => ToField (Maybe a)
instance ToField SQLData
-- | The ToRow typeclass, for rendering a collection of parameters
-- to a SQL query.
--
-- Predefined instances are provided for tuples containing up to ten
-- elements.
module Database.SQLite.Simple.ToRow
-- | A collection type that can be turned into a list of SQLData elements.
class ToRow a
toRow :: ToRow a => a -> [SQLData]
instance (ToRow a, ToRow b) => ToRow (a :. b)
instance ToField a => ToRow [a]
instance (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i, ToField j) => ToRow (a, b, c, d, e, f, g, h, i, j)
instance (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i) => ToRow (a, b, c, d, e, f, g, h, i)
instance (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h) => ToRow (a, b, c, d, e, f, g, h)
instance (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g) => ToRow (a, b, c, d, e, f, g)
instance (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f) => ToRow (a, b, c, d, e, f)
instance (ToField a, ToField b, ToField c, ToField d, ToField e) => ToRow (a, b, c, d, e)
instance (ToField a, ToField b, ToField c, ToField d) => ToRow (a, b, c, d)
instance (ToField a, ToField b, ToField c) => ToRow (a, b, c)
instance (ToField a, ToField b) => ToRow (a, b)
instance ToField a => ToRow (Only a)
instance ToRow ()
module Database.SQLite.Simple
-- | A query string. This type is intended to make it difficult to
-- construct a SQL query by concatenating string fragments, as that is an
-- extremely common way to accidentally introduce SQL injection
-- vulnerabilities into an application.
--
-- This type is an instance of IsString, so the easiest way to
-- construct a query is to enable the OverloadedStrings language
-- extension and then simply write the query in double quotes.
--
--
-- {-# LANGUAGE OverloadedStrings #-}
--
-- import Database.SQLite.Simple
--
-- q :: Query
-- q = "select ?"
--
--
-- The underlying type is a Text, and literal Haskell strings
-- that contain Unicode characters will be correctly transformed to
-- UTF-8.
newtype Query
Query :: Text -> Query
fromQuery :: Query -> Text
-- | Connection to an open database.
data Connection
-- | A collection type that can be turned into a list of SQLData elements.
class ToRow a
toRow :: ToRow a => a -> [SQLData]
-- | A collection type that can be converted from a sequence of fields.
-- Instances are provided for tuples up to 10 elements and lists of any
-- length.
--
-- Note that instances can defined outside of sqlite-simple, which is
-- often useful. For example, here's an instance for a user-defined pair:
--
--
-- data User = User { name :: String, fileQuota :: Int }
--
-- instance FromRow User where
-- fromRow = User <$> field <*> field
--
--
-- The number of calls to field must match the number of fields
-- returned in a single row of the query result. Otherwise, a
-- ConversionFailed exception will be thrown.
--
-- Note the caveats associated with user-defined implementations of
-- fromRow.
class FromRow a
fromRow :: FromRow a => RowParser a
-- | A single-value "collection".
--
-- This is useful if you need to supply a single parameter to a SQL
-- query, or extract a single column from a SQL result.
--
-- Parameter example:
--
--
-- query c "select x from scores where x > ?" (Only (42::Int))
--
--
-- Result example:
--
--
-- xs <- query_ c "select id from users"
-- forM_ xs $ \(Only id) -> {- ... -}
--
newtype Only a
Only :: a -> Only a
fromOnly :: Only a -> a
-- | A composite type to parse your custom data structures without having
-- to define dummy newtype wrappers every time.
--
--
-- instance FromRow MyData where ...
--
--
--
-- instance FromRow MyData2 where ...
--
--
-- then I can do the following for free:
--
--
-- res <- query' c ...
-- forM res $ \(MyData{..} :. MyData2{..}) -> do
-- ....
--
data (:.) h t
(:.) :: h -> t -> :. h t
data SQLData :: *
SQLInteger :: !Int64 -> SQLData
SQLFloat :: !Double -> SQLData
SQLText :: !Text -> SQLData
SQLBlob :: !ByteString -> SQLData
SQLNull :: SQLData
-- | An SQLite prepared statement.
data Statement
-- | Open a database connection to a given file. Will throw an exception if
-- it cannot connect.
--
-- Every open must be closed with a call to close.
--
-- If you specify ":memory:" or an empty string as the input filename,
-- then a private, temporary in-memory database is created for the
-- connection. This database will vanish when you close the connection.
open :: String -> IO Connection
-- | Close a database connection.
close :: Connection -> IO ()
-- | Opens a database connection, executes an action using this connection,
-- and closes the connection, even in the presence of exceptions.
withConnection :: String -> (Connection -> IO a) -> IO a
-- | 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 may crash. Enable only for debugging!
setTrace :: Connection -> Maybe (Text -> IO ()) -> IO ()
-- | Perform a SELECT or other SQL query that is expected to
-- return results. All results are retrieved and converted before this
-- function returns.
--
-- When processing large results, this function will consume a lot of
-- client-side memory. Consider using fold instead.
--
-- Exceptions that may be thrown:
--
--
-- - FormatError: the query string mismatched with given
-- arguments.
-- - ResultError: result conversion failed.
--
query :: (ToRow q, FromRow r) => Connection -> Query -> q -> IO [r]
-- | A version of query that does not perform query substitution.
query_ :: FromRow r => Connection -> Query -> IO [r]
-- | Returns the rowid of the most recent successful INSERT on the given
-- database connection.
--
-- See also http://www.sqlite.org/c3ref/last_insert_rowid.html.
lastInsertRowId :: Connection -> IO Int64
-- | Execute an INSERT, UPDATE, or other SQL query that
-- is not expected to return results.
--
-- Throws FormatError if the query could not be formatted
-- correctly.
execute :: ToRow q => Connection -> Query -> q -> IO ()
-- | A version of execute that does not perform query substitution.
execute_ :: Connection -> Query -> IO ()
field :: FromField a => RowParser a
-- | Perform a SELECT or other SQL query that is expected to
-- return results. Results are converted and fed into the action
-- callback as they are being retrieved from the database.
--
-- This allows gives the possibility of processing results in constant
-- space (for instance writing them to disk).
--
-- Exceptions that may be thrown:
--
--
-- - FormatError: the query string mismatched with given
-- arguments.
-- - ResultError: result conversion failed.
--
fold :: (FromRow row, ToRow params) => Connection -> Query -> params -> a -> (a -> row -> IO a) -> IO a
-- | A version of fold which does not perform parameter
-- substitution.
fold_ :: FromRow row => Connection -> Query -> a -> (a -> row -> IO a) -> IO a
-- | Opens a prepared statement. A prepared statement must always be closed
-- with a corresponding call to closeStatement before closing the
-- connection. Use nextRow to iterate on the values returned. Once
-- nextRow returns Nothing, you need to invoke reset
-- before reexecuting the statement again with nextRow.
openStatement :: Connection -> Query -> IO Statement
-- | Closes a prepared statement.
closeStatement :: Statement -> IO ()
-- | Opens a prepared statement, executes an action using this statement,
-- and closes the statement, even in the presence of exceptions.
withStatement :: Connection -> Query -> (Statement -> IO a) -> IO a
-- | Binds parameters to a prepared statement. Once nextRow returns
-- Nothing, the statement must be reset with the reset
-- function before it can be executed again by calling nextRow.
bind :: ToRow params => Statement -> params -> IO ()
-- | Resets a statement. This does not reset bound parameters, if any, but
-- allows the statement to be reexecuted again by invoking
-- nextRow.
reset :: Statement -> IO ()
-- | Binds parameters to a prepared statement and then resets them, even in
-- the presence of exceptions.
withBind :: ToRow params => Statement -> params -> IO a -> IO a
-- | Extracts the next row from the prepared statement.
nextRow :: FromRow r => Statement -> IO (Maybe r)
-- | Exception thrown if a Query was malformed. This may occur if
-- the number of '?' characters in the query string does not
-- match the number of parameters provided.
data FormatError
-- | Exception thrown if conversion from a SQL value to a Haskell value
-- fails.
data ResultError
instance Typeable FormatError
instance Eq FormatError
instance Show FormatError
instance Exception FormatError