Database.DynamoDB.TH

Template Haskell macros to automatically derive instances, create column datatypes and create migrations functions.

Derive instances for table and indexes

Use mkTableDefs to derive everything about a table and its indexes. After running the function, you will end up with lots of instances, data types for columns (P_TId, P_TBase, P_TDescr) and smart constructors for column (colTId, colTBase, colTDescr, etc.) and one function (migrate) that creates table and updates the indexes.

The migration function has signature:

 MonadAWS m => HashMap T.Text ProvisionedThroughput -> Maybe StreamViewType -> m0 ()

• Table by default equals name of the type.
• Attribute name is a field name from a first underscore (tId). This should make it compatibile with lens.
• Column name is capitalized attribute name with prepended col (colTId)
• Attribute names in an index table must be the same as Attribute names in the main table
• Auxiliary datatype for column is P_ followed by capitalized attribute name (P_TId)

data Test = Test {
    _tId :: Int
  , _tBase :: T.Text
  , _tDescr :: T.Text
  , _tDate :: T.Text
  , _tDict :: HashMap T.Text Inner
} deriving (Show, GHC.Generic)

data TestIndex = TestIndex {
  , i_tDate :: T.Text
  , i_tDescr :: T.Text
} deriving (Show, GHC.Generic)
mkTableDefs "migrate" (tableConfig (''Test, WithRange) [(''TestIndex, NoRange)] [])

Derive instances for nested records

Use deriveCollection for records that are nested. Use deriveEncodable for records that are nested in one table and serve as its own table at the same time.

@ data Book = Book { author :: T.Text , title :: T.Text } deriving (Show)

Sparse indexes

Define sparse index by defining the attribute as Maybe in the main table and directly in the index table.

data Table {
   hashKey :: UUID
 , published :: Maybe UTCTime
 , ...
}
data PublishedIndex {
    published :: UTCTime
 ,  hashKey :: UUID
 ,  ...
}
mkTableDefs "migrate" (tableConfig (''Table, NoRange) [(''PublishedIndex, NoRange)] [])

Main table definition

mkTableDefs

Arguments

:: String

Name of the migration function

-> TableConfig

-> Q [Dec]

Create instances, datatypes for table, fields and instances.

Example of what gets created:

data Test { first :: Text, second :: Text, third :: Int }
data TestIndex { third :: Int, second :: T.Text}

mkTableDefs (tableConfig (''Test, WithRange) [(''TestIndex, NoRange)] [])

deriveGenericOnly ''Test
instance DynamoCollection Test WithRange IsTable
...
instance DynamoTable Test WithRange
   tableName _ = "Test"

deriveGenericOnly ''TestIndex
instance DynamoCollection TestIndex NoRange IsIndex
...
instance DynamoIndex TestIndex Test NoRange IsIndex
   indexName _ = "TestIndex"

data P_First
instance ColumnInfo P_First where
    columnName _ = "first"
instance InCollection P_First Test 'NestedPath -- For every attribute
instance InCollection P_Second TestIndex 'FullPath -- For every non-primary attribute
colFirst :: Column Text TypColumn P_First
colFirst = Column

data TableConfig

Configuration of TH macro for creating table instances

Constructors

TableConfig

Fields

• tableSetup :: (Name, RangeType, String)

  Table type, primary key type, table name

• globalIndexes :: [(Name, RangeType, String)]

  Global index type, primary key type, index name

• localIndexes :: [(Name, String)]

  Local index type, index name

• translateField :: String -> String

  Translation of haskell field names to DynamoDB attribute names

tableConfig

Arguments

:: (Name, RangeType)

Table type name, primary key type

-> [(Name, RangeType)]

Global secondary index records, index key type

-> [Name]

Local secondary index records

-> TableConfig

Simple table configuration

defaultTranslate :: String -> String

Translates haskell field names to database attribute names. Strips everything up to first '_'.

Nested structures

deriveCollection :: Name -> (String -> String) -> Q [Dec]

Derive DynamoEncodable and prepare column instances for nested structures.

deriveEncodable :: Name -> (String -> String) -> WriterT [Dec] Q ()

Derive just the DynamoEncodable instance for structures that were already derived using mkTableDefs and you want to use them as nested structures as well.

Creates:

instance DynamoEncodable Type where
  dEncode val = Just (attributeValue & avM .~ gdEncodeG [fieldnames] val)
  dDecode (Just attr) = gdDecodeG [fieldnames] (attr ^. avM)
  dDecode Nothing = Nothing
instance InCollection column_type P_Column1 'NestedPath
instance InCollection column_type P_Column2 'NestedPath
...

Data types

data RangeType

Data collection type - with hash key or with hash+sort key

Constructors

NoRange

WithRange