Thrown by fetchOne when the query result is empty

Represents fields that may have been updated

The NoUpdate constructor represents the existing value in the database, while the Update constructor holds some new value for the field

Represents fields that have a default value in an SQL schema

The Default constructor represents the default value from the schema, while the NonDefault constructor holds some other value for the field

Every IHP database record has a magic meta field which keeps a MetaBag inside. This data structure is used e.g. to keep track of the validation errors that happend.

Helper type to deal with models where relations are included or that are only partially fetched Examples:

>>> NormalizeModel (Include "author_id" Post)
Post

>>> NormalizeModel Post
Post

Record type for objects of model types labeled with values from different database tables. (e.g. comments labeled with the IDs of the posts they belong to).

We need to map the model to it's table name to prevent infinite recursion in the model data definition E.g. `type Project = Project' { id :: Id Project }` will not work But `type Project = Project' { id :: Id "projects" }` will

Provides the primary key type for a given table. The instances are usually declared by the generated haskell code in Generated.Types

Example: Defining the primary key for a users table

type instance PrimaryKey "users" = UUID

Example: Defining the primary key for a table with a SERIAL pk

type instance PrimaryKey "projects" = Int

Provides the db connection and some IHP-specific db configuration

Provides a mock ModelContext to be used when a database connection is not available

Returns True when the record has not been saved to the database yet. Returns False otherwise.

Example: Returns False when a record has not been inserted yet.

>>> let project = newRecord @Project
>>> isNew project
False

Example: Returns True after inserting a record.

>>> project <- createRecord project
>>> isNew project
True

Example: Returns True for records which have been fetched from the database.

>>> book <- query @Book |> fetchOne
>>> isNew book
False

Returns the model name of a given model as Text

Example:

>>> modelName @User
"User"

>>> modelName @Project
"Project"

Transforms a text, bytestring or string into an Id. Throws an exception if the input is invalid.

Example:

let projectIdText = "7cbc76e2-1c4f-49b6-a7d9-5015e7575a9b" :: Text
let projectId = (textToId projectIdText) :: Id Project

In case your UUID value is hardcoded, there is also an IsString instance, so you can just write it like:

let projectId = "ca63aace-af4b-4e6c-bcfa-76ca061dbdc6" :: Id Project

Measure and log the query time for a given query action if the log level is Debug. If the log level is greater than debug, just perform the query action without measuring time.

Runs a raw sql query

Example:

users <- sqlQuery "SELECT id, firstname, lastname FROM users" ()

Take a look at IHP.QueryBuilder for a typesafe approach on building simple queries.

• AutoRefresh:* When using sqlQuery with AutoRefresh, you need to use trackTableRead to let AutoRefresh know that you have accessed a certain table. Otherwise AutoRefresh will not watch table of your custom sql query.

Runs a sql statement (like a CREATE statement)

Example:

sqlExec "CREATE TABLE users ()" ()

Runs a raw sql query which results in a single scalar value such as an integer or string

Example:

usersCount <- sqlQuery "SELECT COUNT(*) FROM users"

Take a look at IHP.QueryBuilder for a typesafe approach on building simple queries.

Executes the given block with a database transaction

Example:

withTransaction do
   company <- newRecord @Company |> createRecord

   -- When creating the user fails, there will be no company left over
   user <- newRecord @User
       |> set #companyId (get #id company)
       |> createRecord

   company <- company
       |> set #ownerId (get #id user)
       |> updateRecord

Returns the postgres connection when called within a withTransaction block

Throws an error if called from outside a withTransaction

Returns the table name of a given model.

Example:

>>> tableName @User
"users"

Returns the table name of a given model as a bytestring.

Example:

>>> tableNameByteString @User
"users"

Runs a DELETE query for a record.

>>> let project :: Project = ...
>>> deleteRecord project
DELETE FROM projects WHERE id = '..'

Use deleteRecords if you want to delete multiple records.

Like deleteRecord but using an Id

>>> let project :: Id Project = ...
>>> delete projectId
DELETE FROM projects WHERE id = '..'

Runs a DELETE query for a list of records.

>>> let projects :: [Project] = ...
>>> deleteRecords projects
DELETE FROM projects WHERE id IN (..)

Runs a DELETE query to delete all rows in a table.

>>> deleteAll @Project
DELETE FROM projects

Returns the ids for a list of models

Shorthand for map (get #id) records.

>>> users <- query @User |> fetch
>>> ids users
[227fbba3-0578-4eb8-807d-b9b692c3644f, 9d7874f2-5343-429b-bcc4-8ee62a5a6895, ...] :: [Id User]

Returns True if any fields of the record have unsaved changes

Example: Returns False for freshly fetched records

>>> let projectId = "227fbba3-0578-4eb8-807d-b9b692c3644f" :: Id Project
>>> project <- fetch projectId
>>> didChangeRecord project
False

Example: Returns True after setting a field

>>> let projectId = "227fbba3-0578-4eb8-807d-b9b692c3644f" :: Id Project
>>> project <- fetch projectId
>>> project |> set #name "New Name" |> didChangeRecord
True

Returns True if the specific field of the record has unsaved changes

Example: Returns False for freshly fetched records

>>> let projectId = "227fbba3-0578-4eb8-807d-b9b692c3644f" :: Id Project
>>> project <- fetch projectId
>>> didChange #name project
False

Example: Returns True after setting a field

>>> let projectId = "227fbba3-0578-4eb8-807d-b9b692c3644f" :: Id Project
>>> project <- fetch projectId
>>> project |> set #name "New Name" |> didChange #name
True

Example: Setting a flash message after updating the profile picture

when (user |> didChange #profilePictureUrl) (setSuccessMessage "Your Profile Picture has been updated. It might take a few minutes until it shows up everywhere")

Construct a FieldWithDefault

Use the default SQL value when the field hasn't been touched since the record was created. This information is stored in the $sel:touchedFields:MetaBag attribute of the meta field.

Construct a FieldWithUpdate

Use the current database value when the field hasn't been touched since the record was accessed. This information is stored in the $sel:touchedFields:MetaBag attribute of the meta field.

Useful to manually mark a table read when doing a custom sql query inside AutoRefresh or withTableReadTracker.

When using fetch on a query builder, this function is automatically called. That's why you only need to call it yourself when using sqlQuery to run a custom query.

Example:

action MyAction = autoRefresh do
    users <- sqlQuery "SELECT * FROM users WHERE .."
    trackTableRead "users"

    render MyView { .. }

Track all tables in SELECT queries executed within the given IO action.

You can read the touched tables by this function by accessing the variable ?touchedTables inside your given IO action.

Example:

withTableReadTracker do
    project <- query @Project |> fetchOne
    user <- query @User |> fetchOne

    tables <- readIORef ?touchedTables
    -- tables = Set.fromList ["projects", "users"]