Module Database.CDBI.ER

This is the main CDBI-module. It provides datatypes and functions to do Database-Queries working with Entities (ER-Model)

Author: Mike Tallarek, extensions by Julia Krone, Michael Hanus

Summary of exported operations:

insertEntry :: EntityDescription a -> a -> DBAction ()  Deterministic 
Inserts an entry into the database.
insertEntries :: EntityDescription a -> [a] -> DBAction ()  Deterministic 
Inserts several entries into the database.
restoreEntries :: EntityDescription a -> [a] -> DBAction ()  Deterministic 
Stores entries with their current keys in the database.
getEntries :: Specifier -> EntityDescription a -> Criteria -> [Option] -> Maybe Int -> DBAction [a]  Deterministic 
Gets entries from the database.
getColumn :: [SetOp] -> [SingleColumnSelect a] -> [Option] -> Maybe Int -> DBAction [a]  Deterministic 
Gets a single Column from the database.
getColumnTuple :: [SetOp] -> [TupleColumnSelect a b] -> [Option] -> Maybe Int -> DBAction [(a,b)]  Deterministic 
Gets two Columns from the database.
getColumnTriple :: [SetOp] -> [TripleColumnSelect a b c] -> [Option] -> Maybe Int -> DBAction [(a,b,c)]  Deterministic 
Gets three Columns from the database.
getColumnFourTuple :: [SetOp] -> [FourColumnSelect a b c d] -> [Option] -> Maybe Int -> DBAction [(a,b,c,d)]  Deterministic 
Gets four Columns from the database.
getColumnFiveTuple :: [SetOp] -> [FiveColumnSelect a b c d e] -> [Option] -> Maybe Int -> DBAction [(a,b,c,d,e)]  Deterministic 
Gets five Columns from the database.
getColumnSixTuple :: [SetOp] -> [SixColumnSelect a b c d e f] -> [Option] -> Maybe Int -> DBAction [(a,b,c,d,e,f)]  Deterministic 
Gets six Columns from the database.
getEntriesCombined :: Specifier -> CombinedDescription a -> [Join] -> Criteria -> [Option] -> Maybe Int -> DBAction [a]  Deterministic 
Gets combined entries from the database.
insertEntryCombined :: CombinedDescription a -> a -> DBAction ()  Deterministic 
Inserts combined entries.
updateEntries :: EntityDescription a -> [ColVal] -> Constraint -> DBAction ()  Deterministic 
Updates entries depending on wether they fulfill the criteria or not
updateEntry :: EntityDescription a -> a -> DBAction ()  Deterministic 
Updates an entry by ID.
updateEntryCombined :: CombinedDescription a -> a -> DBAction ()  Deterministic 
Same as updateEntry but for combined Data
deleteEntries :: EntityDescription a -> Maybe Constraint -> DBAction ()  Deterministic 
Deletes entries depending on wether they fulfill the criteria or not
getAllEntries :: EntityDescription a -> DBAction [a]  Deterministic 
Gets all entries of an entity stored in the database.
getCondEntries :: EntityDescription a -> (a -> Bool) -> DBAction [a]  Deterministic 
Gets all entries of an entity satisfying a given condition.
getEntryWithKey :: Show a => EntityDescription b -> Column c -> (a -> Value c) -> a -> DBAction b  Deterministic 
Gets an entry of an entity with a given key.
getEntriesWithColVal :: EntityDescription a -> Column b -> Value b -> DBAction [a]  Deterministic 
Get all entries of an entity where some column have a given value.
insertNewEntry :: EntityDescription a -> (a -> b -> a) -> (Int -> b) -> a -> DBAction a  Deterministic 
Inserts a new entry of an entity and returns the new entry with the new key.
deleteEntry :: EntityDescription a -> Column b -> (a -> Value b) -> a -> DBAction ()  Deterministic 
Deletes an existing entry from the database.
deleteEntryR :: EntityDescription a -> Column b -> Value b -> Column c -> Value c -> DBAction ()  Deterministic 
Deletes an existing binary relation entry from the database.
showDatabaseKey :: String -> (a -> Int) -> a -> String  Deterministic 
Shows a database key for an entity name as a string.
readDatabaseKey :: String -> (Int -> a) -> String -> Maybe a  Deterministic 
Transforms a string into a key for an entity name.
saveDBTerms :: Show a => EntityDescription a -> String -> String -> IO ()  Deterministic 
restoreDBTerms :: Read a => EntityDescription a -> String -> String -> IO ()  Deterministic 
Restores entries saved in a term file by deleting all existing entries and inserting the saved entries.
runQueryOnDB :: String -> DBAction a -> IO a  Deterministic 
Executes a DB action on a database and returns the result.
runTransactionOnDB :: String -> DBAction a -> IO (Either DBError a)  Deterministic 
Executes a DB action as a transcation on a database and returns the result.
runJustTransactionOnDB :: String -> DBAction a -> IO a  Deterministic 
Executes a DB action as a transcation on a database and returns the result.

Exported operations:

insertEntry :: EntityDescription a -> a -> DBAction ()  Deterministic 

Inserts an entry into the database.

Example call:
(insertEntry ed ent)
Parameters:
  • ed : The EntityDescription that describes the entity to be saved
  • ent : The entry to be inserted
Returns:
a DBAction with a void result

insertEntries :: EntityDescription a -> [a] -> DBAction ()  Deterministic 

Inserts several entries into the database.

Example call:
(insertEntries ed xs)
Parameters:
  • ed : The EntityDescription that describes the entities to be saved
  • xs : The list of entries to be inserted
Returns:
A Result without parameter if saving worked or an Error if there was a problem. If one saving operation reports an error, every following saving operation will be aborted but every saving operation up to that point will be executed. If these executed saving operations should also be discarded withTransaction or begin/commit/rollback should be used

restoreEntries :: EntityDescription a -> [a] -> DBAction ()  Deterministic 

Stores entries with their current keys in the database. It is an error if entries with the same key are already in the database. Thus, this operation is useful only to restore a database with saved data.

Example call:
(restoreEntries en xs)
Parameters:
  • en : The EntityDescription that describes the entities to be saved
  • xs : The list of entries to stored
Returns:
A Result without parameter if saving worked or an Error if there was a problem. If one saving operation reports an error, every following saving operation will be aborted but every saving operation up to that point will be executed. If these executed saving operations should also be discarded withTransaction or begin/commit/rollback should be used

getEntries :: Specifier -> EntityDescription a -> Criteria -> [Option] -> Maybe Int -> DBAction [a]  Deterministic 

Gets entries from the database.

Example call:
(getEntries spec en crit op limit)
Parameters:
  • spec : Specifier All or Distinct
  • en : The EntityDescription that describes the entity
  • crit : Criteria for the query
  • op : oreder-by clause
  • limit : int value to limit number of entities returned
Returns:
a DBAction with a list of entries

getColumn :: [SetOp] -> [SingleColumnSelect a] -> [Option] -> Maybe Int -> DBAction [a]  Deterministic 

Gets a single Column from the database.

Example call:
(getColumn setops sels)
Parameters:
  • setops : list of Setoperators to combine queries if more than one is given, can be empty otherwise
  • sels : list of SingleColumnSelects to specify query, if there are more requests than can be combined with setoperators they will be ignored (where a is the type of the column)

getColumnTuple :: [SetOp] -> [TupleColumnSelect a b] -> [Option] -> Maybe Int -> DBAction [(a,b)]  Deterministic 

Gets two Columns from the database.

Example call:
(getColumnTuple setops sels)
Parameters:
  • setops : list of Setoperators to combine queries if more than one is given, can be empty otherwise
  • sels : list of TupleColumnSelects to specify queries, if there are more requests than can be combined with setoperators they will be ignored (where a is the type of the column)

getColumnTriple :: [SetOp] -> [TripleColumnSelect a b c] -> [Option] -> Maybe Int -> DBAction [(a,b,c)]  Deterministic 

Gets three Columns from the database.

Example call:
(getColumnTriple setops sels)
Parameters:
  • setops : list of Setoperators to combine queries if more than one is given, can be empty otherwise
  • sels : list of TripleColumnSelects to specify queries, if there are more requests than can be combined with setoperators they will be ignored (where a is the type of the column)

getColumnFourTuple :: [SetOp] -> [FourColumnSelect a b c d] -> [Option] -> Maybe Int -> DBAction [(a,b,c,d)]  Deterministic 

Gets four Columns from the database.

Example call:
(getColumnFourTuple setops sels)
Parameters:
  • setops : list of Setoperators to combine queries if more than one is given, can be empty otherwise
  • sels : list of FourColumnSelects to specify queries, if there are more requests than can be combined with setoperators they will be ignored (where a is the type of the column)

getColumnFiveTuple :: [SetOp] -> [FiveColumnSelect a b c d e] -> [Option] -> Maybe Int -> DBAction [(a,b,c,d,e)]  Deterministic 

Gets five Columns from the database.

Example call:
(getColumnFiveTuple setops sels)
Parameters:
  • setops : list of Setoperators to combine queries if more than one is given, can be empty otherwise
  • sels : list of FiveColumnSelects to specify queries, if there are more requests than can be combined with setoperators they will be ignored (where a is the type of the column)

getColumnSixTuple :: [SetOp] -> [SixColumnSelect a b c d e f] -> [Option] -> Maybe Int -> DBAction [(a,b,c,d,e,f)]  Deterministic 

Gets six Columns from the database.

Example call:
(getColumnSixTuple setops sels)
Parameters:
  • setops : list of Setoperators to combine queries if more than one is given, can be empty otherwise
  • sels : list of SixColumnSelects to specify queries, if there are more requests than can be combined with setoperators they will be ignored (where a is the type of the column)

getEntriesCombined :: Specifier -> CombinedDescription a -> [Join] -> Criteria -> [Option] -> Maybe Int -> DBAction [a]  Deterministic 

Gets combined entries from the database.

Example call:
(getEntriesCombined spec cd joins crit op limit)
Parameters:
  • spec : Specifier Distinct or All
  • cd : The CombinedDescription that describes the entity
  • joins : joins to combine the entity, they will be applied in a left-associative manner
  • crit : Criteria for the query
  • op : order-by-clause
  • limit : int value to determine number of values returned
Returns:
A DBAction with a list of entries

insertEntryCombined :: CombinedDescription a -> a -> DBAction ()  Deterministic 

Inserts combined entries.

Example call:
(insertEntryCombined cd ent)
Parameters:
  • cd : The CombinedDescription that describes the entity
  • ent : The combined Entity to be inserted
Returns:
A Result without parameter if saving worked or an Error if there was a problem

updateEntries :: EntityDescription a -> [ColVal] -> Constraint -> DBAction ()  Deterministic 

Updates entries depending on wether they fulfill the criteria or not

Example call:
(updateEntries en xs const)
Parameters:
  • en : The EntityDescription descriping the Entities that are to be updated
  • xs : A list of ColVal that descripe the columns that should be updated and which values are to be inserted into them
  • const : A Constraint can be be given as input which describes which entities should be updated. Only entities fulfilling the constraint will be updated. Nothing updates every entry.
Returns:
A Result without parameter if everything went right, an Error if something went wrong
Further infos:
  • partially defined

updateEntry :: EntityDescription a -> a -> DBAction ()  Deterministic 

Updates an entry by ID. Works for Entities that have a primary key as first value. This operation updates the entry in the database with the ID of the entry that is given as parameter with the values of the entry given as parameter.

Example call:
(updateEntry ed entry)
Parameters:
  • ed : The EntityDescription describung the entity-type
  • entry : The entry that will be updated
Returns:
A Result without parameter if everything went right, an Error if something went wrong

updateEntryCombined :: CombinedDescription a -> a -> DBAction ()  Deterministic 

Same as updateEntry but for combined Data

deleteEntries :: EntityDescription a -> Maybe Constraint -> DBAction ()  Deterministic 

Deletes entries depending on wether they fulfill the criteria or not

Example call:
(deleteEntries en const)
Parameters:
  • en : The EntityDescription descriping the Entities that are to be updated
  • const : A Constraint can be be given as input which describes which entities should be deleted. Only entities fulfilling the constraint will be deleted. Nothing deletes every entry.
Returns:
A Result without parameter if everything went right, an Error if something went wrong

getAllEntries :: EntityDescription a -> DBAction [a]  Deterministic 

Gets all entries of an entity stored in the database.

Example call:
(getAllEntries endescr)
Parameters:
  • endescr : the EntityDescription describing the entities
Returns:
a DB result with the list of entries if everything went right, or an error if something went wrong

getCondEntries :: EntityDescription a -> (a -> Bool) -> DBAction [a]  Deterministic 

Gets all entries of an entity satisfying a given condition.

Example call:
(getCondEntries endescr cond)
Parameters:
  • endescr : the EntityDescription describing the entities
  • cond : a predicate on entities
Returns:
a DB result with the list of entries if everything went right, or an error if something went wrong

getEntryWithKey :: Show a => EntityDescription b -> Column c -> (a -> Value c) -> a -> DBAction b  Deterministic 

Gets an entry of an entity with a given key.

Example call:
(getEntryWithKey endescr keycolumn keyval key)
Parameters:
  • endescr : the EntityDescription describing the entities
  • keycolumn : the column containing the primary key
  • keyval : the id-to-value function for entities
  • key : the key of the entity to be fetched
Returns:
a DB result with the entry if everything went right, or an error if something went wrong

getEntriesWithColVal :: EntityDescription a -> Column b -> Value b -> DBAction [a]  Deterministic 

Get all entries of an entity where some column have a given value.

Example call:
(getEntriesWithColVal endescr valcolumn val)
Parameters:
  • endescr : the EntityDescription describing the entities
  • valcolumn : the column containing the required value
  • val : the value required for fetched entities
Returns:
a DB result with the entry if everything went right, or an error if something went wrong

insertNewEntry :: EntityDescription a -> (a -> b -> a) -> (Int -> b) -> a -> DBAction a  Deterministic 

Inserts a new entry of an entity and returns the new entry with the new key.

Example call:
(insertNewEntry endescr setkey keycons entity)
Parameters:
  • endescr : the EntityDescription describing the inserted entities
  • setkey : the operation to set the key of an entry
  • keycons : the constructor for entity keys
  • entity : the entity to be inserted
Returns:
a DB result without a value if everything went right, or an error if something went wrong

deleteEntry :: EntityDescription a -> Column b -> (a -> Value b) -> a -> DBAction ()  Deterministic 

Deletes an existing entry from the database.

Example call:
(deleteEntry endescr keycolumn keyval entity)
Parameters:
  • endescr : the EntityDescription describing the entities to be deleted
  • keycolumn : the column containing the primary key
  • keyval : the mapping from entities to their primary keys as SQL vals
  • entity : the entity to be deleted
Returns:
a DB result without a value if everything went right, or an error if something went wrong

deleteEntryR :: EntityDescription a -> Column b -> Value b -> Column c -> Value c -> DBAction ()  Deterministic 

Deletes an existing binary relation entry from the database.

Example call:
(deleteEntryR endescr keycol1 keyval1 keycol2 keyval2)
Parameters:
  • endescr : the EntityDescription describing the entities to be deleted
  • keycol1 : the column containing the first key
  • keyval1 : the value of the first key to be deleted
  • keycol2 : the column containing the second key
  • keyval2 : the value of the second key to be deleted
Returns:
a DB result without a value if everything went right, or an error if something went wrong

showDatabaseKey :: String -> (a -> Int) -> a -> String  Deterministic 

Shows a database key for an entity name as a string. Useful if a textual representation of a database key is necessary, e.g., as URL parameters in web pages. This textual representation should not be used to store database keys in attributes!

readDatabaseKey :: String -> (Int -> a) -> String -> Maybe a  Deterministic 

Transforms a string into a key for an entity name. Nothing is returned if the string does not represent a reasonable key.

saveDBTerms :: Show a => EntityDescription a -> String -> String -> IO ()  Deterministic 

Example call:
(saveDBTerms endescr dbname path)
Parameters:
  • endescr : the EntityDescription of the entities to be saved
  • dbname : name of the database (e.g. "database.db")
  • path : directory where term file is written

restoreDBTerms :: Read a => EntityDescription a -> String -> String -> IO ()  Deterministic 

Restores entries saved in a term file by deleting all existing entries and inserting the saved entries.

Example call:
(restoreDBTerms endescr dbname path)
Parameters:
  • endescr : the EntityDescription of the entities to be restored
  • dbname : name of the database (e.g. "database.db")
  • path : directory where term file was saved

runQueryOnDB :: String -> DBAction a -> IO a  Deterministic 

Executes a DB action on a database and returns the result. An error is raised if the DB action produces an error.

Example call:
(runQueryOnDB dbname dbaction)
Parameters:
  • dbname : name of the database (e.g. "database.db")
  • dbaction : a database action
Returns:
the result of the action

runTransactionOnDB :: String -> DBAction a -> IO (Either DBError a)  Deterministic 

Executes a DB action as a transcation on a database and returns the result. If the DB action produces an error, the transaction is rolled back and the error is returned, otherwise the transaction is committed.

Example call:
(runTransactionOnDB str dbaction)
Parameters:
  • str : name of the database (e.g. "database.db")
  • dbaction : a database action
Returns:
the result of the action

runJustTransactionOnDB :: String -> DBAction a -> IO a  Deterministic 

Executes a DB action as a transcation on a database and returns the result. An error is raised if the DB action produces an error so that the transaction is rolled back.

Example call:
(runJustTransactionOnDB str dbaction)
Parameters:
  • str : name of the database (e.g. "database.db")
  • dbaction : a database action
Returns:
the result of the action