v1.4.0

[mpscholten]

Highlights

• 🚀 Improved Dev Server: faster, more reliable reloads without race conditions.
• 📦 Ecosystem split: IHP now modular (ihp-ide, ihp-ssc, ihp-migrate, ihp-sitemap).
• 🔧 New helpers: createRecordDiscardResult, copyRecord, queryUnionList, orderByAscJoinedTable.
• 🛠️ Production-ready: warp + systemd integration, healthcheck endpoint, better job runner handling.
• 🐘 Compiler upgrade: GHC 9.8 (with support for 9.10 and 9.12).

---

Major Changes

• Added createRecordDiscardResult (complements updateRecordDiscardResult) for cases where the result is not needed (e.g. scheduling jobs).
• Added copyRecord for easier duplication of database records.
• Improved Dev Server reliability and performance. Race conditions on rapid file updates are fixed by using proper bracketed resource management.
• Split IHP into multiple packages (ihp-ide, ihp-ssc, ihp-migrate, ihp-sitemap) for cleaner dependency boundaries.
• Production improvements: integrated warp-systemd, added healthcheck endpoint, and improved socket activation.
• Upgraded to GHC 9.8, with support for 9.10.x and 9.12.x.

Minor Changes

Nix / Deployment

• Added options: rtsFlags, optimizationLevel, appName.
• Support for aarch64 NixOS deployments.
• Faster nix build via caching of Generated.Types.
• Simplified migration service (IHP_MIGRATION_DIR).
• Dropped dependency on ihp source to reduce closure size.
• Updated nixpkgs to 25.05 and devenv to 1.8.2.
• Use flake overlays instead of manual mkGhcCompiler.
• Don’t set system.stateVersion automatically (configured in project’s flake.nix).

Job Runner

• Jobs with timeouts are now restarted if workers crash.
• Improved async handling of jobrunner.
• Use ResourceT for job worker scheduling to avoid leaks.
• Exceptions are now printed to logs for easier debugging.
• Don’t log job worker SQL queries.

DataSync

• Fixes: arrays double-escaped, connections closed prematurely, crash with spaces in table names, non-snake_case column names.
• Features: added useCount, custom newRecordBehaviour, support for event triggers, React 18 useSyncExternalStore.
• Avoid creating large_pg_notifications table when not needed.

HSX / View Layer

• Added uncheckedHsx and customHsx.
• Lucid2 port and core library split.
• Added missing HTML attributes.
• Fixed generator issues (brackets, variable references, migrations).
• Use Blaze helpers in HSX.

SQL / Query Layer

• Added filterWhereInCaseInsensitive, queryUnionList, orderByAscJoinedTable / orderByDescJoinedTable.
• Refactored pagination queries.
• Logging improvements: show final SQL, rounded runtimes, simplified log format with icons.

Storage

• Support custom storage directory via IHP_STORAGE_DIR.
• Support custom filenames in storeFileFromPath.
• S3 storagePrefix now returns base URL.
• Fix createTemporaryDownloadUrlFromPath.

Miscellaneous

• Support custom base URL in assetPath.
• Add withPGListener.
• Always evaluate Blaze HTML.
• Added mainInParentDirectory.
• Enabled warp file cache in production.
• Set default gracefulShutdownTimeout.
• Improved schema compiler performance.

IHP OpenAI

• Removed deprecated prompt field.
• Added support for tools and tool calls, response_format, Anthropic cache_control, Google Gemini.
• Added extraHeaders, finish_reason, usage in streaming responses.
• Changed maxTokens, temperature, presencePenalty, frequencyPenalty to Maybe.
• Improved error messages and quota exceeded feedback.
• Added reasoningEffort and parallelToolCalls.
• system_fingerprint is now optional.

Documentation

• Improved deployment docs (workers, systemd integration, AWS Terraform).
• Updated guides for pagination, htmx, realtime SPAs.
• Clarified environment differences between dev/prod.
• Added docs for validateFieldIO and scheduled job execution with runAt.
• Removed outdated NixOS installation instructions.
• Cleaned up Emacs docs.
• Added troubleshooting notes for EC2 deployments.

New Contributors

• @andreytroeglazov made their first contribution in Fix multiple checkboxes submit #1986
• @leifmetcalf made their first contribution in Update shopify blog link in tutorial #2002
• @kukimik made their first contribution in Fix grepping for direnv, add profile files to messages #2001
• @kursataktas made their first contribution in Introducing IHP Guru on Gurubase.io #2014
• @mmc102 made their first contribution in update two small grammatical errors in the docs #2019
• @Nathan-8963 made their first contribution in Update realtime SPA docs #2025
• @iteratee made their first contribution in Add Lucid2 backend to ihp-hsx #2055
• @stephenbenedict made their first contribution in Add docs for using validateFieldIO #2062
• @ANU-2524 made their first contribution in Fix deprecated 'convert' command to 'magick' in ImageMagick.hs #2078

Full Changelog: v1.3.0...v1.4.0

---

This discussion was created from the release v1.4.0.

[unhammer]

Congrats on the release 🎉 Happy to be able to delete my own versions getCookie and copyRecord helpers, and looking forward to the dev server improvements and many papercut-fixes :-)

---

Here are some of my own upgrade notes, maybe some of this could be mentioned in UPGRADE.md:

Migrations

Before, I would nix-shell --run migrate to run migrations before deploying a new docker image. But that command is no longer available by default since ihp-migrate is now its own package.

By adding p.ihp-migrate to haskellPackages I can run it from nix-shell or in the direnv. However, for running it when deploying from Github Actions I found it ran faster by adding its own devshell. I put

                devShells.ihp-migrate = pkgs.mkShell {
                  buildInputs = [
                    pkgs.ghc.ihp-migrate
                  ];
                };

in flake.nix in perSystem (after the whole ihp block). This lets you run nix develop .#ihp-migrate --command migrate.

Maybe there's already something like this builtin? (In any case, Guide/database-migrations.markdown needs updating.)

Package management

Before, version overrides went in Config/nix/haskell-packages. These are no longer used. The procedure is now to fork nixpkgs, do the changes there, and point flake.nix at the fork. But the fork should start from the nixpkgs commit that this IHP version was based off.

So before adding nixpkgs.url to the flake you need to find the IHP nixpkgs commit (Revision), ie. run

$ nix flake metadata nixpkgs
Resolved URL:  github:NixOS/nixpkgs/nixpkgs-unstable
Locked URL:    github:NixOS/nixpkgs/c6a788f552b7b7af703b1a29802a7233c0067908
Description:   A collection of packages for the Nix package manager
Revision:      c6a788f552b7b7af703b1a29802a7233c0067908
Last modified: 2025-09-03 16:58:13
Fingerprint:   3e05021e9dd32512ef43eb88791de71e5e822d62db4d9db7aa5fe41348da26cd

The hit fork on https://github.com/NixOS/nixpkgs and open https://github.com/YOURUSER/nixpkgs/tree/c6a788f552b7b7af703b1a29802a7233c0067908 and click the tag/branch selector and give it a name like ihp-1.4 and click the "Create branch ihp-1.4 from c6a788f" button.

The you can shallow clone (nixpkgs is big, shallow is faster) from that commit, and give it some new name for your changes:

git clone --depth 3 -b ihp-1.4 https://github.com/YOURUSER/nixpkgs
git checkout -b some-new-name

Now you can edit pkgs/development/haskell-modules/hackage-packages.nix and pkgs/development/haskell-modules/configuration-hackage2nix/stackage.yaml, e.g. I wanted to change HPDF so I look for "HPDF" in that file and replace the existing entry with the output of cabal2nix (that I earlier had in Config/nix/haskell-packages/HPDF.nix). Then commit and push those changes to your fork. Grab the revision of your fork and use that commit in nixpkgs.url in your flake.nix, e.g.

        # nixpkgs.follows = "ihp/nixpkgs"; # Overridden to upgrade HPDF:
        nixpkgs.url = "github:YOURUSER/nixpkgs?rev=f1a3f4a14f65dde8450c80cf57132a87f0f06b45";

and Config/nix/haskell-packages can be deleted.

(I guess Guide/package-management.markdown needs updating with something like this.)

[mpscholten]

thanks 👍 these are great notes! :) Could you make a PR to add these to UPGRADE.md?

If you're up to, we could also update the documentation on package management with some of these notes

[unhammer]

#2120