Safe Haskell	None
Language	Haskell2010

Database.Selda.Backend

Description

API for building Selda backends and adding support for more types in queries.

Synopsis

class MonadIO m => MonadSelda m where
data SeldaT m a
type SeldaM = SeldaT IO
data SeldaError
- = DbError String
- | SqlError String
data StmtID
data BackendID
- = SQLite
- | PostgreSQL
- | Other Text
type QueryRunner a = Text -> [Param] -> IO a
data SeldaBackend = SeldaBackend {
- runStmt :: Text -> [Param] -> IO (Int, [[SqlValue]])
- runStmtWithPK :: Text -> [Param] -> IO Int
- prepareStmt :: StmtID -> [SqlTypeRep] -> Text -> IO Dynamic
- runPrepared :: Dynamic -> [Param] -> IO (Int, [[SqlValue]])
- getTableInfo :: TableName -> IO [ColumnInfo]
- ppConfig :: PPConfig
- closeConnection :: SeldaConnection -> IO ()
- backendId :: BackendID
- disableForeignKeys :: Bool -> IO ()
}
data SeldaConnection
data SqlValue where
- SqlInt :: !Int -> SqlValue
- SqlFloat :: !Double -> SqlValue
- SqlString :: !Text -> SqlValue
- SqlBool :: !Bool -> SqlValue
- SqlBlob :: !ByteString -> SqlValue
- SqlNull :: SqlValue
data IndexMethod
- = BTreeIndex
- | HashIndex
data Param where
- Param :: !(Lit a) -> Param
data ColAttr
- = Primary
- | AutoIncrement
- | Required
- | Optional
- | Unique
- | Indexed (Maybe IndexMethod)
data PPConfig = PPConfig {
- ppType :: SqlTypeRep -> Text
- ppTypeHook :: SqlTypeRep -> [ColAttr] -> (SqlTypeRep -> Text) -> Text
- ppTypePK :: SqlTypeRep -> Text
- ppPlaceholder :: Int -> Text
- ppColAttrs :: [ColAttr] -> Text
- ppColAttrsHook :: SqlTypeRep -> [ColAttr] -> ([ColAttr] -> Text) -> Text
- ppAutoIncInsert :: Text
- ppMaxInsertParams :: Maybe Int
- ppIndexMethodHook :: IndexMethod -> Text
}
defPPConfig :: PPConfig
data TableName
data ColName
data ColumnInfo = ColumnInfo {
- colName :: ColName
- colType :: Either Text SqlTypeRep
- colIsPK :: Bool
- colIsAutoIncrement :: Bool
- colIsUnique :: Bool
- colIsNullable :: Bool
- colHasIndex :: Bool
- colFKs :: [(TableName, ColName)]
}
columnInfo :: Table a -> [ColumnInfo]
fromColInfo :: ColInfo -> ColumnInfo
mkTableName :: Text -> TableName
mkColName :: Text -> ColName
fromTableName :: TableName -> Text
fromColName :: ColName -> Text
rawTableName :: TableName -> Text
newConnection :: MonadIO m => SeldaBackend -> Text -> m SeldaConnection
allStmts :: SeldaConnection -> IO [(StmtID, Dynamic)]
seldaBackend :: MonadSelda m => m SeldaBackend
runSeldaT :: (MonadIO m, MonadMask m) => SeldaT m a -> SeldaConnection -> m a
seldaClose :: MonadIO m => SeldaConnection -> m ()
module Database.Selda.SqlType

Documentation

class MonadIO m => MonadSelda m where Source #

Some monad with Selda SQL capabilitites.

Note that the default implementations of invalidateTable and wrapTransaction flush the entire cache and disable caching when invoked. If you want to use Selda's built-in caching mechanism, you will need to implement these operations yourself.

Minimal complete definition

seldaConnection

Methods

seldaConnection :: m SeldaConnection Source #

Get the connection in use by the computation.

invalidateTable :: Table a -> m () Source #

Invalidate the given table as soon as the current transaction finishes. Invalidate the table immediately if no transaction is ongoing.

wrapTransaction Source #

Arguments

:: m ()	Signal transaction commit to SQL backend.
-> m ()	Signal transaction rollback to SQL backend.
-> m a	Transaction to perform.
-> m a

Safely wrap a transaction. To ensure consistency of the in-process cache, it is important that any cached tables modified during a transaction are invalidated ONLY if that transaction succeeds, AFTER the changes become visible in the database.

In order to be thread-safe in the presence of asynchronous exceptions, instances should:

Mask async exceptions.
Start bookkeeping of tables invalidated during the transaction.
Perform the transaction, with async exceptions restored.
Commit transaction, invalidate tables, and disable bookkeeping; OR
If an exception was raised, rollback transaction, disable bookkeeping, and re-throw the exception.

wrapTransaction Source #

Arguments

:: MonadMask m
=> m ()	Signal transaction commit to SQL backend.
-> m ()	Signal transaction rollback to SQL backend.
-> m a	Transaction to perform.
-> m a

Safely wrap a transaction. To ensure consistency of the in-process cache, it is important that any cached tables modified during a transaction are invalidated ONLY if that transaction succeeds, AFTER the changes become visible in the database.

In order to be thread-safe in the presence of asynchronous exceptions, instances should:

Mask async exceptions.
Start bookkeeping of tables invalidated during the transaction.
Perform the transaction, with async exceptions restored.
Commit transaction, invalidate tables, and disable bookkeeping; OR
If an exception was raised, rollback transaction, disable bookkeeping, and re-throw the exception.

Instances

(MonadIO m, MonadMask m) => MonadSelda (SeldaT m) Source #
Instance details Defined in Database.Selda.Backend.Internal Methods seldaConnection :: SeldaT m SeldaConnection Source # invalidateTable :: Table a -> SeldaT m () Source # wrapTransaction :: SeldaT m () -> SeldaT m () -> SeldaT m a -> SeldaT m a Source #

data SeldaT m a Source #

Monad transformer adding Selda SQL capabilities.

Instances

MonadTrans SeldaT Source #
Instance details Defined in Database.Selda.Backend.Internal Methods lift :: Monad m => m a -> SeldaT m a #
Monad m => Monad (SeldaT m) Source #
Instance details Defined in Database.Selda.Backend.Internal Methods (>>=) :: SeldaT m a -> (a -> SeldaT m b) -> SeldaT m b # (>>) :: SeldaT m a -> SeldaT m b -> SeldaT m b # return :: a -> SeldaT m a # fail :: String -> SeldaT m a #
Functor m => Functor (SeldaT m) Source #
Instance details Defined in Database.Selda.Backend.Internal Methods fmap :: (a -> b) -> SeldaT m a -> SeldaT m b # (<$) :: a -> SeldaT m b -> SeldaT m a #
Monad m => Applicative (SeldaT m) Source #
Instance details Defined in Database.Selda.Backend.Internal Methods pure :: a -> SeldaT m a # (<>) :: SeldaT m (a -> b) -> SeldaT m a -> SeldaT m b # liftA2 :: (a -> b -> c) -> SeldaT m a -> SeldaT m b -> SeldaT m c # (>) :: SeldaT m a -> SeldaT m b -> SeldaT m b # (<*) :: SeldaT m a -> SeldaT m b -> SeldaT m a #
MonadIO m => MonadIO (SeldaT m) Source #
Instance details Defined in Database.Selda.Backend.Internal Methods liftIO :: IO a -> SeldaT m a #
MonadThrow m => MonadThrow (SeldaT m) Source #
Instance details Defined in Database.Selda.Backend.Internal Methods throwM :: Exception e => e -> SeldaT m a #
MonadCatch m => MonadCatch (SeldaT m) Source #
Instance details Defined in Database.Selda.Backend.Internal Methods catch :: Exception e => SeldaT m a -> (e -> SeldaT m a) -> SeldaT m a #
MonadMask m => MonadMask (SeldaT m) Source #
Instance details Defined in Database.Selda.Backend.Internal Methods mask :: ((forall a. SeldaT m a -> SeldaT m a) -> SeldaT m b) -> SeldaT m b # uninterruptibleMask :: ((forall a. SeldaT m a -> SeldaT m a) -> SeldaT m b) -> SeldaT m b # generalBracket :: SeldaT m a -> (a -> ExitCase b -> SeldaT m c) -> (a -> SeldaT m b) -> SeldaT m (b, c) #
(MonadIO m, MonadMask m) => MonadSelda (SeldaT m) Source #
Instance details Defined in Database.Selda.Backend.Internal Methods seldaConnection :: SeldaT m SeldaConnection Source # invalidateTable :: Table a -> SeldaT m () Source # wrapTransaction :: SeldaT m () -> SeldaT m () -> SeldaT m a -> SeldaT m a Source #

type SeldaM = SeldaT IO Source #

The simplest form of Selda computation; SeldaT specialized to IO.

data SeldaError Source #

Thrown by any function in SeldaT if an error occurs.

Constructors

DbError String	Unable to open or connect to database.
SqlError String	An error occurred while executing query.

Instances

Eq SeldaError Source #
Instance details Defined in Database.Selda.Backend.Internal Methods (==) :: SeldaError -> SeldaError -> Bool # (/=) :: SeldaError -> SeldaError -> Bool #
Show SeldaError Source #
Instance details Defined in Database.Selda.Backend.Internal Methods showsPrec :: Int -> SeldaError -> ShowS # show :: SeldaError -> String # showList :: [SeldaError] -> ShowS #
Exception SeldaError Source #
Instance details Defined in Database.Selda.Backend.Internal Methods toException :: SeldaError -> SomeException # fromException :: SomeException -> Maybe SeldaError # displayException :: SeldaError -> String #

data StmtID Source #

A prepared statement identifier. Guaranteed to be unique per application.

Instances

Eq StmtID Source #
Instance details Defined in Database.Selda.Backend.Internal Methods (==) :: StmtID -> StmtID -> Bool # (/=) :: StmtID -> StmtID -> Bool #
Ord StmtID Source #
Instance details Defined in Database.Selda.Backend.Internal Methods compare :: StmtID -> StmtID -> Ordering # (<) :: StmtID -> StmtID -> Bool # (<=) :: StmtID -> StmtID -> Bool # (>) :: StmtID -> StmtID -> Bool # (>=) :: StmtID -> StmtID -> Bool # max :: StmtID -> StmtID -> StmtID # min :: StmtID -> StmtID -> StmtID #
Show StmtID Source #
Instance details Defined in Database.Selda.Backend.Internal Methods showsPrec :: Int -> StmtID -> ShowS # show :: StmtID -> String # showList :: [StmtID] -> ShowS #
Hashable StmtID Source #
Instance details Defined in Database.Selda.Backend.Internal Methods hashWithSalt :: Int -> StmtID -> Int # hash :: StmtID -> Int #

data BackendID Source #

Uniquely identifies some particular backend.

When publishing a new backend, consider submitting a pull request with a constructor for your backend instead of using the Other constructor.

Constructors

SQLite
PostgreSQL
Other Text

Instances

Eq BackendID Source #
Instance details Defined in Database.Selda.Backend.Internal Methods (==) :: BackendID -> BackendID -> Bool # (/=) :: BackendID -> BackendID -> Bool #
Ord BackendID Source #
Instance details Defined in Database.Selda.Backend.Internal Methods compare :: BackendID -> BackendID -> Ordering # (<) :: BackendID -> BackendID -> Bool # (<=) :: BackendID -> BackendID -> Bool # (>) :: BackendID -> BackendID -> Bool # (>=) :: BackendID -> BackendID -> Bool # max :: BackendID -> BackendID -> BackendID # min :: BackendID -> BackendID -> BackendID #
Show BackendID Source #
Instance details Defined in Database.Selda.Backend.Internal Methods showsPrec :: Int -> BackendID -> ShowS # show :: BackendID -> String # showList :: [BackendID] -> ShowS #

type QueryRunner a = Text -> [Param] -> IO a Source #

A function which executes a query and gives back a list of extensible tuples; one tuple per result row, and one tuple element per column.

data SeldaBackend Source #

A collection of functions making up a Selda backend.

Constructors

SeldaBackend

Fields

runStmt :: Text -> [Param] -> IO (Int, [[SqlValue]])
Execute an SQL statement.
runStmtWithPK :: Text -> [Param] -> IO Int
Execute an SQL statement and return the last inserted primary key, where the primary key is auto-incrementing. Backends must take special care to make this thread-safe.
prepareStmt :: StmtID -> [SqlTypeRep] -> Text -> IO Dynamic
Prepare a statement using the given statement identifier.
runPrepared :: Dynamic -> [Param] -> IO (Int, [[SqlValue]])
Execute a prepared statement.
getTableInfo :: TableName -> IO [ColumnInfo]
Get a list of all columns in the given table, with the type and any modifiers for each column. Return an empty list if the given table does not exist.
ppConfig :: PPConfig
SQL pretty-printer configuration.
closeConnection :: SeldaConnection -> IO ()
Close the currently open connection.
backendId :: BackendID
Unique identifier for this backend.
disableForeignKeys :: Bool -> IO ()
Turn on or off foreign key checking, and initiate/commit a transaction.
When implementing this function, it is safe to assume that disableForeignKeys True will always be called exactly once before each disableForeignKeys False.

data SeldaConnection Source #

data SqlValue where Source #

Some value that is representable in SQL.

Constructors

SqlInt :: !Int -> SqlValue
SqlFloat :: !Double -> SqlValue
SqlString :: !Text -> SqlValue
SqlBool :: !Bool -> SqlValue
SqlBlob :: !ByteString -> SqlValue
SqlNull :: SqlValue

Instances

Show SqlValue Source #
Instance details Defined in Database.Selda.SqlType Methods showsPrec :: Int -> SqlValue -> ShowS # show :: SqlValue -> String # showList :: [SqlValue] -> ShowS #

data IndexMethod Source #

Method to use for indexing with indexedUsing. Index methods are ignored by the SQLite backend, as SQLite doesn't support different index methods.

Constructors

BTreeIndex
HashIndex

Instances

Eq IndexMethod Source #
Instance details Defined in Database.Selda.Table.Type Methods (==) :: IndexMethod -> IndexMethod -> Bool # (/=) :: IndexMethod -> IndexMethod -> Bool #
Ord IndexMethod Source #
Instance details Defined in Database.Selda.Table.Type Methods compare :: IndexMethod -> IndexMethod -> Ordering # (<) :: IndexMethod -> IndexMethod -> Bool # (<=) :: IndexMethod -> IndexMethod -> Bool # (>) :: IndexMethod -> IndexMethod -> Bool # (>=) :: IndexMethod -> IndexMethod -> Bool # max :: IndexMethod -> IndexMethod -> IndexMethod # min :: IndexMethod -> IndexMethod -> IndexMethod #
Show IndexMethod Source #
Instance details Defined in Database.Selda.Table.Type Methods showsPrec :: Int -> IndexMethod -> ShowS # show :: IndexMethod -> String # showList :: [IndexMethod] -> ShowS #

data Param where Source #

A parameter to a prepared SQL statement.

Constructors

Param :: !(Lit a) -> Param

Instances

Eq Param Source #
Instance details Defined in Database.Selda.SQL Methods (==) :: Param -> Param -> Bool # (/=) :: Param -> Param -> Bool #
Ord Param Source #
Instance details Defined in Database.Selda.SQL Methods compare :: Param -> Param -> Ordering # (<) :: Param -> Param -> Bool # (<=) :: Param -> Param -> Bool # (>) :: Param -> Param -> Bool # (>=) :: Param -> Param -> Bool # max :: Param -> Param -> Param # min :: Param -> Param -> Param #
Show Param Source #
Instance details Defined in Database.Selda.SQL Methods showsPrec :: Int -> Param -> ShowS # show :: Param -> String # showList :: [Param] -> ShowS #
Hashable Param #
Instance details Defined in Database.Selda.Caching Methods hashWithSalt :: Int -> Param -> Int # hash :: Param -> Int #

data ColAttr Source #

Column attributes such as nullability, auto increment, etc. When adding elements, make sure that they are added in the order required by SQL syntax, as this list is only sorted before being pretty-printed.

Constructors

Primary
AutoIncrement
Required
Optional
Unique
Indexed (Maybe IndexMethod)

Instances

Eq ColAttr Source #
Instance details Defined in Database.Selda.Table.Type Methods (==) :: ColAttr -> ColAttr -> Bool # (/=) :: ColAttr -> ColAttr -> Bool #
Ord ColAttr Source #
Instance details Defined in Database.Selda.Table.Type Methods compare :: ColAttr -> ColAttr -> Ordering # (<) :: ColAttr -> ColAttr -> Bool # (<=) :: ColAttr -> ColAttr -> Bool # (>) :: ColAttr -> ColAttr -> Bool # (>=) :: ColAttr -> ColAttr -> Bool # max :: ColAttr -> ColAttr -> ColAttr # min :: ColAttr -> ColAttr -> ColAttr #
Show ColAttr Source #
Instance details Defined in Database.Selda.Table.Type Methods showsPrec :: Int -> ColAttr -> ShowS # show :: ColAttr -> String # showList :: [ColAttr] -> ShowS #

data PPConfig Source #

Backend-specific configuration for the SQL pretty-printer.

Constructors

PPConfig

Fields

ppType :: SqlTypeRep -> Text
The SQL type name of the given type.
This function should be used everywhere a type is needed to be printed but in primary keys position. This is due to the fact that some backends might have a special representation of primary keys (using sequences are such). If you have such a need, please use the ppTypePK record instead.
ppTypeHook :: SqlTypeRep -> [ColAttr] -> (SqlTypeRep -> Text) -> Text
Hook that allows you to modify ppType output.
ppTypePK :: SqlTypeRep -> Text
The SQL type name of the given type for primary keys uses.
ppPlaceholder :: Int -> Text
Parameter placeholder for the nth parameter.
ppColAttrs :: [ColAttr] -> Text
List of column attributes.
ppColAttrsHook :: SqlTypeRep -> [ColAttr] -> ([ColAttr] -> Text) -> Text
Hook that allows you to modify ppColAttrs output.
ppAutoIncInsert :: Text
The value used for the next value for an auto-incrementing column. For instance, DEFAULT for PostgreSQL, and NULL for SQLite.
ppMaxInsertParams :: Maybe Int
Insert queries may have at most this many parameters; if an insertion has more parameters than this, it will be chunked.
Note that only insertions of multiple rows are chunked. If your table has more than this many columns, you should really rethink your database design.
ppIndexMethodHook :: IndexMethod -> Text
CREATE INDEX suffix to indicate that the index should use the given index method.

defPPConfig :: PPConfig Source #

Default settings for pretty-printing. Geared towards SQLite.

The default definition of ppTypePK is 'defType, so that you don’t have to do anything special if you don’t use special types for primary keys.

data TableName Source #

Name of a database table.

Instances

Eq TableName Source #
Instance details Defined in Database.Selda.Types Methods (==) :: TableName -> TableName -> Bool # (/=) :: TableName -> TableName -> Bool #
Ord TableName Source #
Instance details Defined in Database.Selda.Types Methods compare :: TableName -> TableName -> Ordering # (<) :: TableName -> TableName -> Bool # (<=) :: TableName -> TableName -> Bool # (>) :: TableName -> TableName -> Bool # (>=) :: TableName -> TableName -> Bool # max :: TableName -> TableName -> TableName # min :: TableName -> TableName -> TableName #
Show TableName Source #
Instance details Defined in Database.Selda.Types Methods showsPrec :: Int -> TableName -> ShowS # show :: TableName -> String # showList :: [TableName] -> ShowS #
IsString TableName Source #
Instance details Defined in Database.Selda.Types Methods fromString :: String -> TableName #
Hashable TableName Source #
Instance details Defined in Database.Selda.Types Methods hashWithSalt :: Int -> TableName -> Int # hash :: TableName -> Int #

data ColName Source #

Name of a database column.

Instances

Eq ColName Source #
Instance details Defined in Database.Selda.Types Methods (==) :: ColName -> ColName -> Bool # (/=) :: ColName -> ColName -> Bool #
Ord ColName Source #
Instance details Defined in Database.Selda.Types Methods compare :: ColName -> ColName -> Ordering # (<) :: ColName -> ColName -> Bool # (<=) :: ColName -> ColName -> Bool # (>) :: ColName -> ColName -> Bool # (>=) :: ColName -> ColName -> Bool # max :: ColName -> ColName -> ColName # min :: ColName -> ColName -> ColName #
Show ColName Source #
Instance details Defined in Database.Selda.Types Methods showsPrec :: Int -> ColName -> ShowS # show :: ColName -> String # showList :: [ColName] -> ShowS #
IsString ColName Source #
Instance details Defined in Database.Selda.Types Methods fromString :: String -> ColName #

data ColumnInfo Source #

Comprehensive information about a column.

Constructors

ColumnInfo

Fields

colName :: ColName
Name of the column.
colType :: Either Text SqlTypeRep
Selda type of the column, or the type name given by the database if Selda couldn't make sense of the type.
colIsPK :: Bool
Is the given column the primary key of its table?
colIsAutoIncrement :: Bool
Is the given column auto-incrementing?
colIsUnique :: Bool
Is the column unique, either through a UNIQUE constraint or by virtue of being a primary key?
colIsNullable :: Bool
Can the column be NULL?
colHasIndex :: Bool
Does the column have an index?
colFKs :: [(TableName, ColName)]
Any foreign key (table, column) pairs referenced by this column.

Instances

Eq ColumnInfo Source #
Instance details Defined in Database.Selda.Backend.Internal Methods (==) :: ColumnInfo -> ColumnInfo -> Bool # (/=) :: ColumnInfo -> ColumnInfo -> Bool #
Show ColumnInfo Source #
Instance details Defined in Database.Selda.Backend.Internal Methods showsPrec :: Int -> ColumnInfo -> ShowS # show :: ColumnInfo -> String # showList :: [ColumnInfo] -> ShowS #

columnInfo :: Table a -> [ColumnInfo] Source #

Get the column information for each column in the given table.

fromColInfo :: ColInfo -> ColumnInfo Source #

Convert a ColInfo into a ColumnInfo.

mkTableName :: Text -> TableName Source #

Create a column name.

mkColName :: Text -> ColName Source #

Create a column name.

fromTableName :: TableName -> Text Source #

Convert a table name into a string, with quotes.

fromColName :: ColName -> Text Source #

Convert a column name into a string, with quotes.

rawTableName :: TableName -> Text Source #

Convert a table name into a string, without quotes.

newConnection :: MonadIO m => SeldaBackend -> Text -> m SeldaConnection Source #

Create a new Selda connection for the given backend and database identifier string.

allStmts :: SeldaConnection -> IO [(StmtID, Dynamic)] Source #

Get all statements and their corresponding identifiers for the current connection.

seldaBackend :: MonadSelda m => m SeldaBackend Source #

Get the backend in use by the computation.

runSeldaT :: (MonadIO m, MonadMask m) => SeldaT m a -> SeldaConnection -> m a Source #

Run a Selda transformer. Backends should use this to implement their withX functions.

seldaClose :: MonadIO m => SeldaConnection -> m () Source #

Close a reusable Selda connection. Closing a connection while in use is undefined. Passing a closed connection to runSeldaT results in a SeldaError being thrown. Closing a connection more than once is a no-op.

module Database.Selda.SqlType