Access meta data for a database table

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

Returns True when a record has no validation errors attached from a previous validation call

Example:

isValidProject :: Project -> Bool
isValidProject project =
    project
    |> validateField #name isNonEmpty
    |> isValid

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

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

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

Returns the model name of a given model as Text

Example:

>>> modelName @User
"User"

>>> modelName @Project
"Project"

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 True if set was called on that field

Example: Returns False for freshly fetched records

>>> let projectId = "227fbba3-0578-4eb8-807d-b9b692c3644f" :: Id Project
>>> project <- fetch projectId
>>> didTouchField #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 project.name |> didTouchField #name
True

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

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

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.

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.

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.

Use sqlQuerySingleRow if you expect only a single row to be returned.

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.

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 a mock ModelContext to be used when a database connection is not available

Unwraps a Id value into an UUID

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

Turns an UUID into a Id type

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

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

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.

Catches SqlError and wraps them in EnhancedSqlError

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, that is expected to return a single result row

Like sqlQuery, but useful when you expect only a single row as the result

Example:

user <- sqlQuerySingleRow "SELECT id, firstname, lastname FROM users WHERE id = ?" (Only user.id)

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

• AutoRefresh:* When using sqlQuerySingleRow 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 sql statement (like a CREATE statement), but doesn't return any result

Example:

sqlExecDiscardResult "CREATE TABLE users ()" ()

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

Returns ByteString, that represents the part of an SQL where clause, that matches on a tuple consisting of all the primary keys For table with simple primary keys this simply returns the name of the primary key column, without wrapping in a tuple >>> primaryKeyColumnSelector PostTag "(post_tags.post_id, post_tags.tag_id)" >>> primaryKeyColumnSelector Post "post_tags.post_id"

Returns WHERE conditions to match an entity by it's primary key

For tables with a simple primary key this returns a tuple with the id:

>>> primaryKeyCondition project
Plain "d619f3cf-f355-4614-8a4c-e9ea4f301e39"

If the table has a composite primary key, this returns multiple elements:

>>> primaryKeyCondition postTag
Many [Plain "(", Plain "0ace9270-568f-4188-b237-3789aa520588", Plain ",", Plain "0b58fdf5-4bbb-4e57-a5b7-aa1c57148e1c", Plain ")"]

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

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]

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

>>> deleteAll @Project
DELETE FROM projects

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 touchedFields attribute of the meta field.

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

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 touchedFields attribute of the meta field.

Thrown by fetchOne when the query result is empty

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.

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.

Copies all the fields (except the id field) into a new record

Example: Duplicate a database record (except the primary key of course)

project <- fetch projectId
duplicatedProject <- createRecord (copyRecord project)

Runs sql queries without logging them

Example:

users <- withoutQueryLogging (sqlQuery "SELECT * FROM users" ())