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

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

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.

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.

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

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

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 query using the hasql pool with prepared statements

This function executes a query using hasql's prepared statement mechanism, which provides better performance than postgresql-simple for repeated queries.

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

Example:

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

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

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.

Runs a sql statement (like a CREATE statement), but doesn't return any result

Example:

sqlExecDiscardResult "CREATE TABLE users ()" ()

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.

Detects errors caused by stale schema after make db recreates the database.

Matches four categories:

1. PostgreSQL "cached plan must not change result type" (error code 0A000) — the server rejects a prepared statement whose result columns changed.
2. PostgreSQL "cache lookup failed for type" (error code XX000) — a prepared statement references a type OID that no longer exists after schema recreation (types get new OIDs).
3. Hasql MissingTypesSessionError — custom enum types (e.g. JOB_STATUS) get new OIDs after schema recreation, and hasql's type registry can't find them.
4. Hasql UnexpectedColumnTypeStatementError — the column's type OID no longer matches the OID cached in the prepared statement / decoder.

Exception type for hasql errors

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.

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

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.

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.

Like fieldWithDefault but produces a hasql Snippet instead of a FieldWithDefault

When the field hasn't been touched, produces DEFAULT. Otherwise encodes the value using hasql's DefaultParamEncoder.

Like fieldWithUpdate but produces a hasql Snippet instead of a FieldWithUpdate

When the field hasn't been touched, produces the column name (keeping the current DB value). Otherwise encodes the new value using hasql's DefaultParamEncoder.

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