nix: add example on how to use a library locally

nix/README.md

@@ -302,6 +302,55 @@ ghci> decodeMediaType "application/json"
 MTApplicationJSON
 ```
 
+## Working with locally modified Haskell packages
+
+Sometimes, we need to modify Haskell libraries in order to debug them or enhance them.
+For example, if you want to debug the [`hasql-pool`](https://hackage.haskell.org/package/hasql-pool)
+library:
+
+First, copy the package to the repo root. We'll use GitHub in this example.
+
+```bash
+$ git clone --depth=1 --branch=0.10.1 https://github.com/nikita-volkov/hasql-pool.git
+$ rm -rf ./hasql-pool/.git
+```
+
+Then, pin the local package to the [`haskell-packages.nix`](./overlays/haskell-packages.nix) file.
+
+```nix
+  overrides =
+    # ...
+    rec {
+
+      # Different subpath may be needed if the cabal file is not in the library's base directory
+      hasql-pool = lib.dontCheck
+        (prev.callCabal2nixWithOptions "hasql-pool" ../../hasql-pool "--subpath=." {} );
+
+    };
+```
+
+Next, both [`cabal.project`](/cabal.project) and [`stack.yaml`](/stack.yaml) need to be updated
+with the local library:
+
+```cabal
+-- cabal.project
+packages:
+  ./hasql-pool/hasql-pool.cabal
+```
+
+```yaml
+# stack.yaml
+extra-deps:
+  - ./hasql-pool/hasql-pool.cabal
+```
+
+Lastly, run `nix-shell` to build the local package. You don't need to exit and
+enter the Nix shell every time you modify the library's code, re-executing
+`postgrest-run` should be enough.
+
+This is done for development purposes only. Local libraries must not be left
+in production ready code.
+
 ## Tour
 
 The following is not required for working on PostgREST with Nix, but it will

nix/overlays/haskell-packages.nix

@@ -34,6 +34,11 @@ let
       # - If the library fails its test suite (usually when it runs IO tests), wrap the expression with `lib.dontCheck ()`
       # - <subpath> is usually "."
       # - When adding a new library version here, postgrest.cabal and stack.yaml must also be updated
+      #
+      # Note:
+      # - This should NOT be the first place to start managing dependencies. Check postgrest.cabal.
+      # - To modify and try packages locally, see "Working with locally modified Haskell packages" in the Nix README.
+      #
 
 
       configurator-pg =