chore: bump version to 14.17

fix: JWT validation uses wrong current time due to a bug in auto-update
Upgrade auto-update to 0.2.7 which contains a fix to a bug causing some threads not seeing updates to the cached values. (cherry picked from commit a2a592a617)
2026-08-13 10:48:30 -05:00 · 2026-08-13 09:30:02 -05:00 · 2026-08-07 07:40:59 +00:00 · 2026-08-04 21:04:54 +00:00 · 2026-07-30 20:41:24 +00:00 · 2026-07-27 11:19:37 +05:00
267 changed files with 8082 additions and 8145 deletions
@@ -0,0 +1,8 @@
 # TODO: Remove this once a new actionlint release has been cut
 # and made its way to us through nixpkgs.
 self-hosted-runner:
  labels:
    - macos-15-intel
    - macos-26
    - ubuntu-24.04-arm
    - ubuntu-slim
@@ -8,6 +8,7 @@ inputs:
    required: true
  save-prs:
    description: Whether to additionally store the cache in a pull request, too. Should only be used for very small caches.
    type: boolean
  prefix:
    description: Cache key prefix to be used in both primary key and restore-keys.
    required: true
@@ -22,13 +23,13 @@ runs:
      if: ${{ startsWith(github.ref, 'refs/heads/') || (inputs.save-prs && startsWith(github.ref, 'refs/pull/')) }}
      with:
        path: ${{ inputs.path }}
-        key: ${{ runner.os }}-${{ runner.arch }}-${{ inputs.prefix }}-${{ inputs.suffix }}
+        key: ${{ runner.os }}-${{ inputs.prefix }}-${{ inputs.suffix }}
        restore-keys: |
-          ${{ runner.os }}-${{ runner.arch }}-${{ inputs.prefix }}-
+          ${{ runner.os }}-${{ inputs.prefix }}-
    - uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
      if: ${{ !startsWith(github.ref, 'refs/heads/') && !(inputs.save-prs && startsWith(github.ref, 'refs/pull/'))  }}
      with:
        path: ${{ inputs.path }}
-        key: ${{ runner.os }}-${{ runner.arch }}-${{ inputs.prefix }}-${{ inputs.suffix }}
+        key: ${{ runner.os }}-${{ inputs.prefix }}-${{ inputs.suffix }}
        restore-keys: |
-          ${{ runner.os }}-${{ runner.arch }}-${{ inputs.prefix }}-
+          ${{ runner.os }}-${{ inputs.prefix }}-
@@ -4,9 +4,6 @@ codecov:
 comment: false
 github_checks:
  annotations: true
 coverage:
  status:
    project:
@@ -13,6 +13,9 @@
  },
  "packageRules": [
    {
      "matchBaseBranches": [
        "/^v[0-9]+/"
      ],
      "matchManagers": [
        "haskell-cabal"
      ],
@@ -23,6 +26,44 @@
        "/^v[0-9]+/"
      ],
      "groupName": "all dependencies"
    },
    {
      "matchManagers": [
        "haskell-cabal"
      ],
      "matchPackageNames": [
        "base",
        "bytestring",
        "containers",
        "directory",
        "mtl",
        "parsec",
        "process",
        "text"
      ],
      "groupName": "GHC dependencies"
    },
    {
      "matchManagers": [
        "haskell-cabal"
      ],
      "matchPackageNames": [
        "hasql",
        "hasql-dynamic-statements",
        "hasql-notifications",
        "hasql-transaction",
        "hasql-pool"
      ],
      "groupName": "hasql"
    },
    {
      "matchManagers": [
        "haskell-cabal"
      ],
      "matchPackageNames": [
        "fuzzyset"
      ],
      "allowedVersions": "<0.3"
    }
  ]
 }
@@ -40,7 +40,6 @@ jobs:
      - name: Fetch PR ref
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          allow-unsafe-pr-checkout: true
          ref: ${{ github.event.pull_request.head.sha }}
          token: ${{ steps.app-token.outputs.token }}
@@ -31,18 +31,8 @@ concurrency:
 jobs:
  static:
-    strategy:
+    name: Nix - Linux x86-64 static
      fail-fast: false
      matrix:
        include:
          - name: Linux aarch64
            runs-on: ubuntu-24.04-arm
            artifact: aarch64
          - name: Linux x86-64
    runs-on: ubuntu-24.04
            artifact: x86-64
    name: Nix - ${{ matrix.name }} static
    runs-on: ${{ matrix.runs-on }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Setup Nix Environment
@@ -55,24 +45,19 @@ jobs:
      - name: Save built executable as artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
-          name: postgrest-linux-static-${{ matrix.artifact }}
+          name: postgrest-linux-static-x86-64
          path: result/bin/postgrest
          if-no-files-found: error
      - name: Build Docker image
-        run: nix-build -A docker.image --out-link postgrest-docker-${{ matrix.artifact }}.tar.gz
+        run: nix-build -A docker.image --out-link postgrest-docker.tar.gz
      - name: Save built Docker image as artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
-          name: postgrest-docker-${{ matrix.artifact }}
+          name: postgrest-docker-x86-64
-          path: postgrest-docker-${{ matrix.artifact }}.tar.gz
+          path: postgrest-docker.tar.gz
          if-no-files-found: error
      - name: Test static executable with NixOS' VM test
        # GHA's ARM runner does not support KVM
        if: runner.arch == 'X64'
        run: nix-build -A nixpkgs-nixos-test
  macos:
    name: Nix - MacOS
@@ -104,6 +89,11 @@ jobs:
            artifact: postgrest-freebsd-x86-64
            deps: pkg install -y git postgresql16-client hs-stack
          - name: Linux aarch64
            runs-on: ubuntu-24.04-arm
            artifact: postgrest-ubuntu-aarch64
            deps: sudo apt-get update && sudo apt-get install libpq-dev
          - name: MacOS aarch64
            runs-on: macos-14
            artifact: postgrest-macos-aarch64
@@ -130,7 +120,7 @@ jobs:
        uses: haskell-actions/setup@6037f33647c3f17758a2356c80fc4a53d7e0685d # v2.12.0
        with:
          # This must match the version in stack.yaml's resolver
-          ghc-version: 9.10.3
+          ghc-version: 9.6.7
          enable-stack: true
          stack-no-global: true
          stack-setup-ghc: true
@@ -169,7 +159,7 @@ jobs:
  cabal:
    strategy:
      matrix:
-        ghc: ['9.10.3', '9.12.3']
+        ghc: ['9.6.7', '9.8.4']
      fail-fast: false
    name: Cabal - Linux x86-64 - GHC ${{ matrix.ghc }}
    runs-on: ubuntu-24.04
@@ -60,9 +60,6 @@ jobs:
          mkdir -p release-bundle
          tar cJvf "release-bundle/postgrest-${GITHUB_REF_NAME}-linux-static-aarch64.tar.xz" \
            -C artifacts/postgrest-linux-static-aarch64 postgrest
          tar cJvf "release-bundle/postgrest-${GITHUB_REF_NAME}-linux-static-x86-64.tar.xz" \
            -C artifacts/postgrest-linux-static-x86-64 postgrest
@@ -75,6 +72,9 @@ jobs:
          tar cJvf "release-bundle/postgrest-${GITHUB_REF_NAME}-freebsd-x86-64.tar.xz" \
            -C artifacts/postgrest-freebsd-x86-64 postgrest
          tar cJvf "release-bundle/postgrest-${GITHUB_REF_NAME}-ubuntu-aarch64.tar.xz" \
            -C artifacts/postgrest-ubuntu-aarch64 postgrest
          zip --junk-paths "release-bundle/postgrest-${GITHUB_REF_NAME}-windows-x86-64.zip" \
            artifacts/postgrest-windows-x86-64/postgrest.exe
@@ -124,41 +124,49 @@ jobs:
      DOCKER_REPO: ${{ vars.DOCKER_REPO }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Download aarch64 Docker image
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: postgrest-docker-aarch64
      - name: Download x86-64 Docker image
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: postgrest-docker-x86-64
      - name: Download aarch64 binary
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: postgrest-ubuntu-aarch64
      - uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          username: ${{ vars.DOCKER_USER }}
          password: ${{ secrets.DOCKER_PASS }}
      - name: Build aarch64 Docker image
        run: |
          # This only pushes the image via digest, not a tag. This will not appear
          # in the image list on Docker Hub, yet. It will be later added to the main
          # tag's manifest.
          docker buildx build \
            -t "$DOCKER_REPO/postgrest" \
            --platform linux/arm64 \
            --output push-by-digest=true,type=image,push=true \
            --metadata-file metadata.json \
            .
          echo "SHA256_ARM=$(jq -r '."containerimage.digest"' metadata.json)" >> "$GITHUB_ENV"
      - name: Publish images on Docker Hub
        run: |
-          docker load -i postgrest-docker-aarch64.tar.gz
+          docker load -i postgrest-docker.tar.gz
          docker tag postgrest:latest "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}-linux-arm64"
          docker push "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}-linux-arm64"
-          docker load -i postgrest-docker-x86-64.tar.gz
+          docker tag postgrest:latest "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}"
-          docker tag postgrest:latest "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}-linux-amd64"
+          docker push "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}"
-          docker push "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}-linux-amd64"
+          docker buildx imagetools create --append \
-
+            -t "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}" \
-          docker manifest create "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}" \
+            "$DOCKER_REPO/postgrest@$SHA256_ARM"
            "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}-linux-arm64" \
            "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}-linux-amd64"
          docker manifest push "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}"
          # Only tag 'latest' for full releases
          if [ "${GITHUB_REF_NAME}" != "devel" ]; then
            echo "Pushing to 'latest' tag for full release of ${GITHUB_REF_NAME} ..."
-            docker manifest create "$DOCKER_REPO/postgrest:latest" \
+            docker tag postgrest:latest "$DOCKER_REPO"/postgrest:latest
-              "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}-linux-arm64" \
+            docker push "$DOCKER_REPO"/postgrest:latest
-              "$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}-linux-amd64"
+            docker buildx imagetools create --append \
-            docker manifest push "$DOCKER_REPO/postgrest:latest"
+              -t "$DOCKER_REPO/postgrest:latest" \
              "$DOCKER_REPO/postgrest@$SHA256_ARM"
          else
            echo "Skipping push to 'latest' tag for pre-release..."
          fi
@@ -173,54 +181,3 @@ jobs:
          short-description: ${{ github.event.repository.description }}
          readme-filepath: ./docker-hub-readme.md
  ghcr:
    name: GitHub Container Registry
    runs-on: ubuntu-24.04-arm
    needs:
      - github
    permissions:
      packages: write
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Download aarch64 Docker image
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: postgrest-docker-aarch64
      - name: Download x86-64 Docker image
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: postgrest-docker-x86-64
      - uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Publish images on Docker Hub
        run: |
          docker load -i postgrest-docker-aarch64.tar.gz
          docker tag postgrest:latest "ghcr.io/${GITHUB_REPOSITORY,,}:${GITHUB_REF_NAME}-linux-arm64"
          docker push "ghcr.io/${GITHUB_REPOSITORY,,}:${GITHUB_REF_NAME}-linux-arm64"
          docker load -i postgrest-docker-x86-64.tar.gz
          docker tag postgrest:latest "ghcr.io/${GITHUB_REPOSITORY,,}:${GITHUB_REF_NAME}-linux-amd64"
          docker push "ghcr.io/${GITHUB_REPOSITORY,,}:${GITHUB_REF_NAME}-linux-amd64"
          docker manifest create "ghcr.io/${GITHUB_REPOSITORY,,}:${GITHUB_REF_NAME}" \
            "ghcr.io/${GITHUB_REPOSITORY,,}:${GITHUB_REF_NAME}-linux-arm64" \
            "ghcr.io/${GITHUB_REPOSITORY,,}:${GITHUB_REF_NAME}-linux-amd64"
          docker manifest push "ghcr.io/${GITHUB_REPOSITORY,,}:${GITHUB_REF_NAME}"
          # Only tag 'latest' for full releases
          if [ "${GITHUB_REF_NAME}" != "devel" ]; then
            echo "Pushing to 'latest' tag for full release of ${GITHUB_REF_NAME} ..."
            docker manifest create "ghcr.io/${GITHUB_REPOSITORY,,}:latest" \
              "ghcr.io/${GITHUB_REPOSITORY,,}:${GITHUB_REF_NAME}-linux-arm64" \
              "ghcr.io/${GITHUB_REPOSITORY,,}:${GITHUB_REF_NAME}-linux-amd64"
            docker manifest push "ghcr.io/${GITHUB_REPOSITORY,,}:latest"
          else
            echo "Skipping push to 'latest' tag for pre-release..."
          fi
@@ -25,10 +25,6 @@ on:
      - test/**
      - '!**.md'
 defaults:
  run:
    shell: bash
 concurrency:
  # Terminate all previous runs of the same workflow for pull requests
  group: test-${{ github.head_ref || github.run_id }}
@@ -53,7 +49,7 @@ jobs:
      - run: postgrest-cabal-update
-      - name: Run coverage (IO tests and Spec tests against latest supported PostgreSQL)
+      - name: Run coverage (IO tests and Spec tests against PostgreSQL 15)
        run: postgrest-coverage
      - name: Upload coverage to codecov
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
@@ -63,7 +59,7 @@ jobs:
      - name: Run doctests
        if: always()
-        run: nix-shell --run postgrest-test-doctests
+        run: postgrest-test-doctests
      - name: Check the spec tests for idempotence
        if: always()
@@ -75,8 +71,8 @@ jobs:
      fail-fast: false
      matrix:
        # Latest version is tested via `coverage` above.
-        pgVersion: [pg-14, pg-15, pg-16, pg-17, oriole-18, pg-18]
+        pgVersion: [13, 14, 15, 16]
-    name: ${{ matrix.pgVersion }}
+    name: PG ${{ matrix.pgVersion }}
    runs-on: ubuntu-24.04
    defaults:
      run:
@@ -89,25 +85,25 @@ jobs:
        uses: ./.github/actions/setup-nix
        with:
          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
-          tools: tests.testSpec.bin tests.testObservability.bin tests.testIO.bin tests.testBigSchema.bin withTools.${{ matrix.pgVersion }}.bin cabalTools.update.bin
+          tools: tests.testSpec.bin tests.testObservability.bin tests.testIO.bin tests.testBigSchema.bin withTools.pg-${{ matrix.pgVersion }}.bin cabalTools.update.bin
      - run: postgrest-cabal-update
      - name: Run spec tests
        if: always()
-        run: postgrest-with-${{ matrix.pgVersion }} postgrest-test-spec
+        run: postgrest-with-pg-${{ matrix.pgVersion }} postgrest-test-spec
      - name: Run observability tests
        if: always()
-        run: postgrest-with-${{ matrix.pgVersion }} postgrest-test-observability
+        run: postgrest-with-pg-${{ matrix.pgVersion }} postgrest-test-observability
      - name: Run IO tests
        if: always()
-        run: postgrest-with-${{ matrix.pgVersion }} postgrest-test-io -vv
+        run: postgrest-with-pg-${{ matrix.pgVersion }} postgrest-test-io -vv
      - name: Run IO tests on a big schema
        if: always()
-        run: postgrest-with-${{ matrix.pgVersion }} postgrest-test-big-schema -vv
+        run: postgrest-with-pg-${{ matrix.pgVersion }} postgrest-test-big-schema -vv
  memory:
@@ -131,7 +127,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        kind: ['mixed', 'jwt-cache']
+        kind: ['mixed', 'jwt-hs', 'jwt-hs-cache', 'jwt-hs-cache-worst', 'jwt-rsa', 'jwt-rsa-cache', 'jwt-rsa-cache-worst']
    name: Loadtest
    runs-on: ubuntu-24.04
    steps:
@@ -142,7 +138,7 @@ jobs:
        uses: ./.github/actions/setup-nix
        with:
          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
-          tools: loadtest.loadtestAgainst.bin loadtest.report.bin loadtest.report-load.bin cabalTools.update.bin
+          tools: loadtest.loadtestAgainst.bin loadtest.report.bin cabalTools.update.bin
      - run: postgrest-cabal-update
@@ -156,41 +152,14 @@ jobs:
            latest_tag=$(git tag --merged HEAD --sort=-creatordate "v*" | head -n1)
          fi
          postgrest-loadtest-against -k ${{ matrix.kind }} "$TARGET_BRANCH" "$latest_tag"
-
+          postgrest-loadtest-report -g ${{ matrix.kind }} >> "$GITHUB_STEP_SUMMARY"
      - name: Report P50
        # This step checks whether any red cross indicators (:x:) are present in the step summary.
        # The loadtest reporter writes them when any of individual steps fails the performance
        # regression threshold.
        run: |
          ! (postgrest-loadtest-report -g ${{ matrix.kind }} -p 50 \
              | tee "$GITHUB_STEP_SUMMARY" \
              | grep ':x:')
      - name: Report P0
        if: always()
        run: |
          postgrest-loadtest-report -g ${{ matrix.kind }} -p 0 >> "$GITHUB_STEP_SUMMARY"
      - name: Report P90
        if: always()
        run: |
          postgrest-loadtest-report -g ${{ matrix.kind }} -p 90 >> "$GITHUB_STEP_SUMMARY"
      - name: Report P95
        if: always()
        run: |
          postgrest-loadtest-report -g ${{ matrix.kind }} -p 95 >> "$GITHUB_STEP_SUMMARY"
      - name: Report CPU/MEM
        if: always()
        run: |
          postgrest-loadtest-report-load -g ${{ matrix.kind }} >> "$GITHUB_STEP_SUMMARY"
  flake:
    strategy:
      fail-fast: false
      matrix:
        runs-on:
          - macos-15-intel # x86_64-darwin
          - macos-14 # aarch64-darwin
          - ubuntu-24.04 # x86_64-linux
          - ubuntu-24.04-arm # aarch64-linux
@@ -25,9 +25,5 @@ loadtest
 .history
 .docs-build
 gen_targets.http
-gen_jwks.json
+gen_jwk.json
 gen_private.json
 .pytest_cache
 .ruff_cache
 postgrest-module-graph.png
 .ghc.environment.*
@@ -7,4 +7,4 @@ python:
 build:
  os: ubuntu-24.04
  tools:
-    python: "3.12"
+    python: "3.11"
@@ -200,7 +200,7 @@ steps:
 # A common setting is the number of columns (parts of) code will be wrapped
 # to. Different steps take this into account. Default: 80.
-columns: 80
+columns: 70
 # By default, line endings are converted according to the OS. You can override
 # preferred format here.
@@ -4,108 +4,12 @@ All notable changes to this project will be documented in this file. From versio
 ## Unreleased
-## [16.1] - 2026-08-10
+## [14.17] - 2026-08-13
 ### Fixed
 - JWT validation uses wrong current time due to a bug in auto-update by @mkleczek in #5159
 ## [16.0] - 2026-08-07
 ### Changes
 #### HTTP Server
 - [Graceful shutdown](https://docs.postgrest.org/en/v16/references/http_server.html#graceful-shutdown) by @mkleczek, @Vlix in #4702
 - [server-reuseport](https://docs.postgrest.org/en/v16/references/configuration.html#server-reuseport) allows starting multiple PostgREST instances using the same port on supported platforms by @mkleczek in #4703, #4694
 #### Performance
 - Optimize schema cache domain type resolution by using [pg_basetype](https://www.postgresql.org/docs/current/functions-info.html#FUNCTIONS-INFO-CATALOG) on PostgreSQL 17+ by @joelonsql in #4567
 - [Prefer: count=exact](https://docs.postgrest.org/en/v16/references/api/pagination_count.html#exact-count) no longer does a double count on requests that do not use ranges or `db-max-rows` by @laurenceisla in #3957
 - [Prefer: timezone](https://docs.postgrest.org/en/v16/references/api/preferences.html#prefer-timezone) no longer requires the schema cache by @steve-chavez in #5100
  + Previously this required caching [pg_timezone_names](https://www.postgresql.org/docs/current/view-pg-timezone-names.html) which was slow in some systems
 #### Integrations
 - PostgREST is now tested to work with [OrioleDB](https://github.com/orioledb/orioledb/) in #4845 by @wolfgangwalther
  + See [our guide for running OrioleDB on NixOS](https://docs.postgrest.org/en/v16/integrations/nixos.html)
 #### JWT
 - [JWT Role Extraction](https://docs.postgrest.org/en/v16/references/auth.html#jwt-role-extract) is now more flexible, supporting the standard JSON Path defined in RFC 9535 by @taimoorzaeem in #4984
 #### API
 - [Prefer: timezone](https://docs.postgrest.org/en/v16/references/api/preferences.html#timezone) now supports numeric offsets like `05:00` or `-4` by @steve-chavez in #5100
 - Fix unexpected results when embedding and filtering the same table more than once by @laurenceisla in #4075
  + You need to set [url-use-legacy-target-names](https://docs.postgrest.org/en/v16/references/configuration.html#url-use-legacy-target-names) to `false`.
 - Deprecate filters, orders and limits with the name of an embedded table when it has an alias by @steve-chavez, @laurenceisla in #4075
  + e.g. `?select=alias:table(*)&table.id=eq.1` will not be possible anymore, use `?select=alias:table(*)&alias.id=eq.1` instead.
  + You will see a warning in the logs and a `Warning` header on the client response when this happens.
  + You can disable this behavior now by setting `url-use-legacy-target-names = false`.
 - Add `Vary` header to responses by @develop7 in #4609
 - Fix automatic transaction retries on `40001 (serialization_failure)` errors to prevent replication lag by @laurenceisla in #3673
 #### Observability
 - [GHC runtime metrics](https://docs.postgrest.org/en/v16/references/observability.html#ghc-runtime-metrics) by @mkleczek in #4862
 - [client-error-verbosity](https://docs.postgrest.org/en/v16/references/configuration.html#client-error-verbosity) to customize responses error verbosity by @taimoorzaeem in #4088, #3980, #3824
 - [log-level](https://docs.postgrest.org/en/v16/references/configuration.html#log-level) config is now reloadable by @taimoorzaeem in #5113
 - Log error when `db-schemas` config contains schema `pg_catalog` or `information_schema` by @taimoorzaeem in #4359
 - Log schema cache queries timings on `log-level=debug` by @steve-chavez in #4805
 #### Admin Server
 - [admin-server-unix-socket](https://docs.postgrest.org/en/v16/references/configuration.html#admin-server-unix-socket)/[admin-server-unix-socket-mode](https://docs.postgrest.org/en/v16/references/configuration.html#admin-server-unix-socket-mode) to run the admin server on a unix socket by @wolfgangwalther in #5003
 - Fix responding with `Something went wrong` on Admin server when under EMFILE by @mkleczek in #5077
 #### Deployment
 - Make executable for aarch64-linux static instead of Ubuntu-based by @wolfgangwalther in #4193
 - Docker image for aarch64-linux is now built from scratch instead of being Ubuntu-based by @wolfgangwalther in #4193
 - Besides Docker Hub, docker images are now published to Github Container Registry by @wolfgangwalther in #2836
 #### Schema Cache
 - Fix requests failing when the schema cache fails to reload, when this happens PostgREST will continue serving requests in "best effort" by @mkleczek in #4873 #4869
 - Fix reporting 503s errors unnecessarily while the schema cache is loading at startup by @mkleczek in #4880
 - Fix schema cache dump missing RPC transaction isolation level by @taimoorzaeem in #5079
 #### Listener
 - Fix config `db-channel-enabled` not reloading by @taimoorzaeem in #4894
 ### Migration to v16
 - Drop support for PostgreSQL EOL version 13 by @wolfgangwalther in #4193
  + PostgreSQL 13 end of life was on 2025 ([ref](https://www.postgresql.org/support/versioning/))
  + Upgrade your PostgreSQL version to at least 14 to use this new PostgREST version.
 - Fail at startup when `db-schemas` contains schema `pg_catalog` or `information_schema` by @taimoorzaeem in #4359
  + Previously it failed at runtime with `PGRST205` on requests related to these schemas.
  + Remove `pg_catalog` and `information_schema` from `db-schemas`.
 - `Prefer: timezone` no longer complies with `handling=lenient` and instead always fails by @steve-chavez in #5128
  + Supporting this required caching `pg_timezone_names`, which was expensive.
  + Ensure your requests always have a valid timezone.
 - `jwt-role-claim-key` no longer uses the JSPath DSL and instead uses JSON Path by @taimoorzaeem in #4984
  + Now all config values must start with `$` character.
     Example: `.roles.read` -> `$.roles.read`
  + Keys with special characters, with the exception of `_` char must be quoted.
      Example: `.roles.write-role` -> `$.roles["write-role"]`
  + String comparison operators (`^==`, `==^` and `*==`) are replaced with regular expression search.
      Example: `.roles[?(@ ^== "postgrest_test_")]` -> `$.roles[?search(@, "^postgrest_test_")]`
  + Update the `jwt-role-claim-key` value accoring to the above rules. Also see the syntax reference: [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535.html#name-jsonpath-syntax-and-semanti).
 ## [14.16] - 2026-07-27
 ### Fixed
@@ -201,7 +105,7 @@ All notable changes to this project will be documented in this file. From versio
 - Ensure Listener connections are released by @mkleczek in #4614
 - Fix incorrectly filtering the returned representation for PATCH requests when using `or/and` filters by @laurenceisla in #3707
- Fix listener running with exception masked after first failure by @mkleczek in #4615
+- Fix listener running with exception masked after first failure by @mkleczek #4615
 ## [14.3] - 2026-01-03
@@ -805,7 +709,7 @@ All notable changes to this project will be documented in this file. From versio
 ### Added
 - #1933, #2109, Add a minimal health check endpoint - @steve-chavez
-   + For enabling this, the `admin-server-port` config must be set explicitly
+   + For enabling this, the `admin-server-port` config must be set explictly
   + A `<host>:<admin_server_port>/live` endpoint is available for checking if postgrest is running on its port/socket. 200 OK = alive, 503 = dead.
   + A `<host>:<admin_server_port>/ready` endpoint is available for checking a correct internal state(the database connection plus the schema cache). 200 OK = ready, 503 = not ready.
 - #1988, Add the current user to the request log on stdout - @DavidLindbom, @wolfgangwalther
@@ -1288,7 +1192,7 @@ All notable changes to this project will be documented in this file. From versio
 - Customize content negotiation per route - @begriffs
 - Allow using nulls order without explicit order direction - @steve-chavez
 - Fatal error on postgres unsupported version, format supported version in error message - @steve-chavez
- Prevent database memory consumption by prepared statements caches - @ruslantalpa
+- Prevent database memory cosumption by prepared statements caches - @ruslantalpa
 - Use specific columns in the RETURNING section - @ruslantalpa
 - Fix columns alias for RETURNING - @steve-chavez
@@ -1,12 +1,17 @@
 # Contributing to PostgREST
-## AI Policy
+**First:** if you're unsure or afraid of _anything_, just ask or
 submit the issue or pull request anyways. You won't be yelled at
 for giving your best effort. The worst that can happen is that
 you'll be politely asked to change something. We appreciate any
 sort of contributions, and don't want a wall of rules to get in the
 way of that.
-We adhere to [Gentoo's AI policy](https://wiki.gentoo.org/wiki/Project:Council/AI_policy):
+However, for those individuals who want a bit more guidance on the
-
+best way to contribute to the project, read on. This document will
-> It is expressly forbidden to contribute [...] any content that has been created with the assistance of Natural Language Processing artificial intelligence tools. This motion can be revisited, should a case been made over such a tool that does not pose copyright, ethical and quality concerns.
+cover what we're looking for. By addressing all the points we're
-
+looking for, it raises the chances we can quickly merge or address
-You can find more about its rationale [here](https://wiki.gentoo.org/wiki/Project:Council/AI_policy#Rationale).
+your contributions.
 ## Issues
@@ -35,14 +40,12 @@ For questions on how to use PostgREST, please use
 We have a fully nix-based development environment with many tools for a smooth development workflow available.
 Check the [development docs](https://github.com/PostgREST/postgrest/blob/main/nix/README.md) on how to set it up and use it.
 ### Haskell Conventions
 * All contributions must pass the tests before being merged. When
  you create a pull request your code will automatically be tested.
-* All fixes or features must have a test proving the improvement.
+* All code must also pass [hlint](http://community.haskell.org/~ndm/hlint/) and [stylish-haskell](https://github.com/jaspervdj/stylish-haskell)
 * All features must document the new behavior. Critical fixes that introduce new behavior must be documented too.
 * All code must also pass a [linter](http://community.haskell.org/~ndm/hlint/) and [styler](https://github.com/jaspervdj/stylish-haskell)
  with no warnings. This helps enforce a uniform style for all committers. Continuous integration will check this as well on every
  pull request. There are useful tools in the nix-shell that help with checking this locally. You can run `postgrest-check` to do this manually but
  we recommend adding it to `.git/hooks/pre-commit` as `nix-shell --run postgrest-check` to automatically check this before doing a commit.
@@ -50,15 +53,3 @@ Check the [development docs](https://github.com/PostgREST/postgrest/blob/main/ni
 ### Running Tests
 For instructions on running tests, see the [development docs](https://github.com/PostgREST/postgrest/blob/main/nix/README.md#testing).
 ### Structuring commits in pull requests
 To simplify reviews, make it easy to split pull requests if deemed necessary, and to maintain clean and meaningful history of changes, you will be asked to update your PR if it does not follow the below rules:
 * It must be possible to merge the PR branch into target using `git merge --ff-only`, ie. the source branch must be rebased on top of target.
 * No merge commits in the source branch.
 * All commits in the source branch must be self contained, meaning: it should be possible to treat each commit as a separate PR.
 * Commits in the source branch must contain only related changes (related means the changes target a single problem/goal). For example, any refactorings should be isolated from the actual change implementation into separate commits.
 * Tests, documentation, and changelog updates should be contained in the same commits as the actual code changes they relate to. An exception to this rule is when test or documentation changes are made in separate PR.
 * Commit messages must be prefixed with one of the prefixes defined in [the list used by commit verification scripts](https://github.com/PostgREST/postgrest/blob/main/nix/tools/gitTools.nix#L11).
 * Commit messages should contain a longer description of the purpose of the changes contained in the commit and, for non-trivial changes, a description of the changes themselves.
@@ -0,0 +1,21 @@
 # PostgREST Docker Hub image for aarch64.
 # The x86-64 is a single-static-binary image built via Nix, see:
 # nix/tools/docker/README.md
 FROM ubuntu:resolute@sha256:678c6550cc43645e08669028bc177f50be4e7c5b8cca677067b1914d4afc7a03 AS postgrest
 RUN apt-get update -y \
    && apt install -y --no-install-recommends libpq-dev zlib1g-dev jq gcc libnuma-dev \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*
 COPY postgrest /usr/bin/postgrest
 RUN chmod +x /usr/bin/postgrest
 EXPOSE 3000
 USER 1000
 # Use the array form to avoid running the command using bash, which does not handle `SIGTERM` properly. 
 # See https://docs.docker.com/compose/faq/#why-do-my-services-take-10-seconds-to-recreate-or-stop 
 CMD ["postgrest"]
@@ -1,4 +1,5 @@
-Copyright (c) 2014-2026 The PostgREST contributors
+Copyright (c) 2014 Joe Nelson
 Copyright (c) 2019 Steve Chavez
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -125,7 +125,7 @@ and limited with - range headers. More about
 ## Data Integrity
 Rather than relying on an Object Relational Mapper and custom
-imperative coding, this system requires you to put declarative constraints
+imperative coding, this system requires you put declarative constraints
 directly into your database. Hence no application can corrupt your
 data (including your API server).
@@ -1,7 +1,2 @@
 packages: postgrest.cabal
 tests: true
 allow-newer:
  hasql:postgresql-libpq
 -- https://github.com/martijnbastiaan/doctest-parallel/blob/main/example/README.md#cabalproject
 write-ghc-environment-files: always
@@ -1,6 +1,6 @@
 { system ? builtins.currentSystem
-, compiler ? "ghc9123"
+, compiler ? "ghc948"
 , # Commit of the Nixpkgs repository that we want to use.
  # It defaults to reading the inputs from flake.lock, which serves
@@ -44,6 +44,7 @@ let
      allOverlays.checked-shell-script
      allOverlays.gitignore
      (allOverlays.haskell-packages { inherit compiler; })
      allOverlays.slocat
    ];
  # Evaluated expression of the Nixpkgs repository.
@@ -52,20 +53,11 @@ let
  postgresqlVersions =
    [
      { name = "pg-19"; postgresql = pkgs.postgresql_19.withPackages (p: [ p.postgis p.pg_safeupdate ]); }
      { name = "pg-18"; postgresql = pkgs.postgresql_18.withPackages (p: [ p.postgis p.pg_safeupdate ]); }
      { name = "pg-17"; postgresql = pkgs.postgresql_17.withPackages (p: [ p.postgis p.pg_safeupdate ]); }
      { name = "pg-16"; postgresql = pkgs.postgresql_16.withPackages (p: [ p.postgis p.pg_safeupdate ]); }
      { name = "pg-15"; postgresql = pkgs.postgresql_15.withPackages (p: [ p.postgis p.pg_safeupdate ]); }
      { name = "pg-14"; postgresql = pkgs.postgresql_14.withPackages (p: [ p.postgis p.pg_safeupdate ]); }
-      {
+      { name = "pg-13"; postgresql = pkgs.postgresql_13.withPackages (p: [ p.postgis p.pg_safeupdate ]); }
        name = "oriole-18";
        postgresql = pkgs.orioledb.withPackages (p: [ p.postgis p.pg_safeupdate ]);
        config = "
          default_table_access_method = 'orioledb'
          shared_preload_libraries = 'orioledb, pg_stat_statements'
        ";
      }
    ];
  haskellPackages = pkgs.haskell.packages."${compiler}";
@@ -86,16 +78,6 @@ let
    "-f dev --test-show-detail=direct";
  inherit (pkgs.haskell) lib;
  nixos-lib = import (pkgs.path + "/nixos/lib") { };
  runTest = postgrest: test: (nixos-lib.runTest {
    hostPkgs = pkgs;
    # Replace the top-level `pkgs.postgrest` attribute with our current version on this branch.
    defaults.nixpkgs.overlays = [ (_: _: { inherit postgrest; }) ];
    # Speeds up evaluation a little bit; documentation is really not required for tests.
    defaults.documentation.enable = pkgs.lib.mkDefault false;
    imports = [ test ];
  }).config.result;
 in
 rec {
  inherit nixpkgs pkgs;
@@ -139,7 +121,7 @@ rec {
  # Development tools.
  devTools =
-    pkgs.callPackage nix/tools/devTools.nix { inherit tests style devCabalOptions hsie; };
+    pkgs.callPackage nix/tools/devTools.nix { inherit tests style devCabalOptions hsie withTools; };
  # Documentation tools.
  docs =
@@ -181,7 +163,4 @@ rec {
  # Docker images and loading script.
  docker =
    pkgs.callPackage nix/tools/docker { postgrest = postgrestStatic; };
  # NixOS VM tests
  nixpkgs-nixos-test = runTest postgrestStatic (pkgs.path + "/nixos/tests/postgrest.nix");
 }
@@ -61,3 +61,5 @@ The image is built from scratch using
 no commands are listed in the image history. See the [PostgREST
 repository](https://github.com/PostgREST/postgrest/tree/main/nix/tools/docker) for
 details on the build process and how to inspect the image.
 This does not apply to the arm64 variant, which is based on Ubuntu.
@@ -87,8 +87,8 @@ url of Authorization is [[../explanations/db_authz.html]]
 url of CLI is [[../references/cli.html#cli]]
 url of "Connection Pool" is [[../references/connection_pool.html]]
 url of Config is [[../references/configuration.html#configuration]]
-url of HTTPADMIN is [[../references/http_server.html]]
+url of HTTPADMIN is [[../explanations/architecture.html#http]]
-url of HTTPAPI is [[../references/http_server.html]]
+url of HTTPAPI is [[../explanations/architecture.html#http]]
 url of Listener is [[../references/listener.html#listener]]
 url of Proxy is [[../explanations/nginx.html]]
 url of "Schema Cache" is [[../references/schema_cache.html#schema-cache]]
@@ -48,14 +48,14 @@ source_suffix = ".rst"
 # The master toctree document.
 master_doc = "index"
-# This is overridden by readthedocs with the version tag anyway
+# This is overriden by readthedocs with the version tag anyway
-version = "devel"
+version = "14"
 # To avoid repetition in <title> we set this to an empty string.
 release = ""
 # General information about the project.
 project = "PostgREST " + version
-author = "The PostgREST contributors"
+author = "Joe Nelson, Steve Chavez"
 copyright = "2017, " + author
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -300,7 +300,6 @@ linkcheck_ignore = [
    r"https://www.patreon.com/postgrest",
    r"https://blog.frankel.ch/poor-man-api",
    r"https://www.cybertec-postgresql.com/.*",
    r"https://stackoverflow.com/.*",
    # Odd SSL error
    r"https://www.dripdepot.com",
    r"https://www.euronodes.com",
@@ -37,7 +37,6 @@ Example Apps
 * `archtika <https://github.com/thiloho/archtika>`_ - self-hosted CMS
 * `delibrium-postgrest <https://gitlab.com/delibrium/delibrium-postgrest/>`_ - example school API and front-end in Vue.js
 * `ETH-transactions-storage <https://github.com/Adamant-im/ETH-transactions-storage>`_ - indexer for Ethereum to get transaction list by ETH address
 * `fullstack template <https://github.com/jenstroeger/fullstack-webapp-template>`_ - a complete fullstack webapp template using PG as db and message queue, Python and Dramatiq to implement async jobs, db migrations, test runners, and more.
 * `general <https://github.com/PierreRochard/general>`_ - example auth back-end
 * `guild-operators <https://github.com/cardano-community/koios-artifacts/tree/main/files/grest>`_ - example queries and functions that the Cardano Community uses for their Guild Operators' Repository
 * `PostGUI <https://github.com/priyank-purohit/PostGUI>`_ - React Material UI admin panel
@@ -83,7 +82,6 @@ Extensions
 Client-Side Libraries
 ---------------------
 * `efcore-postgrest <https://github.com/pedro-gilmora/EF.PostgREST.Provider>`_ - C#
 * `postgrest-csharp <https://github.com/supabase-community/postgrest-csharp>`_ - C#
 * `postgrest-dart <https://github.com/supabase/postgrest-dart>`_ - Dart
 * `postgrest-ex <https://github.com/supabase-community/postgrest-ex>`_ - Elixir
@@ -31,60 +31,65 @@ This section talks briefly about various important modules.
 Main
 ----
-The starting point of the program is `Main.hs <https://github.com/PostgREST/postgrest/blob/main/src/executable/Main.hs>`_.
+The starting point of the program is `Main.hs <https://github.com/PostgREST/postgrest/blob/v14/main/Main.hs>`_.
 CLI
 ---
-Main then calls `CLI.hs <https://github.com/PostgREST/postgrest/blob/main/src/library/PostgREST/CLI.hs>`_, which is in charge of :ref:`cli`.
+Main then calls `CLI.hs <https://github.com/PostgREST/postgrest/blob/v14/src/PostgREST/CLI.hs>`_, which is in charge of :ref:`cli`.
 App
 ---
-`App.hs <https://github.com/PostgREST/postgrest/blob/main/src/library/PostgREST/App.hs>`_ is then in charge of composing the different modules.
+`App.hs <https://github.com/PostgREST/postgrest/blob/v14/src/PostgREST/App.hs>`_ is then in charge of composing the different modules.
 Auth
 ----
-`Auth.hs <https://github.com/PostgREST/postgrest/blob/main/src/library/PostgREST/Auth.hs>`_ is in charge  of :ref:`authn`.
+`Auth.hs <https://github.com/PostgREST/postgrest/blob/v14/src/PostgREST/Auth.hs>`_ is in charge  of :ref:`authn`.
 Api Request
 -----------
-`ApiRequest.hs <https://github.com/PostgREST/postgrest/blob/main/src/library/PostgREST/ApiRequest.hs>`_ is in charge of parsing the URL query string (following PostgREST syntax), the request headers, and the request body.
+`ApiRequest.hs <https://github.com/PostgREST/postgrest/blob/v14/src/PostgREST/ApiRequest.hs>`_ is in charge of parsing the URL query string (following PostgREST syntax), the request headers, and the request body.
 A request might be rejected at this level if it's invalid. For example when providing an unknown media type to PostgREST or using an unknown HTTP method.
 Plan
 ----
-Using the Schema Cache, `Plan.hs <https://github.com/PostgREST/postgrest/blob/main/src/library/PostgREST/Plan.hs>`_ generates an internal AST, filling out-of-band SQL details (like an ``ON CONFLICT (pk)`` clause) required to complete the user request.
+Using the Schema Cache, `Plan.hs <https://github.com/PostgREST/postgrest/blob/v14/src/PostgREST/Plan.hs>`_ generates an internal AST, filling out-of-band SQL details (like an ``ON CONFLICT (pk)`` clause) required to complete the user request.
 A request might be rejected at this level if it's invalid. For example when doing resource embedding on a nonexistent resource.
 Query
 -----
-`Query.hs <https://github.com/PostgREST/postgrest/blob/main/src/library/PostgREST/Query.hs>`_ generates the SQL queries (parametrized and prepared) required to satisfy the user request.
+`Query.hs <https://github.com/PostgREST/postgrest/blob/v14/src/PostgREST/Query.hs>`_ generates the SQL queries (parametrized and prepared) required to satisfy the user request.
 Only at this stage a connection from the pool might be used.
 Schema Cache
 ------------
-`SchemaCache.hs <https://github.com/PostgREST/postgrest/blob/main/src/library/PostgREST/SchemaCache.hs>`_ is in charge of :ref:`schema_cache`.
+`SchemaCache.hs <https://github.com/PostgREST/postgrest/blob/v14/src/PostgREST/SchemaCache.hs>`_ is in charge of :ref:`schema_cache`.
 Config
 ------
-`Config.hs <https://github.com/PostgREST/postgrest/blob/main/src/library/PostgREST/Config.hs>`_ is in charge of :ref:`configuration`.
+`Config.hs <https://github.com/PostgREST/postgrest/blob/v14/src/PostgREST/Config.hs>`_ is in charge of :ref:`configuration`.
 Admin
 -----
-`Admin.hs <https://github.com/PostgREST/postgrest/blob/main/src/library/PostgREST/Admin.hs>`_ is in charge of the :ref:`admin_server`.
+`Admin.hs <https://github.com/PostgREST/postgrest/blob/v14/src/PostgREST/Admin.hs>`_ is in charge of the :ref:`admin_server`.
 HTTP
 ----
 The HTTP server is provided by `Warp <https://aosabook.org/en/posa/warp.html>`_.
 Listener
 --------
-`Reload.hs <https://github.com/PostgREST/postgrest/blob/main/src/library/PostgREST/AppState/Reload.hs>`_ is in charge of the :ref:`listener`.
+`Listener.hs <https://github.com/PostgREST/postgrest/blob/v14/src/PostgREST/Listener.hs>`_ is in charge of the :ref:`listener`.
@@ -163,7 +163,7 @@ Another option is to define the function with the :code:`SECURITY DEFINER` optio
 .. code-block:: postgres
-  -- login as a user which has privileges on the private schemas
+  -- login as a user wich has privileges on the private schemas
  -- create a sample function
  create or replace function login(email text, pass text, out token text) as $$
@@ -16,7 +16,7 @@ Supported PostgreSQL versions
 =============================
 =============== =================================
-**Supported**   PostgreSQL >= 14
+**Supported**   PostgreSQL >= 13
 =============== =================================
 PostgREST works with all PostgreSQL versions still `officially supported <https://www.postgresql.org/support/versioning/>`_.
@@ -181,23 +181,6 @@ If you want to have a visual overview of your API in your browser you can add sw
 With this you can see the swagger-ui in your browser on port 8080.
 .. _docker_cpu_contraint:
 Docker Resource Constraints
 ---------------------------
 PostgREST does not support ``--cpus`` `constraint option <https://docs.docker.com/engine/containers/resource_constraints/#configure-the-default-cfs-scheduler>`_.
 As a workaround, you may use the `GHC RTS <https://ghc.gitlab.haskell.org/ghc/doc/users_guide/runtime_control.html#runtime-system-rts-options>`_ ``-N`` option. For instance, to limit it to 2 CPU cores, do:
 .. code::
  # Set environment variable GHCRTS set to "-N2"
  docker run --rm -p 3000:3000 \
    -e PGRST_DB_URI="postgres://app_user:password@10.0.0.10/postgres" \
    -e GHCRTS="-N2"
    postgrest/postgrest
 .. _build_source:
 Building from Source
@@ -1,62 +0,0 @@
 .. _debugging_performance_pg_stat_statements:
 Debugging Performance with pg_stat_statements
 =============================================
 This how-to shows how to get a query identifier through PostgREST and then use it to inspect the same query in ``pg_stat_statements``.
 .. important::
  - :ref:`db-plan-enabled` must be enabled in PostgREST.
  - PostgreSQL 14 or newer with ``pg_stat_statements`` available.
 Get the Query Identifier from PostgREST
 ---------------------------------------
 Request the plan in JSON format with the ``verbose`` option:
 .. code-block:: bash
   curl "http://localhost:3000/projects?select=id,name&order=id" \
     -H "Accept: application/vnd.pgrst.plan+json; options=verbose"
 The response will contain a top-level ``Query Identifier`` field:
 .. code-block:: json
   [
     {
       "Plan": {
         "Node Type": "Aggregate"
       },
       "Query Identifier": -432192689578025496
     }
   ]
 Look up the query in pg_stat_statements
 ---------------------------------------
 Use that identifier against ``pg_stat_statements``:
 .. code-block:: postgres
   select
     calls,
     total_exec_time,
     mean_exec_time,
     rows,
     query
   from pg_stat_statements
   where queryid = -432192689578025496;
 .. csv-table::
   :header: "calls", "total_exec_time", "mean_exec_time", "rows", "query"
   "13", "0.6355850000000001", "0.04889115384615385", "13", "WITH pgrst_source AS (...)"
 This lets you correlate a PostgREST request with PostgreSQL runtime statistics such as:
 - how often the query ran
 - total and average execution time
 - how many rows it produced
 - the normalized SQL text recorded by PostgreSQL
@@ -119,14 +119,11 @@ Releases
 PostgREST follows ``MAJOR.PATCH`` two-part versioning:
 - ``MAJOR``: feature release, may deprecate or remove things.
- ``PATCH``: fix/security release only, no features and no behavior changes.
+- ``PATCH``: fix/security release only; no features, no behavior changes.
-MAJOR releases are published twice a year, with their scope and target dates tracked through `GitHub milestones <https://github.com/PostgREST/postgrest/milestones>`_.
+Starting from ``v14.0``, only even-numbered MAJOR versions will be released, reserving odd-numbered MAJOR versions for development.
 PATCH releases are published on an as-needed basis.
-Starting from ``v14.0``, only even-numbered MAJOR versions are released, reserving odd-numbered MAJOR versions for development.
+All the releases are published on `PostgREST's GitHub release page <https://github.com/PostgREST/postgrest/releases>`_.
 All releases are published on `PostgREST's GitHub release page <https://github.com/PostgREST/postgrest/releases>`_, along with the corresponding upgrade guides.
 Tutorials
 ---------
@@ -1,36 +0,0 @@
 NixOS
 =====
 Nixpkgs contains a `NixOS module to run PostgREST <https://search.nixos.org/options?channel=unstable&query=services.postgrest&type=options>`_, which can be enabled with ``services.postgrest.enable = true``.
 A PostgreSQL server can be enabled on the same machine with ``services.postgresql.enable = true``. Connections will use the name of the system user as user and database names by default, in this case ``postgrest``.
 A minimal example could look like this:
 .. code-block:: nix
  {
    pkgs,
    ...
  }:
  {
    services.postgresql = {
      enable = true;
      initialScript = pkgs.writeText "init.sql" ''
        CREATE ROLE postgrest LOGIN NOINHERIT;
        CREATE ROLE anon ROLE postgrest;
      '';
    };
    services.postgrest = {
      enable = true;
      settings.db-anon-role = "anon";
      settings.db-uri.dbname = "postgres";
    };
  }
 This will expose the PostgREST server on localhost on the NixOS machine and allow anonymous access.
 .. tip::
  NixOS also allows to quickly spin up different PostgreSQL versions or even forks this way. For example, to test the current beta version of `OrioleDB <https://www.orioledb.com>`_, use ``services.postgresql.package = pkgs.orioledb``.
@@ -1,11 +1,9 @@
 personal_ws-1.1 en 0 utf-8
 api
 autoscaling
 API's
 APIs
 APISIX
 AST
 async
 aud
 Auth
 auth
@@ -16,7 +14,6 @@ BOM
 Bytea
 Cardano
 cd
 CDNs
 centric
 CLI
 CMS
@@ -31,11 +28,10 @@ CSV
 durations
 DDL
 DOM
 DSL
 DevOps
 Dramatiq
 dockerize
 enum
 ECS
 Enums
 Entra
 eq
@@ -45,10 +41,7 @@ EveryLayout
 filename
 FreeBSD
 fts
 fullstack
 GC
 GeoJSON
 GHC
 Github
 Google
 grantor
@@ -77,6 +70,7 @@ isdistinct
 JS
 js
 JSON
 JSPath
 JWK
 JWT
 jwt
@@ -99,7 +93,6 @@ namespaced
 Nanos
 neq
 nginx
 NixOS
 nixpkgs
 npm
 nxl
@@ -145,13 +138,11 @@ Redux
 refactor
 reloadable
 Reloadable
 reuseport
 requester's
 RESTful
 RLS
 RPC
 RSA
 RTS
 safeupdate
 savepoint
 schemas
@@ -197,7 +188,6 @@ verifier
 versioning
 Vondra
 Vue
 webapp
 webhooks
 websearch
 Websockets
@@ -3,9 +3,7 @@
 Admin Server
 ############
-PostgREST provides an admin server that can be enabled by setting :ref:`admin-server-port` or :ref:`admin-server-unix-socket`.
+PostgREST provides an admin server that can be enabled by setting :ref:`admin-server-port`.
 Multiple PostgREST instances can share the same public API host and port when :ref:`server-reuseport` is enabled. Admin ports are not shared: give each instance a different :ref:`admin-server-port`, otherwise the new instance will fail to start.
 .. _health_check:
@@ -74,4 +72,5 @@ Provides the ``schema_cache`` endpoint that prints the runtime :ref:`schema_cach
    "dbRepresentations": ["..."],
    "dbRoutines": ["..."],
    "dbTables": ["..."],
    "dbTimezones": ["..."]
  }
@@ -21,7 +21,6 @@ PostgREST exposes three database objects of a schema as resources: tables, views
   api/aggregate_functions.rst
   api/openapi.rst
   api/preferences.rst
   api/vary_header.rst
   api/*
 .. raw:: html
@@ -69,26 +69,6 @@ If the function doesn't modify the database, it will also run under the GET meth
 The function parameter names match the JSON object keys in the POST case, for the GET case they match the query parameters ``?a=1&b=2``.
 If the function is defined to have default values for the parameters then arguments for these parameters can be omitted in the request. For instance:
 .. code-block:: postgres
  CREATE FUNCTION greet_user(username TEXT DEFAULT 'guest')
  RETURNS TEXT AS $$
    SELECT 'Hello ' || username || '!';
  $$ LANGUAGE SQL IMMUTABLE;
 .. code-block:: bash
  curl -i "http://localhost:3000/rpc/greet_user"
 .. code-block:: http
  HTTP/1.1 200 OK
  Context-Type: application/json; charset=utf-8
  "Hello guest!"
 .. _function_single_json:
 Functions with an array of JSON objects
@@ -15,7 +15,7 @@ Using these domains, :ref:`functions <functions>` can become handlers and `user-
 .. important::
-  - PostgREST vendor media types (``application/vnd.pgrst.plan``, ``application/vnd.pgrst.object`` and ``application/vnd.pgrst.array``) cannot be overridden.
+  - PostgREST vendor media types (``application/vnd.pgrst.plan``, ``application/vnd.pgrst.object`` and ``application/vnd.pgrst.array``) cannot be overriden.
  - Long media types like ``application/vnd.openxmlformats-officedocument.wordprocessingml.document`` cannot be expressed as domains since they surpass `PostgreSQL identifier length <https://www.postgresql.org/docs/current/limits.html#LIMITS-TABLE>`_.
    For these you can use the :ref:`any_handler`.
@@ -62,12 +62,8 @@ The server ignores unrecognized or unfulfillable preferences by default. You can
 Timezone
 ========
-.. important::
+The ``timezone`` preference allows you to change the `PostgreSQL timezone <https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-TIMEZONE>`_. It accepts all time zones in `pg_timezone_names <https://www.postgresql.org/docs/current/view-pg-timezone-names.html>`_.
  ``handling=lenient`` is ignored for ``timezone``. Invalid time zones always return an error.
 The ``timezone`` preference allows you to change the `PostgreSQL timezone <https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-TIMEZONE>`_.
 It accepts all time zones in `pg_timezone_names <https://www.postgresql.org/docs/current/view-pg-timezone-names.html>`_ and numeric offsets.
 .. code-block:: bash
@@ -88,36 +84,35 @@ It accepts all time zones in `pg_timezone_names <https://www.postgresql.org/docs
    {"t":"2023-10-18T09:37:59.611-07:00"}
  ]
-Offsets are also accepted:
+For an invalid time zone, PostgREST returns values with the default time zone (configured on ``postgresql.conf`` or as a setting on the :ref:`authenticator <roles>`).
 .. code-block:: bash
  curl -i "http://localhost:3000/timestamps" \
    -H "Prefer: timezone=05:30"
 .. code-block:: http
  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
  Preference-Applied: timezone=05:30
 .. code-block:: json
  [
    {"t":"2023-10-18T17:07:59.611+05:30"},
    {"t":"2023-10-18T19:07:59.611+05:30"},
    {"t":"2023-10-18T21:07:59.611+05:30"}
  ]
 You can also use negative offsets like ``-03:00``.
 For an invalid time zone, PostgREST returns a database error.
 .. code-block:: bash
  curl -i "http://localhost:3000/timestamps" \
    -H "Prefer: timezone=Jupiter/Red_Spot"
 .. code-block:: http
  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
 .. code-block:: json
  [
    {"t":"2023-10-18T12:37:59.611+00:00"},
    {"t":"2023-10-18T14:37:59.611+00:00"},
    {"t":"2023-10-18T16:37:59.611+00:00"}
  ]
 Note that there's no ``Preference-Applied`` in the response.
 However, with ``handling=strict``, an invalid time zone preference will throw an :ref:`error <pgrst122>`.
 .. code-block:: bash
  curl -i "http://localhost:3000/timestamps" \
    -H "Prefer: handling=strict, timezone=Jupiter/Red_Spot"
 .. code-block:: http
  HTTP/1.1 400 Bad Request
@@ -1244,7 +1244,7 @@ You can order the correlated arrays explicitly. For example, to order by the fil
 .. warning::
-   Aliasing spread columns is recommended since JSON allows duplicate keys. Example:
+   Aliasing spreaded columns is recommended since JSON allows duplicate keys. Example:
   .. code-block:: bash
@@ -5,10 +5,6 @@ Schemas
 PostgREST can expose a single or multiple schema's tables, views and functions. The :ref:`active database role <roles>` must have the usage privilege on the schemas to access them.
 .. important::
  ``pg_catalog`` and ``information_schema`` are not allowed in :ref:`db-schemas`. This is done to prevent leaking sensitive information and hence they cannot be accessed directly. If you wish to expose objects of these schemas, expose another schema that contains wrapper views or functions over ``pg_catalog`` or ``information_schema`` objects.
 Single schema
 -------------
@@ -639,7 +639,7 @@ However, it can work with surrogate primary keys (e.g. ``id serial primary key``
 .. code-block:: bash
-  curl "http://localhost:3000/employees?columns=id,name,salary" \
+  curl "http://localhost:3000/employees?colums=id,name,salary" \
    -X POST -H "Content-Type: application/json" \
    -H "Prefer: resolution=merge-duplicates, missing=default" \
    -d @- << EOF
@@ -51,7 +51,7 @@ You can request table/columns with spaces in them by percent encoding the spaces
 Reserved characters
 ~~~~~~~~~~~~~~~~~~~
-If filters include PostgREST reserved characters(``,``, ``.``, ``:``, ``*``, ``(``, ``)``) you'll have to surround them in percent encoded double quotes ``%22`` for correct processing.
+If filters include PostgREST reserved characters(``,``, ``.``, ``:``, ``()``) you'll have to surround them in percent encoded double quotes ``%22`` for correct processing.
 Here ``Hebdon,John`` and ``Williams,Mary`` are values.
@@ -1,16 +0,0 @@
 .. _vary_header:
 Vary Header
 ===========
 In order to assist caching proxies and CDNs, PostgREST includes a ``Vary`` header of value
 ``Accept, Prefer, Range`` in its responses which should fit most of the bills. As any other
 response header, it's available for override
 by updating ``response.headers`` GUC variable accordingly, for example:
 .. code-block:: postgres
   -- Override the Vary header to include Accept, Prefer and X-Test-Vary headers
   perform set_config('response.headers', '[{"Vary": "Accept, Prefer, X-Test-Vary"}]', true);
 In this case PostgREST will use provided value verbatim.
@@ -217,38 +217,47 @@ It's recommended to leave the JWT cache enabled as our load tests indicate ~20%
  - If the ``jwt-secret`` is changed and the config is reloaded, the JWT cache will reset.
  - JWTs that pass :ref:`jwt_signature` are cached, regardless if they pass :ref:`jwt_claims_validation`. We do this to ensure responses stays fast under common failure cases (such as expired JWTs).
-  - You can use the :ref:`server-timing_header` to see the performance benefit of JWT caching.
+  - You can use the :ref:`server-timing_header` to see the peformance benefit of JWT caching.
 .. _jwt_role_extract:
 JWT Role Extraction
 -------------------
-A JSON Path (`RFC 9535 <https://www.rfc-editor.org/rfc/rfc9535.html>`_) can be specified for the location of the :code:`role` key in the JWT claims. It's configured by :ref:`jwt-role-claim-key`. This can be used to consume a JWT provided by a third party service like Auth0, Okta, Microsoft Entra or Keycloak.
+A JSPath DSL that specifies the location of the :code:`role` key in the JWT claims. It's configured by :ref:`jwt-role-claim-key`. This can be used to consume a JWT provided by a third party service like Auth0, Okta, Microsoft Entra or Keycloak.
-You can quickly try out JSON Path by visiting https://serdejsonpath.live.
+The DSL follows the `JSONPath <https://goessner.net/articles/JsonPath/>`_ expression grammar with extended string comparison operators. Supported operators are:
 - ``==`` selects the first array element that exactly matches the right operand
 - ``!=`` selects the first array element that does not match the right operand
 - ``^==`` selects the first array element that starts with the right operand
 - ``==^`` selects the first array element that ends with the right operand
 - ``*==`` selects the first array element that contains the right operand
 Usage examples:
  .. code:: bash
    # {"postgrest":{"roles": ["other", "author"]}}
-    jwt-role-claim-key = "$$.postgrest.roles[1]"
+    # the DSL accepts characters that are alphanumerical or one of "_$@" as keys
    jwt-role-claim-key = ".postgrest.roles[1]"
    # {"https://www.example.com/role": { "key": "author" }}
-    # non-alphanumerical characters can go inside single quotes
+    # non-alphanumerical characters can go inside quotes(escaped in the config value)
-    jwt-role-claim-key = "$$['https://www.example.com/role'].key"
+    jwt-role-claim-key = ".\"https://www.example.com/role\".key"
    # {"postgrest":{"roles": ["other", "author"]}}
-    # filter based on equality or regular expression
+    # `@` represents the current element in the array
-    jwt-role-claim-key = "$$.postgrest.roles[?(@ == 'author')]"
+    # all the these match the string "author"
-    jwt-role-claim-key = "$$.postgrest.roles[?search(@, '^au')]"
+    jwt-role-claim-key = ".postgrest.roles[?(@ == \"author\")]"
    jwt-role-claim-key = ".postgrest.roles[?(@ != \"other\")]"
    jwt-role-claim-key = ".postgrest.roles[?(@ ^== \"aut\")]"
    jwt-role-claim-key = ".postgrest.roles[?(@ ==^ \"hor\")]"
    jwt-role-claim-key = ".postgrest.roles[?(@ *== \"utho\")]"
 .. note::
-  - If JSON Path query returns multiple values, the first one gets selected.
+  The string comparison operators are implemented as a custom extension to the JSPath and does not strictly follow the `RFC 9535 <https://www.rfc-editor.org/rfc/rfc9535.html>`_.
  - Only when using the :ref:`file_config`, all ``$`` characters in the value must be escaped with an additional ``$`` char. For :ref:`env_variables_config` and :ref:`in_db_config`, only use a single ``$`` char.
  - In our implementation, only the `search()` function from `JSON Path Functions <https://www.rfc-editor.org/rfc/rfc9535.html#name-function-extensions>`_ is available for filtering.
 JWT Security
 ------------
@@ -176,46 +176,6 @@ admin-server-port
  Specifies the port for the :ref:`admin_server`. Cannot be equal to :ref:`server-port`.
 .. _admin-server-unix-socket:
 admin-server-unix-socket
 ------------------------
  =============== =================================
  **Type**        String
  **Default**     `n/a`
  **Reloadable**  N
  **Environment** PGRST_ADMIN_SERVER_UNIX_SOCKET
  **In-Database** `n/a`
  =============== =================================
  `Unix domain socket <https://en.wikipedia.org/wiki/Unix_domain_socket>`_ where to bind the :ref:`admin_server`.
  If specified, this takes precedence over :ref:`admin-server-port`. Example:
  .. code:: bash
    admin-server-unix-socket = "/tmp/pgrst-admin.sock"
 .. _admin-server-unix-socket-mode:
 admin-server-unix-socket-mode
 -----------------------------
  =============== ===================================
  **Type**        String
  **Default**     660
  **Reloadable**  N
  **Environment** PGRST_ADMIN_SERVER_UNIX_SOCKET_MODE
  **In-Database** `n/a`
  =============== ===================================
  `Unix file mode <https://en.wikipedia.org/wiki/File_system_permissions>`_ to be set for the socket specified in :ref:`admin-server-unix-socket`
  Needs to be a valid octal between 600 and 777.
  .. code:: bash
    admin-server-unix-socket-mode = "660"
 .. _app.settings.*:
 app.settings.*
@@ -235,33 +195,6 @@ app.settings.*
  The :code:`current_setting` function has `an optional boolean second <https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADMIN-SET>`_ argument to avoid it from raising an error if the value was not defined. Default values to :code:`app.settings` can then be given by combining this argument with :code:`coalesce` and :code:`nullif` : :code:`coalesce(nullif(current_setting('app.settings.my_custom_variable', true), ''), 'default value')`. The use of :code:`nullif` is necessary because if set in a transaction, the setting is sometimes not "rolled back" to :code:`null`. See also :ref:`this section <guc_req_headers_cookies_claims>` for more information on this behaviour.
 .. _client-error-verbosity:
 client-error-verbosity
 ----------------------
  =============== =======================
  **Type**        String
  **Default**     verbose
  **Reloadable**  Y
  **Environment** PGRST_CLIENT_ERROR_VERBOSITY
  **In-Database** pgrst.client_error_verbosity
  =============== =======================
  Specifies the verbosity of PostgREST errors. See :ref:`client_error_verbosity`.
  .. code:: bash
    # Return error "code", "message", "details" and "hint"
    client-error-verbosity = "verbose"
    # Return only "code" and "message"
    client-error-verbosity = "minimal"
  .. note::
    This setting only affects client side error messages. Server side logs are not affected by this setting.
 .. _db-aggregates-enabled:
 db-aggregates-enabled
@@ -331,7 +264,7 @@ db-channel-enabled
  When this is set to :code:`true`, the notification channel specified in :ref:`db-channel` is enabled.
-  You should set this to ``false`` when using PostgreSQL behind an external connection pooler such as PgBouncer working in transaction pooling mode. See :ref:`this section <external_connection_poolers>` for more information.
+  You should set this to ``false`` when using PostgresSQL behind an external connection pooler such as PgBouncer working in transaction pooling mode. See :ref:`this section <external_connection_poolers>` for more information.
 .. _db-config:
@@ -546,7 +479,7 @@ db-prepared-statements
  When disabled, the generated queries will be parameterized (invulnerable to SQL injection) but they will not be prepared (cached in the database session). Not using prepared statements will noticeably decrease performance, so it's recommended to always have this setting enabled.
-  You should only set this to ``false`` when using PostgreSQL behind an external connection pooler such as PgBouncer working in transaction pooling mode. See :ref:`this section <external_connection_poolers>` for more information.
+  You should only set this to ``false`` when using PostgresSQL behind an external connection pooler such as PgBouncer working in transaction pooling mode. See :ref:`this section <external_connection_poolers>` for more information.
 .. _db-root-spec:
@@ -593,7 +526,7 @@ db-tx-end
  **In-Database** pgrst.db_tx_end
  =============== =================================
-  Specifies how to terminate the database transactions. See :ref:`prefer_tx`.
+  Specifies how to terminate the database transactions.
  .. code:: bash
@@ -679,7 +612,7 @@ jwt-role-claim-key
  =============== =================================
  **Type**        String
-  **Default**     $.role
+  **Default**     .role
  **Reloadable**  Y
  **Environment** PGRST_JWT_ROLE_CLAIM_KEY
  **In-Database** pgrst.jwt_role_claim_key
@@ -689,10 +622,6 @@ jwt-role-claim-key
  See :ref:`jwt_role_extract` on how to specify key paths and usage examples.
 .. warning::
  Only when using :ref:`file_config`, the ``$`` char needs to be escaped, so use ``$$`` and PostgREST will interpret it as a single ``$`` character.
 .. _jwt-secret:
 jwt-secret
@@ -752,7 +681,7 @@ log-level
  =============== =================================
  **Type**        String
  **Default**     error
-  **Reloadable**  Y
+  **Reloadable**  N
  **Environment** PGRST_LOG_LEVEL
  **In-Database** `n/a`
  =============== =================================
@@ -928,50 +857,6 @@ server-port
  The TCP port to bind the web server. Use ``0`` to automatically assign a port.
 .. _server-reuseport:
 server-reuseport
 ----------------
  =============== =================================
  **Type**        Bool
  **Default**     false
  **Reloadable**  N
  **Environment** PGRST_SERVER_REUSEPORT
  **In-Database** `n/a`
  =============== =================================
  Enables ``SO_REUSEPORT`` on the TCP server socket. This allows multiple
  PostgREST processes to bind to the same :ref:`server-host` and
  :ref:`server-port` when the operating system supports it.
  For example, two PostgREST processes can use the same configuration:
  .. code:: ini
    server-host = "127.0.0.1"
    server-port = 3000
    server-reuseport = true
  New connections are then distributed by the operating system between the
  running PostgREST processes. This can be used to start a replacement process
  before stopping the old one, or to run several PostgREST processes behind one
  port.
  If ``server-reuseport`` is disabled, starting another PostgREST process on
  the same host and port will fail with the usual address-in-use error.
  Enabling this setting on an operating system that does not support
  ``SO_REUSEPORT`` is a configuration error. PostgREST will fail to start
  instead of falling back to a normal TCP socket.
  When running multiple PostgREST instances on the same :ref:`server-port`, use
  a different ``admin-server-port`` for each instance. Admin ports are not shared
  between instances, so readiness checks always target one specific PostgREST
  instance.
  This setting does not apply when :ref:`server-unix-socket` is used.
 .. _server-trace-header:
 server-trace-header
@@ -1042,37 +927,3 @@ server-unix-socket-mode
  .. code:: bash
    server-unix-socket-mode = "660"
 .. _url-use-legacy-target-names:
 url-use-legacy-target-names
 ---------------------------
  =============== =================================
  **Type**        Boolean
  **Default**     True
  **Reloadable**  Y
  **Environment** PGRST_URL_USE_LEGACY_TARGET_NAMES
  **In-Database** pgrst.url_use_legacy_target_names
  =============== =================================
  When active, it allows using the the name of an embedded table in filters, orders or limits even if it has an alias:
  .. code:: bash
    curl "http://localhost:3000/table?select=alias:target(*)&target.order=id" -i
  .. code:: text
    Warning: 299 PostgRESTv16 "Embedded resource was referenced by relation name even though it has an alias. This is deprecated and will stop working in a future release. Update `target` to `alias` in query string filters, orders or limits."
    [...]
  Note that the response includes a deprecation message in the ``Warning`` header.
  This will also show in the PostgREST logs:
  .. code::
    28/May/2026:20:33:22 -0500: WARNING: Embedded resource was referenced by relation name even though it has an alias. This is deprecated and will stop working in a future release.
    28/May/2026:20:33:22 -0500: Update filters, orders or limits that use `target` to `alias` in `GET /table?select=alias:target(*)&target.order=id`
  This feature will be removed in a future release, so you should start using the ``alias`` in these cases.
@@ -47,8 +47,6 @@ Under a busy system, the :ref:`db-pool-max-idletime` won't be reached and the co
 To avoid this problem and save resources, a connection max lifetime (:ref:`db-pool-max-lifetime`) is enforced.
 After the max lifetime is reached, connections from the pool will be released and new ones will be created. This doesn't affect running requests, only unused connections will be released.
 .. _pool_timeout:
 Acquisition Timeout
 -------------------
@@ -199,7 +199,7 @@ Related to the HTTP request elements.
 |               |             | :ref:`switching schemas <multiple-schemas>` is not present  |
 | PGRST106      |             | in the :ref:`db-schemas` configuration variable.            |
 +---------------+-------------+-------------------------------------------------------------+
-| .. _pgrst107: | 406         | The ``Accept`` media type sent in the request is invalid.   |
+| .. _pgrst107: | 415         | The ``Content-Type`` sent in the request is invalid.        |
 |               |             |                                                             |
 | PGRST107      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
@@ -473,38 +473,3 @@ For example, doing a request on a table with high count (say 30_000_000), we get
  Proxy-Status: PostgREST; error=57014
 The PostgreSQL error code ``57014`` (`ref <https://www.postgresql.org/docs/current/errcodes-appendix.html>`_) reveals that the error is due to a short ``statement_timeout`` value.
 .. _client_error_verbosity:
 Client Error Verbosity
 ======================
 For HTTP clients, the error verbosity can be set via :ref:`client-error-verbosity` config.
 With ``verbose``, it returns ``code``, ``message``, ``details`` and ``hint``.
 .. code:: bash
  curl "localhost:3000/itemsxx"
 .. code-block:: json
  {
      "code": "PGRST205",
      "message": "Could not find the table 'public.itemsxx' in the schema cache",
      "details": "Perhaps you meant the table 'public.items'",
      "hint": null
  }
 With ``minimal``, just ``code`` and ``message`` is returned.
 .. code:: bash
  curl "localhost:3000/itemsxx"
 .. code-block:: json
  {
      "code": "PGRST205",
      "message": "Could not find the table 'public.itemsxx' in the schema cache"
  }
@@ -1,18 +0,0 @@
 .. _http_server:
 HTTP Server
 ###########
 The HTTP server is provided by `Warp <https://aosabook.org/en/posa/warp.html>`_.
 Graceful shutdown
 -----------------
 PostgREST uses Warp's graceful shutdown, when a ``SIGTERM`` is received:
 - It stops accepting new requests.
 - Allows requests that are already in progress to finish.
 - Closes idle ``Keep-Alive`` connections instead of waiting for them to expire.
 - Responses sent during shutdown indicate that the connection should not be reused (e.g. for HTTP/1.x, it sends ``Connection: close``).
 This allows PostgREST to shut down promptly without interrupting in-flight requests. Useful for zero-downtime upgrades and autoscaling/load-balancing under cloud environments (AWS ECS, Kubernetes).
@@ -238,45 +238,6 @@ pgrst_jwt_cache_evictions_total
 The total number of JWT cache evictions.
 GHC Runtime Metrics
 -------------------
 PostgREST can also expose GHC runtime system metrics. These use the ``ghc_*``
 prefix and include
 `GHC RTS statistics <https://ghc.gitlab.haskell.org/ghc/doc/libraries/base-4.22.0.0-inplace/GHC-Stats.html#g:1>`_
 for runtime allocation, garbage collection, memory, and CPU/elapsed time.
 These are useful for monitoring PostgREST process health and diagnosing memory
 pressure or GC behavior.
 To expose these metrics, enable GHC RTS statistics when starting PostgREST:
 .. code-block:: bash
  postgrest +RTS -T -RTS
 When enabled, the admin ``/metrics`` endpoint includes samples such as:
 .. code-block:: text
  # HELP ghc_gcs_total Total number of GCs
  # TYPE ghc_gcs_total counter
  ghc_gcs_total 1
  # HELP ghc_allocated_bytes_total Total bytes allocated
  # TYPE ghc_allocated_bytes_total counter
  ghc_allocated_bytes_total 12345678
 Other available GHC runtime metrics include:
 - ``ghc_gcs_total``
 - ``ghc_major_gcs_total``
 - ``ghc_allocated_bytes_total``
 - ``ghc_max_live_bytes``
 - ``ghc_max_mem_in_use_bytes``
 - ``ghc_mutator_cpu_seconds_total``
 - ``ghc_gc_cpu_seconds_total``
 - ``ghc_elapsed_seconds_total``
 Traces
 ======
@@ -430,8 +391,6 @@ By default the plan is assumed to generate the JSON representation of a resource
 The other available parameters are ``analyze``, ``verbose``, ``settings``, ``buffers`` and ``wal``, which correspond to the `EXPLAIN command options <https://www.postgresql.org/docs/current/sql-explain.html>`_. To use the ``analyze`` and ``wal`` parameters for example, you would add them like ``Accept: application/vnd.pgrst.plan; options=analyze|wal``.
 For a workflow that takes the ``Query Identifier`` from a verbose PostgREST plan and uses it to inspect the same query in ``pg_stat_statements``, see :ref:`debugging_performance_pg_stat_statements`.
 Note that akin to the EXPLAIN command, the changes will be committed when using the ``analyze`` option. To avoid this, you can use the :ref:`db-tx-end` and the ``Prefer: tx=rollback`` header.
 Securing the Execution Plan
@@ -3,16 +3,10 @@
 Schema Cache
 ============
-PostgREST requires metadata from the database to provide a REST API that abstracts SQL details. One example of this is the interface for :ref:`resource_embedding`.
+PostgREST requires metadata from the database schema to provide a REST API that abstracts SQL details. One example of this is the interface for :ref:`resource_embedding`.
 Getting this metadata requires expensive queries. To avoid repeating this work, PostgREST uses a schema cache.
 .. note::
  - Schema cache queries have been optimized over time to stay fast, even on complex databases. You can see a summary of their execution time in :ref:`pgrst_logging` and :ref:`metrics`.
  - If the schema cache queries are slow, the most likely cause is *system catalog bloat*, see `issue#3212 <https://github.com/PostgREST/postgrest/issues/3212>`_ for more details.
  - You can turn the :ref:`log-level` to ``debug`` to see the time of each schema cache query.
 .. _schema_reloading:
 Schema Cache Reloading
@@ -24,7 +18,7 @@ You can do this with UNIX signals or with PostgreSQL notifications. It's also po
 .. note::
-  - If the schema cache fails to reload (e.g. due to a ``statement_timeout`` or :ref:`pool timeout <pool_timeout>`), PostgREST will continue serving requests in a "best effort" basis.
+  - Requests will wait until the schema cache reload is done. This to prevent client errors due to an stale schema cache.
  - If you are using the :ref:`in_db_config`, a schema cache reload will :ref:`reload the configuration<config_reloading>` as well.
 .. _schema_reloading_signals:
@@ -221,7 +221,7 @@ Notice that the ``response.headers`` should be set to an *array* of single-key o
 .. note::
-  PostgREST provided headers such as ``Content-Type``, ``Location``, etc. can be overridden this way. Note that irrespective of overridden ``Content-Type`` response header, the content will still be converted to JSON, unless you use :ref:`custom_media`.
+  PostgREST provided headers such as ``Content-Type``, ``Location``, etc. can be overriden this way. Note that irrespective of overridden ``Content-Type`` response header, the content will still be converted to JSON, unless you use :ref:`custom_media`.
 .. _guc_resp_status:
@@ -1,7 +1,7 @@
 # This file is auto-generated by postgrest-nixpkgs-upgrade
-sphinx==9.1.0
+sphinx==8.2.3
 sphinx-copybutton==0.5.2
 sphinx-rtd-dark-mode==1.3.0
-sphinx-rtd-theme==3.1.0
+sphinx-rtd-theme==3.0.2
-sphinx-tabs==3.5.0
+sphinx-tabs==3.4.7
-sphinxext-opengraph==0.13.0
+sphinxext-opengraph==0.9.1
@@ -22,7 +22,7 @@ Step 1. Install PostgreSQL
 If you're already familiar with using PostgreSQL and have it installed on your system you can use the existing installation (see :ref:`pg-dependency` for minimum requirements). For this tutorial we'll describe how to use the database in Docker because database configuration is otherwise too complicated for a simple tutorial.
-If Docker is not installed, you can get it `here <https://www.docker.com/get-started>`_. Make sure that Docker service is `started <https://docs.docker.com/engine/daemon/start/#start-the-daemon-using-operating-system-utilities>`_. Next, let's pull and start the database image:
+If Docker is not installed, you can get it `here <https://www.docker.com/get-started>`_. Next, let's pull and start the database image:
 .. code-block:: bash
@@ -2,16 +2,16 @@
  "nodes": {
    "nixpkgs": {
      "locked": {
-        "lastModified": 1784115452,
+        "lastModified": 1752006229,
-        "narHash": "sha256-BoYPdqk6jlKXy+DyUzyGV/CtRGfAhk2MmIgBhsemTGI=",
+        "narHash": "sha256-BeuAPwNM2RBc5bvUTb0j4GRs2yBkDeRCw/8Y3v9Xesc=",
        "owner": "nixos",
        "repo": "nixpkgs",
-        "rev": "35d3407a3816f3b341d8cf1d60abaf2b7b8166ac",
+        "rev": "c80edd02003fe3d8af527215a3ac069be9cfd47f",
        "type": "github"
      },
      "original": {
        "owner": "nixos",
-        "ref": "nixpkgs-unstable",
+        "ref": "nixpkgs-25.05-darwin",
        "repo": "nixpkgs",
        "type": "github"
      }
@@ -2,7 +2,7 @@
  description = "REST API for any Postgres database";
  inputs = {
-    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
+    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-25.05-darwin";
  };
  nixConfig = {
@@ -46,9 +46,5 @@
          meta.description = "REST API for any Postgres database";
        };
      });
      devShells = genSystems (postgrest: {
        default = import ./shell.nix { inherit postgrest; };
      });
    };
 }
@@ -70,16 +70,55 @@ The PostgREST utilities available in `nix-shell` all have names that begin with
 `<tab>`) in `nix-shell` to see all that are available:
 ```bash
 # Note: The utilities listed here might not be up to date.
 [nix-shell]$ postgrest-<tab>
-postgrest-build
+postgrest-build                   postgrest-parallel-curl
-postgrest-cabal-update
+postgrest-check                   postgrest-profiled-run
-postgrest-check
+postgrest-clean                   postgrest-push-cachix
-postgrest-clean
+postgrest-commitlint              postgrest-release
-postgrest-commitlint
+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-pg-13
 postgrest-hsie-graph-symbols      postgrest-with-pg-14
 postgrest-hsie-minimal-imports    postgrest-with-pg-15
 postgrest-lint                    postgrest-with-pg-16
 postgrest-loadtest                postgrest-with-pg-17
 postgrest-loadtest-against        postgrest-with-slow-pg
 postgrest-loadtest-report         postgrest-with-slow-postgrest
 postgrest-nixpkgs-upgrade
 ...
 [nix-shell]$
 ```
-Most of these commands provide a `--help` output, make sure to check it out.
+The `docker` module has large dependencies to be build before the shell becomes
 available, which could take an especially long time if the cachix binary cache
 is not used. You can activate it by passing a flag to `nix-shell` with
 `nix-shell --arg docker true`. This will make the respective utilities available:
 ```bash
 $ nix-shell --arg docker true
 [nix-shell]$ postgrest-docker-<tab>
 postgrest-docker-load
 ...
 ```
 Note that `postgrest-docker-load` is now also available.
 To run one-off commands, you can also use `nix-shell --run <command>`, which
 will launch the Nix shell, run that one command and exit. Note that the tab
@@ -95,6 +134,16 @@ $ nix-shell --run "postgrest-foo --bar"
 ```
 A third option is to install utilities that you use very often locally:
 ```bash
 $ nix-env -f default.nix -iA devTools
 # `postgrest-style` can now be run directly:
 $ postgrest-style
 ```
 If you use `nix-shell` very often, you might like to use
 https://github.com/xzfc/cached-nix-shell, which skips evaluating all our Nix
 expressions if nothing changed, reducing startup time for the shell
@@ -125,7 +174,7 @@ $ nix-shell --run "postgrest-with-all postgrest-test-spec"
 # Run the tests against a specific version of PostgreSQL (use tab-completion in
 # nix-shell to see all available versions):
-$ nix-shell --run "postgrest-with-pg-17 postgrest-test-spec"
+$ nix-shell --run "postgrest-with-pg-13 postgrest-test-spec"
 ```
@@ -160,7 +209,13 @@ The loadtests ensure that performance doesn't drop on a change. Underlyingly the
 [nix-shell]$ postgrest-loadtest
 # You can loadtest comparing to a different branch
-[nix-shell]$ postgrest-loadtest-against main
+[nix-shell]$ postgrest-loadtest-against master
 # You can simulate latency client/postgrest and postgrest/database
 [nix-shell]$ PGRST_DELAY=5ms PGDELAY=5ms postgrest-loadtest
 # You can build postgrest directly with cabal for faster iteration
 [nix-shell]$ PGRST_BUILD_CABAL=1 postgrest-loadtest
 # Produce a markdown report to be used on CI
 [nix-shell]$ postgrest-loadtest-report
@@ -16,8 +16,11 @@ The following checklist guides you through the complete process in more detail.
 ## Upgrade the pinned version of `nixpkgs`
 The pinned version of [`nixpkgs`](https://github.com/NixOS/nixpkgs) is defined
-in [`flake.nix`](../flake.nix). To upgrade it, you can use a small utility
+in [`nix/nixpkgs-version.nix`](nixpkgs-version.nix). The pin refers directly to
-script defined in [`nix/tools/nixpkgsTools.nix`](tools/nixpkgsTools.nix):
+a GitHub tarball for the given revision, which is more efficient than pulling
 the complete Git repository. To upgrade it to the current `main` of
 `nixpkgs`, you can use a small utility script defined in
 [`nix/nixpkgs-update.nix`](nixpkgs-update.nix):
 ```bash
 # From the root of the repository, enter nix-shell
@@ -27,12 +30,21 @@ nix-shell
 postgrest-nixpkgs-upgrade
 # Exit the nix-shell with Ctrl-d
 ```
 ## Review overlays
 Check whether the individual [overlays](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`](patches).
 Check whether the pull-requests/issues linked in the
 [`default.nix`](patches/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
@@ -46,19 +58,25 @@ errors, this is probably due to one of our patches. Try to fix them and re-run
 ## Update the PostgREST binary cache
-If you have access to the PostgREST cachix project, you can push the
+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 login with your token with `cachix authtoken <token>`.
+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 your shell history.
 To push all new artifacts to Cachix, run:
 ```
 nix-store -qR --include-outputs $$(nix-instantiate) | cachix push postgrest
 # Or, equivalently
 nix-shell --run postgrest-push-cachix
 ```
-The `postgrest-push-cachix` command will query the nix-store to list all
+The `nix-store` command will query the nix-store to list all dependencies and
-dependencies and build artifacts of PostgREST. It will then push
+build artifacts of PostgREST. The `cachix` command will efficiently push
 everything that is not yet cached to the binary cache.
@@ -4,7 +4,6 @@
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE RecordWildCards   #-}
 {-# LANGUAGE TupleSections     #-}
 {-# LANGUAGE TypeApplications  #-}
 {-# LANGUAGE TypeFamilies      #-}
 -- | Haskell Imports and Exports tool
@@ -34,15 +33,13 @@ import Data.Function              ((&))
 import Data.List                  (intercalate)
 import Data.Maybe                 (catMaybes, mapMaybe)
 import Data.Text                  (Text)
 import GHC.Driver.Errors.Types    (GhcMessage)
 import GHC.Generics               (Generic)
 import GHC.Hs.Extension           (GhcPs)
-import GHC.Types.Error            (Messages, defaultDiagnosticOpts, getMessages)
+import GHC.Types.Error            (getMessages)
 import GHC.Types.Name.Occurrence  (occNameString)
 import GHC.Types.Name.Reader      (rdrNameOcc)
-import GHC.Unit.Module            (moduleNameString)
+import GHC.Unit.Module.Name       (moduleNameString)
 import GHC.Utils.Error            (pprMsgEnvelopeBagWithLoc)
 import GHC.Utils.Outputable       (showSDocUnsafe)
 import System.Directory.Recursive (getFilesRecursive)
 import System.Exit                (exitFailure)
@@ -201,7 +198,7 @@ sourceSymbols source = do
      return $ concatMap (importSymbols source filepath . GHC.unLoc) hsmodImports
 -- | Parse a Haskell module
-parseModule :: FilePath -> IO (GHC.HsModule GhcPs)
+parseModule :: FilePath -> IO GHC.HsModule
 parseModule filepath = do
  result <- ExactPrint.parseModule GHC.Paths.libdir filepath
  case result of
@@ -209,13 +206,7 @@ parseModule filepath = do
      return $ GHC.unLoc hsmod
    Left errs ->
      fail $ "Errors with " <> show filepath <> ":\n    "
-        <> formatParseErrors errs
+        <> show (pprMsgEnvelopeBagWithLoc $ getMessages errs)
 formatParseErrors :: Messages GhcMessage -> String
 formatParseErrors errs =
  intercalate "\n    "
    . fmap showSDocUnsafe
    $ pprMsgEnvelopeBagWithLoc (defaultDiagnosticOpts @GhcMessage) (getMessages errs)
 -- | Symbols imported in an import declaration.
 --
@@ -223,12 +214,9 @@ formatParseErrors errs =
 -- only one item is returned.
 importSymbols :: FilePath -> FilePath -> GHC.ImportDecl GhcPs -> [ImportedSymbol]
 importSymbols source filepath GHC.ImportDecl{..} =
-  case ideclImportList of
+  case ideclHiding of
-    Just (importListInterpretation, syms) ->
+    Just (hiding, syms) ->
-      symbol (if importListInterpretation == GHC.EverythingBut then Hiding else Explicit)
+      symbol (if hiding then Hiding else Explicit) . Just . GHC.unLoc <$> GHC.unLoc syms
        . Just
        . GHC.unLoc
        <$> GHC.unLoc syms
    Nothing ->
      [ symbol Wildcard Nothing ]
  where
@@ -5,10 +5,10 @@ project. It's available in PostgREST's `nix-shell` by default.
 ## Dumping imports
-Given source code in the directories `src/library` and `src/executable`, for example, you can run:
+Given source code in the directories `src` and `main`, for example, you can run:
 ```
-hsie dump-imports src/library src/executable
+hsie dump-imports src main
 ```
 This dumps all imports of the modules in the given directory to a CSV file,
@@ -18,7 +18,7 @@ To dump to a JSON file (e.g., to further process with `jq`), add the `--json`
 flag:
 ```
-hsie dump-imports --json src/library src/executable
+hsie dump-imports --json src main
 ```
 ## Graphing imports
@@ -27,7 +27,7 @@ The tool can generate `graphviz` graphs of module and symbol imports by printing
 a file to `stdout` that can directly be rendered with `dot`:
 ```
-hsie graph-modules src/library src/executable | dot -Tpng -o modules.png
+hsie graph-modules src main | dot -Tpng -o modules.png
 ```
 The command `graph-modules` prints a graph of which modules insert which other
@@ -39,7 +39,7 @@ To check whether modules are imported under consistent aliases in your project,
 run:
 ```
-hsie check-aliases src/library src/executable
+hsie check-aliases main src
 ```
 This will exit with a non-zero exit code if any inconsistent aliases are found.
@@ -48,13 +48,13 @@ The following command checks whether any modules are imported as wildcards, i.e.
 not qualified and without specifying symbols.
 ```
-hsie check-wildcards src/library src/executable
+hsie check-wildcards main src
 ```
 To whitelist certain modules to be imported as wildcards, use `--ok`:
 ```
-hsie check-wildcards src/library src/executable --ok Protolude --ok Test.Module
+hsie check-wildcards main src --ok Protolude --ok Test.Module
 ```
 ## Current limitations
@@ -104,7 +104,7 @@ let
        ''
        + lib.optionalString withTmpDir ''
-          tmpdir="$(${coreutils}/bin/mktemp -d --tmpdir=/tmp ${name}-XXX)"
+          tmpdir="$(${coreutils}/bin/mktemp -d --tmpdir ${name}-XXX)"
          # we keep the tmpdir when an error occurs for debugging
          trap 'echo Temporary directory kept at: $tmpdir' ERR
@@ -3,4 +3,5 @@
  checked-shell-script = import ./checked-shell-script;
  gitignore = import ./gitignore.nix;
  haskell-packages = import ./haskell-packages.nix;
  slocat = import ./slocat.nix;
 }
@@ -47,6 +47,7 @@ let
      # - To modify and try packages locally, see "Working with locally modified Haskell packages" in the Nix README.
      # Before upgrading fuzzyset to 0.3, check: https://github.com/PostgREST/postgrest/issues/3329
      # jailbreak, because hspec limit for tests
      fuzzyset = prev.fuzzyset_0_2_4;
      # TODO: Remove once available in nixpkgs
@@ -59,13 +60,23 @@ let
          }
          { };
-      # TODO: Remove once available in nixpkgs
+      # TODO: Remove once available in nixpkgs haskellPackages
-      aeson-jsonpath =
+      configurator-pg =
        prev.callHackageDirect
          {
-            pkg = "aeson-jsonpath";
+            pkg = "configurator-pg";
-            ver = "0.4.2.0";
+            ver = "0.2.11";
-            sha256 = "sha256-K+3brf1zjSSjojtSCXFrip5rrP7AO/S4zndAxAnvEfc=";
+            sha256 = "sha256-mtGtNawDJgz2ZIEVca+IYXVu4oNw9xsfJiYWAqAbbgc=";
          }
          { };
      # TODO: Remove once available in nixpkgs haskellPackages
      streaming-commons =
        prev.callHackageDirect
          {
            pkg = "streaming-commons";
            ver = "0.2.3.1";
            sha256 = "sha256-Gl2eaJcWe1sxmcE/octWlH9uSnERguf+5H66K4fV87s=";
          }
          { };
@@ -87,6 +98,24 @@ let
          }
          { };
      jose-jwt =
        prev.callHackageDirect
          {
            pkg = "jose-jwt";
            ver = "0.9.6";
            sha256 = "sha256-FhBz5wzyNrDvmjHWOeNAHuVMyJUVSlm+DeQQuITSjaI=";
          }
          { };
      time-manager =
        prev.callHackageDirect
          {
            pkg = "time-manager";
            ver = "0.2.4";
            sha256 = "sha256-sAt/331YLQ2IU3z90aKYSq1nxoazv87irsuJp7ZG3pw=";
          }
          { };
      network-run =
        prev.callHackageDirect
          {
@@ -105,6 +134,15 @@ let
              sha256 = "sha256-RnoOUlC6dOP0sK/tYAJCX1oLzVFG1GILUY+yVbmvW8Y=";
            }
            { });
      # Downgrade hasql and related packages while we are still on GHC 9.4 for the static build.
      hasql = lib.dontCheck (lib.doJailbreak prev.hasql_1_6_4_4);
      hasql-dynamic-statements = lib.dontCheck prev.hasql-dynamic-statements_0_3_1_5;
      hasql-implicits = lib.dontCheck prev.hasql-implicits_0_1_1_3;
      hasql-notifications = lib.dontCheck prev.hasql-notifications_0_2_2_2;
      hasql-pool = lib.dontCheck prev.hasql-pool_1_0_1;
      hasql-transaction = lib.dontCheck prev.hasql-transaction_1_1_0_1;
      postgresql-binary = lib.dontCheck (lib.doJailbreak prev.postgresql-binary_0_13_1_3);
    };
 in
 {
@@ -0,0 +1,13 @@
 _: prev:
 {
  slocat = prev.buildGoModule {
    name = "slocat";
    src = prev.fetchFromGitHub {
      owner = "robx";
      repo = "slocat";
      rev = "52e7512c6029fd00483e41ccce260a3b4b9b3b64";
      sha256 = "sha256-qn6luuh5wqREu3s8RfuMCP5PKdS2WdwPrujRYTpfzQ8=";
    };
    vendorHash = null;
  };
 }
@@ -51,7 +51,7 @@ let
        docs = "Run PostgREST after building it interactively with cabal-install";
        args =
          [
-            "ARG_USE_ENV([PGRST_DB_ANON_ROLE], [], [PostgREST anonymous role. (default: 'postgrest_test_anonymous')])"
+            "ARG_USE_ENV([PGRST_DB_ANON_ROLE], [postgrest_test_anonymous], [PostgREST anonymous role])"
            "ARG_USE_ENV([PGRST_DB_POOL], [1], [PostgREST pool size])"
            "ARG_USE_ENV([PGRST_DB_POOL_ACQUISITION_TIMEOUT], [1], [PostgREST pool timeout])"
            "ARG_USE_ENV([PGRST_JWT_SECRET], [reallyreallyreallyreallyverysafe], [PostgREST JWT secret])"
@@ -62,10 +62,6 @@ let
        withEnv = postgrest.env;
      }
      ''
        # when there's a default, argbash conflates empty string with unset, so we do this workaround to be able to do `PGRST_DB_ANON_ROLE="" <command>` for manual testing
        if [[ ! ''${PGRST_DB_ANON_ROLE+x} ]]; then
          PGRST_DB_ANON_ROLE="postgrest_test_anonymous"
        fi
        export PGRST_DB_ANON_ROLE
        export PGRST_DB_POOL
        export PGRST_DB_POOL_ACQUISITION_TIMEOUT
@@ -84,7 +80,7 @@ let
        docs = "Run a profiled build of postgREST. This will generate a postgrest.prof file that can be used to do optimization.";
        args =
          [
-            "ARG_USE_ENV([PGRST_DB_ANON_ROLE], [], [PostgREST anonymous role. (default: 'postgrest_test_anonymous')])"
+            "ARG_USE_ENV([PGRST_DB_ANON_ROLE], [postgrest_test_anonymous], [PostgREST anonymous role])"
            "ARG_USE_ENV([PGRST_DB_POOL], [1], [PostgREST pool size])"
            "ARG_USE_ENV([PGRST_DB_POOL_ACQUISITION_TIMEOUT], [1], [PostgREST pool timeout])"
            "ARG_USE_ENV([PGRST_JWT_SECRET], [reallyreallyreallyreallyverysafe], [PostgREST JWT secret])"
@@ -94,10 +90,6 @@ let
        withEnv = postgrest.env;
      }
      ''
        # when there's a default, argbash conflates empty string with unset, so we do this workaround to be able to do `PGRST_DB_ANON_ROLE="" <command>` for manual testing
        if [[ ! ''${PGRST_DB_ANON_ROLE+x} ]]; then
          PGRST_DB_ANON_ROLE="postgrest_test_anonymous"
        fi
        export PGRST_DB_ANON_ROLE
        export PGRST_DB_POOL
        export PGRST_DB_POOL_ACQUISITION_TIMEOUT
@@ -5,13 +5,15 @@
 , curl
 , devCabalOptions
 , entr
-, fd
+, git
 , graphviz
 , hsie
 , nix
 , silver-searcher
 , stdenv
 , style
 , tests
 , withTools
 , haskellPackages
 , ctags
 , openssl
@@ -39,7 +41,7 @@ let
      }
      ''
        while true; do
-          (! ${fd}/bin/fd -H -E .git | ${entr}/bin/entr -dr "$_arg_command" "''${_arg_leftovers[@]}")
+          (! ${silver-searcher}/bin/ag -l . | ${entr}/bin/entr -dr "$_arg_command" "''${_arg_leftovers[@]}")
        done
      '';
@@ -89,6 +91,156 @@ let
        ${style}/bin/postgrest-style-check
      '';
  gitHooks =
    let
      name = "postgrest-git-hooks";
    in
    checkedShellScript
      {
        inherit name;
        docs =
          ''
            Enable or disable git pre-commit and pre-push hooks.
            Basic is faster and will only run:
              - pre-commit: postgrest-style
              - pre-push: postgrest-lint
            Full takes a lot more time and will run:
              - pre-commit: postgrest-style && postgrest-lint
              - pre-push: postgrest-check
            Changes made by postgrest-style will be staged automatically.
            Example usage:
              postgrest-git-hooks disable
              postgrest-git-hooks enable basic
              postgrest-git-hooks enable full
            The "run" operation and "--hook" argument are only used internally.
          '';
        args =
          [
            "ARG_POSITIONAL_SINGLE([operation], [Operation])"
            "ARG_TYPE_GROUP_SET([OPERATION], [OPERATION], [operation], [disable,enable,run])"
            "ARG_POSITIONAL_SINGLE([mode], [Mode], [basic])"
            "ARG_TYPE_GROUP_SET([MODE], [MODE], [mode], [basic,full])"
            "ARG_OPTIONAL_SINGLE([hook], , [Hook], [pre-commit])"
            "ARG_TYPE_GROUP_SET([HOOK], [HOOK], [hook], [pre-commit,pre-push])"
          ];
        positionalCompletion =
          ''
            if test "$prev" == "${name}"; then
              COMPREPLY=( $(compgen -W "enable disable" -- "$cur") )
            elif test "$prev" == "enable" || test "$prev" == "disable"; then
              COMPREPLY=( $(compgen -W "basic full" -- "$cur") )
            fi
          '';
        workingDir = "/";
      }
      ''
        if [ run != "$_arg_operation" ]; then
          # Remove all hooks first and ignore failures because the file might be missing.
          # This assumes that we're only adding lines that include "postgrest-git-hooks"
          # to the hook file.
          sed -i -e '/postgrest-git-hooks/d' .git/hooks/pre-{commit,push} 2> /dev/null || true
          if [ disable != "$_arg_operation" ]; then
            # The nix-shell && + nix-shell || pattern makes sure we can run the hook
            # in a pure nix-shell, where nix-shell itself is not available, too.
            # The $(nix-shell --run "command -v ...") pattern ensures we only need to enable
            # the hooks once and still run the latest of our hook scripts, even when we
            # update them in the repo.
            echo 'command -v nix-shell > /dev/null || postgrest-git-hooks --hook=pre-commit run' "$_arg_mode" \
              >> .git/hooks/pre-commit
            # shellcheck disable=SC2016
            echo 'command -v nix-shell > /dev/null && $(nix-shell --quiet -Q --run "command -v postgrest-git-hooks") --hook=pre-commit run' "$_arg_mode" \
             >> .git/hooks/pre-commit
            chmod +x .git/hooks/pre-commit
            echo 'command -v nix-shell > /dev/null || postgrest-git-hooks --hook=pre-push run' "$_arg_mode" \
              >> .git/hooks/pre-push
            # shellcheck disable=SC2016
            echo 'command -v nix-shell > /dev/null && $(nix-shell --quiet -Q --run "command -v postgrest-git-hooks") --hook=pre-push run' "$_arg_mode" \
             >> .git/hooks/pre-push
            chmod +x .git/hooks/pre-push
          fi
        else
          # When run from a git hook, the GIT_ environment variables conflict with our withGit helper.
          # The following unsets all GIT_ variables.
          unset "''${!GIT_@}"
          # shellcheck disable=SC2317
          function restore () {
            ref="$(git stash list --format=format:%gD --grep "$1" -n1)"
            # this will avoid merge conflicts when applying the stash
            ${git}/bin/git restore --source="$ref" .
            # restore untracked files, too. could fail with no files
            if [ "$(git show --numstat --format=oneline "$ref^3" | wc -l)" -gt 1 ]; then
              ${git}/bin/git restore --overlay --source="$ref^3" .
            fi
            ${git}/bin/git stash drop "$ref"
          }
          case "$_arg_mode" in
            basic)
              case "$_arg_hook" in
                pre-commit)
                  # To be able to automatically add only changes from postgrest-style to the staging area,
                  # we need to run postgrest-style twice. Otherwise we'd risk merge conflicts when popping
                  # the stash afterwards.
                  ${style}/bin/postgrest-style
                  stash="postgrest-git-hooks-$RANDOM"
                  ${git}/bin/git stash push --include-untracked --keep-index -m "$stash"
                  if [ "$(git stash list --grep $stash)" ]; then
                    # Only create the stash pop trap, if we actually created a stash.
                    # Otherwise stash pop will cause havoc.
                    trap 'restore "$stash"' EXIT
                  fi
                  ${style}/bin/postgrest-style
                  ${git}/bin/git add .
                  ;;
                pre-push)
                  # Create a clean working tree without any uncomitted changes.
                  ${withTools.withGit} HEAD ${style}/bin/postgrest-lint
                  ;;
              esac
              ;;
            full)
              case "$_arg_hook" in
                pre-commit)
                  # To be able to automatically add only changes from postgrest-style to the staging area,
                  # we need to run postgrest-style twice. Otherwise we'd risk merge conflicts when popping
                  # the stash afterwards.
                  ${style}/bin/postgrest-style
                  stash="postgrest-git-hooks-$RANDOM"
                  ${git}/bin/git stash push --include-untracked --keep-index -m "$stash"
                  if [ "$(git stash list --grep $stash)" ]; then
                    # Only create the stash pop trap, if we actually created a stash.
                    # Otherwise stash pop will cause havoc.
                    trap 'restore "$stash"' EXIT
                  fi
                  ${style}/bin/postgrest-style
                  ${git}/bin/git add .
                  ${style}/bin/postgrest-lint
                  ;;
                pre-push)
                  # Create a clean working tree without any uncomitted changes.
                  ${withTools.withGit} HEAD ${check}
                  ;;
              esac
              ;;
          esac
        fi
      '';
  dumpMinimalImports =
    checkedShellScript
      {
@@ -129,10 +281,10 @@ let
      {
        name = "postgrest-hsie-graph-modules";
        docs = "Create a PNG graph of modules imported within the codebase.";
-        args = [ "ARG_OPTIONAL_SINGLE([outfile], [o], [Output filename], [postgrest-module-graph.png])" ];
+        args = [ "ARG_POSITIONAL_SINGLE([outfile], [Output filename])" ];
      }
      ''
-        ${hsie} graph-modules src/library src/executable | ${graphviz}/bin/dot -Tpng -o "$_arg_outfile"
+        ${hsie} graph-modules main src | ${graphviz}/bin/dot -Tpng -o "$_arg_outfile"
      '';
  hsieGraphSymbols =
@@ -243,6 +395,7 @@ buildToolbox
    inherit
      check
      dumpMinimalImports
      gitHooks
      hsieGraphModules
      hsieGraphSymbols
      hsieMinimalImports
@@ -43,7 +43,7 @@ let
        }
        if [ "$_arg_language" == "" ]; then
-          # clean previous build, otherwise some errors might be suppressed
+          # clean previous build, otherwise some errors might be supressed
          rm -rf "../.docs-build/html/default"
          if [ -d languages ]; then
@@ -54,7 +54,7 @@ let
          build html "../.docs-build/html/default"
        else
-          # clean previous build, otherwise some errors might be suppressed
+          # clean previous build, otherwise some errors might be supressed
          rm -rf "../.docs-build/html/$_arg_language"
          # update and build specific locale, can be used to create new locale
@@ -12,39 +12,42 @@
 # from an array
 import time
 import argparse
 import sys
 import random
-import jwcrypto.jwt as jwt
+import jwt
 import jwcrypto.jwk as jwk
 from typing import Optional
 from pathlib import Path
 URL = "http://postgrest"
-secret_key = "reallyreallyreallyreallyverysafe"
+secret_key = b"reallyreallyreallyreallyverysafe"
 key = jwk.JWK.generate(kty="RSA", size=4096)
 private_key = jwt.algorithms.RSAAlgorithm.from_jwk(key.export_private())
 public_key = key.export_public()
-def generate_target(
+def generate_jwt(now: int, exp_inc: Optional[int], is_hs: bool) -> str:
-    now: int,
+    """Generate an HS256 or RS256 JWT"""
-    key: jwt.JWK,
+    payload = {
 ) -> list[str]:
    """Generate a target using an HS256 or RS256 JWT"""
    headers = {
        "sub": f"user_{random.getrandbits(32)}",
        "iat": now,
    }
    claims = {
        "role": "postgrest_test_author",
    }
-    headers["alg"] = "RS256" if key.get("kty") == "RSA" else "HS256"
+    if exp_inc is not None:
        payload["exp"] = now + exp_inc
-    token = jwt.JWT(headers, claims)
+    k = secret_key if is_hs else private_key
-    token.make_signed_token(key)
+    alg = "HS256" if is_hs else "RS256"
    return jwt.encode(payload, k, alg)
-    return [
+
-        f"OPTIONS {URL}/authors_only?{headers["alg"]}",
+def append_targets(lines: list[str], token: str):
-        f"Authorization: Bearer {token.serialize()}",
+    lines.append(f"OPTIONS {URL}/authors_only")
-        "",  # blank line to separate requests
+    lines.append(f"Authorization: Bearer {token}")
-    ]
+    lines.append("")  # blank line to separate requests
 def main():
@@ -52,47 +55,91 @@ def main():
        description="Generate Vegeta targets with unique JWTs"
    )
    parser.add_argument(
-        "generated_path",
+        "output",
-        metavar="GENERATED_PATH",
+        help="Path to write the generated targets file",
-        help="Path to write the generated files",
+    )
    parser.add_argument(
        "--worst",
        dest="worst",
        action=argparse.BooleanOptionalAction,
        default=False,
        help="Generate worst case targets for a JWT cache",
    )
    parser.add_argument(
        "--rsa",
        dest="jwk_path",
        metavar="JWK_PATH",
        type=Path,
        default=None,
        help="Path for generating a RSA JWK file to sign tokens with",
    )
    args = parser.parse_args()
-    targets_path = args.generated_path / "gen_targets.http"
+    is_hs = args.jwk_path is None
-    hs = jwt.JWK.from_password(secret_key)
+    nsamples = 1000
-    rsa = jwt.JWK.generate(kty="RSA", size=4096)
+    if is_hs:
        ntargets = 200000
    else:
        # The asymmetric targets take too long to compute so we reduce them
        ntargets = 50000
-    jwks = jwt.JWKSet()
+    if not is_hs:
-    jwks.add(hs)
+        try:
-    jwks.add(rsa)
+            with open(args.jwk_path, "w") as jwk:
-
+                jwk.write(public_key)
-    jwks_path = args.generated_path / "gen_jwks.json"
+                print(f"Created {args.jwk_path} file containing the RSA JWK")
-
+        except IOError as e:
-    # Technically, this exports the private keys, because HS does not have the concept
+            print(f"Error writing to {args.jwk_path}: {e}", file=sys.stderr)
-    # of a public key. This is not a problem for tests, though, PostgREST can verify
+            sys.exit(1)
    # tokens with the private key just as well.
    jwks_path.write_text(jwks.export())
    print(f"Created JWKSet on {jwks_path}")
    ntargets = 1000
    print(f"Generating {ntargets} targets...")
-    now = int(time.time())
+    start_time = time.time()
    now = int(start_time)
    lines = []
    # We want to ensure 401 Unauthorized responses don't happen during
    # JWT validation, this can happen when the jwt `exp` is too short.
    # At the same time, we want to ensure the `exp` is not too big,
    # so expires will occur and postgREST needs to
    # clean cached expired JWTs
    if args.worst:
        # estimated time takes to build and run postgrest itself
        build_run_postgrest_time = 2
        # estimated time it takes to generate the targets file
        # the division numbers are tuned by hand
        if is_hs:  # hs generation is much faster
            gen_time = ntargets // 66666
        else:  # asymmetric is slower so the time is higher
            gen_time = ntargets // 220
        # estimated exp time so some JWTs will expire
        inc = build_run_postgrest_time + gen_time
        for i in range(ntargets):
-        target = generate_target(now, hs if i % 2 == 0 else rsa)
+            token = generate_jwt(now, inc + i // 1000, is_hs)
-        lines.extend(target)
+            append_targets(lines, token)
-    with open(targets_path, "w") as f:
+    else:
        tokens = [generate_jwt(now, None, is_hs) for _ in range(nsamples)]
        for i in range(ntargets):
            token = random.choice(tokens)
            append_targets(lines, token)
    try:
        with open(args.output, "w") as f:
            f.write("\n".join(lines))
    except IOError as e:
        print(f"Error writing to {args.output}: {e}", file=sys.stderr)
        sys.exit(1)
    elapsed = time.time() - start_time
    print(f"Created {ntargets} targets", end=" ")
    print(f"in {args.output} ({elapsed:.2f}s)")
 if __name__ == "__main__":
@@ -1,11 +1,7 @@
 { buildToolbox
 , checkedShellScript
 , git
 , jq
 , libfaketime
 , python3
 , python3Packages
 , runCommand
 , vegeta
 , withTools
 , writers
@@ -22,8 +18,6 @@ let
        ];
      }
      ''
        echo "Starting vegeta loadtest..."
        # ARG_USE_ENV only adds defaults or docs for environment variables
        # We manually implement a required check here
        # See also: https://github.com/matejak/argbash/issues/80
@@ -46,75 +40,86 @@ let
        docs = "Run the vegeta loadtests with PostgREST.";
        args = [
          "ARG_OPTIONAL_SINGLE([output], [o], [Filename to dump json output to], [./loadtest/result.bin])"
          "ARG_OPTIONAL_SINGLE([testdir], [t], [Directory to load tests and fixtures from], [./test/load])"
          "ARG_OPTIONAL_SINGLE([kind], [k], [Kind of loadtest], [mixed])"
-          "ARG_TYPE_GROUP_SET([KIND], [KIND], [kind], [mixed,jwt-cache,jwt-cache-worst])"
+          "ARG_TYPE_GROUP_SET([KIND], [KIND], [kind], [mixed,jwt-hs,jwt-hs-cache,jwt-hs-cache-worst,jwt-rsa,jwt-rsa-cache,jwt-rsa-cache-worst])"
          "ARG_OPTIONAL_SINGLE([monitor], [m], [Monitoring file], [./loadtest/result.csv])"
          "ARG_LEFTOVERS([additional vegeta arguments])"
        ];
        workingDir = "/";
      }
      ''
        # previously required settings to make this work with older branches
        export PGRST_DB_ANON_ROLE="postgrest_test_anonymous"
        export PGRST_DB_URI="postgresql://"
        export PGRST_DB_SCHEMAS="test"
        export PGRST_DB_CONFIG="false"
        export PGRST_DB_POOL="1"
        export PGRST_DB_SCHEMAS="test"
        export PGRST_DB_TX_END="rollback-allow-override"
        export PGRST_LOG_LEVEL="crit"
        export PGRST_JWT_SECRET="reallyreallyreallyreallyverysafe"
        # set previous PGRST_JWT_CACHE_MAX_LIFETIME configuration so that
        # load test works across branches
        # TODO clean once PGRST_JWT_CACHE_MAX_ENTRIES merged and released
        export PGRST_JWT_CACHE_MAX_LIFETIME="86400"
        mkdir -p "$(dirname "$_arg_output")"
        abs_output="$(realpath "$_arg_output")"
        case "$_arg_kind" in
-          jwt-cache)
+          jwt-hs)
-            export PGRST_JWT_SECRET="@${generatedTargets}/gen_jwks.json"
+            ${genTargetsHS} "$_arg_testdir"/gen_targets.http
-
+            export PGRST_JWT_CACHE_MAX_ENTRIES="0"
-            # shellcheck disable=SC2145
+            export PGRST_JWT_CACHE_MAX_LIFETIME="0"
            ${withTools.withPg} -f test/load/fixtures.sql \
            ${withTools.withPgrst} --faketime '2000-01-01 00:00:00' -m "$_arg_monitor" \
            sh -c "cd test/load && \
            ${runner} -targets ${generatedTargets}/gen_targets.http -output \"$abs_output\" \"''${_arg_leftovers[@]}\""
            ;;
-          # here we sleep purposefully to check how much memory does the schema cache consume in the final report
+          jwt-hs-cache)
-          mixed)
+            ${genTargetsHS} "$_arg_testdir"/gen_targets.http
-            # shellcheck disable=SC2145
+            ;;
-            ${withTools.withPg} -f test/load/fixtures.sql \
+
-            ${withTools.withPgrst} --timeout 2 --sleep 5 -m "$_arg_monitor" \
+          jwt-hs-cache-worst)
-            sh -c "cd test/load && \
+            ${genTargetsHS} --worst "$_arg_testdir"/gen_targets.http
-            ${runner} -targets targets.http -output \"$abs_output\" \"''${_arg_leftovers[@]}\""
+            ;;
          jwt-rsa)
            ${genTargetsHS} --rsa="$_arg_testdir"/gen_jwk.json "$_arg_testdir"/gen_targets.http
            export PGRST_JWT_CACHE_MAX_ENTRIES="0"
            export PGRST_JWT_CACHE_MAX_LIFETIME="0"
            export PGRST_JWT_SECRET="@$_arg_testdir/gen_jwk.json"
            ;;
          jwt-rsa-cache)
            ${genTargetsHS} --rsa="$_arg_testdir"/gen_jwk.json "$_arg_testdir"/gen_targets.http
            export PGRST_JWT_SECRET="@$_arg_testdir/gen_jwk.json"
            ;;
          jwt-rsa-cache-worst)
            ${genTargetsHS} --worst --rsa="$_arg_testdir"/gen_jwk.json "$_arg_testdir"/gen_targets.http
            export PGRST_JWT_SECRET="@$_arg_testdir/gen_jwk.json"
            ;;
          *)
            ;;
        esac
-        ${vegeta}/bin/vegeta report -type=text "$_arg_output"
+        if [ "$_arg_kind" == "mixed" ]; then
-
+          # shellcheck disable=SC2145
-        if [ "$_arg_kind" != "mixed" ]; then
+          ${withTools.withPg} -f "$_arg_testdir"/fixtures.sql \
-          # fail in case 401 happened on jwt loadtests
+          ${withTools.withSlowPg} \
-          unauthorized_count="$(${vegeta}/bin/vegeta report -type=json "$_arg_output" \
+          ${withTools.withPgrst} -m "$_arg_monitor" \
-            | ${jq}/bin/jq -r '.status_codes["401"] // 0')"
+          ${withTools.withSlowPgrst} \
-
+          sh -c "cd \"$_arg_testdir\" && \
-          if [ "$unauthorized_count" -gt 0 ]; then
+          ${runner} -targets targets.http -output \"$abs_output\" \"''${_arg_leftovers[@]}\""
            last_unauthorized_body="$(${vegeta}/bin/vegeta encode "$_arg_output" \
              | ${jq}/bin/jq -rn '
                  reduce inputs as $item (null;
                    if $item.code == 401 then $item else . end
                  )
                  | if . == null then
                      empty
        else
-                      (.body | @base64d)
+          # shellcheck disable=SC2145
-                    end
+          ${withTools.withPg} -f "$_arg_testdir"/fixtures.sql \
-                ')"
+          ${withTools.withPgrst} -m "$_arg_monitor" \
-
+          sh -c "cd \"$_arg_testdir\" && \
-            echo "loadtest failed: found $unauthorized_count 401 Unauthorized responses" >&2
+          ${runner} -lazy -targets gen_targets.http -output \"$abs_output\" \"''${_arg_leftovers[@]}\""
            if [ -n "$last_unauthorized_body" ]; then
              printf '%s\n' "Last 401 response body:" >&2
              printf '%s\n' "$last_unauthorized_body" >&2
        fi
-            exit 1
+        ${vegeta}/bin/vegeta report -type=text "$_arg_output"
          fi
        fi
      '';
  loadtestAgainst =
@@ -129,9 +134,6 @@ let
            Run the vegeta loadtest against every target branch and HEAD:
            - once on the every <target-#> branch
            - once in the current worktree
            Note that the Nix tooling is always taken from the HEAD branch, while the PostgREST binary is taken from the target branch.
            For a discussion on why this is set up like this, see https://github.com/PostgREST/postgrest/pull/5013#discussion_r3431508441.
          '';
        args = [
          "ARG_POSITIONAL_INF([target], [Commit-ish reference to compare with], 1)"
@@ -146,40 +148,8 @@ let
        workingDir = "/";
      }
      ''
-        # Build postgrest for every target and HEAD.
+        # run loadtest for every target
-        # Keeps a reference to the postgrest binary and faketime lib for every branch to run later.
+        for tgt in "''${_arg_target[@]}"; do
        declare -A pgrst faketime
        for tgt in "''${_arg_target[@]}" HEAD; do
          # not using withTmpDir here, because we don't want to keep the directory on error
          tmpdir="$(mktemp -d)"
          trap 'rm -rf "$tmpdir"' EXIT
          ${git}/bin/git worktree add -f "$tmpdir" "$tgt" > /dev/null
          pushd "$tmpdir" > /dev/null
          build_start=$SECONDS
          echo -n "${name}: Building postgrest (nix) on $tgt... "
          # Using lib.getBin to also make this work with older checkouts, where .bin was not a thing, yet.
          nix-build --no-out-link -E 'with import ./. {}; pkgs.lib.getBin postgrestPackage' > build.log 2>&1 || {
            echo "failed, output:"
            cat build.log
            exit 1
          }
          pgrst[$tgt]="$(nix-build --no-out-link -E 'with import ./. {}; pkgs.lib.getBin postgrestPackage')/bin/postgrest"
          # To avoid glibc mismatches with back-branches, we need to take libfaketime from the target branch.
          faketime[$tgt]="$(nix-build --no-out-link -A pkgs.libfaketime)/lib/libfaketime.so.1"
          build_end=$((SECONDS - build_start))
          printf "done in %ss.\n" "$build_end"
          popd > /dev/null
          ${git}/bin/git worktree remove -f "$tmpdir" > /dev/null
          rm -rf "$tmpdir"
        done
        # Run loadtest for every target and HEAD.
        # Running the tests is separated from building them to reduce the chances of
        # other processes skewing the results between two runs.
        for tgt in "''${_arg_target[@]}" HEAD; do
        cat << EOF
@@ -187,7 +157,12 @@ let
        EOF
-        FAKETIME_LIB="''${faketime[$tgt]}" PGRST_CMD="''${pgrst[$tgt]}" ${loadtest} -k "$_arg_kind" -m "loadtest/$tgt.csv" --output "loadtest/$tgt.bin"
+        # Runs the test files from the current working tree
        # to make sure both tests are run with the same files.
        # Save the results in the current working tree, too,
        # otherwise they'd be lost in the temporary working tree
        # created by withTools.withGit.
        ${withTools.withGit} "$tgt" ${loadtest} -k "$_arg_kind" -m "$PWD/loadtest/$tgt.csv" --output "$PWD/loadtest/$tgt.bin" --testdir "$PWD/test/load"
        cat << EOF
@@ -196,6 +171,22 @@ let
        EOF
        done
        # run loadtest once on HEAD
        cat << EOF
        Running "$_arg_kind" loadtest on HEAD...
        EOF
        ${loadtest} -k "$_arg_kind" -m "$PWD/loadtest/head.csv" --output "$PWD/loadtest/head.bin" --testdir "$PWD/test/load"
        cat << EOF
        Done running on HEAD.
        EOF
      '';
  reporter =
@@ -205,14 +196,12 @@ let
        docs = "Create a named json report for a single result file.";
        args = [
          "ARG_POSITIONAL_SINGLE([file], [Filename of result to create report for])"
          "ARG_OPTIONAL_SINGLE([percentile], [p], [Percentile to report latency for], 50)"
          "ARG_LEFTOVERS([additional vegeta arguments])"
        ];
        workingDir = "/";
      }
      ''
-        ${vegeta}/bin/vegeta encode "$_arg_file" \
+        ${vegeta}/bin/vegeta report -type=json "$_arg_file" \
          | ${jq}/bin/jq --arg percentile "$_arg_percentile" --slurp 'map(select(.url != "")) | group_by("\(.code) \(.method) \(.url)") | map({("\(.[0].code) \(.[0].method) \(.[0].url)" | sub("http://postgrest";"")): map(.latency) | sort | .[(length-1) * ($percentile | tonumber) / 100 | floor] / 10e3 }) | .[]' \
          | ${jq}/bin/jq --arg branch "$(basename "$_arg_file" .bin)" '. + {branch: $branch}'
      '';
@@ -225,31 +214,12 @@ let
        import sys
        import pandas as pd
        def evaluate_change(df):
            try:
                return ((df['HEAD'] / df['main'] - 1) * 100) \
                  .map(lambda r: "{icon} {ratio:.1f} %".format(
                    ratio=r,
                    # Hardcoded failure threshold for CI is 5% here.
                    icon="" if r < 5 else ":x:"
                  ))
            except KeyError:
                return None
        pd.read_json(sys.stdin) \
-          .rename(columns={'latency': sys.argv[1]}) \
+          .set_index('param') \
-          .set_index(sys.argv[1]) \
+          .drop(['branch', 'earliest', 'end', 'latest']) \
-          .drop(['branch']) \
+          .fillna("") \
          .convert_dtypes() \
-          .assign(change=evaluate_change) \
+          .to_markdown(sys.stdout, floatfmt='.0f')
          .to_markdown(
            sys.stdout,
            floatfmt='.1f',
            colglobalalign='right',
            colalign=('left',)
          )
      '';
@@ -260,46 +230,32 @@ let
        docs = "Create a report of all loadtest reports as markdown.";
        args = [
          "ARG_OPTIONAL_SINGLE([group], [g], [Marker to group results])"
          "ARG_OPTIONAL_SINGLE([percentile], [p], [Percentile to report latency for], 50)"
        ];
        workingDir = "/";
      }
      ''
-        echo -e "## Loadtest results $_arg_group (P$_arg_percentile)\n"
+        marker=''${_arg_group:+"($_arg_group)"}
-        find loadtest -type f -iname '*.bin' -exec ${reporter} -p "$_arg_percentile" {} \; \
+        echo -e "## Loadtest results $marker\n"
          | ${jq}/bin/jq '[paths(scalars) as $path | {latency: $path | join("."), (.branch): getpath($path)}]' \
          | ${jq}/bin/jq --slurp 'flatten | group_by(.latency) | map(add)' \
          | ${toMarkdown} "P$_arg_percentile latency [μs]"
      '';
-  report-load =
+        find loadtest -type f -iname '*.bin' -exec ${reporter} {} \; \
-    checkedShellScript
+          | ${jq}/bin/jq '[paths(scalars) as $path | {param: $path | join("."), (.branch): getpath($path)}]' \
-      {
+          | ${jq}/bin/jq --slurp 'flatten | group_by(.param) | map(add)' \
-        name = "postgrest-loadtest-report-load";
+          | ${toMarkdown}
-        docs = "Create a report of all CPU/MEM usage as markdown.";
+
-        args = [
+        echo -e "\n\n## Loadtest elapsed seconds vs CPU/MEM usage $marker\n"
          "ARG_OPTIONAL_SINGLE([group], [g], [Marker to group results])"
        ];
        workingDir = "/";
      }
      ''
        echo -e "\n\n## Loadtest elapsed seconds vs CPU/MEM usage $_arg_group\n"
        find loadtest -type f -iname '*.csv' \
          | sort -m \
          | ${mergeMonitorResults}
      '';
-  generatedTargets =
+  genTargetsHS =
-    runCommand "postgrest-loadtest-targets"
+    writers.writePython3 "postgrest-gen-loadtest-targets-hs"
      {
-        nativeBuildInputs = [ (python3.withPackages (pyps: [ pyps.jwcrypto ])) ];
+        libraries = [ python3Packages.pyjwt python3Packages.jwcrypto ];
      }
-      ''
+      (builtins.readFile ./generate_targets.py);
        mkdir -p "$out"
        ${libfaketime}/bin/faketime '2000-01-01 00:00:00' python3 ${./generate_targets.py} "$out"
      '';
  mergeMonitorResults =
    writers.writePython3 "postgrest-merge-monitor-results"
@@ -310,5 +266,5 @@ let
 in
 buildToolbox {
  name = "postgrest-loadtest";
-  tools = { inherit loadtest loadtestAgainst report report-load; };
+  tools = { inherit loadtest loadtestAgainst report; };
 }
@@ -17,7 +17,7 @@ let
        nix flake update
        echo "# This file is auto-generated by postgrest-nixpkgs-upgrade" > docs/requirements.txt
-        cat "$(nix-build --no-out-link -A docs.requirements)" >> docs/requirements.txt
+        cat "$(nix-build -A docs.requirements)" >> docs/requirements.txt
      '';
 in
@@ -7,6 +7,7 @@ let
      {
        name = "postgrest-release";
        docs = "Patch postgrest.cabal, CHANGELOG.md, commit and push all in one go.";
        args = [ "ARG_OPTIONAL_BOOLEAN([major], [m], [Bump to new major version (only applies on main branch).])" ];
        workingDir = "/";
      }
      ''
@@ -19,6 +20,7 @@ let
        git diff --exit-code HEAD postgrest.cabal > /dev/null
        trap "" ERR
        # TODO: Support C+D bumps when implementing hackage releases
        bump () {
          current_version="$(grep -oP '^version:\s*\K.*' postgrest.cabal)"
          # shellcheck disable=SC2034
@@ -45,10 +47,7 @@ let
          echo "Updating docs/conf.py ..."
          sed -i -E "s/^(version = ).*$/\1\"$new_docs_version\"/" docs/conf.py > /dev/null
-          echo "Updating Haskell source file links ..."
+          git add postgrest.cabal docs/conf.py > /dev/null
          sed -i -E "s#(github\.com/PostgREST/postgrest/blob)/main/#\1/$new_version/#g" docs/explanations/architecture.rst
          git add postgrest.cabal docs/conf.py docs/explanations/architecture.rst > /dev/null
        }
        today_date_for_changelog="$(date '+%Y-%m-%d')"
@@ -69,7 +68,7 @@ let
          bump devel
          # The order of operations is important here:
-          # - bump devel is run and $A is updated to the new version
+          # - bump devel is run and $A is upated to the new version
          # - the branch is created with the new A, but the commit before the devel bump
          # - the devel bump is committed
          git branch "v$A"
@@ -3,13 +3,13 @@
 , buildToolbox
 , checkedShellScript
 , deadnix
 , fd
 , git
 , hlint
 , hsie
 , nixpkgs-fmt
 , python3Packages
 , ruff
 , silver-searcher
 , statix
 , stylish-haskell
 , writeText
@@ -21,27 +21,27 @@ let
        name = "postgrest-style";
        docs = "Automatically format Haskell, Nix and Python files.";
        workingDir = "/";
        withTmpDir = true;
      }
      ''
        # Format Nix files
        ${statix}/bin/statix fix
-        ${nixpkgs-fmt}/bin/nixpkgs-fmt .
+        ${nixpkgs-fmt}/bin/nixpkgs-fmt . > /dev/null 2> /dev/null
        # Format Haskell files
-        ${fd}/bin/fd '\.l?hs$' \
+        # --vimgrep fixes a bug in ag: https://github.com/ggreer/the_silver_searcher/issues/753
        ${silver-searcher}/bin/ag -l --vimgrep -g '\.l?hs$' . \
          | xargs ${stylish-haskell}/bin/stylish-haskell -i
        # Format Python files
-        TMPDIR="$tmpdir" ${black}/bin/black .
+        ${black}/bin/black . 2> /dev/null
      '';
-  # Script to check whether any uncommitted changes result from postgrest-style
+  # Script to check whether any uncommited changes result from postgrest-style
  styleCheck =
    checkedShellScript
      {
        name = "postgrest-style-check";
-        docs = "Check whether postgrest-style results in any uncommitted changes.";
+        docs = "Check whether postgrest-style results in any uncommited changes.";
        workingDir = "/";
      }
      ''
@@ -82,17 +82,18 @@ let
        # ruff has gaps in scanning for unused code, so we use vulture
        echo "Scanning python files for unused code..."
-        ${fd}/bin/fd '\.l?py$' \
+        ${silver-searcher}/bin/ag -l --vimgrep -g '\.l?py$' . \
-          | xargs ${python3Packages.vulture}/bin/vulture --exclude docs/conf.py --min-confidence 80
+          | xargs ${python3Packages.vulture}/bin/vulture --exclude docs/conf.py
        echo "Linting python files..."
        ${ruff}/bin/ruff check .
        echo "Checking consistency of import aliases in Haskell code..."
-        ${hsie} check-aliases src/library src/executable
+        ${hsie} check-aliases main src
        echo "Linting Haskell files..."
-        ${fd}/bin/fd '\.l?hs$' \
+        # --vimgrep fixes a bug in ag: https://github.com/ggreer/the_silver_searcher/issues/753
        ${silver-searcher}/bin/ag -l --vimgrep -g '\.l?hs$' . \
          | xargs ${hlint}/bin/hlint --hint=${hlintConfig}
      '';
@@ -7,6 +7,7 @@
 , glibcLocales ? null
 , gnugrep
 , hpc-codecov
 , hostPlatform
 , jq
 , lib
 , nginx
@@ -55,6 +56,8 @@ let
        withEnv = postgrest.env;
      }
      ''
        # This makes nix-env -iA tests.doctests.bin work.
        export NIX_GHC=${postgrest.env.NIX_GHC}
        ${cabal-install}/bin/cabal v2-run ${devCabalOptions} test:doctests
      '';
@@ -159,7 +162,7 @@ let
      }
      (
        # required for `hpc markup` in CI; glibcLocales is not available e.g. on Darwin
-        lib.optionalString (stdenv.isLinux && stdenv.hostPlatform.libc == "glibc") ''
+        lib.optionalString (stdenv.isLinux && hostPlatform.libc == "glibc") ''
          export LOCALE_ARCHIVE="${glibcLocales}/lib/locale/locale-archive"
        '' +
@@ -1,25 +1,20 @@
 { buildToolbox
 , checkedShellScript
 , curl
 , git
 , lib
 , libfaketime
 , postgresqlVersions
 , postgrest
 , python3Packages
 , slocat
 , writeText
 , writers
 }:
 let
  withTmpDb =
-    { name, postgresql, config ? "" }:
+    { name, postgresql }:
    let
      commandName = "postgrest-with-${name}";
      postgresqlConf = writeText "postgresql.conf" ("
        autovacuum = false
        listen_addresses = ''
        log_statement = all
        shared_preload_libraries=pg_stat_statements
      " + config);
    in
    checkedShellScript
      {
@@ -78,10 +73,6 @@ let
          TZ=$PGTZ initdb --no-locale --encoding=UTF8 --nosync -U postgres --auth=trust \
            >> "$setuplog"
          # Append our own config to the one initdb created to avoid replacing
          # default values created by the latter.
          cat ${postgresqlConf} >> "$tmpdir/db/postgresql.conf"
          log "Starting the database cluster..."
          # Instead of listening on a local port, we will listen on a unix domain socket.
@@ -90,7 +81,7 @@ let
          # On MacOS, it's 104 chars
          # See: https://serverfault.com/questions/641347/check-if-a-path-exceeds-maximum-for-unix-domain-socket
-          pg_ctl -l "$tmpdir/db.log" -w start -o "-F -c hba_file=$HBA_FILE -k $PGHOST " \
+          pg_ctl -l "$tmpdir/db.log" -w start -o "-F -c listen_addresses=\"\" -c hba_file=$HBA_FILE -k $PGHOST -c log_statement=\"all\" " \
            >> "$setuplog"
          log "Creating a minimally privileged $PGUSER connection role..."
@@ -115,8 +106,7 @@ let
            log "Starting replica on $replica_host"
-            # We set a low max_standby_streaming_delay to make the replication conflict fail faster in tests (otherwise it waits for the default 30s)
+            pg_ctl -D "$replica_dir" -l "$replica_dblog" -w start -o "-F -c listen_addresses=\"\" -c hba_file=$HBA_FILE -k $replica_host -c log_statement=\"all\" " \
            pg_ctl -D "$replica_dir" -l "$replica_dblog" -w start -o "-F -c hba_file=$HBA_FILE -k $replica_host -c max_standby_streaming_delay=\"3s\" " \
              >> "$setuplog"
            >&2 echo "${commandName}: Replica enabled. You can connect to it with: psql 'postgres:///$PGDATABASE?host=$replica_host' -U postgres"
@@ -127,7 +117,7 @@ let
            export PGRST_DB_URI="postgres:///$PGDATABASE?host=$PGREPLICAHOST,$PGHOST"
          fi
-          # shellcheck disable=SC2329
+          # shellcheck disable=SC2317
          stop () {
            log "Stopping the database cluster..."
            pg_ctl stop --mode=immediate >> "$setuplog"
@@ -142,12 +132,9 @@ let
        fi
        if test "$_arg_fixtures"; then
-          load_start=$SECONDS
+          log "Loading fixtures under the postgres role..."
          >&2 printf "${commandName}: Loading fixtures under the postgres role..."
          psql -U postgres -v PGUSER="$PGUSER" -v ON_ERROR_STOP=1 -f "$_arg_fixtures" >> "$setuplog"
-          psql -U postgres -v ON_ERROR_STOP=1 -c "VACUUM ANALYZE;" >> "$setuplog"
+          log "Done. Running command..."
          load_end=$((SECONDS - load_start))
          >&2 printf " done in %ss. Running command...\n" "$load_end"
        fi
        ("$_arg_command" "''${_arg_leftovers[@]}")
@@ -196,6 +183,134 @@ let
  withPg = withTmpDb (builtins.head postgresqlVersions);
  withSlowPg =
    checkedShellScript
      {
        name = "postgrest-with-slow-pg";
        docs = "Run the given command with simulated high latency postgresql";
        args =
          [
            "ARG_POSITIONAL_SINGLE([command], [Command to run])"
            "ARG_LEFTOVERS([command arguments])"
            "ARG_USE_ENV([PGHOST], [], [PG host (socket name)])"
            "ARG_USE_ENV([PGDELAY], [0ms], [extra PG latency (duration)])"
          ];
        positionalCompletion = "_command";
        workingDir = "/";
        redirectTixFiles = false;
        withTmpDir = true;
      }
      ''
        delay="''${PGDELAY:-0ms}"
        echo "delaying data to/from postgres by $delay"
        REALPGHOST="$PGHOST"
        export PGHOST="$tmpdir/socket"
        mkdir -p "$PGHOST"
        ${slocat}/bin/slocat -delay "$delay" -src "$PGHOST/.s.PGSQL.5432" -dst "$REALPGHOST/.s.PGSQL.5432" &
        SLOCAT_PID=$!
        # shellcheck disable=SC2317
        stop_slocat() {
          kill "$SLOCAT_PID" || true
          wait "$SLOCAT_PID" || true
        }
        trap stop_slocat EXIT
        sleep 1 # should wait for socket file to appear instead
        ("$_arg_command" "''${_arg_leftovers[@]}")
      '';
  withSlowPgrst =
    checkedShellScript
      {
        name = "postgrest-with-slow-postgrest";
        docs = "Run the given command with simulated high latency postgrest";
        args =
          [
            "ARG_POSITIONAL_SINGLE([command], [Command to run])"
            "ARG_LEFTOVERS([command arguments])"
            "ARG_USE_ENV([PGRST_SERVER_UNIX_SOCKET], [], [PostgREST host (socket name)])"
            "ARG_USE_ENV([PGRST_DELAY], [0ms], [extra PostgREST latency (duration)])"
          ];
        positionalCompletion = "_command";
        workingDir = "/";
        redirectTixFiles = false;
        withTmpDir = true;
      }
      ''
        delay="''${PGRST_DELAY:-0ms}"
        echo "delaying data to/from PostgREST by $delay"
        REAL_PGRST_SERVER_UNIX_SOCKET="$PGRST_SERVER_UNIX_SOCKET"
        export PGRST_SERVER_UNIX_SOCKET="$tmpdir/postgrest.socket"
        ${slocat}/bin/slocat -delay "$delay" -src "$PGRST_SERVER_UNIX_SOCKET" -dst "$REAL_PGRST_SERVER_UNIX_SOCKET" &
        SLOCAT_PID=$!
        # shellcheck disable=SC2317
        stop_slocat() {
          kill "$SLOCAT_PID" || true
          wait "$SLOCAT_PID" || true
        }
        trap stop_slocat EXIT
        sleep 1 # should wait for socket file to appear instead
        ("$_arg_command" "''${_arg_leftovers[@]}")
      '';
  withGit =
    let
      name = "postgrest-with-git";
    in
    checkedShellScript
      {
        inherit name;
        docs =
          ''
            Create a new worktree of the postgrest repo in a temporary directory and
            check out <commit>, then run <command> with arguments inside the temporary folder.
          '';
        args =
          [
            "ARG_POSITIONAL_SINGLE([commit], [Commit-ish reference to run command with])"
            "ARG_POSITIONAL_SINGLE([command], [Command to run])"
            "ARG_LEFTOVERS([command arguments])"
          ];
        positionalCompletion =
          ''
            if test "$prev" == "${name}"; then
              __gitcomp_nl "$(__git_refs)"
            else
              _command_offset 2
            fi
          '';
        workingDir = "/";
      }
      ''
        # not using withTmpDir here, because we don't want to keep the directory on error
        tmpdir="$(mktemp -d)"
        trap 'rm -rf "$tmpdir"' EXIT
        ${git}/bin/git worktree add -f "$tmpdir" "$_arg_commit" > /dev/null
        cd "$tmpdir"
        ("$_arg_command" "''${_arg_leftovers[@]}")
        ${git}/bin/git worktree remove -f "$tmpdir" > /dev/null
      '';
  legacyConfig =
    writeText "legacy.conf"
      ''
        # Using this config file to support older postgrest versions for `postgrest-loadtest-against`
        db-uri="$(PGRST_DB_URI)"
        db-schema="$(PGRST_DB_SCHEMAS)"
        db-anon-role="$(PGRST_DB_ANON_ROLE)"
        db-pool="$(PGRST_DB_POOL)"
        server-unix-socket="$(PGRST_SERVER_UNIX_SOCKET)"
        log-level="$(PGRST_LOG_LEVEL)"
      '';
  waitForPgrstReady =
    checkedShellScript
      {
@@ -237,23 +352,15 @@ let
      '';
  withPgrst =
    let
      commandName = "postgrest-with-pgrst";
    in
    checkedShellScript
      {
-        name = commandName;
+        name = "postgrest-with-pgrst";
        docs = "Build and run PostgREST and run <command> with PGRST_SERVER_UNIX_SOCKET set.";
        args =
          [
            "ARG_POSITIONAL_SINGLE([command], [Command to run])"
            "ARG_LEFTOVERS([command arguments])"
            "ARG_OPTIONAL_SINGLE([faketime], [f], [Fake the system time when starting PostgREST. This is useful to test expiry of JWT, for example in loadtests])"
            "ARG_OPTIONAL_SINGLE([monitor], [m], [Enable CPU and memory monitoring of the PostgREST process and output to the designated file as markdown])"
            "ARG_OPTIONAL_SINGLE([timeout], [t], [Maximum time to wait for PostgREST to be ready], [5])"
            "ARG_OPTIONAL_SINGLE([sleep], [s],   [Sleep time after PostgREST is ready, this is useful for monitoring])"
            "ARG_USE_ENV([FAKETIME_LIB], [${libfaketime}/lib/libfaketime.so.1], [Faketime Library to preload])"
            "ARG_USE_ENV([PGRST_CMD], [postgrest-run], [PostgREST executable to run])"
          ];
        positionalCompletion = "_command";
        workingDir = "/";
@@ -263,25 +370,30 @@ let
      ''
        export PGRST_SERVER_UNIX_SOCKET="$tmpdir"/postgrest.socket
-        if [ "''${PGRST_CMD}" == "postgrest-run" ]; then
+        rm -f result
-          build_start=$SECONDS
+        if [ -z "''${PGRST_BUILD_CABAL:-}" ]; then
-          echo -n "${commandName}: Building postgrest (cabal)... "
+          echo -n "Building postgrest (nix)... "
-          postgrest-build
+          # Using lib.getBin to also make this work with older checkouts, where .bin was not a thing, yet.
-          build_end=$((SECONDS - build_start))
+          nix-build -E 'with import ./. {}; pkgs.lib.getBin postgrestPackage' > "$tmpdir"/build.log 2>&1 || {
-          printf "done in %ss.\n" "$build_end"
+            echo "failed, output:"
-        fi
+            cat "$tmpdir"/build.log
-
+            exit 1
-        ver=$($PGRST_CMD --version)
+          }
-
+          PGRST_CMD=$(echo ./result*/bin/postgrest)
        echo -n "${commandName}: Starting $ver... "
        if [[ -n "$_arg_faketime" ]]; then
          LD_PRELOAD="$FAKETIME_LIB" FAKETIME="$_arg_faketime" "$PGRST_CMD" > "$tmpdir"/run.log 2>&1 &
        else
-          $PGRST_CMD > "$tmpdir"/run.log 2>&1 &
+          echo -n "Building postgrest (cabal)... "
          postgrest-build
          PGRST_CMD=postgrest-run
        fi
        echo "done."
        ver=$($PGRST_CMD ${legacyConfig} --version)
        echo -n "Starting $ver... "
        $PGRST_CMD ${legacyConfig} > "$tmpdir"/run.log 2>&1 &
        pid=$!
-        # shellcheck disable=SC2329
+        # shellcheck disable=SC2317
        cleanup() {
          # Send INT to all postgrest processes.
          # Workaround to trigger dumping postgrest.prof for postgrest-profiled-run
@@ -295,25 +407,17 @@ let
        }
        trap cleanup EXIT
-        wait_start=$SECONDS
+        timeout -s TERM 5 ${waitForPgrstReady} || {
        timeout -s TERM "$_arg_timeout" ${waitForPgrstReady} || {
          echo "timed out, output:"
          cat "$tmpdir"/run.log
          exit 1
        }
-        wait_duration=$((SECONDS - wait_start))
+        echo "done."
        printf "done in %ss.\n" "$wait_duration"
        echo "${commandName}: You can tail the server logs with: tail -f $tmpdir/run.log"
        if [[ -n "$_arg_monitor" ]]; then
          ${monitorPid} "$pid" > "$_arg_monitor" &
        fi
        if [[ -n "$_arg_sleep" ]]; then
          sleep "$_arg_sleep"
        fi
        ("$_arg_command" "''${_arg_leftovers[@]}")
      '';
@@ -329,8 +433,11 @@ buildToolbox
  name = "postgrest-with";
  tools = {
    inherit
      withGit
      withPgAll
-      withPgrst;
+      withPgrst
      withSlowPg
      withSlowPgrst;
  } // builtins.listToAttrs (
    # Create a `postgrest-with-pg-` for each PostgreSQL version
    builtins.map (pg: { inherit (pg) name; value = withTmpDb pg; }) postgresqlVersions
@@ -1,27 +1,28 @@
 cabal-version:      3.0
 name:               postgrest
-version:            17
+version:            14.17
 synopsis:           REST API for any Postgres database
 description:        Reads the schema of a PostgreSQL database and creates RESTful routes
                    for tables, views, and functions, supporting all HTTP methods that security
                    permits.
 license:            MIT
 license-file:       LICENSE
-author:             Joe Nelson, Adam Baker, Steve Chavez, Wolfgang Walther
+author:             Joe Nelson, Adam Baker, Steve Chavez
 maintainer:         Steve Chavez <stevechavezast@gmail.com>
 category:           Executable, PostgreSQL, Network APIs
 homepage:           https://postgrest.org
 bug-reports:        https://github.com/PostgREST/postgrest/issues
 build-type:         Simple
 extra-source-files: CHANGELOG.md
 cabal-version:      >= 1.10
 tested-with:
    -- nix
    GHC == 9.4.8
    -- cabal on Ubuntu
    -- stack on FreeBSD, MacOS, Ubuntu, Windows
-  , GHC == 9.10.3
+  , GHC == 9.6.7
    -- cabal on Ubuntu
-    -- nix
+  , GHC == 9.8.4
  , GHC == 9.12.3
 source-repository head
  type:     git
@@ -38,16 +39,13 @@ flag hpc
  description: Enable HPC (dev only)
 library
-  default-language:   GHC2021
+  default-language:   Haskell2010
  default-extensions: OverloadedStrings
                      NoImplicitPrelude
-  hs-source-dirs:     src/library
+  hs-source-dirs:     src
  exposed-modules:    PostgREST.Admin
                      PostgREST.App
                      PostgREST.AppState
                      PostgREST.AppState.Pool
                      PostgREST.AppState.Reload
                      PostgREST.AppState.Types
                      PostgREST.Auth
                      PostgREST.Auth.Jwt
                      PostgREST.Auth.JwtCache
@@ -57,7 +55,6 @@ library
                      PostgREST.Client
                      PostgREST.Config
                      PostgREST.Config.Database
                      PostgREST.Debounce
                      PostgREST.Config.JSPath
                      PostgREST.Config.PgVersion
                      PostgREST.Config.Proxy
@@ -69,10 +66,9 @@ library
                      PostgREST.SchemaCache.Representations
                      PostgREST.SchemaCache.Table
                      PostgREST.Error
-                      PostgREST.Error.Types
+                      PostgREST.Listener
                      PostgREST.Logger
                      PostgREST.MainTx
                      PostgREST.Logger.Apache
                      PostgREST.MediaType
                      PostgREST.Metrics
                      PostgREST.Network
@@ -85,7 +81,6 @@ library
                      PostgREST.Plan
                      PostgREST.Plan.CallPlan
                      PostgREST.Plan.MutatePlan
                      PostgREST.Plan.Negotiate
                      PostgREST.Plan.ReadPlan
                      PostgREST.Plan.Types
                      PostgREST.RangeQuery
@@ -101,36 +96,31 @@ library
                      PostgREST.Response.Performance
                      PostgREST.TimeIt
                      PostgREST.Version
-  build-depends:      base                      >= 4.9 && < 4.22
+  build-depends:      base                      >= 4.9 && < 4.20
                    , HTTP                      >= 4000.3.7 && < 4000.5
-                    , Ranged-sets               >= 0.3 && < 0.6
+                    , Ranged-sets               >= 0.3 && < 0.5
                    , aeson                     >= 2.0.3 && < 2.3
                    , aeson-jsonpath            >= 0.4.2 && < 0.5
                    , auto-update               >= 0.2.7 && < 0.3
                    , base64-bytestring         >= 1 && < 1.3
                    , bytestring                >= 0.10.8 && < 0.13
                    , case-insensitive          >= 1.2 && < 1.3
                    , cassava                   >= 0.4.5 && < 0.6
                    , configurator-pg           >= 0.2.11 && < 0.3
-                    , containers                >= 0.5.7 && < 0.8
+                    , containers                >= 0.5.7 && < 0.7
                    , cookie                    >= 0.4.2 && < 0.6
                    -- crypton 1.1.0 moved from `memory` to `ram`, which jose-jwt fails to build with right now.
                    -- should be possible to remove this once jose-jwt had a new release.
                    , crypton                   < 1.1.0
                    , directory                 >= 1.2.6 && < 1.4
                    , either                    >= 4.4.1 && < 5.1
                    , extra                     >= 1.7.0 && < 2.0
                    , fast-logger               >= 3.2.0 && < 3.3
                    , fuzzyset                  >= 0.2.4 && < 0.3
-                    , hasql                     >= 1.9 && <= 1.9.3.1
+                    , hasql                     >= 1.6.1.1 && < 1.7
-                    , hasql-dynamic-statements  >= 0.3.1 && <= 0.3.1.8
+                    , hasql-dynamic-statements  >= 0.3.1 && < 0.4
-                    , hasql-notifications       >= 0.2.4.0 && < 0.3
+                    , hasql-notifications       >= 0.2.2.2 && < 0.2.3
-                    , hasql-pool                >= 1.1 && <= 1.3.0.4
+                    , hasql-pool                >= 1.0.1 && < 1.1
-                    , hasql-transaction         >= 1.0.1 && <= 1.2.1
+                    , hasql-transaction         >= 1.0.1 && < 1.2
                    , http-client               >= 0.7.19 && < 0.8
                    , http-types                >= 0.12.2 && < 0.13
                    , insert-ordered-containers >= 0.2.2 && < 0.3
-                    , jose-jwt                  >= 0.9.6 && < 0.11
+                    , jose-jwt                  >= 0.9.6 && < 0.10
                    , lens                      >= 4.14 && < 5.4
                    , lens-aeson                >= 1.0.1 && < 1.3
                    , mtl                       >= 2.2.2 && < 2.4
@@ -139,9 +129,9 @@ library
                    , network-uri               >= 2.6.1 && < 2.8
                    , optparse-applicative      >= 0.13 && < 0.19
                    , parsec                    >= 3.1.11 && < 3.2
                    -- Technically unused, can be removed after updating to hasql >= 1.7
                    , postgresql-libpq          >= 0.10
                    , prometheus-client         >= 1.1.1 && < 1.2.0
                    , prometheus-metrics-ghc    >= 1.0.1.2 && < 1.2
                    , protolude                 >= 0.3.1 && < 0.4
                    , regex-tdfa                >= 1.2.2 && < 1.4
                    , retry                     >= 0.7.4 && < 0.10
@@ -149,16 +139,17 @@ library
                    , streaming-commons         >= 0.2.3.1 && < 0.3
                    , swagger2                  >= 2.4 && < 2.9
                    , text                      >= 1.2.2 && < 2.2
-                    , time                      >= 1.6 && < 1.15
+                    , time                      >= 1.6 && < 1.13
                    , unordered-containers      >= 0.2.8 && < 0.3
                    , unix-compat               >= 0.5.4 && < 0.8
                    , vault                     >= 0.3.1.5 && < 0.4
                    , vector                    >= 0.11 && < 0.14
                    , wai                       >= 3.2.1 && < 3.3
                    , wai-cors                  >= 0.2.5 && < 0.3
                    , wai-extra                 >= 3.1.8 && < 3.2
                    -- We already depend on wai-logger >= 2.3.7 indirectly via wai-extra,
                    -- but we want to depend on 2.4.0 which fixes 'unknownSocket' log output
-                    -- for unix sockets; this is tested in test/io/test_log.py. See
+                    -- for unix sockets; this is tested in test/io/test_io.py. See
                    -- https://github.com/kazu-yamamoto/logger/commit/3a71ca70afdbb93d4ecf0083eeba1fbbbcab3fc3
                    , wai-logger                >= 2.4.0
                    , warp                      >= 3.4.14 && < 3.5
@@ -172,7 +163,7 @@ library
                      -- -optP-Wno-nonportable-include-path
                      --   prevents build failures on case-insensitive filesystems (macos),
                      --   see https://github.com/commercialhaskell/stack/issues/3918
-  ghc-options:        -j -Werror -Wall -fwarn-identities
+  ghc-options:        -Werror -Wall -fwarn-identities
                      -fno-spec-constr -optP-Wno-nonportable-include-path
  if flag(dev)
@@ -181,27 +172,22 @@ library
      ghc-options: -fhpc -hpcdir .hpc
  else
    ghc-options: -O2
    if impl(ghc >= 9.12)
      -- Makes GHC consider cross-module specialization for polymorphic functions
      -- without explicitly needing to add INLINE, INLINABLE or SPECIALIZE pragmas.
      -- Slightly increases the binary size but improves performance considerably.
      ghc-options: -fexpose-overloaded-unfoldings -fspecialise-aggressively
  if !os(windows)
    build-depends:
      unix
 executable postgrest
-  default-language:   GHC2021
+  default-language:   Haskell2010
  default-extensions: OverloadedStrings
                      NoImplicitPrelude
-  hs-source-dirs:     src/executable
+  hs-source-dirs:     main
  main-is:            Main.hs
-  build-depends:      base                >= 4.9 && < 4.22
+  build-depends:      base                >= 4.9 && < 4.20
-                    , containers          >= 0.5.7 && < 0.8
+                    , containers          >= 0.5.7 && < 0.7
                    , postgrest
                    , protolude           >= 0.3.1 && < 0.4
-  ghc-options:        -j -threaded -rtsopts "-with-rtsopts=-N -I0 -qg"
+  ghc-options:        -threaded -rtsopts "-with-rtsopts=-N -I0 -qg"
                      -O2 -Werror -Wall -fwarn-identities
                      -fno-spec-constr -optP-Wno-nonportable-include-path
@@ -216,7 +202,7 @@ executable postgrest
 test-suite spec
  type:               exitcode-stdio-1.0
-  default-language:   GHC2021
+  default-language:   Haskell2010
  default-extensions: OverloadedStrings
                      QuasiQuotes
                      NoImplicitPrelude
@@ -226,12 +212,10 @@ test-suite spec
                      Feature.Auth.AudienceJwtSecretSpec
                      Feature.Auth.AuthSpec
                      Feature.Auth.BinaryJwtSecretSpec
                      Feature.Auth.JwtCacheSpec
                      Feature.Auth.NoAnonSpec
                      Feature.Auth.NoJwtSecretSpec
                      Feature.ConcurrentSpec
                      Feature.CorsSpec
                      Feature.HttpHeaderSpec
                      Feature.ExtraSearchPathSpec
                      Feature.NoSuperuserSpec
                      Feature.ObservabilitySpec
@@ -257,10 +241,7 @@ test-suite spec
                      Feature.Query.PgSafeUpdateSpec
                      Feature.Query.PlanSpec
                      Feature.Query.PostGISSpec
-                      Feature.Query.Preferences.HandlingSpec
+                      Feature.Query.PreferencesSpec
                      Feature.Query.Preferences.MaxAffectedSpec
                      Feature.Query.Preferences.TimezoneSpec
                      Feature.Query.PreparedStatementsSpec
                      Feature.Query.QueryLimitedSpec
                      Feature.Query.QuerySpec
                      Feature.Query.RangeSpec
@@ -276,23 +257,23 @@ test-suite spec
                      Feature.RollbackSpec
                      Feature.RpcPreRequestGucsSpec
                      SpecHelper
-  build-depends:      base              >= 4.9 && < 4.22
+  build-depends:      base              >= 4.9 && < 4.20
                    , aeson             >= 2.0.3 && < 2.3
                    , aeson-qq          >= 0.8.1 && < 0.9
                    , async             >= 2.1.1 && < 2.3
                    , base64-bytestring >= 1 && < 1.3
                    , bytestring        >= 0.10.8 && < 0.13
                    , case-insensitive  >= 1.2 && < 1.3
-                    , containers        >= 0.5.7 && < 0.8
+                    , containers        >= 0.5.7 && < 0.7
-                    , hasql-pool        >= 1.0.1 && <= 1.3.0.4
+                    , hasql-pool        >= 1.0.1 && < 1.1
-                    , hasql-transaction >= 1.0.1 && <= 1.2.1
+                    , hasql-transaction >= 1.0.1 && < 1.2
                    , heredoc           >= 0.2 && < 0.3
                    , hspec             >= 2.3 && < 2.12
                    , hspec-expectations >= 0.8.4 && < 0.9
                    , hspec-wai         >= 0.10 && < 0.12
                    , hspec-wai-json    >= 0.10 && < 0.12
                    , http-types        >= 0.12.3 && < 0.13
-                    , jose-jwt          >= 0.9.6 && < 0.11
+                    , jose-jwt          >= 0.9.6 && < 0.10
                    , lens              >= 4.14 && < 5.4
                    , lens-aeson        >= 1.0.1 && < 1.3
                    , monad-control     >= 1.0.1 && < 1.1
@@ -303,11 +284,10 @@ test-suite spec
                    , regex-tdfa        >= 1.2.2 && < 1.4
                    , scientific        >= 0.3.4 && < 0.4
                    , text              >= 1.2.2 && < 2.2
                    , time              >= 1.6 && < 1.15
                    , transformers-base >= 0.4.4 && < 0.5
                    , wai               >= 3.2.1 && < 3.3
                    , wai-extra         >= 3.0.19 && < 3.2
-  ghc-options:        -j -threaded -O0 -Werror -Wall -fwarn-identities
+  ghc-options:        -threaded -O0 -Werror -Wall -fwarn-identities
                      -fno-spec-constr -optP-Wno-nonportable-include-path
                      -fno-warn-missing-signatures
                      -fwrite-ide-info
@@ -316,7 +296,7 @@ test-suite spec
 test-suite observability
  type:               exitcode-stdio-1.0
-  default-language:   GHC2021
+  default-language:   Haskell2010
  default-extensions: OverloadedStrings
                      QuasiQuotes
                      NoImplicitPrelude
@@ -326,23 +306,23 @@ test-suite observability
                      Observation.JwtCache
                      Observation.MetricsSpec
                      Observation.SchemaCacheSpec
-  build-depends:      base              >= 4.9 && < 4.22
+  build-depends:      base              >= 4.9 && < 4.20
                    , base64-bytestring >= 1 && < 1.3
                    , bytestring        >= 0.10.8 && < 0.13
-                    , hasql-pool        >= 1.0.1 && <= 1.3.0.4
+                    , hasql-pool        >= 1.0.1 && < 1.1
-                    , hasql-transaction >= 1.0.1 && <= 1.2.1
+                    , hasql-transaction >= 1.0.1 && < 1.2
                    , hspec             >= 2.3 && < 2.12
                    , hspec-expectations >= 0.8.4 && < 0.9
                    , hspec-wai         >= 0.10 && < 0.12
                    , hspec-wai-json    >= 0.10 && < 0.12
                    , http-types        >= 0.12.3 && < 0.13
-                    , jose-jwt          >= 0.9.6 && < 0.11
+                    , jose-jwt          >= 0.9.6 && < 0.10
                    , postgrest
                    , prometheus-client >= 1.1.1 && < 1.2.0
                    , protolude         >= 0.3.1 && < 0.4
                    , text              >= 1.2.2 && < 2.2
                    , wai               >= 3.2.1 && < 3.3
-  ghc-options:        -j -threaded -O0 -Werror -Wall -fwarn-identities
+  ghc-options:        -threaded -O0 -Werror -Wall -fwarn-identities
                      -fno-spec-constr -optP-Wno-nonportable-include-path
                      -fwrite-ide-info
                      -- https://github.com/PostgREST/postgrest/issues/387
@@ -350,12 +330,15 @@ test-suite observability
 test-suite doctests
  type:               exitcode-stdio-1.0
-  default-language:   GHC2021
+  default-language:   Haskell2010
  default-extensions: OverloadedStrings
                      NoImplicitPrelude
  hs-source-dirs:     test/doc
  main-is:            Main.hs
-  build-depends:      base              >= 4.9 && < 4.22
+  build-depends:      base              >= 4.9 && < 4.20
-                    , doctest-parallel  >= 0.4
+                    , doctest           >= 0.8
                    , postgrest
                    , pretty-simple
-  ghc-options:        -j -threaded -O0 -Werror -Wall -fwarn-identities
+                    , protolude         >= 0.3.1 && < 0.4
  ghc-options:        -threaded -O0 -Werror -Wall -fwarn-identities
                      -fno-spec-constr -optP-Wno-nonportable-include-path
@@ -7,9 +7,11 @@
 # We highly recommend that use the PostgREST binary cache by installing cachix
 # (https://app.cachix.org/) and running `cachix use postgrest`.
 { docker ? false
 , postgrest ? import ./default.nix { }
 }:
 let
  postgrest =
    import ./default.nix { };
  inherit (postgrest) pkgs;
  inherit (pkgs) lib;
@@ -35,7 +37,10 @@ lib.overrideDerivation postgrest.env (
    buildInputs =
      base.buildInputs ++ [
        pkgs.cabal-install
        pkgs.cabal2nix
        pkgs.git
        pkgs.postgresql
        pkgs.update-nix-fetchgit
        postgrest.hsie.bin
      ]
      ++ toolboxes;
@@ -44,10 +49,6 @@ lib.overrideDerivation postgrest.env (
      ''
        export HISTFILE=.history
        # Bypass proxy for all hosts, it prevents HTTP client failures used in test
        # suites. See: https://github.com/PostgREST/postgrest/issues/4633 for more info
        export NO_PROXY=*
        source ${pkgs.bash-completion}/etc/profile.d/bash_completion.sh
        source ${pkgs.git}/share/git/contrib/completion/git-completion.bash
        source ${postgrest.hsie.bash-completion}
@@ -8,8 +8,10 @@ import qualified Network.Wai               as Wai
 import qualified Network.Wai.Handler.Warp  as Warp
 import Control.Monad.Extra       (whenJust)
 import Network.Socket            hiding (addrFamily)
 import Network.Socket.ByteString
-import PostgREST.AppState    (AppState, getConfig, killApp)
+import PostgREST.AppState    (AppState, getConfig, getMainThreadId)
 import PostgREST.Config      (AppConfig (..))
 import PostgREST.MediaType   (MediaType (..), toContentType)
 import PostgREST.Metrics     (metricsToText)
@@ -21,15 +23,15 @@ import qualified PostgREST.AppState as AppState
 import qualified Network.Socket as NS
 import           Protolude
-runAdmin :: AppState -> Maybe NS.Socket -> IO Bool -> Warp.Settings -> IO ()
+runAdmin :: AppState -> Maybe NS.Socket -> NS.Socket -> Warp.Settings -> IO ()
-runAdmin appState maybeAdminSocket checkMainAppLive settings = do
+runAdmin appState maybeAdminSocket socketREST settings = do
  conf <- getConfig appState
  whenJust maybeAdminSocket $ \adminSocket -> do
    address <- resolveSocketToAddress adminSocket
    void . forkIO $ handle onError $
      Warp.runSettingsSocket (adminServerSettings conf address) adminSocket adminApp
  where
-    adminApp = admin appState checkMainAppLive
+    adminApp = admin appState socketREST
    observer = AppState.getObserver appState
    adminServerSettings config addr =
      settings
@@ -38,22 +40,22 @@ runAdmin appState maybeAdminSocket checkMainAppLive settings = do
    onError ex = do
      observer $ AdminServerCrashedObs ex
-      killApp appState -- Admin server crash is deemed unrecoverable, so we kill postgrest
+      killThread (getMainThreadId appState) -- Admin server crash is deemed unrecoverable, so we kill postgrest
 -- | PostgREST admin application
-admin :: AppState.AppState -> IO Bool -> Wai.Application
+admin :: AppState.AppState -> NS.Socket -> Wai.Application
-admin appState checkMainAppLive req respond = do
+admin appState socketREST req respond  = do
-  isMainAppLive <- checkMainAppLive
+  isMainAppReachable  <- isRight <$> reachMainApp socketREST
  isLoaded <- AppState.isLoaded appState
  isPending <- AppState.isPending appState
  case Wai.pathInfo req of
    ["live"] ->
-      respond $ Wai.responseLBS (if isMainAppLive then HTTP.status200 else HTTP.status500) [] mempty
+      respond $ Wai.responseLBS (if isMainAppReachable then HTTP.status200 else HTTP.status500) [] mempty
    ["ready"] ->
      let
-        status | isPending              = HTTP.status503
+        status | not isMainAppReachable = HTTP.status500
-               | not isMainAppLive      = HTTP.status500
+               | isPending              = HTTP.status503
               | isLoaded               = HTTP.status200
               | otherwise              = HTTP.status500
      in
@@ -66,3 +68,18 @@ admin appState checkMainAppLive req respond = do
      respond $ Wai.responseLBS HTTP.status200 [toContentType MTTextPlain] mets -- Content-Type is required for prometheus compliance
    _ ->
      respond $ Wai.responseLBS HTTP.status404 [] mempty
 -- Try to connect to the main app socket
 -- Note that it doesn't even send a valid HTTP request, we just want to check that the main app is accepting connections
 reachMainApp :: Socket -> IO (Either IOException ())
 reachMainApp appSock = do
  sockAddr <- getSocketName appSock
  sock <- socket (addrFamily sockAddr) Stream defaultProtocol
  try $ do
    connect sock sockAddr
    withSocketsDo $ bracket (pure sock) close sendEmpty
  where
    sendEmpty sock = void $ send sock mempty
    addrFamily (SockAddrInet _ _) = AF_INET
    addrFamily (SockAddrInet6 {}) = AF_INET6
    addrFamily (SockAddrUnix _)   = AF_UNIX
@@ -8,7 +8,6 @@ module PostgREST.ApiRequest
  ( ApiRequest(..)
  , userApiRequest
  , userPreferences
  , userBearerAuth
  ) where
 import qualified Data.CaseInsensitive as CI
@@ -20,25 +19,29 @@ import qualified Data.Text.Encoding   as T
 import Data.List                 (lookup)
 import Data.Ranged.Ranges        (emptyRange, rangeIntersection,
                                  rangeIsEmpty)
-import Network.HTTP.Types.Header       (RequestHeaders, hAuthorization, hCookie)
+import Network.HTTP.Types.Header (RequestHeaders, hCookie)
 import Network.Wai               (Request (..))
 import Network.Wai.Middleware.HttpAuth (extractBearerAuth)
 import Network.Wai.Parse         (parseHttpAccept)
 import Web.Cookie                (parseCookies)
 import PostgREST.ApiRequest.Payload      (getPayload)
 import PostgREST.ApiRequest.QueryParams  (QueryParams (..))
 import PostgREST.ApiRequest.Types        (Action (..), DbAction (..),
-                                          InvokeMethod (..), Mutation (..),
+                                          InvokeMethod (..),
-                                          Payload (..), RequestBody,
+                                          Mutation (..), Payload (..),
-                                          Resource (..))
+                                          RequestBody, Resource (..))
-import PostgREST.Config                  (AppConfig (..), OpenAPIMode (..))
+import PostgREST.Config                  (AppConfig (..),
-import PostgREST.Error                   (ApiRequestError (..), RangeError (..))
+                                          OpenAPIMode (..))
 import PostgREST.Config.Database         (TimezoneNames)
 import PostgREST.Error                   (ApiRequestError (..),
                                          RangeError (..))
 import PostgREST.MediaType               (MediaType (..))
 import PostgREST.RangeQuery              (NonnegRange, allRange,
-                                          convertToLimitZeroRange, hasLimitZero,
+                                          convertToLimitZeroRange,
                                          hasLimitZero,
                                          rangeRequested)
-import PostgREST.SchemaCache.Identifiers (FieldName, QualifiedIdentifier (..),
+import PostgREST.SchemaCache.Identifiers (FieldName,
                                          QualifiedIdentifier (..),
                                          Schema)
 import qualified PostgREST.ApiRequest.Preferences as Preferences
@@ -61,7 +64,7 @@ data ApiRequest = ApiRequest {
  , iPayload             :: Maybe Payload                    -- ^ Data sent by client and used for mutation actions
  , iPreferences         :: Preferences.Preferences          -- ^ Prefer header values
  , iQueryParams         :: QueryParams.QueryParams
-  , iColumns             :: S.Set FieldName                  -- ^ parsed columns from &columns parameter and payload
+  , iColumns             :: S.Set FieldName                  -- ^ parsed colums from &columns parameter and payload
  , iHeaders             :: [(ByteString, ByteString)]       -- ^ HTTP request headers
  , iCookies             :: [(ByteString, ByteString)]       -- ^ Request Cookies
  , iPath                :: ByteString                       -- ^ Raw request path
@@ -108,12 +111,8 @@ userApiRequest conf prefs req reqBody = do
    actIsInvokeSafe x = case x of {ActDb (ActRoutine _  (InvRead _)) -> True; _ -> False}
 -- | Parses the Prefer header
-userPreferences :: AppConfig -> Request -> Preferences.Preferences
+userPreferences :: AppConfig -> Request -> TimezoneNames -> Preferences.Preferences
-userPreferences conf req = Preferences.fromHeaders (configDbTxAllowOverride conf) $ requestHeaders req
+userPreferences conf req timezones = Preferences.fromHeaders (configDbTxAllowOverride conf) timezones $ requestHeaders req
 -- | Obtains the Bearer Auth
 userBearerAuth :: Request -> Maybe ByteString
 userBearerAuth req = extractBearerAuth =<< lookup hAuthorization (requestHeaders req)
 getResource :: AppConfig -> [Text] -> Either ApiRequestError Resource
 getResource AppConfig{configOpenApiMode, configDbRootSpec} = \case
@@ -21,21 +21,20 @@ module PostgREST.ApiRequest.Preferences
  , shouldCount
  , shouldExplainCount
  , prefAppliedHeader
  , toHeaderValue
  ) where
 import qualified Data.ByteString.Char8     as BS
 import qualified Data.Map                  as Map
 import qualified Data.Set                  as S
 import qualified Network.HTTP.Types.Header as HTTP
 import PostgREST.Config.Database (TimezoneNames)
 import Protolude
 -- $setup
 -- Setup for doctests
 -- >>> :set -XStandaloneDeriving
 -- >>> import Text.Pretty.Simple (pPrint)
 -- >>> import qualified Data.Set as S
 -- >>> import Protolude
 -- >>> deriving instance Show PreferResolution
 -- >>> deriving instance Show PreferRepresentation
 -- >>> deriving instance Show PreferCount
@@ -63,8 +62,10 @@ data Preferences
 -- |
 -- Parse HTTP headers based on RFC7240[1] to identify preferences.
 --
 -- >>> let sc = S.fromList ["America/Los_Angeles"]
 --
 -- One header with comma-separated values can be used to set multiple preferences:
-- >>> pPrint $ fromHeaders True [("Prefer", "resolution=ignore-duplicates, count=exact, timezone=America/Los_Angeles, max-affected=100")]
+-- >>> pPrint $ fromHeaders True sc [("Prefer", "resolution=ignore-duplicates, count=exact, timezone=America/Los_Angeles, max-affected=100")]
 -- Preferences
 --     { preferResolution = Just IgnoreDuplicates
 --     , preferRepresentation = Nothing
@@ -81,7 +82,7 @@ data Preferences
 --
 -- Multiple headers can also be used:
 --
-- >>> pPrint $ fromHeaders True [("Prefer", "resolution=ignore-duplicates"), ("Prefer", "count=exact"), ("Prefer", "missing=null"), ("Prefer", "handling=lenient"), ("Prefer", "invalid"), ("Prefer", "max-affected=5999")]
+-- >>> pPrint $ fromHeaders True sc [("Prefer", "resolution=ignore-duplicates"), ("Prefer", "count=exact"), ("Prefer", "missing=null"), ("Prefer", "handling=lenient"), ("Prefer", "invalid"), ("Prefer", "max-affected=5999")]
 -- Preferences
 --     { preferResolution = Just IgnoreDuplicates
 --     , preferRepresentation = Nothing
@@ -97,13 +98,13 @@ data Preferences
 --
 -- If a preference is set more than once, only the first is used:
 --
-- >>> preferTransaction $ fromHeaders True [("Prefer", "tx=commit, tx=rollback")]
+-- >>> preferTransaction $ fromHeaders True sc [("Prefer", "tx=commit, tx=rollback")]
 -- Just Commit
 --
 -- This is also the case across multiple headers:
 --
 -- >>> :{
--   preferResolution . fromHeaders True $
+--   preferResolution . fromHeaders True sc $
 --     [ ("Prefer", "resolution=ignore-duplicates")
 --     , ("Prefer", "resolution=merge-duplicates")
 --     ]
@@ -113,7 +114,7 @@ data Preferences
 --
 -- Preferences can be separated by arbitrary amounts of space, lower-case header is also recognized:
 --
-- >>> pPrint $ fromHeaders True [("prefer", "count=exact,    tx=commit   ,return=representation , missing=default, handling=strict, anything")]
+-- >>> pPrint $ fromHeaders True sc [("prefer", "count=exact,    tx=commit   ,return=representation , missing=default, handling=strict, anything")]
 -- Preferences
 --     { preferResolution = Nothing
 --     , preferRepresentation = Just Full
@@ -126,8 +127,8 @@ data Preferences
 --     , invalidPrefs = [ "anything" ]
 --     }
 --
-fromHeaders :: Bool -> [HTTP.Header] -> Preferences
+fromHeaders :: Bool -> TimezoneNames -> [HTTP.Header] -> Preferences
-fromHeaders allowTxDbOverride headers =
+fromHeaders allowTxDbOverride acceptedTzNames headers =
  Preferences
    { preferResolution     = parsePrefs [MergeDuplicates, IgnoreDuplicates]
    , preferRepresentation = parsePrefs [Full, None, HeadersOnly]
@@ -135,7 +136,7 @@ fromHeaders allowTxDbOverride headers =
    , preferTransaction    = if allowTxDbOverride then parsePrefs [Commit, Rollback] else Nothing
    , preferMissing        = parsePrefs [ApplyDefaults, ApplyNulls]
    , preferHandling       = parsePrefs [Strict, Lenient]
-    , preferTimezone       = PreferTimezone <$> timezonePref
+    , preferTimezone       = if isTimezonePrefAccepted then PreferTimezone <$> timezonePref else Nothing
    , preferMaxAffected    = PreferMaxAffected <$> maxAffectedPref
    , invalidPrefs         = filter isUnacceptable prefs
    }
@@ -155,11 +156,12 @@ fromHeaders allowTxDbOverride headers =
    listStripPrefix prefix prefList = listToMaybe $ mapMaybe (BS.stripPrefix prefix) prefList
    timezonePref = listStripPrefix "timezone=" prefs
    isTimezonePrefAccepted = ((S.member . decodeUtf8 <$> timezonePref) <*> pure acceptedTzNames) == Just True
    maxAffectedPref = listStripPrefix "max-affected=" prefs >>= readMaybe . BS.unpack
    isUnacceptable p = p `notElem` acceptedPrefs &&
-                       isNothing (BS.stripPrefix "timezone=" p) &&
+                       (isNothing (BS.stripPrefix "timezone=" p) ||  not isTimezonePrefAccepted) &&
                       isNothing (BS.stripPrefix "max-affected=" p)
    parsePrefs :: ToHeaderValue a => [a] -> Maybe a
@@ -5,21 +5,11 @@
 -- This module is in charge of parsing all the querystring values in an url, e.g.
 -- the select, id, order in `/projects?select=id,name&id=eq.1&order=id,name.desc`.
 {-# LANGUAGE LambdaCase    #-}
 {-# LANGUAGE TupleSections #-}
 module PostgREST.ApiRequest.QueryParams
  ( parse
  , QueryParams(..)
  , pFieldForest
  , pFieldName
  , pFieldSelect
  , pJsonPath
  , pLogicTree
  , pOpExpr
  , pOrder
  , pRelationSelect
  , pRequestFilter
  , pRequestRange
  , pSingleVal
  , pSpreadRelationSelect
  ) where
 import qualified Data.ByteString.Char8         as BS
@@ -38,38 +28,40 @@ import Data.List                     (init, last)
 import Data.Ranged.Boundaries        (Boundary (..))
 import Data.Ranged.Ranges            (Range (..))
 import Data.Tree                     (Tree (..))
-import Text.Parsec.Error             (errorMessages, showErrorMessages)
+import Text.Parsec.Error             (errorMessages,
-import Text.ParserCombinators.Parsec (GenParser, ParseError, Parser, anyChar,
+                                      showErrorMessages)
-                                      between, char, choice, digit, eof,
+import Text.ParserCombinators.Parsec (GenParser, ParseError, Parser,
-                                      errorPos, letter, lookAhead, many1,
+                                      anyChar, between, char, choice,
-                                      noneOf, notFollowedBy, oneOf, optionMaybe,
+                                      digit, eof, errorPos, letter,
-                                      sepBy, sepBy1, string, try, (<?>))
+                                      lookAhead, many1, noneOf,
                                      notFollowedBy, oneOf,
                                      optionMaybe, sepBy, sepBy1,
                                      string, try, (<?>))
-import PostgREST.RangeQuery              (NonnegRange, allRange, rangeGeq,
+import PostgREST.RangeQuery              (NonnegRange, allRange,
-                                          rangeLimit, rangeOffset,
+                                          rangeGeq, rangeLimit,
-                                          restrictRange)
+                                          rangeOffset, restrictRange)
 import PostgREST.SchemaCache.Identifiers (FieldName)
-import PostgREST.ApiRequest.Types (AggregateFunction (..), EmbedParam (..),
+import PostgREST.ApiRequest.Types (AggregateFunction (..),
-                                   EmbedPath, Field, Filter (..),
+                                   EmbedParam (..), EmbedPath, Field,
-                                   FtsOperator (..), Hint, IsVal (..),
+                                   Filter (..), FtsOperator (..),
-                                   JoinType (..), JsonOperand (..),
+                                   Hint, IsVal (..), JoinType (..),
-                                   JsonOperation (..), JsonPath, ListVal,
+                                   JsonOperand (..),
-                                   LogicOperator (..), LogicTree (..),
+                                   JsonOperation (..), JsonPath,
-                                   OpExpr (..), OpQuantifier (..),
+                                   ListVal, LogicOperator (..),
-                                   Operation (..), OrderDirection (..),
+                                   LogicTree (..), OpExpr (..),
                                   OpQuantifier (..), Operation (..),
                                   OrderDirection (..),
                                   OrderNulls (..), OrderTerm (..),
-                                   QuantOperator (..), SelectItem (..),
+                                   QuantOperator (..),
                                   SelectItem (..),
                                   SimpleOperator (..), SingleVal)
 import PostgREST.Error (QPError (..))
 import Protolude hiding (Sum, try)
 -- $setup
 -- >>> import qualified Text.ParserCombinators.Parsec as P
 -- >>> import Protolude hiding (Sum, try)
 data QueryParams =
  QueryParams
    { qsCanonical      :: ByteString
@@ -42,7 +42,8 @@ module PostgREST.ApiRequest.Types
 import qualified Data.ByteString.Lazy as LBS
 import qualified Data.Set             as S
-import PostgREST.SchemaCache.Identifiers (FieldName, QualifiedIdentifier (..),
+import PostgREST.SchemaCache.Identifiers (FieldName,
                                          QualifiedIdentifier (..),
                                          Schema)
 import Protolude
@@ -0,0 +1,274 @@
 {-|
 Module      : PostgREST.App
 Description : PostgREST main application
 This module is in charge of mapping HTTP requests to PostgreSQL queries.
 Some of its functionality includes:
 - Mapping HTTP request methods to proper SQL statements. For example, a GET request is translated to executing a SELECT query in a read-only TRANSACTION.
 - Producing HTTP Headers according to RFCs.
 - Content Negotiation
 -}
 {-# LANGUAGE RecordWildCards     #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE ViewPatterns        #-}
 module PostgREST.App
  ( postgrest
  , run
  ) where
 import GHC.IO.Exception (IOErrorType (..))
 import System.IO.Error  (ioeGetErrorType)
 import Control.Monad.Except     (liftEither)
 import Data.Either.Combinators  (mapLeft, whenLeft)
 import Data.Maybe               (fromJust)
 import Data.String              (IsString (..))
 import Network.Wai.Handler.Warp (defaultSettings, setHost,
                                 setOnException, setPort,
                                 setServerName)
 import qualified Data.Text.Encoding       as T
 import qualified Network.Wai              as Wai
 import qualified Network.Wai.Handler.Warp as Warp
 import qualified PostgREST.Admin      as Admin
 import qualified PostgREST.ApiRequest as ApiRequest
 import qualified PostgREST.AppState   as AppState
 import qualified PostgREST.Auth       as Auth
 import qualified PostgREST.Cors       as Cors
 import qualified PostgREST.Error      as Error
 import qualified PostgREST.Listener   as Listener
 import qualified PostgREST.Logger     as Logger
 import qualified PostgREST.MainTx     as MainTx
 import qualified PostgREST.Plan       as Plan
 import qualified PostgREST.Query      as Query
 import qualified PostgREST.Response   as Response
 import qualified PostgREST.Unix       as Unix (installSignalHandlers)
 import PostgREST.ApiRequest           (ApiRequest (..))
 import PostgREST.AppState             (AppState)
 import PostgREST.Auth.Types           (AuthResult (..))
 import PostgREST.Config               (AppConfig (..), LogLevel (..))
 import PostgREST.Error                (Error)
 import PostgREST.Network              (resolveSocketToAddress)
 import PostgREST.Observation          (Observation (..))
 import PostgREST.Response.Performance (ServerTiming (..),
                                       serverTimingHeader)
 import PostgREST.SchemaCache          (SchemaCache (..))
 import PostgREST.TimeIt               (timeItT)
 import PostgREST.Version              (docsVersion, prettyVersion)
 import qualified Data.ByteString.Char8  as BS
 import qualified Data.List              as L
 import           Data.Streaming.Network (bindPortTCP,
                                         bindRandomPortTCP)
 import qualified Data.Text              as T
 import qualified Network.HTTP.Types     as HTTP
 import qualified Network.Socket         as NS
 import           PostgREST.Unix         (createAndBindDomainSocket)
 import           Protolude              hiding (Handler)
 type Handler = ExceptT Error
 run :: AppState -> IO ()
 run appState = do
  conf@AppConfig{..} <- AppState.getConfig appState
  AppState.schemaCacheLoader appState -- Loads the initial SchemaCache
  (mainSocket, adminSocket) <- initSockets conf
  Unix.installSignalHandlers observer (AppState.getMainThreadId appState) (AppState.schemaCacheLoader appState) (AppState.readInDbConfig False appState)
  Listener.runListener appState
  Admin.runAdmin appState adminSocket mainSocket (serverSettings conf)
  let app = postgrest configLogLevel appState (AppState.schemaCacheLoader appState)
  do
    address <- resolveSocketToAddress mainSocket
    observer $ AppServerAddressObs address
  Warp.runSettingsSocket (serverSettings conf & setOnException onWarpException) mainSocket app
  where
    observer = AppState.getObserver appState
    onWarpException :: Maybe Wai.Request -> SomeException -> IO ()
    onWarpException _ ex =
      when (shouldDisplayException ex) $
        observer $ WarpServerObs $ show ex
    -- Similar to wai defaultShouldDisplayException in
    -- https://github.com/yesodweb/wai//blob/8c3882c60f6abe043889fc20c7efd3fa9747fa4a/warp/Network/Wai/Handler/Warp/Settings.hs#L251-L258
    -- but without omitting AsyncException since it's important to log for ThreadKilled, StackOverflow and other cases.
    -- We want to reuse this to avoid flooding the logs for some transient failure cases.
    shouldDisplayException :: SomeException -> Bool
    shouldDisplayException se
        | Just (_ :: Warp.InvalidRequest) <- fromException se = False
        | Just (ioeGetErrorType -> et) <- fromException se, et == ResourceVanished || et == InvalidArgument = False
        | otherwise = True
 serverSettings :: AppConfig -> Warp.Settings
 serverSettings AppConfig{..} =
  defaultSettings
    & setHost (fromString $ toS configServerHost)
    & setPort configServerPort
    & setServerName ("postgrest/" <> prettyVersion)
 -- | PostgREST application
 postgrest :: LogLevel -> AppState.AppState -> IO () -> Wai.Application
 postgrest logLevel appState connWorker =
  traceHeaderMiddleware appState .
  Cors.middleware appState .
  Auth.middleware appState .
  Logger.middleware logLevel Auth.getRole $
    -- fromJust can be used, because the auth middleware will **always** add
    -- some AuthResult to the vault.
    \req respond -> case fromJust $ Auth.getResult req of
      Left err -> respond $ Error.errorResponseFor err
      Right authResult -> do
        appConf <- AppState.getConfig appState -- the config must be read again because it can reload
        maybeSchemaCache <- AppState.getSchemaCache appState
        let
          eitherResponse :: IO (Either Error Wai.Response)
          eitherResponse =
            runExceptT $ postgrestResponse appState appConf maybeSchemaCache authResult req
        response <- either Error.errorResponseFor identity <$> eitherResponse
        -- Launch the connWorker when the connection is down. The postgrest
        -- function can respond successfully (with a stale schema cache) before
        -- the connWorker is done. However, when there's an empty schema cache
        -- postgrest responds with the error `PGRST002`; this means that the schema
        -- cache is still loading, so we don't launch the connWorker here because
        -- it would duplicate the loading process, e.g. https://github.com/PostgREST/postgrest/issues/3704
        -- TODO: this process may be unnecessary when the Listener is enabled. Revisit once https://github.com/PostgREST/postgrest/issues/1766 is done
        when (isServiceUnavailable response && isJust maybeSchemaCache) connWorker
        resp <- do
          delay <- AppState.getNextDelay appState
          return $ addRetryHint delay response
        respond resp
 postgrestResponse
  :: AppState.AppState
  -> AppConfig
  -> Maybe SchemaCache
  -> AuthResult
  -> Wai.Request
  -> Handler IO Wai.Response
 postgrestResponse appState conf@AppConfig{..} maybeSchemaCache authResult@AuthResult{..} req = do
  let observer = AppState.getObserver appState
  sCache <-
    case maybeSchemaCache of
      Just sCache ->
        return sCache
      Nothing -> do
        lift $ observer SchemaCacheEmptyObs
        throwError Error.NoSchemaCacheError
  body <- lift $ Wai.strictRequestBody req
  let jwtTime = if configServerTimingEnabled then Auth.getJwtDur req else Nothing
      timezones = dbTimezones sCache
      prefs = ApiRequest.userPreferences conf req timezones
  (parseTime, apiReq@ApiRequest{..}) <- withTiming $ liftEither . mapLeft Error.ApiRequestError $ ApiRequest.userApiRequest conf prefs req body
  (planTime, plan)                   <- withTiming $ liftEither $ Plan.actionPlan iAction conf apiReq sCache
  let mainQ = Query.mainQuery plan conf apiReq authResult configDbPreRequest
      tx = MainTx.mainTx mainQ conf authResult apiReq plan sCache
      obsQuery s = when configLogQuery $ observer $ QueryObs mainQ s
  (txTime, txResult) <- withTiming $ do
    case tx of
      MainTx.NoDbTx r -> pure r
      MainTx.DbTx{..} -> do
        dbRes <- lift $ AppState.usePool appState (dqTransaction dqIsoLevel dqTxMode $ runExceptT dqDbHandler)
        let eitherResp = join $ mapLeft (Error.PgErr . Error.PgError (Just authRole /= configDbAnonRole)) dbRes
        -- TODO: we use obsQuery twice, one here and one below because in case of an error with the usePool above, the request will finish here and return an error message.
        -- This is because of a combination of ExceptT + our Error module which has Wai.responseLBS.
        -- This needs refactoring so only the below obsQuery is used.
        lift $ whenLeft eitherResp $ obsQuery . Error.status
        liftEither eitherResp
  (respTime, resp) <- withTiming $ do
    let response = Response.actionResponse txResult apiReq (T.decodeUtf8 prettyVersion, docsVersion) conf sCache iSchema iNegotiatedByProfile
        status' = either Error.status Response.pgrstStatus response
    -- TODO: see above obsQuery, only this obsQuery should remain after refactoring (because the QueryObs depends on the status)
    lift $ obsQuery status'
    liftEither response
  return $ toWaiResponse (ServerTiming jwtTime parseTime planTime txTime respTime) resp
  where
    toWaiResponse :: ServerTiming -> Response.PgrstResponse -> Wai.Response
    toWaiResponse timing (Response.PgrstResponse st hdrs bod) = Wai.responseLBS st (hdrs ++ ([serverTimingHeader timing | configServerTimingEnabled])) bod
    withTiming :: Handler IO a -> Handler IO (Maybe Double, a)
    withTiming f = if configServerTimingEnabled
        then do
          (t, r) <- timeItT f
          pure (Just t, r)
        else do
          r <- f
          pure (Nothing, r)
 traceHeaderMiddleware :: AppState -> Wai.Middleware
 traceHeaderMiddleware appState app req respond = do
  conf <- AppState.getConfig appState
  case configServerTraceHeader conf of
    Nothing -> app req respond
    Just hdr ->
      let hdrVal = L.lookup hdr $ Wai.requestHeaders req in
      app req (respond . Wai.mapResponseHeaders ([(hdr, fromMaybe mempty hdrVal)] ++))
 addRetryHint :: Int -> Wai.Response -> Wai.Response
 addRetryHint delay response = do
  let h = ("Retry-After", BS.pack $ show delay)
  Wai.mapResponseHeaders (\hs -> if isServiceUnavailable response then h:hs else hs) response
 isServiceUnavailable :: Wai.Response -> Bool
 isServiceUnavailable response = Wai.responseStatus response == HTTP.status503
 type AppSockets = (NS.Socket, Maybe NS.Socket)
 initSockets :: AppConfig -> IO AppSockets
 initSockets AppConfig{..} = do
  let
    cfg'usp = configServerUnixSocket
    cfg'uspm = configServerUnixSocketMode
    cfg'host = configServerHost
    cfg'port = configServerPort
    cfg'adminHost = configAdminServerHost
    cfg'adminPort = configAdminServerPort
  sock <- case cfg'usp of
    -- I'm not using `streaming-commons`' bindPath function here because it's not defined for Windows,
    -- but we need to have runtime error if we try to use it in Windows, not compile time error
    Just path -> createAndBindDomainSocket path cfg'uspm
    Nothing -> do
      (_, sock) <-
        if cfg'port /= 0
          then do
            sock <- bindPortTCP cfg'port (fromString $ T.unpack cfg'host)
            pure (cfg'port, sock)
          else do
            -- explicitly bind to a random port, returning bound port number
            (num, sock) <- bindRandomPortTCP (fromString $ T.unpack cfg'host)
            pure (num, sock)
      pure sock
  adminSock <- case cfg'adminPort of
    Just adminPort -> do
      adminSock <- bindPortTCP adminPort (fromString $ T.unpack cfg'adminHost)
      pure $ Just adminSock
    Nothing -> pure Nothing
  pure (sock, adminSock)
@@ -0,0 +1,429 @@
 {-# LANGUAGE LambdaCase      #-}
 {-# LANGUAGE NamedFieldPuns  #-}
 {-# LANGUAGE RecordWildCards #-}
 module PostgREST.AppState
  ( AppState
  , destroy
  , getConfig
  , getSchemaCache
  , getMainThreadId
  , getPgVersion
  , getNextDelay
  , getNextListenerDelay
  , getTime
  , getJwtCacheState
  , init
  , initWithPool
  , putConfig -- For tests TODO refactoring
  , putNextListenerDelay
  , putSchemaCache
  , putPgVersion
  , putIsListenerOn
  , usePool
  , readInDbConfig
  , schemaCacheLoader
  , getObserver
  , isLoaded
  , isPending
  ) where
 import qualified Data.ByteString.Char8      as BS
 import           Data.Either.Combinators    (whenLeft)
 import qualified Hasql.Pool                 as SQL
 import qualified Hasql.Pool.Config          as SQL
 import qualified Hasql.Session              as SQL
 import qualified Hasql.Transaction.Sessions as SQL
 import qualified Network.HTTP.Types.Status  as HTTP
 import qualified PostgREST.Auth.JwtCache    as JwtCache
 import qualified PostgREST.Error            as Error
 import qualified PostgREST.Logger           as Logger
 import qualified PostgREST.Metrics          as Metrics
 import           PostgREST.Observation
 import           PostgREST.TimeIt           (timeItT)
 import           PostgREST.Version          (prettyVersion)
 import Control.AutoUpdate (defaultUpdateSettings, mkAutoUpdate,
                           updateAction)
 import Control.Debounce
 import Control.Retry      (RetryPolicy, RetryStatus (..), capDelay,
                           exponentialBackoff, retrying,
                           rsPreviousDelay)
 import Data.IORef         (IORef, atomicWriteIORef, newIORef,
                           readIORef)
 import Data.Time.Clock    (UTCTime, getCurrentTime)
 import PostgREST.Auth.JwtCache           (JwtCacheState, update)
 import PostgREST.Config                  (AppConfig (..),
                                          addFallbackAppName,
                                          readAppConfig)
 import PostgREST.Config.Database         (queryDbSettings,
                                          queryPgVersion,
                                          queryRoleSettings)
 import PostgREST.Config.PgVersion        (PgVersion (..),
                                          minimumPgVersion)
 import PostgREST.SchemaCache             (SchemaCache (..),
                                          querySchemaCache,
                                          showSummary)
 import PostgREST.SchemaCache.Identifiers (quoteQi)
 import Protolude
 data AppState = AppState
  -- | Database connection pool
  { statePool              :: SQL.Pool
  -- | Database server version
  , statePgVersion         :: IORef PgVersion
  -- | Schema cache
  , stateSchemaCache       :: IORef (Maybe SchemaCache)
  -- | The schema cache status
  , stateSCacheStatus      :: IORef SchemaCacheStatus
  -- | State of the LISTEN channel
  , stateIsListenerOn      :: IORef Bool
  -- | starts the connection worker with a debounce
  , debouncedSCacheLoader  :: IO ()
  -- | Config that can change at runtime
  , stateConf              :: IORef AppConfig
  -- | Time used for verifying JWT expiration
  , stateGetTime           :: IO UTCTime
  -- | Used for killing the main thread in case a subthread fails
  , stateMainThreadId      :: ThreadId
  -- | Keeps track of the next delay for db connection retry
  , stateNextDelay         :: IORef Int
  -- | Keeps track of the next delay for the listener
  , stateNextListenerDelay :: IORef Int
  -- | Observation handler
  , stateObserver          :: ObservationHandler
  -- | JWT Cache
  , stateJwtCache          :: JwtCache.JwtCacheState
  , stateLogger            :: Logger.LoggerState
  , stateMetrics           :: Metrics.MetricsState
  }
 -- | Schema cache status
 data SchemaCacheStatus
  = SCLoaded
  | SCPending
  deriving Eq
 init :: AppConfig -> IO AppState
 init conf@AppConfig{configLogLevel, configDbPoolSize} = do
  loggerState  <- Logger.init
  metricsState <- Metrics.init configDbPoolSize
  let observer = liftA2 (>>) (Logger.observationLogger loggerState configLogLevel) (Metrics.observationMetrics metricsState)
  observer $ AppStartObs prettyVersion
  pool <- initPool conf observer
  initWithPool pool conf loggerState metricsState observer --{ stateSocketREST = sock, stateSocketAdmin = adminSock}
 initWithPool :: SQL.Pool -> AppConfig -> Logger.LoggerState -> Metrics.MetricsState -> ObservationHandler -> IO AppState
 initWithPool pool conf loggerState metricsState observer = do
  appState <- AppState pool
    <$> newIORef minimumPgVersion -- assume we're in a supported version when starting, this will be corrected on a later step
    <*> newIORef Nothing
    <*> newIORef SCPending
    <*> newIORef False
    <*> pure (pure ())
    <*> newIORef conf
    <*> mkAutoUpdate defaultUpdateSettings { updateAction = getCurrentTime }
    <*> myThreadId
    <*> newIORef 0
    <*> newIORef 1
    <*> pure observer
    <*> JwtCache.init conf observer
    <*> pure loggerState
    <*> pure metricsState
  deb <-
    let decisecond = 100000 in
    mkDebounce defaultDebounceSettings
       { debounceAction = retryingSchemaCacheLoad appState
       , debounceFreq = decisecond
       , debounceEdge = leadingEdge -- runs the worker at the start and the end
       }
  return appState { debouncedSCacheLoader = deb}
 destroy :: AppState -> IO ()
 destroy = destroyPool
 initPool :: AppConfig -> ObservationHandler -> IO SQL.Pool
 initPool AppConfig{..} observer = do
  SQL.acquire $ SQL.settings
    [ SQL.size configDbPoolSize
    , SQL.acquisitionTimeout $ fromIntegral configDbPoolAcquisitionTimeout
    , SQL.agingTimeout $ fromIntegral configDbPoolMaxLifetime
    , SQL.idlenessTimeout $ fromIntegral configDbPoolMaxIdletime
    , SQL.staticConnectionSettings (toUtf8 $ addFallbackAppName prettyVersion configDbUri)
    , SQL.observationHandler $ observer . HasqlPoolObs
    ]
 -- | Run an action with a database connection.
 usePool :: AppState -> SQL.Session a -> IO (Either SQL.UsageError a)
 usePool AppState{stateObserver=observer, stateMainThreadId=mainThreadId, ..} sess = do
  observer PoolRequest
  res <- SQL.use statePool sess
  observer PoolRequestFullfilled
  whenLeft res (\case
    SQL.AcquisitionTimeoutUsageError ->
      observer $ PoolAcqTimeoutObs SQL.AcquisitionTimeoutUsageError
    err@(SQL.ConnectionUsageError e) ->
      let failureMessage = BS.unpack $ fromMaybe mempty e in
      when (("FATAL:  password authentication failed" `isInfixOf` failureMessage) || ("no password supplied" `isInfixOf` failureMessage)) $ do
        observer $ ExitDBFatalError ServerAuthError err
        killThread mainThreadId
    err@(SQL.SessionUsageError (SQL.QueryError tpl _ (SQL.ResultError resultErr))) -> do
      case resultErr of
        SQL.UnexpectedResult{} -> do
          observer $ ExitDBFatalError ServerPgrstBug err
          killThread mainThreadId
        SQL.RowError{} -> do
          observer $ ExitDBFatalError ServerPgrstBug err
          killThread mainThreadId
        SQL.UnexpectedAmountOfRows{} -> do
          observer $ ExitDBFatalError ServerPgrstBug err
          killThread mainThreadId
        -- Check for a syntax error (42601 is the pg code) only for queries that don't have `WITH pgrst_source` as prefix.
        -- This would mean the error is on our schema cache queries, so we treat it as fatal.
        -- TODO have a better way to mark this as a schema cache query
        SQL.ServerError "42601" _ _ _ _ ->
          unless ("WITH pgrst_source" `BS.isPrefixOf` tpl) $ do
            observer $ ExitDBFatalError ServerPgrstBug err
            killThread mainThreadId
        -- Check for a "prepared statement <name> already exists" error (Code 42P05: duplicate_prepared_statement).
        -- This would mean that a connection pooler in transaction mode is being used
        -- while prepared statements are enabled in the PostgREST configuration,
        -- both of which are incompatible with each other.
        SQL.ServerError "42P05" _ _ _ _ -> do
          observer $ ExitDBFatalError ServerError42P05 err
          killThread mainThreadId
        -- Check for a "transaction blocks not allowed in statement pooling mode" error (Code 08P01: protocol_violation).
        -- This would mean that a connection pooler in statement mode is being used which is not supported in PostgREST.
        SQL.ServerError "08P01" "transaction blocks not allowed in statement pooling mode" _ _ _ -> do
          observer $ ExitDBFatalError ServerError08P01 err
          killThread mainThreadId
        SQL.ServerError{} ->
          when (Error.status (Error.PgError False err) >= HTTP.status500) $
            observer $ QueryErrorCodeHighObs err
    err@(SQL.SessionUsageError (SQL.QueryError _ _ (SQL.ClientError _))) ->
      -- An error on the client-side, usually indicates problems wth connection
        observer $ QueryErrorCodeHighObs err
    )
  return res
 -- | Flush the connection pool so that any future use of the pool will
 -- use connections freshly established after this call.
 -- | Emits PoolFlushed observation
 flushPool :: AppState -> IO ()
 flushPool AppState{..} = do
  SQL.release statePool
  stateObserver PoolFlushed
 -- | Destroy the pool on shutdown.
 -- | Differs from flushPool in not emiting PoolFlushed observation.
 destroyPool :: AppState -> IO ()
 destroyPool AppState{..} = SQL.release statePool
 getPgVersion :: AppState -> IO PgVersion
 getPgVersion = readIORef . statePgVersion
 putPgVersion :: AppState -> PgVersion -> IO ()
 putPgVersion = atomicWriteIORef . statePgVersion
 getSchemaCache :: AppState -> IO (Maybe SchemaCache)
 getSchemaCache = readIORef . stateSchemaCache
 putSchemaCache :: AppState -> Maybe SchemaCache -> IO ()
 putSchemaCache appState = atomicWriteIORef (stateSchemaCache appState)
 schemaCacheLoader :: AppState -> IO ()
 schemaCacheLoader = debouncedSCacheLoader
 getNextDelay :: AppState -> IO Int
 getNextDelay = readIORef . stateNextDelay
 getNextListenerDelay :: AppState -> IO Int
 getNextListenerDelay = readIORef . stateNextListenerDelay
 putNextListenerDelay :: AppState -> Int -> IO ()
 putNextListenerDelay = atomicWriteIORef . stateNextListenerDelay
 getConfig :: AppState -> IO AppConfig
 getConfig = readIORef . stateConf
 putConfig :: AppState -> AppConfig -> IO ()
 putConfig = atomicWriteIORef . stateConf
 getTime :: AppState -> IO UTCTime
 getTime = stateGetTime
 getJwtCacheState :: AppState -> JwtCacheState
 getJwtCacheState = stateJwtCache
 getMainThreadId :: AppState -> ThreadId
 getMainThreadId = stateMainThreadId
 isConnEstablished :: AppState -> IO Bool
 isConnEstablished appState = do
  AppConfig{..} <- getConfig appState
  if configDbChannelEnabled then -- if the listener is enabled, we can be sure the connection is up
    readIORef $ stateIsListenerOn appState
  else -- otherwise the only way to check the connection is to make a query
    isRight <$> usePool appState (SQL.sql "SELECT 1")
 putIsListenerOn :: AppState -> Bool -> IO ()
 putIsListenerOn = atomicWriteIORef . stateIsListenerOn
 isLoaded :: AppState -> IO Bool
 isLoaded x = do
  scacheStatus <- readIORef $ stateSCacheStatus x
  connEstablished <- isConnEstablished x
  return $ scacheStatus == SCLoaded && connEstablished
 isPending :: AppState -> IO Bool
 isPending x = do
  scacheStatus <- readIORef $ stateSCacheStatus x
  connEstablished <- isConnEstablished x
  return $ scacheStatus == SCPending || not connEstablished
 putSCacheStatus :: AppState -> SchemaCacheStatus -> IO ()
 putSCacheStatus = atomicWriteIORef . stateSCacheStatus
 getObserver :: AppState -> ObservationHandler
 getObserver = stateObserver
 -- | Try to load the schema cache and retry if it fails.
 --
 -- This is done by repeatedly: 1) flushing the pool, 2) querying the version and validating that the postgres version is supported by us, and 3) loading the schema cache.
 -- It's necessary to flush the pool:
 --
 -- + Because connections cache the pg catalog(see #2620)
 -- + For rapid recovery. Otherwise, the pool idle or lifetime timeout would have to be reached for new healthy connections to be acquired.
 retryingSchemaCacheLoad :: AppState -> IO ()
 retryingSchemaCacheLoad appState@AppState{stateObserver=observer, stateMainThreadId=mainThreadId} =
  void $ retrying retryPolicy shouldRetry (\RetryStatus{rsIterNumber, rsPreviousDelay} -> do
    when (rsIterNumber > 0) $ do
      let delay = fromMaybe 0 rsPreviousDelay `div` oneSecondInUs
      observer $ ConnectionRetryObs delay
      putNextListenerDelay appState delay
    (,) <$> qPgVersion <*> (qInDbConfig *> qSchemaCache)
  )
  where
    qPgVersion :: IO (Maybe PgVersion)
    qPgVersion = do
      AppConfig{..} <- getConfig appState
      pgVersion <- usePool appState (queryPgVersion False) -- No need to prepare the query here, as the connection might not be established
      case pgVersion of
        Left e -> do
          observer $ QueryPgVersionError e
          unless configDbPoolAutomaticRecovery $ do
            observer ExitDBNoRecoveryObs
            killThread mainThreadId
          return Nothing
        Right actualPgVersion ->
          if actualPgVersion < minimumPgVersion then do
            observer $ ExitUnsupportedPgVersion actualPgVersion minimumPgVersion
            killThread mainThreadId
            return Nothing
          else do
            observer $ DBConnectedObs $ pgvFullName actualPgVersion
            observer $ PoolInit configDbPoolSize
            putPgVersion appState actualPgVersion
            return $ Just actualPgVersion
    qInDbConfig :: IO ()
    qInDbConfig = do
      AppConfig{..} <- getConfig appState
      when configDbConfig $ readInDbConfig False appState
    qSchemaCache :: IO (Maybe SchemaCache)
    qSchemaCache = do
      conf@AppConfig{..} <- getConfig appState
      (resultTime, result) <-
        let transaction = if configDbPreparedStatements then SQL.transaction else SQL.unpreparedTransaction in
        timeItT $ usePool appState (transaction SQL.ReadCommitted SQL.Read $ querySchemaCache conf)
      case result of
        Left e -> do
          putSCacheStatus appState SCPending
          putSchemaCache appState Nothing
          observer $ SchemaCacheErrorObs configDbSchemas configDbExtraSearchPath e
          return Nothing
        Right sCache -> do
          -- IMPORTANT: While the pending schema cache state starts from running the above querySchemaCache, only at this stage we block API requests due to the usage of an
          -- IORef on putSchemaCache. This is why SCacheStatus is put at SCPending here to signal the Admin server (using isPending) that we're on a recovery state.
          putSCacheStatus appState SCPending
          putSchemaCache appState $ Just sCache
          -- Flush the pool after loading the schema cache to reset any stale session cache entries
          -- We do it after successfully querying the schema cache (because this can fail and during retries we would flush the pool repeatedly unnecessarily)
          -- and after marking sCacheStatus as pending,
          flushPool appState
          observer $ SchemaCacheQueriedObs resultTime
          (t, _) <- timeItT $ observer $ SchemaCacheSummaryObs $ showSummary sCache
          observer $ SchemaCacheLoadedObs t
          putSCacheStatus appState SCLoaded
          return $ Just sCache
    shouldRetry :: RetryStatus -> (Maybe PgVersion, Maybe SchemaCache) -> IO Bool
    shouldRetry _ (pgVer, sCache) = do
      AppConfig{..} <- getConfig appState
      let itShould = configDbPoolAutomaticRecovery && (isNothing pgVer || isNothing sCache)
      return itShould
    retryPolicy :: RetryPolicy
    retryPolicy =
      let delayMicroseconds = 32*oneSecondInUs {-32 seconds-} in
      capDelay delayMicroseconds $ exponentialBackoff oneSecondInUs
    oneSecondInUs = 1000000 -- one second in microseconds
 -- | Reads the in-db config and reads the config file again
 -- | We don't retry reading the in-db config after it fails immediately, because it could have user errors. We just report the error and continue.
 readInDbConfig :: Bool -> AppState -> IO ()
 readInDbConfig startingUp appState@AppState{stateObserver=observer} = do
  conf <- getConfig appState
  pgVer <- getPgVersion appState
  dbSettings <-
    if configDbConfig conf then do
      qDbSettings <- usePool appState (queryDbSettings (quoteQi <$> configDbPreConfig conf) (configDbPreparedStatements conf))
      case qDbSettings of
        Left e -> do
          observer $ ConfigReadErrorObs e
          pure mempty
        Right x -> pure x
    else
      pure mempty
  (roleSettings, roleIsolationLvl) <-
    if configDbConfig conf then do
      rSettings <- usePool appState (queryRoleSettings pgVer (configDbPreparedStatements conf))
      case rSettings of
        Left e -> do
          observer $ QueryRoleSettingsErrorObs e
          pure (mempty, mempty)
        Right x -> pure x
    else
      pure mempty
  readAppConfig dbSettings (configFilePath conf) (Just $ configDbUri conf) roleSettings roleIsolationLvl >>= \case
    Left err   ->
      if startingUp then
        panic err -- die on invalid config if the program is starting up
      else
        observer $ ConfigInvalidObs err
    Right newConf -> do
      putConfig appState newConf
      -- After the config has reloaded, jwt-secret might have changed, so
      -- if it has changed, it is important to invalidate the jwt cache
      -- entries, because they were cached using the old secret
      update (getJwtCacheState appState) newConf
      if startingUp then
        pass
      else
        observer ConfigSucceededObs
@@ -0,0 +1,77 @@
 {-# LANGUAGE RecordWildCards #-}
 {-|
 Module      : PostgREST.Auth
 Description : PostgREST authentication functions.
 This module provides functions to deal with the JWT authentication (http://jwt.io).
 It also can be used to define other authentication functions,
 in the future Oauth, LDAP and similar integrations can be coded here.
 Authentication should always be implemented in an external service.
 In the test suite there is an example of simple login function that can be used for a
 very simple authentication system inside the PostgreSQL database.
 -}
 module PostgREST.Auth
  ( getResult
  , getJwtDur
  , getRole
  , middleware
  ) where
 import qualified Data.ByteString                 as BS
 import qualified Data.Vault.Lazy                 as Vault
 import qualified Network.HTTP.Types.Header       as HTTP
 import qualified Network.Wai                     as Wai
 import qualified Network.Wai.Middleware.HttpAuth as Wai
 import Data.List        (lookup)
 import PostgREST.TimeIt (timeItT)
 import System.IO.Unsafe (unsafePerformIO)
 import PostgREST.AppState      (AppState, getConfig, getJwtCacheState,
                                getTime)
 import PostgREST.Auth.Jwt      (parseClaims)
 import PostgREST.Auth.JwtCache (lookupJwtCache)
 import PostgREST.Auth.Types    (AuthResult (..))
 import PostgREST.Config        (AppConfig (..))
 import PostgREST.Error         (Error (..))
 import Protolude
 -- | Validate authorization header
 --   Parse and store JWT claims for future use in the request.
 middleware :: AppState -> Wai.Middleware
 middleware appState app req respond = do
  conf@AppConfig{..} <- getConfig appState
  time <- getTime appState
  let token  = Wai.extractBearerAuth =<< lookup HTTP.hAuthorization (Wai.requestHeaders req)
      parseJwt = runExceptT $ lookupJwtCache jwtCacheState token >>= parseClaims conf time
      jwtCacheState = getJwtCacheState appState
  -- If ServerTimingEnabled -> calculate JWT validation time
  req' <- if configServerTimingEnabled then do
      (dur, authResult) <- timeItT parseJwt
      pure $ req { Wai.vault = Wai.vault req & Vault.insert authResultKey authResult & Vault.insert jwtDurKey dur }
    else do
      authResult <- parseJwt
      pure $ req { Wai.vault = Wai.vault req & Vault.insert authResultKey authResult }
  app req' respond
 authResultKey :: Vault.Key (Either Error AuthResult)
 authResultKey = unsafePerformIO Vault.newKey
 {-# NOINLINE authResultKey #-}
 getResult :: Wai.Request -> Maybe (Either Error AuthResult)
 getResult = Vault.lookup authResultKey . Wai.vault
 jwtDurKey :: Vault.Key Double
 jwtDurKey = unsafePerformIO Vault.newKey
 {-# NOINLINE jwtDurKey #-}
 getJwtDur :: Wai.Request -> Maybe Double
 getJwtDur =  Vault.lookup jwtDurKey . Wai.vault
 getRole :: Wai.Request -> Maybe BS.ByteString
 getRole req = authRole <$> (rightToMaybe =<< getResult req)
@@ -4,6 +4,8 @@ Description : PostgREST JWT support functions.
 This module provides functions to deal with JWT parsing and validation (http://jwt.io).
 -}
 {-# LANGUAGE DeriveGeneric         #-}
 {-# LANGUAGE FlexibleContexts      #-}
 {-# LANGUAGE ImpredicativeTypes    #-}
 {-# LANGUAGE LambdaCase            #-}
 {-# LANGUAGE NamedFieldPuns        #-}
@@ -14,10 +16,14 @@ module PostgREST.Auth.Jwt
  , parseClaims) where
 import qualified Data.Aeson                 as JSON
 import qualified Data.Aeson.Key             as K
 import qualified Data.Aeson.KeyMap          as KM
 import qualified Data.ByteString            as BS
 import qualified Data.ByteString.Internal   as BS
 import qualified Data.ByteString.Lazy.Char8 as LBS
 import qualified Data.Scientific            as Sci
 import qualified Data.Text                  as T
 import qualified Data.Vector                as V
 import qualified Jose.Jwk                   as JWT
 import qualified Jose.Jwt                   as JWT
@@ -28,9 +34,10 @@ import Data.Time.Clock         (UTCTime, nominalDiffTimeToSeconds)
 import Data.Time.Clock.POSIX   (utcTimeToPOSIXSeconds)
 import PostgREST.Auth.Types (AuthResult (..))
-import PostgREST.Config        (AppConfig (..), audMatchesCfg)
+import PostgREST.Config     (AppConfig (..), FilterExp (..), JSPath,
-import PostgREST.Config.JSPath (evaluateJSPath)
+                             JSPathExp (..), audMatchesCfg)
-import PostgREST.Error         (Error (..), JwtClaimsError (..),
+import PostgREST.Error      (Error (..),
                             JwtClaimsError (AudClaimNotStringOrArray, ExpClaimNotNumber, IatClaimNotNumber, JWTExpired, JWTIssuedAtFuture, JWTNotInAudience, JWTNotYetValid, NbfClaimNotNumber, ParsingClaimsFailed),
                             JwtDecodeError (..), JwtError (..))
 import Data.Aeson       ((.:?))
@@ -88,10 +95,13 @@ checkForErrors time audMatches = mconcat
 parseToken :: (MonadError Error m, MonadIO m) => JwkSet -> ByteString -> m JWT.JwtContent
 parseToken _ "" = throwError $ JwtErr $ JwtDecodeErr EmptyAuthHeader
 parseToken secret tkn = do
  -- secret <- liftEither . maybeToRight (JwtErr JwtSecretMissing) $ configJWKS
  tknWith3Parts <- hasThreeParts tkn
  eitherContent <- liftIO $ JWT.decode (JWT.keys secret) Nothing tknWith3Parts
  liftEither . mapLeft (JwtErr . jwtDecodeError) $ eitherContent
  --liftEither $ mapLeft JwtErr $ verifyClaims content
  where
      --hasThreeParts :: ByteString -> Either Error ByteString
      hasThreeParts token = case length $ BS.split (BS.c2w '.') token of
        3 -> pure token
        n -> throwError $ JwtErr $ JwtDecodeErr $ UnexpectedParts n
@@ -112,12 +122,30 @@ parseClaims cfg@AppConfig{configJwtRoleClaimKey, configDbAnonRole} time mclaims
  validateClaims time (audMatchesCfg cfg) mclaims
  -- role defaults to anon if not specified in jwt
  role <- liftEither . maybeToRight (JwtErr JwtTokenRequired) $
-    unquoted <$> evaluateJSPath (Just $ JSON.Object mclaims) configJwtRoleClaimKey <|> configDbAnonRole
+    unquoted <$> walkJSPath (Just $ JSON.Object mclaims) configJwtRoleClaimKey <|> configDbAnonRole
  pure AuthResult
-           { authClaims = mclaims
+           { authClaims = mclaims & KM.insert "role" (JSON.toJSON $ decodeUtf8 role)
           , authRole = role
           }
  where
    walkJSPath :: Maybe JSON.Value -> JSPath -> Maybe JSON.Value
    walkJSPath x                      []                = x
    walkJSPath (Just (JSON.Object o)) (JSPKey key:rest) = walkJSPath (KM.lookup (K.fromText key) o) rest
    walkJSPath (Just (JSON.Array ar)) (JSPIdx idx:rest) = walkJSPath (ar V.!? idx) rest
    walkJSPath (Just (JSON.Array ar)) [JSPFilter (EqualsCond txt)] = findFirstMatch (==) txt ar
    walkJSPath (Just (JSON.Array ar)) [JSPFilter (NotEqualsCond txt)] = findFirstMatch (/=) txt ar
    walkJSPath (Just (JSON.Array ar)) [JSPFilter (StartsWithCond txt)] = findFirstMatch T.isPrefixOf txt ar
    walkJSPath (Just (JSON.Array ar)) [JSPFilter (EndsWithCond txt)] = findFirstMatch T.isSuffixOf txt ar
    walkJSPath (Just (JSON.Array ar)) [JSPFilter (ContainsCond txt)] = findFirstMatch T.isInfixOf txt ar
    walkJSPath _                      _                 = Nothing
    findFirstMatch matchWith pattern = foldr checkMatch Nothing
      where
        checkMatch (JSON.String txt) acc
            | pattern `matchWith` txt = Just $ JSON.String txt
            | otherwise = acc
        checkMatch _ acc = acc
    unquoted :: JSON.Value -> BS.ByteString
    unquoted (JSON.String t) = encodeUtf8 t
    unquoted v               = LBS.toStrict $ JSON.encode v
@@ -4,7 +4,10 @@ Description : PostgREST JWT validation results Cache.
 This module provides functions to deal with the JWT cache.
 -}
 {-# LANGUAGE ExistentialQuantification #-}
 {-# LANGUAGE FlexibleInstances         #-}
 {-# LANGUAGE LambdaCase                #-}
 {-# LANGUAGE MultiParamTypeClasses     #-}
 {-# LANGUAGE NamedFieldPuns            #-}
 {-# LANGUAGE StrictData                #-}
@@ -20,12 +23,13 @@ import qualified Data.Aeson.KeyMap as KM
 import PostgREST.Error (Error (..), JwtError (JwtSecretMissing))
-import           Control.Concurrent.STM      (newTVarIO, readTVar, writeTVar)
+import           Control.Concurrent.STM      (newTVarIO, readTVar,
                                              writeTVar)
 import           Control.Concurrent.STM.TVar (TVar)
 import           Control.Monad.Error.Class   (liftEither)
 import           Data.ByteString             hiding (all, init)
-import           Data.IORef                  (IORef, newIORef, readIORef,
+import           Data.IORef                  (IORef, newIORef,
-                                              writeIORef)
+                                              readIORef, writeIORef)
 import           Jose.Jwk                    (JwkSet)
 import           PostgREST.Auth.Jwt          (parseAndDecodeClaims)
 import           PostgREST.Cache.Sieve       (alwaysValid)
@@ -38,7 +42,7 @@ import           Protolude
 data JwtCacheState = JwtCacheState ObservationHandler (IORef JwtCache)
 class CacheVariant m v where
-  cached :: (MonadError Error n, MonadIO n) => SC.Cache m ByteString v -> ByteString -> n JSON.Object
+  cached :: SC.Cache m ByteString v -> ByteString -> ExceptT Error IO JSON.Object
 {-|
 Jwt caching can have three different configurations:
@@ -56,12 +60,12 @@ data JwtCache =
  forall m v. CacheVariant m v => JwtCache JwkSet (TVar Int) (SC.Cache m ByteString v)
 instance CacheVariant IO (Either Error JSON.Object) where
-  cached c = liftIO . SC.cached c >=> liftEither
+  cached c = lift . SC.cached c >=> liftEither
 instance CacheVariant (ExceptT Error IO) JSON.Object where
-  cached c = liftIO . runExceptT . SC.cached c >=> liftEither
+  cached = SC.cached
-decode :: (MonadError Error m, MonadIO m) => JwtCache -> ByteString -> m JSON.Object
+decode :: JwtCache -> ByteString -> ExceptT Error IO JSON.Object
 decode JwtNoJwks        = const $ throwError (JwtErr JwtSecretMissing)
 decode (JwtNoCache key) = parseAndDecodeClaims key
 decode (JwtCache _ _ c) = cached c
@@ -106,5 +110,5 @@ newJwtCache AppConfig{configJWKS, configJwtCacheMaxEntries} observationHandler =
            (const . const $ lift $ observationHandler JwtCacheEviction) -- evictions metrics
            alwaysValid) -- no invalidation for now
-lookupJwtCache :: (MonadError Error m, MonadIO m) => JwtCacheState -> Maybe ByteString -> m JSON.Object
+lookupJwtCache :: JwtCacheState -> Maybe ByteString -> ExceptT Error IO JSON.Object
 lookupJwtCache (JwtCacheState _ cacheState) k = liftIO (readIORef cacheState) >>= flip (maybe (pure KM.empty)) k . decode
@@ -6,9 +6,7 @@ import qualified Data.Aeson        as JSON
 import qualified Data.Aeson.KeyMap as KM
 import qualified Data.ByteString   as BS
-- |
+-- | Parse result for JWT Claims
 -- Parse and store result for JWT Claims. Can be accessed in
 -- db through GUCs (for RLS etc)
 data AuthResult = AuthResult
  { authClaims :: KM.KeyMap JSON.Value
  , authRole   :: BS.ByteString
@@ -42,13 +42,11 @@ runClientCommand conf CmdReady = Client.ready conf
 -- | Run postgrest with command
 runAppCommand :: AppConfig -> RunCommand -> IO ()
 runAppCommand conf@AppConfig{..} runCmd = do
  mainThreadId <- myThreadId
  mainThreadIdRef <- mkWeakThreadId mainThreadId
  -- Per https://github.com/PostgREST/postgrest/issues/268, we want to
  -- explicitly close the connections to PostgreSQL on shutdown.
  -- 'AppState.destroy' takes care of that.
  bracket
-    (AppState.init conf (killThread mainThreadId))
+    (AppState.init conf)
    AppState.destroy
    (\appState -> case runCmd of
      CmdDumpConfig -> do
@@ -57,21 +55,22 @@ runAppCommand conf@AppConfig{..} runCmd = do
      CmdDumpSchema -> do
        when configDbConfig $ AppState.readInDbConfig True appState
        putStrLn =<< dumpSchema appState
-      CmdRun -> App.run appState mainThreadIdRef)
+      CmdRun -> App.run appState)
 -- | Dump SchemaCache schema to JSON
 dumpSchema :: AppState -> IO LBS.ByteString
 dumpSchema appState = do
  conf@AppConfig{..} <- AppState.getConfig appState
  pgVer <- AppState.getPgVersion appState
  result <-
-    AppState.usePool appState (SQL.transactionNoRetry SQL.ReadCommitted SQL.Read $ querySchemaCache pgVer conf)
+    let transaction = if configDbPreparedStatements then SQL.transaction else SQL.unpreparedTransaction in
    AppState.usePool appState
      (transaction SQL.ReadCommitted SQL.Read $ querySchemaCache conf)
  case result of
    Left e -> do
      let observer = AppState.getObserver appState
      observer $ SchemaCacheErrorObs configDbSchemas configDbExtraSearchPath e
      exitFailure
-    Right (sCache, _) -> return $ JSON.encode sCache
+    Right sCache -> return $ JSON.encode sCache
 -- | Command line interface options
 data CLI = CLI
@@ -8,9 +8,11 @@ This module provides implementation of a mutable cache on Sieve algorithm.
 {-# LANGUAGE GADTs           #-}
 {-# LANGUAGE LambdaCase      #-}
 {-# LANGUAGE NamedFieldPuns  #-}
 {-# LANGUAGE PolyKinds       #-}
 {-# LANGUAGE RecordWildCards #-}
 {-# LANGUAGE RecursiveDo     #-}
 {-# LANGUAGE StrictData      #-}
 {-# LANGUAGE TupleSections   #-}
 module PostgREST.Cache.Sieve (
      Cache
@@ -3,16 +3,19 @@ Module      : PostgREST.Config
 Description : Manages PostgREST configuration type and parser.
 -}
 {-# LANGUAGE FlexibleContexts      #-}
 {-# LANGUAGE FlexibleInstances     #-}
 {-# LANGUAGE LambdaCase            #-}
 {-# LANGUAGE MultiParamTypeClasses #-}
 {-# LANGUAGE RecordWildCards       #-}
 {-# OPTIONS_GHC -fno-warn-type-defaults #-}
 {-# LANGUAGE NamedFieldPuns  #-}
 module PostgREST.Config
  ( AppConfig (..)
  , Environment
  , JSPath
-  , defaultRoleJSPathKey
+  , JSPathExp(..)
  , FilterExp(..)
  , LogLevel(..)
  , OpenAPIMode(..)
  , Proxy(..)
@@ -24,10 +27,8 @@ module PostgREST.Config
  , parseSecret
  , addFallbackAppName
  , addTargetSessionAttrs
  , toConnectionSettings
  , exampleConfigFile
  , audMatchesCfg
  , Verbosity (..)
  ) where
 import qualified Data.Aeson             as JSON
@@ -39,8 +40,6 @@ import qualified Data.Map.Strict                     as M
 import qualified Data.String            as S
 import qualified Data.Text              as T
 import qualified Data.Text.Encoding     as T
 import qualified Hasql.Connection.Setting            as SQL
 import qualified Hasql.Connection.Setting.Connection as SQL
 import qualified Jose.Jwa               as JWT
 import qualified Jose.Jwk               as JWT
@@ -57,14 +56,16 @@ import Numeric                 (readOct, showOct)
 import System.Environment      (getEnvironment)
 import System.Posix.Types      (FileMode)
-import PostgREST.Config.Database         (RoleIsolationLvl, RoleSettings)
+import PostgREST.Config.Database         (RoleIsolationLvl,
-import PostgREST.Config.JSPath           (JSPath (..), defaultRoleJSPathKey,
+                                          RoleSettings)
-                                          dumpJSPath, pRoleClaimKey)
+import PostgREST.Config.JSPath           (FilterExp (..), JSPath,
-import PostgREST.Config.Proxy            (Proxy (..), isMalformedProxyUri,
+                                          JSPathExp (..), dumpJSPath,
-                                          toURI)
+                                          pRoleClaimKey)
-import PostgREST.SchemaCache.Identifiers (QualifiedIdentifier (..), toQi)
+import PostgREST.Config.Proxy            (Proxy (..),
                                          isMalformedProxyUri, toURI)
 import PostgREST.SchemaCache.Identifiers (QualifiedIdentifier, dumpQi,
                                          toQi)
 import PostgREST.Version (prettyVersion)
 import Protolude hiding (Proxy, toList)
 audMatchesCfg :: AppConfig -> Text -> Bool
@@ -72,7 +73,6 @@ audMatchesCfg =  maybe (const True) (==) . configJwtAudience
 data AppConfig = AppConfig
  { configAppSettings              :: [(Text, Text)]
  , configClientErrorVerbosity      :: Verbosity
  , configDbAggregates             :: Bool
  , configDbAnonRole               :: Maybe BS.ByteString
  , configDbChannel                :: Text
@@ -107,23 +107,18 @@ data AppConfig = AppConfig
  , configOpenApiMode              :: OpenAPIMode
  , configOpenApiSecurityActive    :: Bool
  , configOpenApiServerProxyUri    :: Maybe Text
-  , configServerCorsAllowedOrigins  :: [Text]
+  , configServerCorsAllowedOrigins :: Maybe [Text]
  , configServerHost               :: Text
  , configServerPort               :: Int
  , configServerReusePort           :: Bool
  , configServerTraceHeader        :: Maybe (CI.CI BS.ByteString)
  , configServerTimingEnabled      :: Bool
  , configServerUnixSocket         :: Maybe FilePath
  , configServerUnixSocketMode     :: FileMode
  , configUrlUseLegacyTargetNames   :: Bool
  , configAdminServerHost          :: Text
  , configAdminServerPort          :: Maybe Int
  , configAdminServerUnixSocket     :: Maybe FilePath
  , configAdminServerUnixSocketMode :: FileMode
  , configRoleSettings             :: RoleSettings
  , configRoleIsoLvl               :: RoleIsolationLvl
-  , configInternalSCQuerySleepFst   :: Maybe Int32
+  , configInternalSCQuerySleep     :: Maybe Int32
  , configInternalSCQuerySleepSnd   :: Maybe Int32
  }
 data LogLevel = LogCrit | LogError | LogWarn | LogInfo | LogDebug
@@ -137,15 +132,6 @@ dumpLogLevel = \case
  LogInfo  -> "info"
  LogDebug -> "debug"
 data Verbosity
  = Minimal
  | Verbose
 dumpClientErrorVerbosity :: Verbosity -> Text
 dumpClientErrorVerbosity = \case
  Minimal -> "minimal"
  Verbose -> "verbose"
 data OpenAPIMode = OAFollowPriv | OAIgnorePriv | OADisabled
  deriving Eq
@@ -158,12 +144,11 @@ dumpOpenApiMode = \case
 -- | Dump the config
 toText :: AppConfig -> Text
 toText conf =
-  unlines $ sort $ (\(k, v) -> k <> " = " <> v) <$> pgrstSettings ++ appSettings
+  unlines $ (\(k, v) -> k <> " = " <> v) <$> pgrstSettings ++ appSettings
  where
    -- apply conf to all pgrst settings
    pgrstSettings = (\(k, v) -> (k, v conf)) <$>
-      [("client-error-verbosity",    q . dumpClientErrorVerbosity . configClientErrorVerbosity)
+      [("db-aggregates-enabled",         T.toLower . show . configDbAggregates)
      ,("db-aggregates-enabled",         T.toLower . show . configDbAggregates)
      ,("db-anon-role",              q . T.decodeUtf8 . fromMaybe "" . configDbAnonRole)
      ,("db-channel",                q . configDbChannel)
      ,("db-channel-enabled",            T.toLower . show . configDbChannelEnabled)
@@ -185,7 +170,7 @@ toText conf =
      ,("db-tx-end",                 q . showTxEnd)
      ,("db-uri",                    q . configDbUri)
      ,("jwt-aud",                   q . fromMaybe mempty . configJwtAudience)
-      ,("jwt-role-claim-key",        q . dumpJSPath . configJwtRoleClaimKey)
+      ,("jwt-role-claim-key",        q . T.intercalate mempty . fmap dumpJSPath . configJwtRoleClaimKey)
      ,("jwt-secret",                q . T.decodeUtf8 . showJwtSecret)
      ,("jwt-secret-is-base64",          T.toLower . show . configJwtSecretIsBase64)
      ,("jwt-cache-max-entries",         show . configJwtCacheMaxEntries)
@@ -194,19 +179,15 @@ toText conf =
      ,("openapi-mode",              q . dumpOpenApiMode . configOpenApiMode)
      ,("openapi-security-active",       T.toLower . show . configOpenApiSecurityActive)
      ,("openapi-server-proxy-uri",  q . fromMaybe mempty . configOpenApiServerProxyUri)
-      ,("server-cors-allowed-origins", q . T.intercalate "," . configServerCorsAllowedOrigins)
+      ,("server-cors-allowed-origins",      q . maybe "" (T.intercalate ",") . configServerCorsAllowedOrigins)
      ,("server-host",               q . configServerHost)
      ,("server-port",                   show . configServerPort)
      ,("server-reuseport",              T.toLower . show . configServerReusePort)
      ,("server-trace-header",       q . T.decodeUtf8 . maybe mempty CI.original . configServerTraceHeader)
      ,("server-timing-enabled",         T.toLower . show . configServerTimingEnabled)
      ,("server-unix-socket",        q . maybe mempty T.pack . configServerUnixSocket)
      ,("server-unix-socket-mode",   q . T.pack . showSocketMode)
      ,("url-use-legacy-target-names",   T.toLower . show . configUrlUseLegacyTargetNames)
      ,("admin-server-host",         q . configAdminServerHost)
      ,("admin-server-port",             maybe "\"\"" show . configAdminServerPort)
      ,("admin-server-unix-socket",  q . maybe mempty T.pack . configAdminServerUnixSocket)
      ,("admin-server-unix-socket-mode", q . T.pack . showAdminSocketMode)
      ]
    -- quote all app.settings
@@ -215,10 +196,6 @@ toText conf =
    -- quote strings and replace " with \"
    q s = "\"" <> T.replace "\"" "\\\"" s <> "\""
    dumpQi :: QualifiedIdentifier -> Text
    dumpQi (QualifiedIdentifier s i) =
      (if T.null s then mempty else s <> ".") <> i
    showTxEnd c = case (configDbTxRollbackAll c, configDbTxAllowOverride c) of
      ( False, False ) -> "commit"
      ( False, True  ) -> "commit-allow-override"
@@ -230,7 +207,6 @@ toText conf =
      where
        secret = fromMaybe mempty $ configJwtSecret c
    showSocketMode c = showOct (configServerUnixSocketMode c) mempty
    showAdminSocketMode c = showOct (configAdminServerUnixSocketMode c) mempty
 -- This class is needed for the polymorphism of overrideFromDbOrEnvironment
 -- because C.required and C.optional have different signatures
@@ -272,7 +248,6 @@ parser :: Maybe FilePath -> Environment -> [(Text, Text)] -> RoleSettings -> Rol
 parser optPath env dbSettings roleSettings roleIsolationLvl =
  AppConfig
    <$> parseAppSettings "app.settings"
    <*> parseErrorVerbosity "client-error-verbosity"
    <*> (fromMaybe False <$> optBool "db-aggregates-enabled")
    <*> (fmap encodeUtf8 <$> optString "db-anon-role")
    <*> (fromMaybe "pgrst" <$> optString "db-channel")
@@ -293,7 +268,8 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
    <*> (fromMaybe True <$> optBool "db-prepared-statements")
    <*> (fmap toQi <$> optWithAlias (optString "db-root-spec")
                                    (optString "root-spec"))
-    <*> parseDbSchemas "db-schemas" "db-schema"
+    <*> (fromList . maybe ["public"] splitOnCommas <$> optWithAlias (optString "db-schemas")
                                                                    (optString "db-schema"))
    <*> (fromMaybe True <$> optBool "db-config")
    <*> (fmap toQi <$> optString "db-pre-config")
    <*> parseTxEnd "db-tx-end" snd
@@ -316,30 +292,17 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
    <*> parseCORSAllowedOrigins "server-cors-allowed-origins"
    <*> (defaultServerHost <$> optString "server-host")
    <*> parseServerPort "server-port"
    <*> (fromMaybe False <$> optBool "server-reuseport")
    <*> (fmap (CI.mk . encodeUtf8) <$> optString "server-trace-header")
    <*> (fromMaybe False <$> optBool "server-timing-enabled")
    <*> (fmap T.unpack <$> optString "server-unix-socket")
    <*> parseSocketFileMode "server-unix-socket-mode"
    <*> (fromMaybe True <$> optBool "url-use-legacy-target-names")
    <*> (defaultServerHost <$> optWithAlias (optString "admin-server-host")
                                            (optString "server-host"))
    <*> parseAdminServerPort "admin-server-port"
    <*> (fmap T.unpack <$> optString "admin-server-unix-socket")
    <*> parseSocketFileMode "admin-server-unix-socket-mode"
    <*> pure roleSettings
    <*> pure roleIsolationLvl
    <*> optInt "internal-schema-cache-query-sleep-before-queries"
    <*> optInt "internal-schema-cache-query-sleep"
  where
    parseErrorVerbosity :: C.Key -> C.Parser C.Config Verbosity
    parseErrorVerbosity k =
      optString k >>= \case
        Nothing        -> pure Verbose -- default
        Just "minimal" -> pure Minimal
        Just "verbose" -> pure Verbose
        Just _         -> fail "Invalid client-error-verbosity. Check your configuration."
    parseAppSettings :: C.Key -> C.Parser C.Config [(Text, Text)]
    parseAppSettings key = addFromEnv . fmap (fmap coerceText) <$> C.subassocs key C.value
      where
@@ -358,18 +321,6 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
        Just asp | asp == serverPort -> fail "admin-server-port cannot be the same as server-port"
                 | otherwise         -> pure $ Just asp
    parseDbSchemas :: C.Key -> C.Key -> C.Parser C.Config (NonEmpty Text)
    parseDbSchemas k al =
      optWithAlias (optString k) (optString al) >>= \case
        Nothing  -> pure $ fromList ["public"]
        Just s
          | "pg_catalog"         `elem` schemas -> fail (errMsg "pg_catalog")
          | "information_schema" `elem` schemas -> fail (errMsg "information_schema")
          | otherwise -> pure $ fromList schemas
          where
            schemas = splitOnCommas s
            errMsg x = "db-schemas does not allow schema: '" <> x <> "'"
    parseSocketFileMode :: C.Key -> C.Parser C.Config FileMode
    parseSocketFileMode k =
      optString k >>= \case
@@ -377,10 +328,10 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
        Just fileModeText ->
          case readOct $ T.unpack fileModeText of
            []              ->
-              fail $ "Invalid " <> T.unpack k <> ": not an octal"
+              fail "Invalid server-unix-socket-mode: not an octal"
            (fileMode, _):_ ->
              if fileMode < 384 || fileMode > 511
-                then fail $ "Invalid " <> T.unpack k <> ": needs to be between 600 and 777"
+                then fail "Invalid server-unix-socket-mode: needs to be between 600 and 777"
                else pure fileMode
    parseOpenAPIMode :: C.Key -> C.Parser C.Config OpenAPIMode
@@ -424,13 +375,13 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
    parseRoleClaimKey :: C.Key -> C.Key -> C.Parser C.Config JSPath
    parseRoleClaimKey k al =
      optWithAlias (optString k) (optString al) >>= \case
-        Nothing  -> pure defaultRoleJSPathKey -- $.role
+        Nothing  -> pure [JSPKey "role"]
        Just rck -> either (fail . show) pure $ pRoleClaimKey rck
    parseCORSAllowedOrigins k =
      optString k >>= \case
-        Nothing   -> pure []
+        Nothing   -> pure Nothing
-        Just orig -> pure (T.strip <$> T.splitOn "," orig)
+        Just orig -> pure $ Just (T.strip <$> T.splitOn "," orig)
    optWithAlias :: C.Parser C.Config (Maybe a) -> C.Parser C.Config (Maybe a) -> C.Parser C.Config (Maybe a)
    optWithAlias orig alias =
@@ -591,7 +542,6 @@ pgConnString conn | uriDesignator `T.isPrefixOf` conn || shortUriDesignator `T.i
 -- | Adds a `fallback_application_name` value to the connection string. This allows querying the PostgREST version on pg_stat_activity.
 --
 -- >>> import Protolude
 -- >>> let ver = "11.1.0 (5a04ec7)"::ByteString
 -- >>> let strangeVer = "11'1&0@#$%,.:\"[]{}?+^()=asdfqwer"::ByteString
 --
@@ -623,10 +573,10 @@ pgConnString conn | uriDesignator `T.isPrefixOf` conn || shortUriDesignator `T.i
 -- >>> addFallbackAppName ver "postgres://admin2:?pass?special?@localhost:5432/postgres"
 -- "postgres://admin2:?pass?special?@localhost:5432/postgres?fallback_application_name=PostgREST%2011.1.0%20%285a04ec7%29"
 --
-- >>> addFallbackAppName ver "postgresql://?dbname=postgres&host=/run/user/1000/postgrest/postgrest-with-postgresql-16-BuR/socket&user=some_protected_user&password=invalid_pass"
+-- addFallbackAppName ver "postgresql://?dbname=postgres&host=/run/user/1000/postgrest/postgrest-with-postgresql-16-BuR/socket&user=some_protected_user&password=invalid_pass"
 -- "postgresql://?dbname=postgres&host=/run/user/1000/postgrest/postgrest-with-postgresql-16-BuR/socket&user=some_protected_user&password=invalid_pass&fallback_application_name=PostgREST%2011.1.0%20%285a04ec7%29"
 --
-- >>> addFallbackAppName ver "postgresql:///postgres?host=/run/user/1000/postgrest/postgrest-with-postgresql-16-BuR/socket&user=some_protected_user&password=invalid_pass"
+-- addFallbackAppName ver "postgresql:///postgres?host=/run/user/1000/postgrest/postgrest-with-postgresql-16-BuR/socket&user=some_protected_user&password=invalid_pass"
 -- "postgresql:///postgres?host=/run/user/1000/postgrest/postgrest-with-postgresql-16-BuR/socket&user=some_protected_user&password=invalid_pass&fallback_application_name=PostgREST%2011.1.0%20%285a04ec7%29"
 addFallbackAppName :: ByteString -> Text -> Text
 addFallbackAppName version dbUri = addConnStringOption dbUri "fallback_application_name" pgrstVer
@@ -653,12 +603,6 @@ addFallbackAppName version dbUri = addConnStringOption dbUri "fallback_applicati
 addTargetSessionAttrs :: Text -> Text
 addTargetSessionAttrs dbUri = addConnStringOption dbUri "target_session_attrs" "read-write"
 toConnectionSettings :: (Text -> Text) -> AppConfig -> [SQL.Setting]
 toConnectionSettings transformUri AppConfig{configDbUri, configDbPreparedStatements} =
  [ SQL.connection $ SQL.string $ transformUri . addFallbackAppName prettyVersion $ configDbUri
  , SQL.usePreparedStatements configDbPreparedStatements
  ]
 addConnStringOption :: Text -> Text -> Text -> Text
 addConnStringOption dbUri key val = dbUri <>
  case pgConnString dbUri of
@@ -679,9 +623,6 @@ exampleConfigFile = S.unlines
  [ "## Admin server used for checks. It's disabled by default unless a port is specified."
  , "# admin-server-port = 3001"
  , ""
  , "# PostgREST error json verbosity config"
  , "# client-error-verbosity = \"verbose\""
  , ""
  , "## The database role to use when no client authentication is provided"
  , "# db-anon-role = \"anon\""
  , ""
@@ -734,13 +675,13 @@ exampleConfigFile = S.unlines
  , "## How to terminate database transactions"
  , "## Possible values are:"
  , "## commit (default)"
-  , "##   Transaction is always committed, this can not be overridden"
+  , "##   Transaction is always committed, this can not be overriden"
  , "## commit-allow-override"
-  , "##   Transaction is committed, but can be overridden with Prefer tx=rollback header"
+  , "##   Transaction is committed, but can be overriden with Prefer tx=rollback header"
  , "## rollback"
-  , "##   Transaction is always rolled back, this can not be overridden"
+  , "##   Transaction is always rolled back, this can not be overriden"
  , "## rollback-allow-override"
-  , "##   Transaction is rolled back, but can be overridden with Prefer tx=commit header"
+  , "##   Transaction is rolled back, but can be overriden with Prefer tx=commit header"
  , "db-tx-end = \"commit\""
  , ""
  , "## The standard connection URI format, documented at"
@@ -778,7 +719,6 @@ exampleConfigFile = S.unlines
  , ""
  , "server-host = \"!4\""
  , "server-port = 3000"
  , "server-reuseport = false"
  , ""
  , "## Allow getting the request-response timing information through the `Server-Timing` header"
  , "server-timing-enabled = false"
@@ -790,9 +730,4 @@ exampleConfigFile = S.unlines
  , "## Unix socket file mode"
  , "## When none is provided, 660 is applied by default"
  , "# server-unix-socket-mode = \"660\""
  , ""
  , "## Use legacy target names in relationship filters"
  , "## If active, allows using the target name of the relationship in filters even if it has an alias."
  , "## Otherwise it only allows the alias in filters"
  , "url-use-legacy-target-names = true"
  ]
@@ -7,6 +7,7 @@ module PostgREST.Config.Database
  , queryRoleSettings
  , RoleSettings
  , RoleIsolationLvl
  , TimezoneNames
  , toIsolationLevel
  ) where
@@ -30,6 +31,7 @@ import Protolude
 type RoleSettings     = (HM.HashMap ByteString (HM.HashMap ByteString ByteString))
 type RoleIsolationLvl = HM.HashMap ByteString SQL.IsolationLevel
 type TimezoneNames    = Set Text -- cache timezone names for prefer timezone=
 toIsolationLevel :: Text -> SQL.IsolationLevel
 toIsolationLevel a = case T.toLower a of
@@ -45,7 +47,6 @@ dbSettingsNames :: [Text]
 dbSettingsNames =
  (prefix <>) <$>
  ["db_aggregates_enabled"
  ,"client_error_verbosity"
  ,"db_anon_role"
  ,"db_pre_config"
  ,"db_extra_search_path"
@@ -68,11 +69,10 @@ dbSettingsNames =
  ,"server_cors_allowed_origins"
  ,"server_trace_header"
  ,"server_timing_enabled"
  ,"url_use_legacy_target_names"
  ]
-queryPgVersion :: Session PgVersion
+queryPgVersion :: Bool -> Session PgVersion
-queryPgVersion = statement mempty $ pgVersionStatement False
+queryPgVersion prepared = statement mempty $ pgVersionStatement prepared
 pgVersionStatement :: Bool -> SQL.Statement () PgVersion
 pgVersionStatement = SQL.Statement sql HE.noParams versionRow
@@ -91,9 +91,10 @@ pgVersionStatement = SQL.Statement sql HE.noParams versionRow
 --
 -- The example above will result in <prefix>jwt_aud = 'val'
 -- A setting on the database only will have no effect: ALTER DATABASE postgres SET <prefix>jwt_aud = 'xx'
-queryDbSettings :: Maybe Text -> Session [(Text, Text)]
+queryDbSettings :: Maybe Text -> Bool -> Session [(Text, Text)]
-queryDbSettings preConfFunc =
+queryDbSettings preConfFunc prepared =
-  SQL.transactionNoRetry SQL.ReadCommitted SQL.Read $ SQL.statement dbSettingsNames $ SQL.Statement sql (arrayParam HE.text) decodeSettings True
+  let transaction = if prepared then SQL.transaction else SQL.unpreparedTransaction in
  transaction SQL.ReadCommitted SQL.Read $ SQL.statement dbSettingsNames $ SQL.Statement sql (arrayParam HE.text) decodeSettings prepared
  where
    sql = encodeUtf8 [trimming|
      WITH
@@ -131,9 +132,10 @@ queryDbSettings preConfFunc =
      |]::Text
    decodeSettings = HD.rowList $ (,) <$> column HD.text <*> column HD.text
-queryRoleSettings :: PgVersion -> Session (RoleSettings, RoleIsolationLvl)
+queryRoleSettings :: PgVersion -> Bool -> Session (RoleSettings, RoleIsolationLvl)
-queryRoleSettings pgVer =
+queryRoleSettings pgVer prepared =
-  SQL.transactionNoRetry SQL.ReadCommitted SQL.Read $ SQL.statement mempty $ SQL.Statement sql HE.noParams (processRows <$> rows) True
+  let transaction = if prepared then SQL.transaction else SQL.unpreparedTransaction in
  transaction SQL.ReadCommitted SQL.Read $ SQL.statement mempty $ SQL.Statement sql HE.noParams (processRows <$> rows) prepared
  where
    sql = encodeUtf8 [trimming|
      with
@@ -0,0 +1,100 @@
 {-# OPTIONS_GHC -Wno-unused-do-bind #-}
 module PostgREST.Config.JSPath
  ( JSPath
  , JSPathExp(..)
  , FilterExp(..)
  , dumpJSPath
  , pRoleClaimKey
  ) where
 import qualified Text.ParserCombinators.Parsec as P
 import Data.Either.Combinators       (mapLeft)
 import Text.ParserCombinators.Parsec ((<?>))
 import Text.Read                     (read)
 import Protolude
 -- | full jspath, e.g. .property[0].attr.detail[?(@ == "role1")]
 type JSPath = [JSPathExp]
 -- NOTE: We only accept one JSPFilter expr (at the end of input)
 -- | jspath expression
 data JSPathExp
  = JSPKey Text         -- .property or ."property-dash"
  | JSPIdx Int          -- [0]
  | JSPFilter FilterExp -- [?(@ == "match")]
 data FilterExp
  = EqualsCond Text
  | NotEqualsCond Text
  | StartsWithCond Text
  | EndsWithCond Text
  | ContainsCond Text
 dumpJSPath :: JSPathExp -> Text
 -- TODO: this needs to be quoted properly for special chars
 dumpJSPath (JSPKey k) = "." <> show k
 dumpJSPath (JSPIdx i) = "[" <> show i <> "]"
 dumpJSPath (JSPFilter cond) = "[?(@" <> expr <> ")]"
  where
    expr =
      case cond of
        EqualsCond text     -> " == " <> show text
        NotEqualsCond text  -> " != " <> show text
        StartsWithCond text -> " ^== " <> show text
        EndsWithCond text   -> " ==^ " <> show text
        ContainsCond text   -> " *== " <> show text
 -- Used for the config value "role-claim-key"
 pRoleClaimKey :: Text -> Either Text JSPath
 pRoleClaimKey selStr =
  mapLeft show $ P.parse pJSPath ("failed to parse role-claim-key value (" <> toS selStr <> ")") (toS selStr)
 pJSPath :: P.Parser JSPath
 pJSPath = P.many1 pJSPathExp <* P.eof
 pJSPathExp :: P.Parser JSPathExp
 pJSPathExp = pJSPKey <|> pJSPFilter <|> pJSPIdx
 pJSPKey :: P.Parser JSPathExp
 pJSPKey = do
  P.char '.'
  val <- toS <$> P.many1 (P.alphaNum <|> P.oneOf "_$@") <|> pQuotedValue
  return (JSPKey val) <?> "pJSPKey: JSPath attribute key"
 pJSPIdx :: P.Parser JSPathExp
 pJSPIdx = do
  P.char '['
  num <- read <$> P.many1 P.digit
  P.char ']'
  return (JSPIdx num) <?> "pJSPIdx: JSPath array index"
 pJSPFilter :: P.Parser JSPathExp
 pJSPFilter = do
  P.try $ P.string "[?("
  condition <- pFilterConditionParser
  P.char ')'
  P.char ']'
  P.eof -- this should be the last jspath expression
  return (JSPFilter condition) <?> "pJSPFilter: JSPath filter exp"
 pFilterConditionParser :: P.Parser FilterExp
 pFilterConditionParser = do
  P.char '@'
  P.spaces
  filt <- matchOperator
  P.spaces
  filt <$> pQuotedValue
    where
      matchOperator =
        P.try (P.string "==^" $> EndsWithCond)
        <|> P.try (P.string "==" $> EqualsCond)
        <|> P.try (P.string "!=" $> NotEqualsCond)
        <|> P.try (P.string "^==" $> StartsWithCond)
        <|> P.try (P.string "*==" $> ContainsCond)
 pQuotedValue :: P.Parser Text
 pQuotedValue = toS <$> (P.char '"' *> P.many (P.noneOf "\"") <* P.char '"')
@@ -1,11 +1,11 @@
 {-# LANGUAGE DeriveAnyClass #-}
 {-# LANGUAGE DeriveGeneric  #-}
 module PostgREST.Config.PgVersion
  ( PgVersion(..)
  , minimumPgVersion
  , pgVersion140
  , pgVersion150
  , pgVersion170
  , pgVersion180
  , pgVersion190
  ) where
 import qualified Data.Aeson as JSON
@@ -25,7 +25,10 @@ instance Ord PgVersion where
 -- | Tells the minimum PostgreSQL version required by this version of PostgREST
 minimumPgVersion :: PgVersion
-minimumPgVersion = pgVersion140
+minimumPgVersion = pgVersion130
 pgVersion130 :: PgVersion
 pgVersion130 = PgVersion 130000 "13.0" "13.0"
 pgVersion140 :: PgVersion
 pgVersion140 = PgVersion 140000 "14.0" "14.0"
@@ -35,9 +38,3 @@ pgVersion150 = PgVersion 150000 "15.0" "15.0"
 pgVersion170 :: PgVersion
 pgVersion170 = PgVersion 170000 "17.0" "17.0"
 pgVersion180 :: PgVersion
 pgVersion180 = PgVersion 180000 "18.0" "18.0"
 pgVersion190 :: PgVersion
 pgVersion190 = PgVersion 190000 "19.0" "19.0"
@@ -2,6 +2,9 @@
 Module      : PostgREST.Cors
 Description : Wai Middleware to set cors policy.
 -}
 {-# LANGUAGE TupleSections #-}
 module PostgREST.Cors (middleware) where
 import qualified Data.ByteString.Char8       as BS
@@ -23,13 +26,11 @@ middleware appState app req res = do
  Wai.cors (corsPolicy $ configServerCorsAllowedOrigins conf) app req res
 -- | CORS policy to be used in by Wai Cors middleware
-corsPolicy :: [Text] -> Wai.Request -> Maybe Wai.CorsResourcePolicy
+corsPolicy :: Maybe [Text] -> Wai.Request -> Maybe Wai.CorsResourcePolicy
 corsPolicy corsAllowedOrigins req = case lookup "origin" headers of
  Just _ ->
    Just Wai.CorsResourcePolicy
-    { Wai.corsOrigins = case corsAllowedOrigins of
+    { Wai.corsOrigins = (, True) . map T.encodeUtf8 <$> corsAllowedOrigins
        []      -> Nothing
        origins -> Just (map T.encodeUtf8 origins, True)
    , Wai.corsMethods = ["GET", "POST", "PATCH", "PUT", "DELETE", "OPTIONS"]
    , Wai.corsRequestHeaders = "Authorization" : accHeaders
    , Wai.corsExposedHeaders = Just
@@ -19,8 +19,6 @@ module PostgREST.Error
  , JwtClaimsError(..)
  , errorPayload
  , status
  , noRelBetweenHint
  , noRpcHint
  ) where
 import qualified Data.Aeson                as JSON
@@ -44,52 +42,31 @@ import Network.HTTP.Types.Header (Header)
 import           PostgREST.MediaType (MediaType (..))
 import qualified PostgREST.MediaType as MediaType
 import PostgREST.Config                   (Verbosity (..))
 import PostgREST.SchemaCache              (SchemaCache (SchemaCache, dbTablesFuzzyIndex))
-import PostgREST.SchemaCache.Identifiers  (QualifiedIdentifier (..), Schema)
+import PostgREST.SchemaCache.Identifiers  (QualifiedIdentifier (..),
-import PostgREST.SchemaCache.Relationship (Cardinality (..), Junction (..),
+                                           Schema)
-                                           Relationship (..), RelationshipsMap)
+import PostgREST.SchemaCache.Relationship (Cardinality (..),
-import PostgREST.SchemaCache.Routine      (Routine (..), RoutineParam (..))
+                                           Junction (..),
-
+                                           Relationship (..),
-import PostgREST.Error.Types
+                                           RelationshipsMap)
-
+import PostgREST.SchemaCache.Routine      (Routine (..),
                                           RoutineParam (..))
 import Protolude
-- $setup
+class (ErrorBody a, JSON.ToJSON a) => PgrstError a where
-- >>> import qualified Data.HashMap.Strict as HM
+  status   :: a -> HTTP.Status
-- >>> import PostgREST.SchemaCache.Identifiers (QualifiedIdentifier (..))
+  headers  :: a -> [Header]
 -- >>> import PostgREST.SchemaCache.Relationship (Relationship (..))
 -- >>> import PostgREST.SchemaCache.Routine (Routine (..), RoutineParam (..))
-- | Encode Error to ByteString
+  errorPayload :: a -> LByteString
-errorPayload :: (ErrorBody a, ErrorHeaders a) => Verbosity -> a -> LByteString
+  errorPayload = JSON.encode
 errorPayload verb = JSON.encode . toJsonPgrstError verb
  where
    toJsonPgrstError :: (ErrorBody a, ErrorHeaders a) => Verbosity -> a -> JSON.Value
    toJsonPgrstError Verbose err = JSON.object [
        "code"    .= code err
      , "message" .= message err
      , "details" .= details err
      , "hint"    .= hint err
      ]
    toJsonPgrstError Minimal err = JSON.object [
        "code"    .= code err
      , "message" .= message err
      ]
-- | Create HTTP response from Error
+  errorResponseFor :: a -> Response
-errorResponseFor :: (ErrorBody a, ErrorHeaders a) => Verbosity -> a -> Response
+  errorResponseFor err =
 errorResponseFor verb err =
    let
      baseHeader = MediaType.toContentType MTApplicationJSON
      cLHeader body = (,) "Content-Length" (show $ LBS.length body) :: Header
    pSHeader code' = ("Proxy-Status", "PostgREST; error=" <> T.encodeUtf8 code')
    in
-  responseLBS (status err) (baseHeader : cLHeader (errorPayload verb err) : pSHeader (code err) : headers err) $ errorPayload verb err
+    responseLBS (status err) (baseHeader : cLHeader (errorPayload err) : headers err) $ errorPayload err
 class ErrorHeaders a where
  status  :: a -> HTTP.Status
  headers :: a -> [Header]
 class ErrorBody a where
  code    :: a -> Text
@@ -97,7 +74,49 @@ class ErrorBody a where
  details :: a -> Maybe JSON.Value
  hint    :: a -> Maybe JSON.Value
-instance ErrorHeaders ApiRequestError where
+data ApiRequestError
  = AggregatesNotAllowed
  | MediaTypeError [ByteString]
  | InvalidBody ByteString
  | InvalidFilters
  | InvalidPreferences [ByteString]
  | InvalidRange RangeError
  | InvalidRpcMethod ByteString
  | NotEmbedded Text
  | NotImplemented Text
  | PutLimitNotAllowedError
  | QueryParamError QPError
  | RelatedOrderNotToOne Text Text
  | UnacceptableFilter Text
  | UnacceptableSchema Text [Text]
  | UnsupportedMethod ByteString
  | GucHeadersError
  | GucStatusError
  | PutMatchingPkError
  | SingularityError Integer
  | PGRSTParseError RaiseError
  | MaxAffectedViolationError Integer
  | InvalidResourcePath
  | OpenAPIDisabled
  | MaxAffectedRpcViolation
  deriving Show
 data QPError = QPError Text Text
  deriving Show
 data RaiseError
  = MsgParseError ByteString
  | DetParseError ByteString
  | NoDetail
  deriving Show
 data RangeError
  = NegativeLimit
  | LowerGTUpper
  | OutOfBounds Text Text
  deriving Show
 instance PgrstError ApiRequestError where
  status AggregatesNotAllowed{}      = HTTP.status400
  status MediaTypeError{}            = HTTP.status406
  status InvalidBody{}               = HTTP.status400
@@ -179,7 +198,7 @@ instance ErrorBody ApiRequestError where
  message InvalidFilters               = "Filters must include all and only primary key columns with 'eq' operators"
  message (UnacceptableSchema sch _)   = "Invalid schema: " <> sch
  message (MediaTypeError cts)         = "None of these media types are available: " <> T.intercalate ", " (map T.decodeUtf8 cts)
-  message (NotEmbedded resource _)     = "'" <> resource <> "' is not an embedded resource in this request"
+  message (NotEmbedded resource)       = "'" <> resource <> "' is not an embedded resource in this request"
  message GucHeadersError              = "response.headers guc must be a JSON array composed of objects with a single key and a string value"
  message GucStatusError               = "response.status guc must be a valid status code"
  message PutLimitNotAllowedError      = "limit/offset querystring parameters are not allowed for PUT"
@@ -211,19 +230,30 @@ instance ErrorBody ApiRequestError where
  details (InvalidPreferences prefs) = Just $ JSON.String $ T.decodeUtf8 ("Invalid preferences: " <> BS.intercalate ", " prefs)
  details (MaxAffectedViolationError n) = Just $ JSON.String $ T.unwords ["The query affects", show n, "rows"]
  details (NotImplemented details') = Just $ JSON.String details'
  details (NotEmbedded _ (Just _)) = Just $ JSON.String "Target names are not allowed in filters if they have an alias"
  details _ = Nothing
  -- HINT: Maybe JSON.Value
-  hint (NotEmbedded resource Nothing) = Just $ JSON.String $ "Verify that '" <> resource <> "' is included in the 'select' query parameter."
+  hint (NotEmbedded resource) = Just $ JSON.String $ "Verify that '" <> resource <> "' is included in the 'select' query parameter."
  hint (NotEmbedded _ (Just (name, alias))) = Just $ JSON.String $ "Change '" <> name <> "' to '" <> alias <> "' in filters, orders or limits."
  hint (PGRSTParseError raiseErr) = Just $ JSON.String $ pgrstParseErrorHint raiseErr
  hint (UnacceptableSchema _ schemas) = Just $ JSON.String $ "Only the following schemas are exposed: "  <> T.intercalate ", " schemas
  hint _ = Nothing
-instance ErrorHeaders SchemaCacheError where
+instance JSON.ToJSON ApiRequestError where
  toJSON err = toJsonPgrstError
    (code err) (message err) (details err) (hint err)
 data SchemaCacheError
  = AmbiguousRelBetween Text Text [Relationship]
  | AmbiguousRpc [Routine]
  | NoRelBetween Text Text (Maybe Text) Text RelationshipsMap
  | NoRpc Text Text [Text] MediaType Bool [QualifiedIdentifier] [Routine]
  | ColumnNotFound Text Text
  | TableNotFound Text Text SchemaCache
  deriving Show
 instance PgrstError SchemaCacheError where
  status AmbiguousRelBetween{} = HTTP.status300
  status AmbiguousRpc{}        = HTTP.status300
  status NoRelBetween{}        = HTTP.status400
@@ -287,6 +317,18 @@ instance ErrorBody SchemaCacheError where
  hint _ = Nothing
 instance JSON.ToJSON SchemaCacheError where
  toJSON err = toJsonPgrstError
    (code err) (message err) (details err) (hint err)
 toJsonPgrstError :: Text -> Text -> Maybe JSON.Value -> Maybe JSON.Value -> JSON.Value
 toJsonPgrstError code' message' details' hint' = JSON.object [
    "code"     .= code'
  , "message"  .= message'
  , "details"  .= details'
  , "hint"     .= hint'
  ]
 -- |
 -- If no relationship is found then:
 --
@@ -305,6 +347,9 @@ instance ErrorBody SchemaCacheError where
 -- >>> noRelBetweenHint "films" "role" "api" rels
 -- Just "Perhaps you meant 'roles' instead of 'role'."
 --
 -- >>> noRelBetweenHint "films" "role" "api" rels
 -- Just "Perhaps you meant 'roles' instead of 'role'."
 --
 -- >>> noRelBetweenHint "films" "actors" "api" rels
 -- Nothing
 --
@@ -454,7 +499,12 @@ pgrstParseErrorHint err = case err of
  MsgParseError _ -> "MESSAGE must be a JSON object with obligatory keys: 'code', 'message' and optional keys: 'details', 'hint'."
  _               -> "DETAIL must be a JSON object with obligatory keys: 'status', 'headers' and optional key: 'status_text'."
-instance ErrorHeaders PgError where
+data PgError = PgError Authenticated SQL.UsageError
  deriving Show
 type Authenticated = Bool
 instance PgrstError PgError where
  status (PgError authed usageError) = pgErrorStatus authed usageError
  headers (PgError _ (SQL.SessionUsageError (SQL.QueryError _ _ (SQL.ResultError (SQL.ServerError "PGRST" m d _ _p))))) =
@@ -469,33 +519,44 @@ instance ErrorHeaders PgError where
       then [("WWW-Authenticate", "Bearer") :: Header]
       else mempty
 proxyStatusHeader :: Text -> Header
 proxyStatusHeader code' = ("Proxy-Status", "PostgREST; error=" <> T.encodeUtf8 code')
 instance JSON.ToJSON PgError where
  toJSON (PgError _ usageError) = toJsonPgrstError
    (code usageError) (message usageError) (details usageError) (hint usageError)
 instance ErrorBody PgError where
  code    (PgError _ usageError) = code usageError
  message (PgError _ usageError) = message usageError
  details (PgError _ usageError) = details usageError
  hint    (PgError _ usageError) = hint usageError
 instance JSON.ToJSON SQL.UsageError where
  toJSON err = toJsonPgrstError
    (code err) (message err) (details err) (hint err)
 instance ErrorBody SQL.UsageError where
  code    (SQL.ConnectionUsageError _)                   = "PGRST000"
  code    (SQL.SessionUsageError (SQL.PipelineError e))  = code e
  code    (SQL.SessionUsageError (SQL.QueryError _ _ e)) = code e
  code    SQL.AcquisitionTimeoutUsageError               = "PGRST003"
  message (SQL.ConnectionUsageError _) = "Database connection error."
  message (SQL.SessionUsageError (SQL.PipelineError e))  = message e
  message (SQL.SessionUsageError (SQL.QueryError _ _ e)) = message e
  message SQL.AcquisitionTimeoutUsageError = "Timed out acquiring connection from connection pool."
  details (SQL.ConnectionUsageError e) = JSON.String . T.decodeUtf8 <$> e
  details (SQL.SessionUsageError (SQL.PipelineError e))  = details e
  details (SQL.SessionUsageError (SQL.QueryError _ _ e)) = details e
  details SQL.AcquisitionTimeoutUsageError               = Nothing
  hint    (SQL.ConnectionUsageError _)                   = Nothing
  hint    (SQL.SessionUsageError (SQL.PipelineError e))  = hint e
  hint    (SQL.SessionUsageError (SQL.QueryError _ _ e)) = hint e
  hint    SQL.AcquisitionTimeoutUsageError               = Nothing
 instance JSON.ToJSON SQL.CommandError where
  toJSON err = toJsonPgrstError
    (code err) (message err) (details err) (hint err)
 instance ErrorBody SQL.CommandError where
  -- Special error raised with code PGRST, to allow full response control
  code (SQL.ResultError (SQL.ServerError "PGRST" m d _ _)) =
@@ -537,13 +598,8 @@ instance ErrorBody SQL.CommandError where
 pgErrorStatus :: Bool -> SQL.UsageError -> HTTP.Status
 pgErrorStatus _      (SQL.ConnectionUsageError _) = HTTP.status503
 pgErrorStatus _      SQL.AcquisitionTimeoutUsageError = HTTP.status504
 pgErrorStatus _      (SQL.SessionUsageError (SQL.PipelineError (SQL.ClientError _)))       = HTTP.status503
 pgErrorStatus _      (SQL.SessionUsageError (SQL.QueryError _ _ (SQL.ClientError _)))      = HTTP.status503
-pgErrorStatus authed (SQL.SessionUsageError (SQL.PipelineError (SQL.ResultError rError)))  = mapSQLtoHTTP authed rError
+pgErrorStatus authed (SQL.SessionUsageError (SQL.QueryError _ _ (SQL.ResultError rError))) =
 pgErrorStatus authed (SQL.SessionUsageError (SQL.QueryError _ _ (SQL.ResultError rError))) = mapSQLtoHTTP authed rError
 mapSQLtoHTTP :: Bool -> SQL.ResultError -> HTTP.Status
 mapSQLtoHTTP authed rError =
  case rError of
    (SQL.ServerError c m d _ _) ->
      case BS.unpack c of
@@ -597,45 +653,86 @@ mapSQLtoHTTP authed rError =
    _                       -> HTTP.status500
-instance ErrorHeaders Error where
+data Error
-  status (ApiRequestErr err)  = status err
+  = ApiRequestError ApiRequestError
  | SchemaCacheErr SchemaCacheError
  | JwtErr JwtError
  | NoSchemaCacheError
  | PgErr PgError
  deriving Show
 data JwtError
  = JwtDecodeErr JwtDecodeError
  | JwtSecretMissing
  | JwtTokenRequired
  | JwtClaimsErr JwtClaimsError
  deriving Show
 data JwtDecodeError
  = EmptyAuthHeader
  | UnexpectedParts Int
  | KeyError Text
  | BadAlgorithm Text
  | BadCrypto
  | UnsupportedTokenType
  | UnreachableDecodeError
  deriving Show
 data JwtClaimsError
  = JWTExpired
  | JWTNotYetValid
  | JWTIssuedAtFuture
  | JWTNotInAudience
  | ParsingClaimsFailed
  | ExpClaimNotNumber
  | NbfClaimNotNumber
  | IatClaimNotNumber
  | AudClaimNotStringOrArray
  deriving Show
 instance PgrstError Error where
  status (ApiRequestError err) = status err
  status (SchemaCacheErr err)  = status err
  status (JwtErr err)          = status err
  status NoSchemaCacheError    = HTTP.status503
  status (PgErr err)           = status err
-  headers (ApiRequestErr err)  = headers err
+  headers (ApiRequestError err)  = proxyStatusHeader (code err) : headers err
-  headers (SchemaCacheErr err) = headers err
+  headers (SchemaCacheErr err)   = proxyStatusHeader (code err) : headers err
-  headers (JwtErr err)         = headers err
+  headers (JwtErr err)           = proxyStatusHeader (code err) : headers err
-  headers (PgErr err)          = headers err
+  headers (PgErr err)            = proxyStatusHeader (code err) : headers err
-  headers NoSchemaCacheError   = mempty
+  headers err@NoSchemaCacheError = proxyStatusHeader (code err) : mempty
 instance JSON.ToJSON Error where
  toJSON err = toJsonPgrstError
    (code err) (message err) (details err) (hint err)
 instance ErrorBody Error where
-  code (ApiRequestErr err)  = code err
+  code (ApiRequestError err) = code err
  code (SchemaCacheErr err)  = code err
  code (JwtErr err)          = code err
  code NoSchemaCacheError    = "PGRST002"
  code (PgErr err)           = code err
-  message (ApiRequestErr err) = message err
+  message (ApiRequestError err) = message err
  message (SchemaCacheErr err)  = message err
  message (JwtErr err)          = message err
  message NoSchemaCacheError    = "Could not query the database for the schema cache. Retrying."
  message (PgErr err)           = message err
-  details (ApiRequestErr err)  = details err
+  details (ApiRequestError err) = details err
  details (SchemaCacheErr err)  = details err
  details (JwtErr err)          = details err
  details NoSchemaCacheError    = Nothing
  details (PgErr err)           = details err
-  hint (ApiRequestErr err)  = hint err
+  hint (ApiRequestError err) = hint err
  hint (SchemaCacheErr err)  = hint err
  hint (JwtErr err)          = hint err
  hint NoSchemaCacheError    = Nothing
  hint (PgErr err)           = hint err
-instance ErrorHeaders JwtError where
+instance PgrstError JwtError where
  status JwtDecodeErr{}   = HTTP.unauthorized401
  status JwtSecretMissing = HTTP.status500
  status JwtTokenRequired = HTTP.unauthorized401
@@ -646,6 +743,10 @@ instance ErrorHeaders JwtError where
  headers e@(JwtClaimsErr _) = [invalidTokenHeader $ message e]
  headers _                  = mempty
 instance JSON.ToJSON JwtError where
  toJSON err = toJsonPgrstError
    (code err) (message err) (details err) (hint err)
 instance ErrorBody JwtError where
  code JwtSecretMissing = "PGRST300"
  code (JwtDecodeErr _) = "PGRST301"
@@ -689,6 +790,18 @@ requiredTokenHeader :: Header
 requiredTokenHeader = ("WWW-Authenticate", "Bearer")
 -- For parsing byteString to JSON Object, used for allowing full response control
 data PgRaiseErrMessage = PgRaiseErrMessage {
  getCode    :: Text,
  getMessage :: Text,
  getDetails :: Maybe Text,
  getHint    :: Maybe Text
 }
 data PgRaiseErrDetails = PgRaiseErrDetails {
  getStatus     :: Int,
  getStatusText :: Maybe Text,
  getHeaders    :: Map Text Text
 }
 instance JSON.FromJSON PgRaiseErrMessage where
  parseJSON (JSON.Object m) =
@@ -0,0 +1,116 @@
 {-# LANGUAGE LambdaCase      #-}
 {-# LANGUAGE MultiWayIf      #-}
 {-# LANGUAGE RecordWildCards #-}
 module PostgREST.Listener (runListener) where
 import qualified Data.ByteString.Char8 as BS
 import qualified Hasql.Connection      as SQL
 import qualified Hasql.Notifications   as SQL
 import           PostgREST.AppState    (AppState, getConfig)
 import           PostgREST.Config      (AppConfig (..))
 import           PostgREST.Observation (Observation (..))
 import           PostgREST.Version     (prettyVersion)
 import qualified PostgREST.AppState as AppState
 import qualified PostgREST.Config   as Config
 import           Control.Arrow              ((&&&))
 import           Data.Bitraversable         (bisequence)
 import           Data.Either.Combinators    (whenRight)
 import qualified Data.Text                  as T
 import qualified Database.PostgreSQL.LibPQ  as LibPQ
 import qualified Hasql.Session              as SQL
 import           PostgREST.Config.Database  (queryPgVersion)
 import           PostgREST.Config.PgVersion (pgvFullName)
 import           Protolude
 -- | Starts the Listener in a thread
 runListener :: AppState -> IO ()
 runListener appState = do
  AppConfig{..} <- getConfig appState
  when configDbChannelEnabled $
    void . forkIO . void $ retryingListen appState False
 -- | Starts a LISTEN connection and handles notifications. It recovers with exponential backoff with a cap of 32 seconds, if the LISTEN connection is lost.
 -- | This function never returns (but can throw) and return type enforces that.
 retryingListen :: AppState -> Bool -> IO Void
 retryingListen appState hasDbListenerBug = do
  AppConfig{..} <- AppState.getConfig appState
  let
    dbChannel = toS configDbChannel
    onError err = do
      AppState.putIsListenerOn appState False
      observer $ DBListenFail dbChannel (Right err)
      when (isDbListenerBug err) $
        observer DBListenBugCallQueryFix
      unless configDbPoolAutomaticRecovery $
        killThread mainThreadId
      -- retry the listener
      delay <- AppState.getNextListenerDelay appState
      observer $ DBListenRetry delay
      threadDelay (delay * oneSecondInMicro)
      unless (delay == maxDelay) $
        AppState.putNextListenerDelay appState (delay * 2)
      -- loop running the listener
      retryingListen appState (isDbListenerBug err)
  -- Execute the listener with with error handling
  handle onError $ do
    -- Make sure we don't leak connections on errors
    bracket
      -- acquire connection
      (SQL.acquire $ toUtf8 (Config.addTargetSessionAttrs $ Config.addFallbackAppName prettyVersion configDbUri))
      -- release connection
      (`whenRight` releaseConnection) $
      -- use connection
      \case
        Right db -> do
          (pqHost, pqPort) <- SQL.withLibPQConnection db $ bisequence . (LibPQ.host &&& LibPQ.port)
          pgFullName <- SQL.run (queryPgVersion False) db >>= either throwIO (pure . pgvFullName)
          when hasDbListenerBug $ SQL.run callNotifQueryUsage db >>= either throwIO pure
          SQL.listen db $ SQL.toPgIdentifier dbChannel
          AppState.putIsListenerOn appState True
          delay <- AppState.getNextListenerDelay appState
          when (delay > 1) $ do -- if we did a retry
            -- assume we lost notifications, refresh the schema cache
            AppState.schemaCacheLoader appState
            -- reset the delay
            AppState.putNextListenerDelay appState 1
          observer $ DBListenStart pqHost pqPort pgFullName dbChannel
          -- wait for notifications
          -- this will never return, in case of an error it will throw and be caught by onError
          forever $ SQL.waitForNotifications handleNotification db
        Left err -> do
          observer $ DBListenFail dbChannel (Left err)
          exitFailure
  where
    observer = AppState.getObserver appState
    mainThreadId = AppState.getMainThreadId appState
    oneSecondInMicro = 1000000
    maxDelay = 32
    handleNotification channel msg =
      if | BS.null msg            -> observer (DBListenerGotSCacheMsg channel) >> cacheReloader
         | msg == "reload schema" -> observer (DBListenerGotSCacheMsg channel) >> cacheReloader
         | msg == "reload config" -> observer (DBListenerGotConfigMsg channel) >> AppState.readInDbConfig False appState
         | otherwise              -> pure () -- Do nothing if anything else than an empty message is sent
    cacheReloader =
      AppState.schemaCacheLoader appState
    releaseConnection = void . forkIO . handle (observer . DBListenerConnectionCleanupFail) . SQL.release
    isDbListenerBug e = "could not access status of transaction" `T.isInfixOf` show e
    -- Used to fix a Postgres bug in the listener, see: https://github.com/PostgREST/postgrest/issues/3147#issuecomment-3494591361
    -- This query advances the async notification query tail, which solves this issue.
    callNotifQueryUsage :: SQL.Session ()
    callNotifQueryUsage = SQL.sql "SELECT pg_notification_queue_usage();"
@@ -0,0 +1,272 @@
 {-# LANGUAGE LambdaCase      #-}
 {-# LANGUAGE RecordWildCards #-}
 {-|
 Module      : PostgREST.Logger
 Description : Logging based on the Observation.hs module. Access logs get sent to stdout and server diagnostic get sent to stderr.
 -}
 -- TODO log with buffering enabled to not lose throughput on logging levels higher than LogError
 module PostgREST.Logger
  ( middleware
  , observationLogger
  , init
  , LoggerState
  ) where
 import           Control.AutoUpdate                (defaultUpdateSettings,
                                                    mkAutoUpdate,
                                                    updateAction)
 import           Control.Debounce
 import qualified Data.ByteString.Char8             as BS
 import qualified Data.Text.Encoding                as T
 import qualified Hasql.Decoders                    as HD
 import qualified Hasql.DynamicStatements.Snippet   as SQL hiding (sql)
 import qualified Hasql.DynamicStatements.Statement as SQL
 import qualified Hasql.Statement                   as SQL
 import Data.Time (ZonedTime, defaultTimeLocale, formatTime,
                  getZonedTime)
 import qualified Network.Wai                          as Wai
 import qualified Network.Wai.Middleware.RequestLogger as Wai
 import Network.HTTP.Types.Status (Status, status400, status500)
 import System.IO.Unsafe          (unsafePerformIO)
 import PostgREST.Config      (LogLevel (..))
 import PostgREST.Observation
 import PostgREST.Query       (MainQuery (..))
 import qualified Data.ByteString.Lazy       as LBS
 import qualified Data.Text                  as T
 import qualified Hasql.Connection           as SQL
 import qualified Hasql.Pool.Observation     as SQL
 import           Numeric                    (showFFloat)
 import           PostgREST.Config.PgVersion (pgvName)
 import qualified PostgREST.Error            as Error
 import           Protolude
 data LoggerState = LoggerState
  { stateGetZTime               :: IO ZonedTime  -- ^ Time with time zone used for logs
  , stateLogDebouncePoolTimeout :: MVar (IO ())  -- ^ Logs with a debounce
  }
 init :: IO LoggerState
 init = do
  zTime <- mkAutoUpdate defaultUpdateSettings { updateAction = getZonedTime }
  LoggerState zTime <$> newEmptyMVar
 logWithDebounce :: LoggerState -> IO () -> IO ()
 logWithDebounce loggerState action = do
  debouncer <- tryReadMVar $ stateLogDebouncePoolTimeout loggerState
  case debouncer of
    Just d -> d
    Nothing -> do
      newDebouncer <-
        let oneSecond = 1000000 in
        mkDebounce defaultDebounceSettings
           { debounceAction = action
           , debounceFreq = 5*oneSecond
           , debounceEdge = leadingEdge -- logs at the start and the end
           }
      putMVar (stateLogDebouncePoolTimeout loggerState) newDebouncer
      newDebouncer
 -- TODO stop using this middleware to reuse the same "observer" pattern for all our logs
 middleware :: LogLevel -> (Wai.Request -> Maybe BS.ByteString) -> Wai.Middleware
 middleware logLevel getAuthRole =
    unsafePerformIO $
      Wai.mkRequestLogger Wai.defaultRequestLoggerSettings
      { Wai.outputFormat =
         Wai.ApacheWithSettings $
           Wai.defaultApacheSettings &
           Wai.setApacheRequestFilter (\_ res -> shouldLogResponse logLevel $ Wai.responseStatus res) &
           Wai.setApacheUserGetter getAuthRole
      , Wai.autoFlush = True
      , Wai.destination = Wai.Handle stdout
      }
 shouldLogResponse :: LogLevel -> Status -> Bool
 shouldLogResponse logLevel = case logLevel of
  LogCrit  -> const False
  LogError -> (>= status500)
  LogWarn  -> (>= status400)
  LogInfo  -> const True
  LogDebug -> const True
 -- All observations are logged except some that depend on the log-level
 observationLogger :: LoggerState -> LogLevel -> ObservationHandler
 observationLogger loggerState logLevel obs = case obs of
  o@(PoolAcqTimeoutObs _) -> do
    when (logLevel >= LogError) $ do
      logWithDebounce loggerState $
        logWithZTime loggerState $ observationMessage o
  o@(QueryErrorCodeHighObs _) -> do
    when (logLevel >= LogError) $ do
      logWithZTime loggerState $ observationMessage o
  o@SchemaCacheEmptyObs ->
    when (logLevel >= LogError) $ do
    logWithZTime loggerState $ observationMessage o
  o@(HasqlPoolObs _) -> do
    when (logLevel >= LogDebug) $ do
      logWithZTime loggerState $ observationMessage o
  QueryObs gq status -> do
    when (shouldLogResponse logLevel status) $
      logMainQ loggerState gq
  o@PoolRequest ->
    when (logLevel >= LogDebug) $ do
      logWithZTime loggerState $ observationMessage o
  o@PoolRequestFullfilled ->
    when (logLevel >= LogDebug) $ do
      logWithZTime loggerState $ observationMessage o
  o@PoolFlushed ->
    when (logLevel >= LogDebug) $ do
      logWithZTime loggerState $ observationMessage o
  o@JwtCacheEviction ->
    when (logLevel >= LogDebug) $ do
      logWithZTime loggerState $ observationMessage o
  o@(JwtCacheLookup _) ->
    when (logLevel >= LogDebug) $ do
      logWithZTime loggerState $ observationMessage o
  o@(WarpServerObs _) ->
    when (logLevel >= LogDebug) $ do
      logWithZTime loggerState $ observationMessage o
  o ->
    logWithZTime loggerState $ observationMessage o
 logWithZTime :: LoggerState -> Text -> IO ()
 logWithZTime loggerState txt = do
  zTime <- stateGetZTime loggerState
  hPutStrLn stderr $ toS (formatTime defaultTimeLocale "%d/%b/%Y:%T %z: " zTime) <> txt
 logMainQ :: LoggerState -> MainQuery -> IO ()
 logMainQ loggerState MainQuery{mqOpenAPI=(x, y, z),..} =
  let snipts  = renderSnippet <$> [mqTxVars, fromMaybe mempty mqPreReq, mqMain, x, y, z, fromMaybe mempty mqExplain]
      -- Does not log SQL when it's empty (happens on OPTIONS requests and when the openapi queries are not generated)
      logQ q = when (q /= mempty) $ logWithZTime loggerState $ showOnSingleLine '\n' $ T.decodeUtf8 q in
  mapM_ logQ snipts
 -- TODO: maybe patch upstream hasql-dynamic-statements so we have a less hackish way to convert
 -- the SQL.Snippet or maybe don't use hasql-dynamic-statements and resort to plain strings for the queries and use regular hasql
 renderSnippet :: SQL.Snippet -> ByteString
 renderSnippet snippet =
  let SQL.Statement sql _ _ _ = SQL.dynamicallyParameterized snippet decoder prepared
      decoder = HD.noResult -- unused
      prepared = False  -- unused
  in
    sql
 observationMessage :: Observation -> Text
 observationMessage = \case
  AdminStartObs address ->
    "Admin server listening on " <> address
  AdminServerCrashedObs ex ->
    "Admin server crashed unexpectedly: " <> (showOnSingleLine '\t' . show) ex
  AppStartObs ver ->
    "Starting PostgREST " <> T.decodeUtf8 ver <> "..."
  AppServerAddressObs address ->
    "API server listening on " <> address
  DBConnectedObs ver ->
    "Successfully connected to " <> ver
  ExitUnsupportedPgVersion pgVer minPgVer ->
    "Cannot run in this PostgreSQL version (" <> pgvName pgVer <> "), PostgREST needs at least " <> pgvName minPgVer
  ExitDBNoRecoveryObs ->
    "Automatic recovery disabled, exiting."
  ExitDBFatalError ServerAuthError usageErr ->
    "Failed to establish a connection. " <> jsonMessage usageErr
  ExitDBFatalError ServerPgrstBug usageErr ->
    "This is probably a bug in PostgREST, please report it at https://github.com/PostgREST/postgrest/issues. " <> jsonMessage usageErr
  ExitDBFatalError ServerError42P05 usageErr ->
    "If you are using connection poolers in transaction mode, try setting db-prepared-statements to false. " <> jsonMessage usageErr
  ExitDBFatalError ServerError08P01 usageErr ->
    "Connection poolers in statement mode are not supported." <> jsonMessage usageErr
  SchemaCacheEmptyObs ->
    T.decodeUtf8 . LBS.toStrict . Error.errorPayload $ Error.NoSchemaCacheError
  SchemaCacheErrorObs dbSchemas extraPaths usageErr ->
    "Failed to load the schema cache using "
      <> "db-schemas=" <> T.intercalate "," (toList dbSchemas)
      <> " and "
      <> "db-extra-search-path=" <> T.intercalate "," extraPaths <> ". " <> jsonMessage usageErr
  SchemaCacheQueriedObs resultTime ->
    "Schema cache queried in " <> showMillis resultTime  <> " milliseconds"
  SchemaCacheSummaryObs summary ->
    "Schema cache loaded " <> summary
  SchemaCacheLoadedObs resultTime ->
    "Schema cache loaded in " <> showMillis resultTime <> " milliseconds"
  ConnectionRetryObs delay ->
    "Attempting to reconnect to the database in " <> (show delay::Text) <> " seconds..."
  QueryPgVersionError usageErr ->
    "Failed to query the PostgreSQL version. " <> jsonMessage usageErr
  DBListenStart host port fullName channel -> do
    "Listener connected to " <> fullName <> " on " <> show (fold $ host <> fmap (":" <>) port) <> " and listening for database notifications on the " <> show channel <> " channel"
  DBListenFail channel listenErr ->
    "Failed listening for database notifications on the " <> show channel <> " channel. " <>
      either showListenerConnError showListenerException listenErr
  DBListenRetry delay ->
    "Retrying listening for database notifications in " <> (show delay::Text) <> " seconds..."
  DBListenBugCallQueryFix ->
    "This is likely a PostgreSQL bug in the notification queue, executing the following to try to solve it: SELECT pg_notification_queue_usage();"
  DBListenerGotSCacheMsg channel ->
    "Received a schema cache reload message on the " <> show channel <> " channel"
  DBListenerGotConfigMsg channel ->
    "Received a config reload message on the " <> show channel <> " channel"
  DBListenerConnectionCleanupFail ex ->
    "Failed during listener connection cleanup: " <> showOnSingleLine '\t' (show ex)
  QueryObs{} ->
    mempty -- TODO pending refactor: The logic for printing the query cannot be done here. Join the observationMessage function into observationLogger to avoid this mempty.
  ConfigReadErrorObs usageErr ->
    "Failed to query database settings for the config parameters." <> jsonMessage usageErr
  QueryRoleSettingsErrorObs usageErr ->
    "Failed to query the role settings. " <> jsonMessage usageErr
  QueryErrorCodeHighObs usageErr ->
    jsonMessage usageErr
  ConfigInvalidObs err ->
    "Failed reloading config: " <> err
  ConfigSucceededObs ->
     "Config reloaded"
  PoolInit poolSize ->
     "Connection Pool initialized with a maximum size of " <> show poolSize <> " connections"
  PoolAcqTimeoutObs usageErr ->
    jsonMessage usageErr
  HasqlPoolObs (SQL.ConnectionObservation uuid status) ->
    "Connection " <> show uuid <> (
      case status of
        SQL.ConnectingConnectionStatus   -> " is being established"
        SQL.ReadyForUseConnectionStatus  -> " is available"
        SQL.InUseConnectionStatus        -> " is used"
        SQL.TerminatedConnectionStatus reason -> " is terminated due to " <> case reason of
          SQL.AgingConnectionTerminationReason          -> "max lifetime"
          SQL.IdlenessConnectionTerminationReason       -> "max idletime"
          SQL.ReleaseConnectionTerminationReason        -> "release"
          SQL.NetworkErrorConnectionTerminationReason _ -> "network error" -- usage error is already logged, no need to repeat the same message.
    )
  PoolRequest ->
    "Trying to borrow a connection from pool"
  PoolRequestFullfilled ->
    "Borrowed a connection from the pool"
  PoolFlushed ->
    "Database connection pool flushed"
  JwtCacheLookup _ ->
    "Looked up a JWT in JWT cache"
  JwtCacheEviction ->
    "Evicted entry from JWT cache"
  TerminationUnixSignalObs signal ->
    "Received termination unix signal " <> signal
  WarpServerObs txt ->
    "Warp server: " <> txt
  where
    showMillis :: Double -> Text
    showMillis x = toS $ showFFloat (Just 1) x ""
    jsonMessage err = T.decodeUtf8 . LBS.toStrict . Error.errorPayload $ Error.PgError False err
    showListenerConnError :: SQL.ConnectionError -> Text
    showListenerConnError = maybe "Connection error" (showOnSingleLine '\t' . T.decodeUtf8)
    showListenerException :: SomeException -> Text
    showListenerException = showOnSingleLine '\t' . show
 showOnSingleLine :: Char -> Text -> Text
 showOnSingleLine split txt = T.intercalate " " $ T.filter (/= split) <$> T.lines txt -- the errors from hasql-notifications come intercalated with "\t\n"
--- a/Show More
+++ b/Show More