The class of data types that represent a database table. This class conveys information necessary to move a Haskell data structure in and out of a database table. The most important field is modelInfo, which describes the database table and column names. modelInfo has a reasonable default implementation for types that are members of the Generic class (using GHC's DeriveGeneric extension), provided the following conditions hold:

1. The data type must have a single constructor that is defined using record selector syntax.
2. The very first field of the data type must be a DBKey to represent the primary key. Other orders will cause a compilation error.
3. Every field of the data structure must be an instance of FromField and ToField.

If these three conditions hold and your database naming scheme follows the conventions of defaultModelInfo--namely that the table name is the same as the type name with the first character downcased, and the field names are the same as the column names--then it is reasonable to have a completely empty (default) instance declaration:

   data MyType = MyType { myKey :: !DBKey
                        , myName :: !S.ByteString
                        , myCamelCase :: !Int
                        , ...
                        } deriving (Show, Generic)
   instance Model MyType

The default modelInfo method is called defaultModelInfo. You may wish to use almost all of the defaults, but tweak a few things. This is easily accomplished by overriding a few fields of the default structure. For example, suppose your database columns use exactly the same name as your Haskell field names, but the name of your database table is not the same as the name of the Haskell data type. You can override the database table name (field modelTable) as follows:

   instance Model MyType where
       modelInfo = defaultModelInfo { modelTable = "my_type" }

Finally, if you dislike the conventions followed by defaultModelInfo, you can simply implement an alternate pattern. An example of this is underscoreModelInfo, which strips a prefix off every field name and converts everything from camel-case to underscore notation:

   instance Model MyType where
       modelInfo = underscoreModelInfo "my"

The above code will associate MyType with a database table my_type having column names key, name, camel_case, etc.

You can implement other patterns like underscoreModelInfo by calling defaultModelInfo and modifying the results. Alternatively, you can directly call the lower-level functions from which defaultModelInfo is built (defaultModelTable, defaultModelColumns, defaultModelGetPrimaryKey).

A ModelInfo T contains the information necessary for mapping T to a database table. Each Model type has a single ModelInfo associated with it, accessible through the modelInfo method of the Model class. Note the table and column names must all be unquoted in this data structure, as they will later be quoted using quoteIdent by the modelIdentifiers method.

SQL table and column identifiers that should be copied verbatim into queries. For normal models, these will simply be quoted versions of the fields in the corresponding ModelInfo. However, for special cases, the fields of this structure can contain unquoted SQL including JOIN keywords. In the case of joins, different elements of modelQColumns may be qualified by different table names.

Note that modelQColumns and modelQPrimaryColumn both contain table-qualified names (e.g., "\"my_type\".\"key\""), while modelQWriteColumns contains only the quoted column names.

Standard CRUD (create/read/update/delete) queries on a model.

An alternate Model pattern in which Haskell type and field names are converted from camel-case to underscore notation. The first argument is a prefix to be removed from field names (since Haskell requires field names to be unique across data types, while SQL allows the same column names to be used in different tables).

For example:

 data Bar = Bar {
     barId :: !DBKey
   , barNameOfBar :: !String
   , barParent :: !(Maybe (DBRef Bar))
   } deriving (Show, Generic)

 instance Model Bar where modelInfo = underscoreModelInfo "bar"

would associate type Bar with a database table called bar with fields id, name_of_bar, and parent.

A type large enough to hold database primary keys. Do not use this type directly in your data structures. Use DBKey to hold a Model's primary key and DBRef to reference the primary key of another model.

The type of the Haskell data structure field containing a model's primary key.

Every Model must have exactly one DBKey, and the DBKey must be the Model's very first field in the Haskel data type definition. (The ordering is enforced by defaultModelGetPrimaryKey, which, through use of the DeriveGeneric extension, fails to compile when the first field is not a DBKey.)

Each Model stored in the database should have a unique non-null primary key. However, the key is determined at the time the Model is inserted into the database. While you are constructing a new Model to insert, you will not have its key. Hence, you should use the value NullKey to let the database chose the key.

If you wish to store a Model's primary key as a reference in another Model, do not copy the DBKey structure. Use mkDBRef to convert the Model's primary key to a foreign key reference.

Returns True when a DBKey is NullKey.

A DBRef T represents a many-to-one relationship between tables. For example, if type A contains a DBRef B, then each B is associated with many A's. By contrast, a DBRefUnique represents a one-to-one relationship.

DBRef is a type alias of kind * -> *. The type DBRef T references an instance of type T by the primary key of its database row. The type argument T should be an instance of Model.

A DBRefUnique T represents a one-to-one relationship between types. For example, if type A contains a DBRefUnique B, then each A is associated with one (or at most one) B, and each B has one (or at most one) A associated with it.

By contrast, a DBRef represents a many-to-one relationship.

Many operations can take either a DBRef or a DBRefUnique (both of which consist internally of a DBKeyType). Hence, these two types are just type aliases to a generalized reference type GDBRef, where GDBRef's first type argument, reftype, is a phantom type denoting the flavor of reference (NormalRef or UniqueRef).

Create a reference to the primary key of a Model, suitable for storing in a DBRef or DBRefUnique field of a different Model.

Dump an entire model. Useful for development and debugging only, as every row will be read into memory before the function returns.

Note that unlike the other primary model operations, it is OK to call findAll even on degenerate models such as As and :..

Follow a DBRef or DBRefUnique and fetch the target row from the database into a Model type r.

Like trySave but instead of returning an Either, throws a ValidationError if the Model is invalid.

Write a Model to the database. If the primary key is NullKey, the item is written with an INSERT query, read back from the database, and returned with its primary key filled in. If the primary key is not NullKey, then the Model is written with an UPDATE query and returned as-is.

If the Model is invalid (i.e. the return value of modelValid is non-empty), a list of InvalidError is returned instead.

Remove the row corresponding to a particular data structure from the database. This function only looks at the primary key in the data structure. It is an error to call this function if the primary key is not set.

Remove a row from the database without fetching it first.

Lookup the modelTable of a Model (modelName _ = modelTable (modelInfo :: ModelInfo a)).

Lookup the primary key of a Model.

Generate a SQL SELECT statement with no WHERE predicate. For example, defaultModelLookupQuery consists of modelSelectFragment followed by "WHERE primary-key = ?".

A newtype wrapper in the FromRow class, permitting every model to be used as the result of a database query.

A newtype wrapper in the ToRow class, which marshalls every field except the primary key, followed by the primary key. For use with modelUpdateQuery.

A newtype wrapper in the ToRow class, which marshalls every field except the primary key. For use with modelInsertQuery.

The newtype As can be wrapped around an existing type to give it a table name alias in a query. This is necessary when a model is being joined with itself, to distinguish the two joined instances of the same table.

For example:

{-# LANGUAGE OverloadedStrings #-}

data X = X
instance RowAlias X where rowAliasName = const "x"

  ...
    r <- dbSelect c $ addWhere_ "bar.bar_key = x.bar_parent" modelDBSelect
         :: IO [Bar :. As X Bar]

fromAs extracts the row from an As alias row, but constrains the type of alias to be the same as its first argument (which is non-strict). This can save you from explicitly specifying types. For example:

 data X = X deriving (Generic)
 instance RowAlias X where rowAliasName = const "x"

 ...
   r <- map (\(b1 :. b2) -> (b1, fromAs X b2)) <$>
       dbSelect c $ addWhere \"bar.bar_key = x.bar_parent\" modelDBSelect

A type-restricted wrapper around the As constructor, under the same rationale as fromAs. Not strict in its first argument.

The class of types that can be used as tags in as As alias. Such types should be unit types--in other words, have exactly one constructor where the constructor is nullary (take no arguments). The reason for this class is that the Model instance for As requires a way to extract the name of the row alias without having a concrete instance of the type. This is provided by the rowAliasName method (which must be non-strict).

The default definition of modelInfo. See the documentation at Model for more information. Sets modelTable to the name of the type with the first character converted to lower-case. Sets modelColumns to the names of the Haskell field selectors. Sets modelPrimaryColumn to 0 and extracts the first field of the structure for modelGetPrimaryKey. Will fail to compile unless the data structure is defined with record syntax and that its first field is of type DBKey.

Note that defaults for the individual fields are available in separate functions (e.g., defaultModelTable) with fewer class requirements in the context, in case you want to make piecemeal use of defaults. The default for modelPrimaryColumn is 0. If you overwrite that, you will need to overwrite modelGetPrimaryKey as well (and likely vice versa).

The default name of the database table corresponding to a Haskell type. The default is the same as the type name with the first letter converted to lower-case. (The rationale is that Haskell requires types to start with a capital letter, but all-lower-case table names are easier to use in queries because PostgreSQL generally does not require them to be quoted.)

Returns the Haskell field names in a data structure.

Extract the primary key of type DBKey from a model when the DBKey is the first element of the data structure. Fails to compile if the first field is not of type DBKey.

The default simply quotes the modelInfo and modelColumns fields of ModelInfo using quoteIdent.

Returns a series of Actions serializing each field of a data structure (in the order of the Haskell datatype definition), except the primary key, since the primary key should never be written to a database. Every field must be an instance of ToField.

The default value of modelQueries.

Default SQL lookup query for a model.

Default SQL update query for a model.

Default SQL insert query for a model.

Default SQL delete query for a model.

Quote an identifier such as a table or column name using double-quote characters. Note this has nothing to do with quoting values, which must be quoted using single quotes. (Anyway, all values should be quoted by query or fmtSql.) This function uses a unicode escape sequence to escape '?' characters, which would otherwise be expanded by query, formatQuery, or fmtSql.

>>> S8.putStrLn $ quoteIdent "hello \"world\"!"
"hello ""world""!"
>>> S8.putStrLn $ quoteIdent "hello \"world\"?"
 U&"hello ""world""\003f"

Note that this quoting function is correct only if client_encoding is SQL_ASCII, client_coding is UTF8, or the identifier contains no multi-byte characters. For other coding schemes, this function may erroneously duplicate bytes that look like quote characters but are actually part of a multi-byte character code. In such cases, maliciously crafted identifiers will, even after quoting, allow injection of arbitrary SQL commands to the server.

The upshot is that it is unwise to use this function on identifiers provided by untrustworthy sources. Note this is true anyway, regardless of client_encoding setting, because certain "system column" names (e.g., oid, tableoid, xmin, cmin, xmax, cmax, ctid) are likely to produce unexpected results even when properly quoted.

See Id for a convenient way to include quoted identifiers in parameter lists.

Phantom type for instantiating GDBRef that represents a one-to-many relationship between tables.

Phantom type for instantiating GDBRef that represents a one-to-one relationship between tables.

Extra information for Database.PostgreSQL.ORM.CreateTable. You probably don't need to use this.

A ModelCreateInfo that doesn't imply any extra constraints or exceptions.

This function provides a fromRow function for Generic types, suitable as a default of the FromRow class. This module uses it as the default implementation of modelRead.

This function provides a toRow function for Generic types that marshalls each field of the data type in the order in which it appears in the type definition. This function is not a suitable implementation of modelWrite (since it marshals the primary key, which is not supposed to be written). However, it is required internally by defaultModelWrite, and exposed in the unlikely event it is of use to alternate generic modelWrite functions. You probably don't want to call this function.

Print to stdout the query statement.

This class extracts the first field in a data structure when the field is of type DBKey. If you get a compilation error because of this class, then move the DBKey first in your data structure.

This class extracts the field names of a Haskell data structure. Only defined for types with a single constructor that uses record syntax.

This class returns the name of a datatype.