Database.Groundhog.Inspector

A library for creating datatypes and Groundhog mappings from a database schema. The mappings match the database structure so if you run migration for the generated mappings, no changes to schema should be suggested. The generated Haskell identifiers may sometimes conflict with each other and with Haskell keywords. If that happens, adjust ReverseNamingStyle.

Mapping essentials

collectTables

Arguments

:: (PersistBackend m, SchemaAnalyzer (Conn m))

=> (QualifiedName -> Bool)

Decides if we follow the reference to a table. It can be used to prevent mapping of the referenced audit or system tables

-> Maybe String

Schema name

-> m (Map QualifiedName TableInfo)

Returns tables from a passed schema and tables which they reference. If you call collectTables several times with different filtering functions, it is better to call followReferencedTables afterwards manually to ensure that no dependencies are missing

let filterRefs (schema, tableName) = schema /= "audit"
publicTables  <- collectTables filterRefs (Just "public")
websiteTables <- collectTables filterRefs (Just "website")
let allTables = publicTables <> websiteTables

data ReverseNamingStyle

It supplies the names for the haskell datatypes

Constructors

ReverseNamingStyle

Fields

• mkEntityName :: QualifiedName -> String

  Create name of the datatype. Parameters: table name.

• mkConstructorName :: QualifiedName -> String

  Create name of the constructor. Parameters: table name.

• mkFieldName :: QualifiedName -> String -> String

  Create name of the field. Parameters: table name, column name.

• mkKeyFieldName :: QualifiedName -> Reference -> String

  Create name for unique key field. It creates record name both for one-column and composite keys. Parameters: table name, reference.

• mkChooseReferencedUnique :: QualifiedName -> [UniqueDefInfo] -> UniqueDefInfo

  There can be several uniques with the same columns (one primary key and multiple constraints and indexes). The function must return a stable name regardless of the list order.

• mkUniqueKeyPhantomName :: QualifiedName -> UniqueDefInfo -> String

  Create name for phantom unique key used to parametrise Key. Parameters: table name, unique key definition.

• mkUniqueName :: QualifiedName -> Int -> UniqueDefInfo -> String

  Create name of unique in mapping. Parameters: table name, unique number, unique key definition.

defaultReverseNamingStyle :: ReverseNamingStyle

followReferencedTables

Arguments

:: (PersistBackend m, SchemaAnalyzer (Conn m))

=> (QualifiedName -> Bool)

Decides if we follow reference to this table. It can be used to prevent mapping of the referenced audit or system tables

-> Map QualifiedName TableInfo

-> m (Map QualifiedName TableInfo)

It looks for the references to the tables not contained in the passed map. If there are such references and the reference filter function returns True, the corresponding TableInfo is fetched and included into the map. The references for the newly added tables are processed in the same way. This function can be useful if your set of tables is created not by collectTables.

Creating Haskell datatypes

data DataCodegenConfig

Confuguration datatype generation

Constructors

DataCodegenConfig

Fields

• generateUniqueKeysPhantoms :: Bool

  The unique key phantoms can be generated by groundhog-inspector when creating mappings or by groundhog-th when processing mappings. Set this to False in case you have declaration collisions. They may happen if the mappings are passed to groundhog-th on the fly.

• mkType :: Column -> Type

  Creates a Haskell type. Typically this function analyzes column nullability and its DB type

defaultDataCodegenConfig :: DataCodegenConfig

generateData

Arguments

:: DataCodegenConfig

-> ReverseNamingStyle

-> Map QualifiedName TableInfo

Tables for which the mappings will be generated

-> Map QualifiedName (Dec, [Dec])

Returns declarations for the mapped datatype and auxiliary declarations like unique key phantom datatypes

showData :: Dec -> String

It pretty-prints Template Haskell declaration into compilable Haskell code

defaultMkType :: Column -> Type

sqliteMkType :: Column -> Type

It uses Sqlite type affinity to find the corresponding Haskell type

Creating mapping settings

generateMapping :: (PersistBackend m, SchemaAnalyzer (Conn m)) => ReverseNamingStyle -> Map QualifiedName TableInfo -> m (Map QualifiedName PSEntityDef)

minimizeMapping :: NamingStyle -> Dec -> PSEntityDef -> PSEntityDef

The mappings created by generateMapping contain a lot of setttings. This function makes the settings more compact by eliminating settings which are default for the passed NamingStyle.

showMappings :: [PSEntityDef] -> ByteString

It pretty-prints the mapping settings as JSON. Package groundhog-th accepts JSON and YAML which is a more human-readable superset of JSON. You can use a third-party tool to convert JSON to YAML.