postgrest/nix/UPGRADE.md

Checklist for upgrading Nix dependencies

The Nix dependencies of PostgREST should be updated regularly, in most cases it should be a very simple operation.

# Update pinned version of Nixpkgs
nix-shell --run nixpkgs-upgrade > nix/nixpkgs-version.nix

# Verify that everything builds
nix-build

The following checklist guides you through the complete process in more detail.

Upgrade the pinned version of nixpkgs

The pinned version of nixpkgs is defined in nix/nixpkgs-version.nix. The pin refers directly to a GitHub tarball for the given revision, which is more efficient than pulling the complete Git repository. To upgrade it to the current master of nixpkgs, you can use a small utility script defined in nix/nixpkgs-update.nix:

# From the root of the repository, enter nix-shell
nix-shell

# Run the utility script to pin the latest revision in master
nixpkgs-upgrade > nix/nixpkgs-version.nix

# Exit the nix-shell with Ctrl-d

Update pinned version of static-haskell-nix

We pin static-haskell-nix in nix/static-haskell-package.nix. Upgrade the pinned revision and the tarball hash if necessary. See nix/nixpkgs-upgrade.nix for how to get the correct tarball hash, or just change the hash to an arbitrary value of correct length, run nix-build and use the expected value from the resulting error message.

Review overlays

Check whether the individual overlays are still required.

Check if patches are still required and update them as needed

We track a number of PostgREST-specific patches in nix/patches. Check whether the pull-requests/issues linked in the default.nix have progressed and remove/modify the patches if they did. If conflicting changes occurred, you might have to rebase the respective patches.

Build everything

Using the PostgREST binary Nix cache is recommended. Install Cachix and run cachix use postgrest.

Run nix-build in the root directory of the project to build all PostgREST artifacts. This might take a long time, e.g. when our static GHC version needs to be rebuilt due to changes to some underlying package. If there are any errors, this is probably due to one of our patches. Try to fix them and re-run nix-build until everything builds.

Update the PostgREST binary cache

If you have access to the PostgREST cachix signing key, you can push the artifacts that you built locally to the binary cache. This will accelerate the CI builds and tests, sometimes dramatically. This might sometimes even be required to avoid build timeouts in CI.

You'll need to set the CACHIX_SIGNING_KEY before proceeding, e.g. by creating a file containing export CACHIX_SIGNING_KEY=... and sourcing that file, which avoids having the secret in you shell history.

To push all new artifacts to Cachix, run:

nix-store -qR --include-outputs $$(nix-instantiate) | cachix push postgrest

# Or, equivalently
make cachix-push-all

The nix-store command will query the nix-store to list all dependencies and build artifacts of PostgREST. The cachix command will efficiently push everything that is not yet cached to the binary cache.