Access meta data for a database table

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

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]

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

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

Bracket-style wrapper around createModelContext that ensures the database pool is released when the callback completes (or throws an exception).

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.

Unwraps a Id value into an UUID

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

Runs a query built from a dynamic Snippet.

Converts the snippet to a Statement and delegates to sqlStatementHasql.

Example:

users <- sqlQueryHasql pool snippet (Decoders.rowList userDecoder)

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

Turns an UUID into a Id type

let uuid :: UUID = "5240e79c-97ff-4a5f-8567-84112541aaba"
let userId :: Id User = packId 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

Runs a raw sql query. Untyped escape hatch — prefer the typed [typedSql| ... |] quasi quoter (from IHP.TypedSql) when the query is known at compile time.

Example:

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

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

• AutoRefresh:* When using unsafeSqlQuery 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 unsafeSqlQuerySingleRow if you expect only a single row to be returned.

Deprecated alias of unsafeSqlQuery. Prefer [typedSql| ... |] via sqlQueryTyped.

Runs a raw sql query, that is expected to return a single result row. Untyped escape hatch — prefer the typed [typedSql| ... |] quasi quoter.

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

Example:

user <- unsafeSqlQuerySingleRow "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 unsafeSqlQuerySingleRow 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.

Deprecated alias of unsafeSqlQuerySingleRow.

Runs a sql statement (like a CREATE statement). Untyped escape hatch — prefer the typed [typedSql| ... |] quasi quoter via sqlExecTyped.

Example:

unsafeSqlExec "CREATE TABLE users ()" ()

Like sqlExecHasql but returns the number of affected rows

When RLS is enabled, the statement is wrapped in a transaction that first sets the role and user id via setRLSConfigStatement.

Deprecated alias of unsafeSqlExec.

Runs a sql statement (like a CREATE statement), but doesn't return any result. Untyped escape hatch — prefer the typed [typedSql| ... |] quasi quoter via sqlExecTyped.

Example:

unsafeSqlExecDiscardResult "CREATE TABLE users ()" ()

Like sqlQueryHasql but for statements that don't return results (DELETE, etc.)

When RLS is enabled, the statement is wrapped in a transaction that first sets the role and user id via setRLSConfigStatement.

Deprecated alias of unsafeSqlExecDiscardResult.

Prepared statement that sets the RLS role and user id using set_config().

Uses set_config(setting, value, is_local) which is a regular SQL function that supports parameterized values in the extended query protocol, unlike SET LOCAL which is a utility command that cannot be parameterized.

The third argument true makes the setting local to the current transaction, equivalent to SET LOCAL.

Runs a hasql Statement directly on the pool.

Core execution function that handles session construction, RLS wrapping, pool execution, cached plan error retry, and debug logging. Works with both prepared (preparable) and unprepared statements.

Example:

result <- sqlStatementHasql pool someId myPreparedStatement

Run an IO action, logging its duration when the log level is Debug. The label is prepended to the timing message, e.g. "🔍 SELECT ...".

Like sqlStatementHasql but for write operations (DELETE, UPDATE, INSERT without results).

Uses Write for RLS transactions (vs Read in sqlStatementHasql). Takes a Statement directly — use this when you have a pre-built statement rather than a Snippet.

Example:

sqlExecStatement pool workerId myUpdateStatement

Like sqlExecHasql but for raw Session values (e.g. multi-statement DDL via sql)

Use this instead of sqlExecHasql when you need the simple protocol (no prepared statements), e.g. for multi-statement SQL like trigger creation.

Example:

runSessionHasql pool (Hasql.sql "BEGIN; CREATE ...; COMMIT;")

Existential wrapper for sub-session requests in a transaction

Loop that reads sub-session requests from an MVar and executes them on the current transaction's connection. Stops when it receives Nothing.

Runs a raw sql query which results in a single scalar value such as an integer or string. Untyped escape hatch — prefer the typed [typedSql| ... |] quasi quoter.

Example:

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

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

Deprecated alias of unsafeSqlQueryScalar.

Runs a raw sql query which results in a single scalar value such as an integer or string, or nothing. Untyped escape hatch — prefer the typed [typedSql| ... |] quasi quoter.

Example:

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

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

Deprecated alias of unsafeSqlQueryScalarOrNothing.

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

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 True if the named field has been touched (is in touchedFields). Used by generated Update statement modules to determine which columns to send.

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

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