Whenever calls to query or execute raise an SqlError exception, we wrap that exception in this data structure. This allows us to show the actual database query that has triggered the error.

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 FieldWithDefault 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.

The error message of a validator can be either a plain text value or a HTML formatted value

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

Access meta data for a database table

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 its 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

When row level security is enabled at runtime, this keeps track of the current logged in user and the postgresql role to switch to.

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 True when a record has not been inserted yet.

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

Example: Returns False after inserting a record.

>>> project <- createRecord project
>>> isNew project
False

Example: Returns False 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"

Turns an UUID into a Id type

let uuid :: UUID = "5240e79c-97ff-4a5f-8567-84112541aaba"
let userId :: Id User = packId uuid

Unwraps a Id value into an UUID

>>> unpackId ("296e5a50-b237-4ee9-83b0-17fb1e6f208f" :: Id User)
"296e5a50-b237-4ee9-83b0-17fb1e6f208f" :: UUID

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 ()" ()

Wraps the query with Row level security boilerplate, if a row level security context was provided

Example:

If a row level security context is given, this will turn a query like the following

withRLSParams runQuery "SELECT * FROM projects WHERE id = ?" (Only "..")

Into the following equivalent:

runQuery "SET LOCAL ROLE ?; SET LOCAL rls.ihp_user_id = ?; SELECT * FROM projects WHERE id = ?" ["ihp_authenticated", "<user id>", .."]

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

Example:

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

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

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

Example:

usersCount <- sqlQueryScalarOrNothing "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 company.id
       |> createRecord

   company <- company
       |> set #ownerId user.id
       |> updateRecord

Executes the given block with the main database role and temporarly sidesteps the row level security policies.

This is used e.g. by IHP AutoRefresh to be able to set up it's database triggers. When trying to set up a database trigger from the ihp_authenticated role, it typically fails because it's missing permissions. Using withRowLevelSecurityDisabled we switch to the main role which is allowed to set up database triggers.

SQL queries run from within the passed block are executed in their own transaction.

Example:

-- SQL code executed here might be run from the ihp_authenticated role
withRowLevelSecurityDisabled do
   -- SQL code executed here is run as the main IHP db role
   sqlExec "CREATE OR REPLACE FUNCTION .." ()

Returns the postgres connection when called within a withTransaction block

Throws an error if called from outside a withTransaction

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 (..)

Like deleteRecordById but for a list of Ids.

>>> let projectIds :: [ Id Project ] = ...
>>> delete projectIds
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 (.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.

Catches SqlError and wraps them in EnhancedSqlError

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"]

Shorthand filter function

In IHP code bases you often write filter functions such as these:

getUserPosts user posts =
    filter (\p -> p.userId == user.id) posts

This can be written in a shorter way using onlyWhere:

getUserPosts user posts =
    posts |> onlyWhere #userId user.id

Because the userId field is an Id, we can use onlyWhereReferences to make it even shorter:

getUserPosts user posts =
    posts |> onlyWhereReferences #userId user

If the Id field is nullable, we need to use onlyWhereReferencesMaybe:

getUserTasks user tasks =
    tasks |> onlyWhereReferencesMaybe #optionalUserId user

Shorthand filter function for Id fields

In IHP code bases you often write filter functions such as these:

getUserPosts user posts =
    filter (\p -> p.userId == user.id) posts

This can be written in a shorter way using onlyWhereReferences:

getUserPosts user posts =
    posts |> onlyWhereReferences #userId user

If the Id field is nullable, we need to use onlyWhereReferencesMaybe:

getUserTasks user tasks =
    tasks |> onlyWhereReferencesMaybe #optionalUserId user

See onlyWhere for more details.

Shorthand filter function for nullable Id fields

In IHP code bases you often write filter functions such as these:

getUserTasks user tasks =
    filter (\task -> task.optionalUserId == Just user.id) tasks

This can be written in a shorter way using onlyWhereReferencesMaybe:

getUserTasks user tasks =
    tasks |> onlyWhereReferencesMaybe #optionalUserId user

See onlyWhere for more details.