From bd61cf9b600d8f3c221f3fa8a6b1637a73ef8a78 Mon Sep 17 00:00:00 2001
From: Wolfgang Walther <walther@technowledgy.de>
Date: Thu, 10 Jul 2025 09:34:42 +0200
Subject: [PATCH] nix: re-introduce postgrest-nixpkgs-upgrade

Resolves #4161
---
 default.nix                |  4 ++++
 nix/README.md              | 42 +++++++++++++++++++-------------------
 nix/tools/nixpkgsTools.nix | 28 +++++++++++++++++++++++++
 shell.nix                  |  1 +
 4 files changed, 54 insertions(+), 21 deletions(-)
 create mode 100644 nix/tools/nixpkgsTools.nix

diff --git a/default.nix b/default.nix
index c60524c96..d5d9ead48 100644
--- a/default.nix
+++ b/default.nix
@@ -133,6 +133,10 @@ rec {
   loadtest =
     pkgs.callPackage nix/tools/loadtest.nix { inherit withTools; };
 
+  # Utility for updating the pinned version of Nixpkgs.
+  nixpkgsTools =
+    pkgs.callPackage nix/tools/nixpkgsTools.nix { };
+
   # Scripts for publishing new releases.
   release =
     pkgs.callPackage nix/tools/release.nix { };
diff --git a/nix/README.md b/nix/README.md
index aedc8bc80..9a0cb7b8c 100644
--- a/nix/README.md
+++ b/nix/README.md
@@ -72,25 +72,25 @@ The PostgREST utilities available in `nix-shell` all have names that begin with
 ```bash
 # Note: The utilities listed here might not be up to date.
 [nix-shell]$ postgrest-<tab>
-postgrest-build                   postgrest-profiled-run
-postgrest-check                   postgrest-push-cachix
-postgrest-clean                   postgrest-release
-postgrest-commitlint              postgrest-repl
-postgrest-coverage                postgrest-run
-postgrest-coverage-draft-overlay  postgrest-style
-postgrest-docs-build              postgrest-style-check
-postgrest-docs-check              postgrest-test-big-schema
-postgrest-docs-dictcheck          postgrest-test-doctests
-postgrest-docs-linkcheck          postgrest-test-io
-postgrest-docs-render             postgrest-test-memory
-postgrest-docs-serve              postgrest-test-replica
-postgrest-docs-spellcheck         postgrest-test-spec
-postgrest-dump-minimal-imports    postgrest-test-spec-idempotence
-postgrest-dump-schema             postgrest-watch
-postgrest-gen-ctags               postgrest-with-all
-postgrest-gen-jwt                 postgrest-with-git
-postgrest-gen-secret              postgrest-with-pgrst
-postgrest-git-hooks
+postgrest-build                   postgrest-parallel-curl
+postgrest-check                   postgrest-profiled-run
+postgrest-clean                   postgrest-push-cachix
+postgrest-commitlint              postgrest-release
+postgrest-coverage                postgrest-repl
+postgrest-coverage-draft-overlay  postgrest-run
+postgrest-docs-build              postgrest-style
+postgrest-docs-check              postgrest-style-check
+postgrest-docs-dictcheck          postgrest-test-big-schema
+postgrest-docs-linkcheck          postgrest-test-doctests
+postgrest-docs-render             postgrest-test-io
+postgrest-docs-serve              postgrest-test-memory
+postgrest-docs-spellcheck         postgrest-test-replica
+postgrest-dump-minimal-imports    postgrest-test-spec
+postgrest-dump-schema             postgrest-test-spec-idempotence
+postgrest-gen-ctags               postgrest-watch
+postgrest-gen-jwt                 postgrest-with-all
+postgrest-gen-secret              postgrest-with-git
+postgrest-git-hooks               postgrest-with-pgrst
 postgrest-hsie-graph-modules      postgrest-with-postgresql-13
 postgrest-hsie-graph-symbols      postgrest-with-postgresql-14
 postgrest-hsie-minimal-imports    postgrest-with-postgresql-15
@@ -98,7 +98,7 @@ postgrest-lint                    postgrest-with-postgresql-16
 postgrest-loadtest                postgrest-with-postgresql-17
 postgrest-loadtest-against        postgrest-with-slow-pg
 postgrest-loadtest-report         postgrest-with-slow-postgrest
-postgrest-parallel-curl
+postgrest-nixpkgs-upgrade
 ...
 
 [nix-shell]$
@@ -380,7 +380,7 @@ that).
 We also use `default.nix` to load our pinned version of the `nixpkgs`
 repository. This set of packages will always be the same, independently from
 where or when you use it. The pinned version is taken from `flake.lock` and
-can be updated with `nix flake update`.
+can be updated with `postgrest-nixpkgs-upgrade`.
 
 ### `shell.nix`
 
diff --git a/nix/tools/nixpkgsTools.nix b/nix/tools/nixpkgsTools.nix
new file mode 100644
index 000000000..db1f76234
--- /dev/null
+++ b/nix/tools/nixpkgsTools.nix
@@ -0,0 +1,28 @@
+{ buildToolbox
+, checkedShellScript
+}:
+# Utility script for pinning the latest stable version of Nixpkgs.
+
+# Instead of running `nix flake update` manually, we run this script
+# to also pin readthedocs dependencies at the same time.
+let
+  upgrade =
+    checkedShellScript
+      {
+        name = "postgrest-nixpkgs-upgrade";
+        docs = "Pin the newest version of Nixpkgs.";
+        workingDir = "/";
+      }
+      ''
+        nix flake update
+
+        echo "# This file is auto-generated by postgrest-nixpkgs-upgrade" > docs/requirements.txt
+        cat "$(nix-build -A docs.requirements)" >> docs/requirements.txt
+      '';
+
+in
+buildToolbox
+{
+  name = "postgrest-nixpkgs";
+  tools = { inherit upgrade; };
+}
diff --git a/shell.nix b/shell.nix
index 334af06b8..2b9ae55ce 100644
--- a/shell.nix
+++ b/shell.nix
@@ -23,6 +23,7 @@ let
       postgrest.docs
       postgrest.gitTools
       postgrest.loadtest
+      postgrest.nixpkgsTools
       postgrest.release
       postgrest.style
       postgrest.tests