chore(deps): update cachix/install-nix-action digest to 13d8dd5

chore(deps): update actions/checkout action to v7.0.1
chore(deps): update cachix/install-nix-action digest to 630ae54
2026-08-13 21:06:08 +00:00 · 2026-07-23 20:11:36 +00:00 · 2026-07-15 19:53:33 +00:00 · 2026-07-10 20:26:38 +00:00 · 2026-06-19 19:08:03 +00:00 · 2026-06-03 18:34:24 +00:00
142 changed files with 12035 additions and 1183 deletions
@@ -1,15 +0,0 @@
 freebsd_instance:
  image_family: freebsd-13-1
 build_task:
  name: Build FreeBSD (Stack)
  install_script: pkg install -y postgresql13-client hs-stack git
  stack_cache:
    folders: /.stack
    fingerprint_script: cat postgrest.cabal stack.yaml.lock
    reupload_on_changes: false
  build_script: stack build -j 1 --local-bin-path . --copy-bins
  bin_artifacts:
    path: postgrest
@@ -2,5 +2,5 @@
 When submitting a new feature or fix:
 - Add a new entry to the CHANGELOG - https://github.com/PostgREST/postgrest/blob/main/CHANGELOG.md#unreleased
- If relevant, update the docs     - https://github.com/PostgREST/postgrest-docs
+- If relevant, update the docs
 -->
@@ -1,23 +0,0 @@
 name: Setup Nix
 description: Installs nix, sets up cachix and installs a subset of tooling.
 inputs:
  authToken:
    description: Token to pass to cachix
  tools:
    description: Tools to install with nix-env -iA <tools>
 runs:
  using: composite
  steps:
    - uses: cachix/install-nix-action@v22
      with:
        install_url: https://releases.nixos.org/nix/nix-2.13.3/install
    - uses: cachix/cachix-action@v12
      with:
        name: postgrest
        authToken: ${{ inputs.authToken }}
    - if: ${{ inputs.tools }}
      run: nix-env -f default.nix -iA ${{ inputs.tools }}
      shell: bash
@@ -1,18 +0,0 @@
 codecov:
  branch: main
  require_ci_to_pass: false
 comment: false
 coverage:
  status:
    project:
      default:
        target: auto
        threshold: 1%
        only_pulls: false
    patch:
      default:
        target: auto
        threshold: 1%
        only_pulls: true
@@ -1,11 +0,0 @@
 version: 2
 updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
  - package-ecosystem: github-actions
    directory: /.github/actions/setup-nix
    schedule:
      interval: weekly
@@ -1,57 +0,0 @@
 #!/usr/bin/env bash
 set -euo pipefail
 # Get the FreeBSD PostgREST executable built by CirrusCI for the given GITHUB_COMMIT in GITHUB_REPOSITORY
 # We use the GitHub API for 'check suites' to find the corresponding CirrusCI job, see:
 # https://docs.github.com/en/rest/reference/checks#list-check-suites-for-a-git-reference
 cirrus_artifact_name=bin
 gh_auth_header="Authorization: Bearer $GITHUB_TOKEN"
 gh_accept_header="Accept: application/vnd.github.v3+json"
 get_gh_check_runs_url() {
  gh_checks_list_url="https://api.github.com/repos/$GITHUB_REPOSITORY/commits/$GITHUB_COMMIT/check-suites"
  >&2 echo "Getting list of check-suites from $gh_checks_list_url ..."
  curl --fail -H "$gh_auth_header" -H "$gh_accept_header"  "$gh_checks_list_url" \
    | jq -r '.check_suites[] | select(.app.slug == "cirrus-ci") | .check_runs_url'
 }
 wait_for_cirrusci() {
  gh_check_runs_url="$(get_gh_check_runs_url)"
  >&2 echo "Waiting to CirrusCI run to complete (two hours maximum)..."
  for _ in $(seq 1 120); do
    echo "Checking for CirrusCI task status at $gh_check_runs_url ..."
    status=$(curl --fail -H "$gh_auth_header" "$gh_check_runs_url" | jq -r '.check_runs[] | .status')
    if [ "$status" == "completed" ]; then
      break
    else
      echo "CirrusCI task is still $status, waiting..."
      sleep 60
    fi
  done
 }
 # The CirrusCI taskid can change if a new check run is started for the same commit,
 # e.g. when pushing both a branch and tag. We make sure that we have the very
 # latest taskid by re-loading the 'gh_check_runs_url' and the 'check run' itself.
 get_cirrus_taskid() {
  gh_check_runs_url="$(get_gh_check_runs_url)"
  >&2 echo "Getting the CirrusCI task id from $gh_check_runs_url ..."
  curl --fail -H "$gh_auth_header" -H "$gh_accept_header" "$gh_check_runs_url" \
    | jq -r '.check_runs[] | .external_id'
 }
 download_artifact() {
  cirrus_task_id="$(get_cirrus_taskid)"
  cirrus_artifact_url="https://api.cirrus-ci.com/v1/artifact/task/$cirrus_task_id/$cirrus_artifact_name.zip"
  >&2 echo "Attemping to download the CirrusCI artifact from $cirrus_artifact_url ..."
  curl --fail "$cirrus_artifact_url" -o freebsd.zip
 }
 wait_for_cirrusci
 download_artifact
 echo "Unpacking executable..."
 unzip freebsd.zip -d .
 rm -rf freebsd.zip
@@ -1,12 +0,0 @@
 #!/usr/bin/env bash
 # Tag a release that will be built with Github Actions. The version is
 # read from 'postgrest.cabal'.
 version="$(grep -oP '^version:\s*\K.*' postgrest.cabal)"
 echo "Tagging version v$version"
 git tag -f "v$version"
 echo "Pushing tag..."
 git push -f origin "refs/tags/v$version"
@@ -1,68 +0,0 @@
 #!/bin/bash
 # This script builds PostgREST in a remote ARM server
 [ -z "$1" ] && { echo "Missing 1st argument: PostgREST github commit SHA"; exit 1; }
 [ -z "$2" ] && { echo "Missing 2nd argument: Build environment directory name"; exit 1; }
 [ -z "$3" ] && { echo "Missing 3rd argument: GHC version"; exit 1; }
 PGRST_GITHUB_COMMIT="$1"
 SCRIPT_DIR="$2"
 DOCKER_BUILD_DIR="$SCRIPT_DIR/docker-env"
 # latest is a shortcut documented on https://www.haskell.org/ghcup/guide/#tags-and-shortcuts
 CABAL_VERSION="latest"
 GHC_VERSION="$3"
 install_packages() {
  sudo apt-get update -y
  sudo apt-get upgrade -y
  sudo apt-get install -y git build-essential curl libffi-dev libffi7 libgmp-dev libgmp10 libncurses-dev libncurses5 libtinfo5 llvm libnuma-dev zlib1g-dev libpq-dev jq gcc
  sudo apt-get clean
 }
 install_ghcup() {
  export BOOTSTRAP_HASKELL_NONINTERACTIVE=1
  export BOOTSTRAP_HASKELL_MINIMAL=1
  curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
  source ~/.ghcup/env
 }
 install_cabal() {
  ghcup upgrade
  ghcup install cabal $CABAL_VERSION
  ghcup set cabal $CABAL_VERSION
 }
 install_ghc() {
  ghcup upgrade
  ghcup install ghc $GHC_VERSION
  ghcup set ghc $GHC_VERSION
 }
 install_packages
 # Add ghcup to the PATH for this session
 [ -f ~/.ghcup/env ] && source ~/.ghcup/env
 ghcup --version || install_ghcup
 ghcup set cabal $CABAL_VERSION || install_cabal
 ghcup set ghc $GHC_VERSION || install_ghc
 cd ~/$SCRIPT_DIR
 # Clone the repository and build the project
 git clone https://github.com/PostgREST/postgrest.git
 cd postgrest
 git checkout $PGRST_GITHUB_COMMIT
 cabal v2-update && cabal v2-build
 # Copy the built binary to the Dockerfile directory
 PGRST_BIN=$(cabal exec which postgrest | tail -1)
 cp $PGRST_BIN ~/$DOCKER_BUILD_DIR
 # Move and compress the built binary
 mkdir -p ~/$SCRIPT_DIR/result
 mv $PGRST_BIN ~/$SCRIPT_DIR/result
 cd ~/$SCRIPT_DIR
 tar -cJf result.tar.xz result
@@ -1,18 +0,0 @@
 # PostgREST docker hub image
 FROM ubuntu:focal 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
 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,50 +0,0 @@
 #!/bin/bash
 # This script publishes the Docker ARM images to Docker Hub.
 [ -z "$1" ] && { echo "Missing 1st argument: PostgREST github commit SHA"; exit 1; }
 [ -z "$2" ] && { echo "Missing 2nd argument: Docker repo"; exit 1; }
 [ -z "$3" ] && { echo "Missing 3rd argument: Docker username"; exit 1; }
 [ -z "$4" ] && { echo "Missing 4th argument: Docker password"; exit 1; }
 [ -z "$5" ] && { echo "Missing 5th argument: Build environment directory name"; exit 1; }
 [ -z "$6" ] && { echo "Missing 6th argument: PostgREST version"; exit 1; }
 PGRST_GITHUB_COMMIT="$1"
 DOCKER_REPO="$2"
 DOCKER_USER="$3"
 DOCKER_PASS="$4"
 SCRIPT_DIR="$5"
 PGRST_VERSION="v$6"
 IS_PRERELEASE="$7"
 DOCKER_BUILD_DIR="$SCRIPT_DIR/docker-env"
 clean_env()
 {
    sudo docker logout
 }
 # Login to Docker
 sudo docker logout
 { echo $DOCKER_PASS | sudo docker login -u $DOCKER_USER --password-stdin; } || { echo "Couldn't login to docker"; exit 1; }
 trap clean_env sigint sigterm exit
 # Move to the docker build environment
 cd ~/$DOCKER_BUILD_DIR
 # Push final images to Docker hub
 # NOTE: This command publishes a separate ARM image because the builds cannot
 #       be added to the manifest if they are not in the registry beforehand.
 #       This image must be manually deleted from Docker Hub at the end of the process.
 sudo docker buildx build --build-arg PGRST_GITHUB_COMMIT=$PGRST_GITHUB_COMMIT \
                         -t $DOCKER_REPO/postgrest:$PGRST_VERSION-arm \
                         --push .
 # Add the arm images to the manifest
 # NOTE: This assumes that there already is a `postgrest:<version>` image
 #       for the amd64 architecture pushed to Docker Hub
 sudo docker buildx imagetools create --append -t $DOCKER_REPO/postgrest:$PGRST_VERSION $DOCKER_REPO/postgrest:$PGRST_VERSION-arm
 [ -z $IS_PRERELEASE ] && sudo docker buildx imagetools create --append -t $DOCKER_REPO/postgrest:latest $DOCKER_REPO/postgrest:$PGRST_VERSION-arm
 sudo docker logout
@@ -1,78 +0,0 @@
 name: Cachix
 # This workflow serves to
 #   - keep cachix up to date with the main branch
 #   - incrementally update cachix for large dependency
 #     updates, e.g. after running postgrest-nixpkgs-upgrade,
 #     which can cause the main CI workflow to time out
 on:
  workflow_dispatch:
  push:
    branches:
      - main
      - rel-*
    tags:
      - v*
 jobs:
  Seed-Cachix:
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: Linux
            runs-on: ubuntu-latest
          - os: MacOS
            runs-on: macos-latest
    name: Seed ${{ matrix.os }}
    runs-on: ${{ matrix.runs-on }}
    steps:
      - uses: actions/checkout@v3
      - name: Setup Nix Environment
        uses: ./.github/actions/setup-nix
        with:
          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
      - name: Install cachix tooling
        run: |
          nix-env -f default.nix -iA devTools.pushCachix.bin
          postgrest-push-cachix
      - name: Seed dynamic postgrest build
        run: |
          nix-build -A postgrestPackage
          postgrest-push-cachix
      - name: Seed style tools
        run: |
          nix-build -A style
          postgrest-push-cachix
      - name: Seed test tools
        run: |
          nix-build -A tests
          postgrest-push-cachix
      - name: Seed static toolchain
        if: matrix.os == 'Linux'
        run: |
          nix-build -A packagesStatic.haskellPackages.hello
          postgrest-push-cachix
      - name: Seed static postgresql build (for libpq)
        if: matrix.os == 'Linux'
        run: |
          nix-build -A packagesStatic.pkgs.postgresql
          postgrest-push-cachix
      - name: Seed static postgrest build
        if: matrix.os == 'Linux'
        run: |
          nix-build -A postgrestStatic
          postgrest-push-cachix
      - name: Build and push everything to Cachix
        run: |
          nix-build
          postgrest-push-cachix
@@ -1,535 +0,0 @@
 name: CI
 on:
  push:
    branches:
      - main
      - rel-*
    tags:
      - v*
  pull_request:
    branches:
      - main
      - rel-*
 jobs:
  Lint-Style:
    name: Lint & check code style
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Nix Environment
        uses: ./.github/actions/setup-nix
        with:
          tools: style
      - name: Run linter (check locally with `nix-shell --run postgrest-lint`)
        run: postgrest-lint
      - name: Run style check (auto-format with `nix-shell --run postgrest-style`)
        run: postgrest-style-check
  Test-Nix:
    name: Test (Nix)
    runs-on: ubuntu-latest
    defaults:
      run:
        # Hack for enabling color output, see:
        # https://github.com/actions/runner/issues/241#issuecomment-842566950
        shell: script -qec "bash --noprofile --norc -eo pipefail {0}"
    steps:
      - uses: actions/checkout@v3
      - name: Setup Nix Environment
        uses: ./.github/actions/setup-nix
        with:
          tools: tests
      - name: Run coverage (IO tests and Spec tests against PostgreSQL 15)
        run: postgrest-coverage
      - name: Upload coverage to codecov
        uses: codecov/codecov-action@v3.1.4
        with:
          files: ./coverage/codecov.json
      - name: Run doctests
        if: always()
        run: nix-shell --run postgrest-test-doctests
      - name: Check the spec tests for idempotence
        if: always()
        run: postgrest-test-spec-idempotence
  Test-Pg-Nix:
    strategy:
      fail-fast: false
      matrix:
        pgVersion: [9.6, 10, 11, 12, 13, 14, 15]
    name: Test PG ${{ matrix.pgVersion }} (Nix)
    runs-on: ubuntu-latest
    defaults:
      run:
        # Hack for enabling color output, see:
        # https://github.com/actions/runner/issues/241#issuecomment-842566950
        shell: script -qec "bash --noprofile --norc -eo pipefail {0}"
    steps:
      - uses: actions/checkout@v3
      - name: Setup Nix Environment
        uses: ./.github/actions/setup-nix
        with:
          tools: tests withTools
      - name: Run spec tests
        if: always()
        run: postgrest-with-postgresql-${{ matrix.pgVersion }} postgrest-test-spec
      - name: Run IO tests
        if: always()
        run: postgrest-with-postgresql-${{ matrix.pgVersion }} -f test/io/fixtures.sql postgrest-test-io -vv
  Test-Memory-Nix:
    name: Test memory (Nix)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Nix Environment
        uses: ./.github/actions/setup-nix
        with:
          tools: memory
      - name: Run memory tests
        run: postgrest-test-memory
  Build-Static-Nix:
    name: Build Linux static (Nix)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Nix Environment
        uses: ./.github/actions/setup-nix
        with:
          tools: tests
      - name: Build static executable
        run: nix-build -A postgrestStatic
      - name: Check static executable
        run: postgrest-check-static result/bin/postgrest
      - name: Save built executable as artifact
        uses: actions/upload-artifact@v3
        with:
          name: postgrest-linux-static-x64
          path: result/bin/postgrest
          if-no-files-found: error
      - name: Build Docker image
        run: nix-build -A docker.image --out-link postgrest-docker.tar.gz
      - name: Save built Docker image as artifact
        uses: actions/upload-artifact@v3
        with:
          name: postgrest-docker-x64
          path: postgrest-docker.tar.gz
          if-no-files-found: error
  Build-Macos-Nix:
    name: Build MacOS (Nix)
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Nix Environment
        uses: ./.github/actions/setup-nix
      - name: Build everything
        run: |
          nix-build
  Build-Stack:
    strategy:
      fail-fast: false
      matrix:
        include:
          - name: Linux
            runs-on: ubuntu-latest
            cache: |
              ~/.stack
              .stack-work
            artifact: postgrest-ubuntu-x64
          - name: MacOS
            runs-on: macos-latest
            cache: |
              ~/.stack
              .stack-work
            artifact: postgrest-macos-x64
          - name: Windows
            runs-on: windows-latest
            cache: |
              ~\AppData\Roaming\stack
              ~\AppData\Local\Programs\stack
              .stack-work
            deps: Add-Content $env:GITHUB_PATH $env:PGBIN
            artifact: postgrest-windows-x64
    name: Build ${{ matrix.name }} (Stack)
    runs-on: ${{ matrix.runs-on }}
    steps:
      - uses: actions/checkout@v3
      - name: Stack working files cache
        uses: actions/cache@v3
        with:
          path: ${{ matrix.cache }}
          key: ${{ runner.os }}-${{ hashFiles('stack.yaml.lock') }}
      - name: Install dependencies
        if: ${{ matrix.deps }}
        run: ${{ matrix.deps }}
      - name: Build with Stack
        run: stack build --local-bin-path result --copy-bins
      - name: Save built executable as artifact
        uses: actions/upload-artifact@v3
        with:
          name: ${{ matrix.artifact }}
          path: |
            result/postgrest
            result/postgrest.exe
          if-no-files-found: error
  Get-FreeBSD-CirrusCI:
    name: Get FreeBSD build from CirrusCI
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Get FreeBSD executable from CirrusCI
        env:
          # GITHUB_SHA does weird things for pull request, so we roll our own:
          GITHUB_COMMIT: ${{ github.event.pull_request.head.sha || github.sha }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: .github/get_cirrusci_freebsd
      - name: Save executable as artifact
        uses: actions/upload-artifact@v3
        with:
          name: postgrest-freebsd-x64
          path: postgrest
          if-no-files-found: error
  Build-Cabal:
    strategy:
      matrix:
        ghc: ['9.0.2', '9.2.4']
      fail-fast: false
    name: Build Linux (Cabal, GHC ${{ matrix.ghc }})
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Workaround runner image issue
        # https://github.com/actions/runner-images/issues/7061
        run: sudo chown -R "$USER" /usr/local/.ghcup
      - name: ghcup
        run: |
          ghcup install ghc ${{ matrix.ghc }}
          ghcup set ghc ${{ matrix.ghc }}
      - name: Copy cabal.project
        run: |
          cp cabal.project.non-nix cabal.project
      - name: Cache
        uses: actions/cache@v3
        with:
          path: ~/.cabal
          key: ${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('**/*.cabal') }}-${{ hashFiles('**/cabal.project') }}
          restore-keys: |
            ${{ runner.os }}-${{ matrix.ghc }}-
      - name: Install dependencies
        run: |
          cabal update
          cabal build --only-dependencies --enable-tests --enable-benchmarks
      - name: Build
        run: cabal build --enable-tests --enable-benchmarks all
  Build-Cabal-Arm:
    strategy:
      matrix:
        ghc: ['9.2.4']
      fail-fast: false
    name: Build aarch64 (Cabal, GHC ${{ matrix.ghc }})
    if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') || startsWith(github.ref, 'refs/heads/rel-') }}
    runs-on: ubuntu-latest
    outputs:
      remotepath: ${{ steps.Remote-Dir.outputs.remotepath }}
    env:
      GITHUB_COMMIT: ${{ github.sha }}
      GHC_VERSION: ${{ matrix.ghc }}
    steps:
      - uses: actions/checkout@v3
      - id: Remote-Dir
        name: Unique directory name for the remote build
        run: echo "remotepath=postgrest-build-$(uuidgen)" >> "$GITHUB_OUTPUT"
      - name: Copy script files to the remote server
        uses: appleboy/scp-action@master
        with:
          host: ${{ secrets.SSH_ARM_HOST }}
          username: ubuntu
          key: ${{ secrets.SSH_ARM_PRIVATE_KEY }}
          fingerprint: ${{ secrets.SSH_ARM_FINGERPRINT }}
          source: ".github/scripts/arm/*"
          target: ${{ steps.Remote-Dir.outputs.remotepath }}
          strip_components: 3
      - name: Build ARM
        uses: appleboy/ssh-action@master
        env:
          REMOTE_DIR: ${{ steps.Remote-Dir.outputs.remotepath }}
        with:
          host: ${{ secrets.SSH_ARM_HOST }}
          username: ubuntu
          key: ${{ secrets.SSH_ARM_PRIVATE_KEY }}
          fingerprint: ${{ secrets.SSH_ARM_FINGERPRINT }}
          command_timeout: 120m
          script_stop: true
          envs: GITHUB_COMMIT,REMOTE_DIR,GHC_VERSION
          script: bash ~/$REMOTE_DIR/build.sh "$GITHUB_COMMIT" "$REMOTE_DIR" "GHC_VERSION"
      - name: Download binaries from remote server
        uses: nicklasfrahm/scp-action@main
        with:
          direction: download
          host: ${{ secrets.SSH_ARM_HOST }}
          username: ubuntu
          key: ${{ secrets.SSH_ARM_PRIVATE_KEY }}
          fingerprint: ${{ secrets.SSH_ARM_FINGERPRINT }}
          source: "${{ steps.Remote-Dir.outputs.remotepath }}/result.tar.xz"
          target: "result.tar.xz"
      - name: Extract downloaded binaries
        run: tar -xvf result.tar.xz && rm result.tar.xz
      - name: Save aarch64 executable as artifact
        uses: actions/upload-artifact@v3
        with:
          name: postgrest-ubuntu-aarch64
          path: result/postgrest
          if-no-files-found: error
  Prepare-Release:
    name: Prepare release
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    needs:
      - Lint-Style
      - Test-Nix
      - Test-Pg-Nix
      - Test-Memory-Nix
      - Build-Static-Nix
      - Build-Stack
      #- Get-FreeBSD-CirrusCI
      - Build-Cabal-Arm
    outputs:
      version: ${{ steps.Identify-Version.outputs.version }}
      isprerelease: ${{ steps.Identify-Version.outputs.isprerelease }}
    steps:
      - uses: actions/checkout@v3
      - id: Identify-Version
        name: Identify the version to be released
        run: |
          tag_version="${GITHUB_REF##*/}"
          cabal_version="$(grep -oP '^version:\s*\K.*' postgrest.cabal)"
          if [ "$tag_version" != "v$cabal_version" ]; then
            echo "Tagged version ($tag_version) does not match the one in postgrest.cabal (v$cabal_version). Aborting release..."
            exit 1
          else
            echo "Version to be released is $cabal_version"
            echo "version=$cabal_version" >> "$GITHUB_OUTPUT"
          fi
          if [[ "$cabal_version" != *.*.*.* ]]; then
            echo "Version is for a full release (version does not have four components)"
          else
            echo "Version is for a pre-release (version has four components, e.g., 1.1.1.1)"
            echo "isprerelease=1" >> "$GITHUB_OUTPUT"
          fi
      - name: Identify changes from CHANGELOG.md
        run: |
          version="${{ steps.Identify-Version.outputs.version }}"
          isprerelease="${{ steps.Identify-Version.outputs.isprerelease }}"
          if [ -n "$isprerelease" ]; then
            echo "Getting unreleased changes..."
            sed -n "1,/## Unreleased/d;/## \[/q;p" CHANGELOG.md > CHANGES.md
          else
            echo "Full release (no '-' in version), getting changes for version $version ..."
            sed -n "1,/## \[$version\]/d;/## \[/q;p" CHANGELOG.md > CHANGES.md
          fi
          echo "Relevant extract from CHANGELOG.md:"
          cat CHANGES.md
      - name: Save CHANGES.md as artifact
        uses: actions/upload-artifact@v3
        with:
          name: release-changes
          path: CHANGES.md
          if-no-files-found: error
  Release-GitHub:
    name: Release on GitHub
    permissions:
      contents: write
    runs-on: ubuntu-latest
    needs: Prepare-Release
    env:
      VERSION: ${{ needs.Prepare-Release.outputs.version }}
    steps:
      - uses: actions/checkout@v3
      - name: Download all artifacts
        uses: actions/download-artifact@v3
        with:
          path: artifacts
      - name: Create release bundle with archives for all builds
        run: |
          find artifacts -type f -iname postgrest -exec chmod +x {} \;
          mkdir -p release-bundle
          tar cJvf "release-bundle/postgrest-v$VERSION-linux-static-x64.tar.xz" \
            -C artifacts/postgrest-linux-static-x64 postgrest
          # No need to release Ubuntu, as the static Linux binary built with Nix
          # covers all Linux use-cases
          #tar cfJv "release-bundle/postgrest-v$VERSION-ubuntu-x64.tar.xz" \
          #  -C artifacts/postgrest-ubuntu-x64 postgrest
          tar cJvf "release-bundle/postgrest-v$VERSION-macos-x64.tar.xz" \
            -C artifacts/postgrest-macos-x64 postgrest
          # TODO: Fix timeouts for FreeBSD builds in Cirrus
          #tar cJvf "release-bundle/postgrest-v$VERSION-freebsd-x64.tar.xz" \
          #  -C artifacts/postgrest-freebsd-x64 postgrest
          tar cJvf "release-bundle/postgrest-v$VERSION-ubuntu-aarch64.tar.xz" \
            -C artifacts/postgrest-ubuntu-aarch64 postgrest
          zip "release-bundle/postgrest-v$VERSION-windows-x64.zip" \
            artifacts/postgrest-windows-x64/postgrest.exe
      - name: Save release bundle
        uses: actions/upload-artifact@v3
        with:
          name: release-bundle
          path: release-bundle
          if-no-files-found: error
      - name: Publish release on GitHub
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          isprerelease="${{ needs.Prepare-Release.outputs.isprerelease }}"
          echo "Releasing version v$VERSION on GitHub (isprerelease=$isprerelease)..."
          gh release delete "v$VERSION" || true
          gh release create "v$VERSION" \
            -F artifacts/release-changes/CHANGES.md \
            ${isprerelease:+"--prerelease"} \
            release-bundle/*
  Release-Docker:
    name: Release on Docker Hub
    runs-on: ubuntu-latest
    needs:
      - Prepare-Release
    env:
      GITHUB_COMMIT: ${{ github.sha }}
      DOCKER_REPO: postgrest
      DOCKER_USER: stevechavez
      DOCKER_PASS: ${{ secrets.DOCKER_PASS }}
      VERSION: ${{ needs.Prepare-Release.outputs.version }}
      ISPRERELEASE: ${{ needs.Prepare-Release.outputs.isprerelease }}
    steps:
      - uses: actions/checkout@v3
      - name: Setup Nix Environment
        uses: ./.github/actions/setup-nix
        with:
          tools: release
      - name: Download Docker image
        uses: actions/download-artifact@v3
        with:
          name: postgrest-docker-x64
      - name: Publish images on Docker Hub
        run: |
          docker login -u "$DOCKER_USER" -p "$DOCKER_PASS"
          docker load -i postgrest-docker.tar.gz
          docker tag postgrest:latest "$DOCKER_REPO/postgrest:v$VERSION"
          docker push "$DOCKER_REPO/postgrest:v$VERSION"
          # Only tag 'latest' for full releases
          if [[ -z "$ISPRERELEASE" ]]; then
            echo "Pushing to 'latest' tag for full release of v$VERSION ..."
            docker tag postgrest:latest "$DOCKER_REPO"/postgrest:latest
            docker push "$DOCKER_REPO"/postgrest:latest
          else
            echo "Skipping pushing to 'latest' tag for v$VERSION pre-release..."
          fi
 # TODO: Enable dockerhub description update again, once a solution for the permission problem is found:
 # https://github.com/docker/hub-feedback/issues/1927
 #      - name: Update descriptions on Docker Hub
 #        env:
 #          DOCKER_PASS: ${{ secrets.DOCKER_PASS }}
 #        run: |
 #          if [[ -z "$ISPRERELEASE" ]]; then
 #            echo "Updating description on Docker Hub..."
 #            postgrest-release-dockerhub-description
 #          else
 #            echo "Skipping updating description for pre-release..."
 #          fi
  Release-Docker-Arm:
    name: Release Arm Builds on Docker Hub
    runs-on: ubuntu-latest
    needs:
      - Build-Cabal-Arm
      - Prepare-Release
      - Release-Docker
    env:
      GITHUB_COMMIT: ${{ github.sha }}
      DOCKER_REPO: postgrest
      DOCKER_USER: stevechavez
      DOCKER_PASS: ${{ secrets.DOCKER_PASS }}
      VERSION: ${{ needs.Prepare-Release.outputs.version }}
      ISPRERELEASE: ${{ needs.Prepare-Release.outputs.isprerelease }}
    steps:
      - uses: actions/checkout@v3
      - name: Publish images for ARM builds on Docker Hub
        uses: appleboy/ssh-action@master
        env:
          REMOTE_DIR: ${{ needs.Build-Cabal-Arm.outputs.remotepath }}
        with:
          host: ${{ secrets.SSH_ARM_HOST }}
          username: ubuntu
          key: ${{ secrets.SSH_ARM_PRIVATE_KEY }}
          fingerprint: ${{ secrets.SSH_ARM_FINGERPRINT }}
          script_stop: true
          envs: GITHUB_COMMIT,DOCKER_REPO,DOCKER_USER,DOCKER_PASS,REMOTE_DIR,VERSION,ISPRERELEASE
          script: bash ~/$REMOTE_DIR/docker-publish.sh "$GITHUB_COMMIT" "$DOCKER_REPO" "$DOCKER_USER" "$DOCKER_PASS" "$REMOTE_DIR" "$VERSION" "$ISPRERELEASE"
  Clean-Arm-Server:
    name: Remove copied files from server
    needs:
      - Build-Cabal-Arm
      - Release-Docker-Arm
    if: success() ||
      needs.Build-Cabal-Arm.result == 'failure' ||
      needs.Build-Cabal-Arm.result == 'cancelled' ||
      (needs.Build-Cabal-Arm.result == 'success' && !startsWith(github.ref, 'refs/tags/v'))
    runs-on: ubuntu-latest
    env:
      REMOTE_DIR: ${{ needs.Build-Cabal-Arm.outputs.remotepath }}
    steps:
      - uses: actions/checkout@v3
      - name: Remove uploaded files from server
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SSH_ARM_HOST }}
          username: ubuntu
          key: ${{ secrets.SSH_ARM_PRIVATE_KEY }}
          fingerprint: ${{ secrets.SSH_ARM_FINGERPRINT }}
          envs: REMOTE_DIR
          script: rm -rf $REMOTE_DIR
@@ -0,0 +1,50 @@
 name: Docs
 on:
  push:
    branches:
    - main
    - v[0-9]+
  pull_request:
    branches:
    - main
    - v[0-9]+
 jobs:
  build:
    name: Build docs
    runs-on: ubuntu-24.04
    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    - uses: cachix/install-nix-action@13d8dd58da0234aa297dedd986986ccb8e7f3e24 # v31
    - run: nix-env -f docs/default.nix -iA build
    - run: postgrest-docs-build
  spellcheck:
    name: Run spellcheck
    runs-on: ubuntu-24.04
    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    - uses: cachix/install-nix-action@13d8dd58da0234aa297dedd986986ccb8e7f3e24 # v31
    - run: nix-env -f docs/default.nix -iA spellcheck
    - run: postgrest-docs-spellcheck
  dictcheck:
    name: Run dictcheck
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: cachix/install-nix-action@13d8dd58da0234aa297dedd986986ccb8e7f3e24 # v31
      - run: nix-env -f docs/default.nix -iA dictcheck
      - run: postgrest-docs-dictcheck
  linkcheck:
    name: Run linkcheck
    if: github.base_ref == 'main'
    runs-on: ubuntu-24.04
    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    - uses: cachix/install-nix-action@13d8dd58da0234aa297dedd986986ccb8e7f3e24 # v31
    - run: nix-env -f docs/default.nix -iA linkcheck
    - run: postgrest-docs-linkcheck
@@ -1,34 +0,0 @@
 name: Loadtest
 on:
  push:
    branches:
      - main
    tags:
      - v*
  pull_request:
    branches:
      - main
 jobs:
  Loadtest-Nix:
    name: Loadtest (Nix)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Setup Nix Environment
        uses: ./.github/actions/setup-nix
        with:
          tools: loadtest
      - name: Run loadtest
        run: |
          postgrest-loadtest-against main
          postgrest-loadtest-report > loadtest/loadtest.md
      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: loadtest.md
          path: loadtest/loadtest.md
          if-no-files-found: error
@@ -1,33 +0,0 @@
 name: Upload Reports
 on:
  workflow_run:
    workflows: ["Loadtest"]
    types:
      - completed
 jobs:
  upload:
    name: Loadtest
    permissions:
      checks: write
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
      - name: Download from Artifacts
        uses: dawidd6/action-download-artifact@v2
        with:
          workflow: ${{ github.event.workflow.name }}
          run_id: ${{github.event.workflow_run.id }}
          name: loadtest.md
          path: artifacts
      - name: Upload to GitHub Checks
        uses: LouisBrunner/checks-action@v1.6.2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          sha: ${{ github.event.workflow_run.head_sha }}
          name: Loadtest Results
          conclusion: neutral
          output: |
            {"summary":""}
          output_text_description_file: artifacts/loadtest.md
@@ -23,3 +23,4 @@ coverage
 .hpc
 loadtest
 .history
 .docs-build
@@ -0,0 +1,10 @@
 version: 2
 sphinx:
  configuration: docs/conf.py
 python:
   install:
   - requirements: docs/requirements.txt
 build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
@@ -5,6 +5,29 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## Unreleased
 ## [11.2.2] - 2023-10-25
 ### Fixed
 - #2824, Fix regression by reverting fix that returned 206 when first position = length in a `Range` header - @laurenceisla, @strengthless
 ## [11.2.1] - 2023-10-03
 ### Fixed
 - #2899, Fix `application/vnd.pgrst.array` not accepted as a valid mediatype - @taimoorzaeem
 - #2524, Fix schema cache and configuration reloading with `NOTIFY` not working on Windows - @diogob, @laurenceisla
 - #2915, Fix duplicate headers in response - @taimoorzaeem
 - #2824, Fix range request with first position same as length return status 206 - @taimoorzaeem
 - #2939, Fix wrong `Preference-Applied` with `Prefer: tx=commit` when transaction is rollbacked - @steve-chavez
 - #2939, Fix `count=exact` not being included in `Preference-Applied` - @steve-chavez
 - #2800, Fix not including to-one embed resources that had a `NULL` value in any of the selected fields when doing null filtering on them - @laurenceisla
 - #2846, Fix error when requesting `Prefer: count=<type>` and doing null filtering on embedded resources - @laurenceisla
 - #2959, Fix setting `default_transaction_isolation` unnecessarily - @steve-chavez
 - #2929, Fix arrow filtering on RPC returning dynamic TABLE with composite type - @steve-chavez
 - #2963, Fix RPCs not embedding correctly when using overloaded functions for computed relationships - @laurenceisla
 - #2970, Fix regression that rejects URI connection strings with certain unescaped characters in the password - @laurenceisla, @steve-chavez
 ## [11.2.0] - 2023-08-10
 ### Added
@@ -0,0 +1,3 @@
 This repository follows the same contribution guidelines as the main PostgREST repository contribution guidelines:
 https://github.com/PostgREST/postgrest/blob/main/.github/CONTRIBUTING.md
@@ -1,8 +1,6 @@
 ![Logo](static/bigger-logo.png "Logo")
 [![Donate](https://img.shields.io/badge/Donate-Patreon-orange.svg?colorB=F96854)](https://www.patreon.com/postgrest)
 [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/postgrest)
 [![Join the chat at https://gitter.im/begriffs/postgrest](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/begriffs/postgrest)
 [![Docs](https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat)](http://postgrest.org)
 [![Docker Stars](https://img.shields.io/docker/pulls/postgrest/postgrest.svg)](https://hub.docker.com/r/postgrest/postgrest/)
 [![Build Status](https://github.com/postgrest/postgrest/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/PostgREST/postgrest/actions?query=branch%3Amain)
@@ -145,11 +143,7 @@ and the [API guide](http://postgrest.org/en/stable/api.html).
 ## Supporting development
-You can help PostgREST ongoing maintenance and development by:
+You can help PostgREST ongoing maintenance and development by making a regular donation through Patreon https://www.patreon.com/postgrest
 - Making a regular donation through Patreon https://www.patreon.com/postgrest
 - Alternatively, you can make a one-time donation via Paypal https://www.paypal.me/postgrest
 Every donation will be spent on making PostgREST better for the whole community.
@@ -50,6 +50,19 @@ let
  postgresqlVersions =
    [
      {
        name = "postgresql-16";
        postgresql = pkgs.postgresql_16.withPackages (p: [
          p.postgis
          (p.pg_safeupdate.overrideAttrs (old: {
            installPhase = ''
              mkdir -p $out/bin
              cp safeupdate.dylib safeupdate.so || true
              install -D safeupdate.so -t $out/lib
            '';
          }))
        ]);
      }
      { name = "postgresql-15"; postgresql = pkgs.postgresql_15.withPackages (p: [ p.postgis p.pg_safeupdate ]); }
      { name = "postgresql-14"; postgresql = pkgs.postgresql_14.withPackages (p: [ p.postgis p.pg_safeupdate ]); }
      { name = "postgresql-13"; postgresql = pkgs.postgresql_13.withPackages (p: [ p.postgis p.pg_safeupdate ]); }
@@ -0,0 +1,8 @@
 _build
 Pipfile.lock
 *.aux
 *.log
 _diagrams/db.pdf
 misspellings
 unuseddict
 .history
@@ -0,0 +1,20 @@
 # PostgREST documentation https://postgrest.org/
 PostgREST docs use the reStructuredText format, check this [cheatsheet](https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst) to get acquainted with it.
 To build the docs locally, use [nix](https://nixos.org/nix/):
 ```bash
  nix-shell
 ```
 Once in the nix-shell you have the following commands available:
 - `postgrest-docs-build`: Build the docs.
 - `postgrest-docs-serve`: Build the docs and start a livereload server on `http://localhost:5500`.
 - `postgrest-docs-spellcheck`: Run aspell.
 ## Documentation structure
 This documentation is structured according to tutorials-howtos-topics-references. For more details on the rationale of this structure, 
 see https://www.divio.com/blog/documentation.
@@ -0,0 +1,42 @@
 ## ERD
 The ER diagrams were created with https://github.com/BurntSushi/erd/.
 You can go download erd from https://github.com/BurntSushi/erd/releases and then do:
 ```bash
 ./erd_static-x86-64 -i film.er -o ../_static/film.png
 ```
 The fonts used belong to the GNU FreeFont family. You can download them here: http://ftp.gnu.org/gnu/freefont/
 ## LaTeX
 The schema structure diagram is done with LaTeX. You can use a GUI like https://www.mathcha.io/editor to create the .tex file.
 Then use this command to generate the png file.
 ```bash
 pdflatex --shell-escape -halt-on-error db.tex
 ## and move it to the static folder(it's not easy to do it in one go with the pdflatex)
 mv db.png ../_static/
 ```
 LaTeX is used because it's a tweakable plain text format.
 You can install the full latex suite with `nix`:
 ```
 nix-env -iA texlive.combined.scheme-full
 ```
 To tweak the file with a live reload environment use:
 ```bash
 # open the pdf(zathura used as an example)
 zathura db.pdf &
 # live reload with entr
 echo db.tex | entr pdflatex --shell-escape -halt-on-error db.tex
 ```
@@ -0,0 +1,15 @@
 entity {font: "FreeSans"}
 relationship {font: "FreeMono"}
 [Box_Office]
 *bo_date
 *+film_id
 gross_revenue
 [Films]
 *id
 +director_id
 title
 `...`
 Box_Office +--1 Films
@@ -0,0 +1,71 @@
 \documentclass[convert]{standalone}
 \usepackage{amsmath}
 \usepackage{tikz}
 \usepackage{mathdots}
 \usepackage{yhmath}
 \usepackage{cancel}
 \usepackage{color}
 \usepackage{siunitx}
 \usepackage{array}
 \usepackage{multirow}
 \usepackage{amssymb}
 \usepackage{gensymb}
 \usepackage{tabularx}
 \usepackage{booktabs}
 \usetikzlibrary{fadings}
 \usetikzlibrary{patterns}
 \usetikzlibrary{shadows.blur}
 \usetikzlibrary{shapes}
 \begin{document}
 \newcommand\customScale{0.35}
 \begin{tikzpicture}[x=0.75pt,y=0.75pt,yscale=-1,xscale=1, scale=\customScale, every node/.style={scale=\customScale}]
 %Shape: Can [id:dp7234864758664346]
 \draw  [fill={rgb, 255:red, 47; green, 97; blue, 144 }  ,fill opacity=1 ] (497.5,51.5) -- (497.5,255.5) .. controls (497.5,275.66) and (423.18,292) .. (331.5,292) .. controls (239.82,292) and (165.5,275.66) .. (165.5,255.5) -- (165.5,51.5) .. controls (165.5,31.34) and (239.82,15) .. (331.5,15) .. controls (423.18,15) and (497.5,31.34) .. (497.5,51.5) .. controls (497.5,71.66) and (423.18,88) .. (331.5,88) .. controls (239.82,88) and (165.5,71.66) .. (165.5,51.5) ;
 %Shape: Rectangle [id:dp7384065579958246]
 \draw  [fill={rgb, 255:red, 236; green, 227; blue, 227 }  ,fill opacity=1 ] (189,115) -- (252.5,115) -- (252.5,155) -- (189,155) -- cycle ;
 %Shape: Rectangle [id:dp24763906430298177]
 \draw  [fill={rgb, 255:red, 236; green, 227; blue, 227 }  ,fill opacity=1 ] (292,118) -- (362,118) -- (362,158) -- (292,158) -- cycle ;
 %Shape: Rectangle [id:dp3775601612537265]
 \draw  [fill={rgb, 255:red, 236; green, 227; blue, 227 }  ,fill opacity=1 ] (397,114) -- (467,114) -- (467,154) -- (397,154) -- cycle ;
 %Shape: Rectangle [id:dp7071457022893852]
 \draw  [fill={rgb, 255:red, 248; green, 231; blue, 28 }  ,fill opacity=1 ] (269,199) -- (397.5,199) -- (397.5,273) -- (269,273) -- cycle ;
 %Straight Lines [id:da8846759047437789]
 \draw    (268,234) -- (226.44,155.77) ;
 \draw [shift={(225.5,154)}, rotate = 422.02] [color={rgb, 255:red, 0; green, 0; blue, 0 }  ][line width=0.75]    (10.93,-3.29) .. controls (6.95,-1.4) and (3.31,-0.3) .. (0,0) .. controls (3.31,0.3) and (6.95,1.4) .. (10.93,3.29)   ;
 %Straight Lines [id:da6908444738113828]
 \draw    (309.5,198) -- (307.6,161) ;
 \draw [shift={(307.5,159)}, rotate = 447.06] [color={rgb, 255:red, 0; green, 0; blue, 0 }  ][line width=0.75]    (10.93,-3.29) .. controls (6.95,-1.4) and (3.31,-0.3) .. (0,0) .. controls (3.31,0.3) and (6.95,1.4) .. (10.93,3.29)   ;
 %Straight Lines [id:da7168757864413169]
 \draw    (398.5,233) -- (431.72,154.84) ;
 \draw [shift={(432.5,153)}, rotate = 473.03] [color={rgb, 255:red, 0; green, 0; blue, 0 }  ][line width=0.75]    (10.93,-3.29) .. controls (6.95,-1.4) and (3.31,-0.3) .. (0,0) .. controls (3.31,0.3) and (6.95,1.4) .. (10.93,3.29)   ;
 %Up Down Arrow [id:dp14059754167108496]
 \draw  [fill={rgb, 255:red, 126; green, 211; blue, 33 }  ,fill opacity=1 ] (312.5,288.5) -- (330,273) -- (347.5,288.5) -- (338.75,288.5) -- (338.75,319.5) -- (347.5,319.5) -- (330,335) -- (312.5,319.5) -- (321.25,319.5) -- (321.25,288.5) -- cycle ;
 % Text Node
 \draw (201,129) node [anchor=north west][inner sep=0.75pt]   [align=left] {tables};
 % Text Node
 \draw (307,130) node [anchor=north west][inner sep=0.75pt]   [align=left ] {tables};
 % Text Node
 \draw (414,127) node [anchor=north west][inner sep=0.75pt]   [align=left] {tables};
 % Text Node
 \draw (272,203) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 0; green, 0; blue, 0 }  ,opacity=1 ] [align=center] { \\ views \\ + \\ \ \ stored procedures};
 % Text Node
 \draw (322,178) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 255; green, 255; blue, 255 }  ,opacity=1 ] [align=left] {\large\textbf{api}};
 % Text Node
 \draw (190,97) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 255; green, 255; blue, 255 }  ,opacity=1 ] [align=left] {\large\textbf{internal}};
 % Text Node
 \draw (300,99) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 255; green, 255; blue, 255 }  ,opacity=1 ] [align=left] {\large\textbf{private}};
 % Text Node
 \draw (417,101) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 255; green, 255; blue, 255 }  ,opacity=1 ] [align=left] {\large\textbf{core}};
 % Text Node
 \draw (358,306) node [anchor=north west][inner sep=0.75pt]   [align=left] {REST};
 \end{tikzpicture}
 \end{document}
@@ -0,0 +1,12 @@
 # Build using: -e ortho
 entity {font: "FreeSans"}
 relationship {font: "FreeMono"}
 [Employees]
 *id
 first_name
 last_name
 +supervisor_id
 Employees 1--* Employees
@@ -0,0 +1,51 @@
 entity {font: "FreeSans"}
 relationship {font: "FreeSerif"}
 [Films]
 *id
 +director_id
 title
 year
 rating
 language
 [Directors]
 *id
 first_name
 last_name
 [Actors]
 *id
 first_name
 last_name
 [Roles]
 *+film_id
 *+actor_id
 character
 [Competitions]
 *id
 name
 year
 [Nominations]
 *+competition_id
 *+film_id
 rank
 [Technical_Specs]
 *+film_id
 runtime
 camera
 sound
 Roles *--1 Actors
 Roles *--1 Films
 Nominations *--1 Competitions
 Nominations *--1 Films
 Films *--1 Directors
 Films 1--1 Technical_Specs
@@ -0,0 +1,20 @@
 # Build using: -e ortho
 entity {font: "FreeSans"}
 relationship {font: "FreeMono"}
 [Addresses]
 *id
 name
 city
 state
 postal_code
 [Orders]
 *id
 name
 +billing_address_id
 +shipping_address_id
 Orders *--1 Addresses
 Orders *--1 Addresses
@@ -0,0 +1,16 @@
 entity {font: "FreeSans"}
 relationship {font: "FreeMono"}
 [Premieres]
 *id
 location
 date
 +film_id
 [Films]
 *id
 +director_id
 title
 `...`
 Premieres *--1 Films
@@ -0,0 +1,12 @@
 # Build using: -e ortho
 entity {font: "FreeSans"}
 relationship {font: "FreeMono"}
 [Presidents]
 *id
 first_name
 last_name
 +predecessor_id
 Presidents 1--? Presidents
@@ -0,0 +1,18 @@
 # Build using: -e ortho
 entity {font: "FreeSans"}
 relationship {font: "FreeMono"}
 [Users]
 *id
 first_name
 last_name
 username
 [Subscriptions]
 *+subscriber_id
 *+subscribed_id
 type
 Users 1--* Subscriptions
 Subscriptions *--1 Users
@@ -0,0 +1,95 @@
 .wy-nav-content {
  max-width: initial;
 }
 #postgrest-documentation > h1 {
  display: none;
 }
 div.wy-menu.rst-pro {
  display: none !important;
 }
 div.highlight {
  background: #fff !important;
 }
 div.line-block {
  margin-bottom: 0px !important;
 }
 #sponsors {
  text-align: center;
 }
 #sponsors h2 {
  text-align: left;
 }
 #sponsors img{
  margin: 10px;
 }
 #thanks{
  text-align: center;
 }
 #thanks img{
  margin: 10px;
 }
 #thanks h2{
  text-align: left;
 }
 #thanks p{
  text-align: left;
 }
 #thanks ul{
  text-align: left;
 }
 .image-container {
  max-width: 800px;
  display: block;
  margin-left: auto;
  margin-right: auto;
  margin-bottom: 24px;
 }
 .wy-table-responsive table td {
    white-space: normal !important;
 }
 .wy-table-responsive {
    overflow: visible !important;
 }
 #tutorials span.caption-text {
    display: none;
 }
 #references span.caption-text {
    display: none;
 }
 #explanations span.caption-text {
    display: none;
 }
 #how-tos span.caption-text {
    display: none;
 }
 #ecosystem span.caption-text {
    display: none;
 }
 #integrations span.caption-text {
    display: none;
 }
 #api span.caption-text {
    display: none;
 }
@@ -0,0 +1,293 @@
 # -*- coding: utf-8 -*-
 #
 # PostgREST documentation build configuration file, created by
 # sphinx-quickstart on Sun Oct  9 16:53:00 2016.
 #
 # This file is execfile()d with the current directory set to its
 # containing dir.
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 import sys
 import os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 # sys.path.insert(0, os.path.abspath('.'))
 # -- General configuration ------------------------------------------------
 # If your documentation needs a minimal Sphinx version, state it here.
 # needs_sphinx = '1.0'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ["sphinx_tabs.tabs", "sphinx_copybutton"]
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
 source_suffix = ".rst"
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
 # The master toctree document.
 master_doc = "index"
 # This is overriden by readthedocs with the version tag anyway
 version = "11.2"
 # To avoid repetition in <title> we set this to an empty string.
 release = ""
 # General information about the project.
 project = "PostgREST " + version
 author = "Joe Nelson, Steve Chavez"
 copyright = "2017, " + author
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
 language = None
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 # today = ''
 # Else, today_fmt is used as the format for a strftime call.
 # today_fmt = '%B %d, %Y'
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 # default_role = None
 # If true, '()' will be appended to :func: etc. cross-reference text.
 # add_function_parentheses = True
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 # add_module_names = True
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
 # show_authors = False
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
 # If true, keep warnings as "system message" paragraphs in the built documents.
 # keep_warnings = False
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 # -- Options for HTML output ----------------------------------------------
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = "sphinx_rtd_theme"
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {"display_version": False}
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
 # html_title = u'PostgREST v0.4.0.0'
 # A shorter title for the navigation bar.  Default is the same as html_title.
 # html_short_title = None
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 # html_logo = None
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
 html_favicon = "_static/favicon.ico"
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
 # html_extra_path = []
 # If not None, a 'Last updated on:' timestamp is inserted at every page
 # bottom, using the given strftime format.
 # The empty string is equivalent to '%b %d, %Y'.
 # html_last_updated_fmt = None
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 # html_use_smartypants = True
 # Custom sidebar templates, maps document names to template names.
 # html_sidebars = {}
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 # html_additional_pages = {}
 # If false, no module index is generated.
 # html_domain_indices = True
 # If false, no index is generated.
 # html_use_index = True
 # If true, the index is split into individual pages for each letter.
 # html_split_index = False
 # If true, links to the reST sources are added to the pages.
 # html_show_sourcelink = True
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 # html_show_sphinx = True
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
 # html_show_copyright = True
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 # html_use_opensearch = ''
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 # html_file_suffix = None
 # Language to be used for generating the HTML full-text search index.
 # Sphinx supports the following languages:
 #   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
 #   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
 # html_search_language = 'en'
 # A dictionary with options for the search language support, empty by default.
 # 'ja' uses this config value.
 # 'zh' user can custom change `jieba` dictionary path.
 # html_search_options = {'type': 'default'}
 # The name of a javascript file (relative to the configuration directory) that
 # implements a search results scorer. If empty, the default will be used.
 # html_search_scorer = 'scorer.js'
 # Output file base name for HTML help builder.
 htmlhelp_basename = "PostgRESTdoc"
 # -- Options for LaTeX output ---------------------------------------------
 latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #'papersize': 'letterpaper',
    # The font size ('10pt', '11pt' or '12pt').
    #'pointsize': '10pt',
    # Additional stuff for the LaTeX preamble.
    #'preamble': '',
    # Latex figure (float) alignment
    #'figure_align': 'htbp',
 }
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
    (master_doc, "PostgREST.tex", "PostgREST Documentation", author, "manual"),
 ]
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 # latex_logo = None
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
 # latex_use_parts = False
 # If true, show page references after internal links.
 # latex_show_pagerefs = False
 # If true, show URL addresses after external links.
 # latex_show_urls = False
 # Documents to append as an appendix to all manuals.
 # latex_appendices = []
 # If false, no module index is generated.
 # latex_domain_indices = True
 # -- Options for manual page output ---------------------------------------
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [(master_doc, "postgrest", "PostgREST Documentation", [author], 1)]
 # If true, show URL addresses after external links.
 # man_show_urls = False
 # -- Options for Texinfo output -------------------------------------------
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
    (
        master_doc,
        "PostgREST",
        "PostgREST Documentation",
        author,
        "PostgREST",
        "REST API for any PostgreSQL database",
        "Web",
    ),
 ]
 # Documents to append as an appendix to all manuals.
 # texinfo_appendices = []
 # If false, no module index is generated.
 # texinfo_domain_indices = True
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 # texinfo_show_urls = 'footnote'
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
 # -- Custom setup ---------------------------------------------------------
 def setup(app):
    app.add_css_file("css/custom.css")
 user_agent = "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:135.0) Gecko/20100101 Firefox/135.0"
 # sphinx-tabs configuration
 sphinx_tabs_disable_tab_closing = True
@@ -0,0 +1,93 @@
 let
  # Commit of the Nixpkgs repository that we want to use.
  nixpkgsVersion = {
    date = "2021-06-02";
    rev = "84aa23742f6c72501f9cc209f29c438766f5352d";
    tarballHash = "0h7xl6q0yjrbl9vm3h6lkxw692nm8bg3wy65gm95a2mivhrdjpxp";
  };
  # Nix files that describe the Nixpkgs repository. We evaluate the expression
  # using `import` below.
  pkgs = import
    (fetchTarball {
      url = "https://github.com/nixos/nixpkgs/archive/${nixpkgsVersion.rev}.tar.gz";
      sha256 = nixpkgsVersion.tarballHash;
    })
    { };
  sphinxTabsPkg = ps: ps.callPackage ./extensions/sphinx-tabs.nix { };
  sphinxCopybuttonPkg = ps: ps.callPackage ./extensions/sphinx-copybutton.nix { };
  python = pkgs.python3.withPackages (ps: [ ps.sphinx ps.sphinx_rtd_theme ps.livereload (sphinxTabsPkg ps) (sphinxCopybuttonPkg ps) ]);
 in
 {
  inherit pkgs;
  build =
    pkgs.writeShellScriptBin "postgrest-docs-build"
      ''
        set -euo pipefail
        cd "$(${pkgs.git}/bin/git rev-parse --show-toplevel)/docs"
        # clean previous build, otherwise some errors might be supressed
        rm -rf _build
        ${python}/bin/sphinx-build --color -W -b html -a -n . _build
      '';
  serve =
    pkgs.writeShellScriptBin "postgrest-docs-serve"
      ''
        set -euo pipefail
        cd "$(${pkgs.git}/bin/git rev-parse --show-toplevel)/docs"
        # livereload_docs.py needs to find "sphinx-build"
        PATH=${python}/bin:$PATH
        ${python}/bin/python livereload_docs.py
      '';
  spellcheck =
    pkgs.writeShellScriptBin "postgrest-docs-spellcheck"
      ''
        set -euo pipefail
        cd "$(${pkgs.git}/bin/git rev-parse --show-toplevel)/docs"
        FILES=$(find . -type f -iname '*.rst' | tr '\n' ' ')
        cat $FILES \
         | grep -v '^\(\.\.\|  \)' \
         | sed 's/`.*`//g' \
         | ${pkgs.aspell}/bin/aspell -d ${pkgs.aspellDicts.en}/lib/aspell/en_US -p ./postgrest.dict list \
         | sort -f \
         | tee misspellings
        test ! -s misspellings
      '';
  # dictcheck detects obsolete entries in postgrest.dict, that are not used anymore
  dictcheck =
    pkgs.writeShellScriptBin "postgrest-docs-dictcheck"
      ''
        set -euo pipefail
        cd "$(${pkgs.git}/bin/git rev-parse --show-toplevel)/docs"
        FILES=$(find . -type f -iname '*.rst' | tr '\n' ' ')
        cat postgrest.dict \
         | tail -n+2 \
         | tr '\n' '\0' \
         | xargs -0 -n 1 -i \
           sh -c "grep \"{}\" $FILES > /dev/null || echo \"{}\"" \
         | tee unuseddict
        test ! -s unuseddict
      '';
  linkcheck =
    pkgs.writeShellScriptBin "postgrest-docs-linkcheck"
      ''
        set -euo pipefail
        cd "$(${pkgs.git}/bin/git rev-parse --show-toplevel)/docs"
        ${python}/bin/sphinx-build --color -b linkcheck . _build
      '';
 }
@@ -0,0 +1,95 @@
 .. _community_tutorials:
 Community Tutorials
 -------------------
 * `Building a Contacts List with PostgREST and Vue.js <https://www.youtube.com/watch?v=iHtsALtD5-U>`_ -
  In this video series, DigitalOcean shows how to build and deploy an Nginx + PostgREST(using a managed PostgreSQL database) + Vue.js webapp in an Ubuntu server droplet.
 * `PostgREST + Auth0: Create REST API in minutes, and add social login using Auth0 <https://samkhawase.com/blog/postgrest-1-introduction/>`_ - A step-by-step tutorial to show how to dockerize and integrate Auth0 to PostgREST service.
 * `PostgREST + PostGIS API tutorial in 5 minutes <https://gis-ops.com/postgrest-postgis-api-tutorial-geospatial-api-in-5-minutes/>`_ -
  In this tutorial, GIS • OPS shows how to perform PostGIS calculations through PostgREST :ref:`s_procs` interface.
 * `"CodeLess" backend using postgres, postgrest and oauth2 authentication with keycloak <https://www.mathieupassenaud.fr/codeless_backend/>`_ -
  A step-by-step tutorial for using PostgREST with KeyCloak(hosted on a managed service).
 * `How PostgreSQL triggers work when called with a PostgREST PATCH HTTP request <https://blog.fgribreau.com/2020/11/how-postgresql-triggers-works-when.html>`_ - A tutorial to see how the old and new values are set or not when doing a PATCH request to PostgREST.
 * `REST Data Service on YugabyteDB / PostgreSQL <https://dev.to/yugabyte/rest-data-service-on-yugabytedb-postgresql-5f2h>`_
 * `Build data-driven applications with Workers and PostgreSQL <https://developers.cloudflare.com/workers/tutorials/postgres/>`_ - A tutorial on how to integrate with PostgREST and PostgreSQL using Cloudflare Workers.
 * `A poor man's API <https://blog.frankel.ch/poor-man-api>`_ - Shows how to integrate PostgREST with Apache APISIX as an alternative to Nginx.
 .. _templates:
 Templates
 ---------
 * `compose-postgrest <https://github.com/mattddowney/compose-postgrest>`_ - docker-compose setup with Nginx and HTML example
 * `svelte-postgrest-template <https://github.com/guyromm/svelte-postgrest-template>`_ - Svelte/SvelteKit, PostgREST, EveryLayout and social auth
 .. _eco_example_apps:
 Example Apps
 ------------
 * `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
 * `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
 * `prospector <https://github.com/sfcta/prospector>`_ - data warehouse and visualization platform
 .. _devops:
 DevOps
 ------
 * `cloudgov-demo-postgrest <https://github.com/GSA/cloudgov-demo-postgrest>`_ - demo for a federally-compliant REST API on cloud.gov
 * `cloudstark/helm-charts <https://github.com/cloudstark/helm-charts/tree/master/postgrest>`_ - helm chart to deploy PostgREST to a Kubernetes cluster via a Deployment and Service
 * `jbkarle/postgrest <https://github.com/jbkarle/postgrest>`_ - helm chart with a demo database for development and test purposes
 * `Limezest/postgrest-cloud-run <https://github.com/Limezest/postgrest-cloud-run>`_ - expose a PostgreSQL database on Cloud SQL using Cloud Run
 * `eyberg/postgrest <https://repo.ops.city/v2/packages/eyberg/postgrest/10.1.1/x86_64/show>`_ - run PostgREST as a Nanos unikernel
 .. _eco_external_notification:
 External Notification
 ---------------------
 These are PostgreSQL bridges that propagate LISTEN/NOTIFY to external queues for further processing. This allows stored procedures to initiate actions outside the database such as sending emails.
 * `pg-notify-webhook <https://github.com/vbalasu/pg-notify-webhook>`_ - trigger webhooks from PostgreSQL's LISTEN/NOTIFY
 * `pgsql-listen-exchange <https://github.com/gmr/pgsql-listen-exchange>`_ - RabbitMQ
 * `postgres-websockets <https://github.com/diogob/postgres-websockets>`_ - expose web sockets for PostgreSQL's LISTEN/NOTIFY
 * `postgresql2websocket <https://github.com/frafra/postgresql2websocket>`_ - Websockets
 .. _eco_extensions:
 Extensions
 ----------
 * `aiodata <https://github.com/Exahilosys/aiodata>`_ - Python, event-based proxy and caching client.
 * `pg-safeupdate <https://github.com/eradman/pg-safeupdate>`_ - prevent full-table updates or deletes
 * `postgrest-node <https://github.com/seveibar/postgrest-node>`_ - Run a PostgREST server in Node.js via npm module
 * `PostgREST-writeAPI <https://github.com/ppKrauss/PostgREST-writeAPI>`_ - generate Nginx rewrite rules to fit an OpenAPI spec
 .. _clientside_libraries:
 Client-Side Libraries
 ---------------------
 * `postgrest-csharp <https://github.com/supabase-community/postgrest-csharp>`_ - C#
 * `postgrest-dart <https://github.com/supabase-community/postgrest-dart>`_ - Dart
 * `postgrest-ex <https://github.com/J0/postgrest-ex>`_ - Elixir
 * `postgrest-go <https://github.com/supabase-community/postgrest-go>`_ - Go
 * `postgrest-js <https://github.com/supabase/postgrest-js>`_ - TypeScript/JavaScript
 * `postgrest-kt <https://github.com/supabase-community/postgrest-kt>`_ - Kotlin
 * `postgrest-py <https://github.com/supabase/postgrest-py>`_ - Python
 * `postgrest-rs <https://github.com/supabase-community/postgrest-rs>`_ - Rust
 * `postgrest-swift <https://github.com/supabase-community/postgrest-swift>`_ - Swift
 * `redux-postgrest <https://github.com/andytango/redux-postgrest>`_ - TypeScript/JS, client integrated with (React) Redux.
 * `vue-postgrest <https://github.com/technowledgy/vue-postgrest>`_ - Vue.js
@@ -0,0 +1,207 @@
 .. _db_authz:
 Database Authorization
 ######################
 Database authorization is the process of granting and verifying database access permissions. PostgreSQL manages permissions using the concept of roles.
 Users and Groups
 ================
 A role can be thought of as either a database user, or a group of database users, depending on how the role is set up.
 Roles for Each Web User
 -----------------------
 PostgREST can accommodate either viewpoint. If you treat a role as a single user then the :ref:`jwt_impersonation` does most of what you need. When an authenticated user makes a request PostgREST will switch into the database role for that user, which in addition to restricting queries, is available to SQL through the :code:`current_user` variable.
 You can use row-level security to flexibly restrict visibility and access for the current user. Here is an `example <https://www.enterprisedb.com:443/blog/application-users-vs-row-level-security>`_ from Tomas Vondra, a chat table storing messages sent between users. Users can insert rows into it to send messages to other users, and query it to see messages sent to them by other users.
 .. code-block:: postgres
  CREATE TABLE chat (
    message_uuid    UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    message_time    TIMESTAMP NOT NULL DEFAULT now(),
    message_from    NAME      NOT NULL DEFAULT current_user,
    message_to      NAME      NOT NULL,
    message_subject VARCHAR(64) NOT NULL,
    message_body    TEXT
  );
  ALTER TABLE chat ENABLE ROW LEVEL SECURITY;
 We want to enforce a policy that ensures a user can see only those messages sent by them or intended for them. Also we want to prevent a user from forging the ``message_from`` column with another person's name.
 PostgreSQL allows us to set this policy with row-level security:
 .. code-block:: postgres
  CREATE POLICY chat_policy ON chat
    USING ((message_to = current_user) OR (message_from = current_user))
    WITH CHECK (message_from = current_user)
 Anyone accessing the generated API endpoint for the chat table will see exactly the rows they should, without our needing custom imperative server-side coding.
 .. warning::
   Roles are namespaced per-cluster rather than per-database so they may be prone to collision.
 Web Users Sharing Role
 ----------------------
 Alternately database roles can represent groups instead of (or in addition to) individual users. You may choose that all signed-in users for a web app share the role ``webuser``. You can distinguish individual users by including extra claims in the JWT such as email.
 .. code:: json
  {
    "role": "webuser",
    "email": "john@doe.com"
  }
 SQL code can access claims through PostgREST :ref:`tx_settings`. For instance to get the email claim, call this function:
 .. code:: sql
  current_setting('request.jwt.claims', true)::json->>'email';
 .. note::
  For PostgreSQL < 14
  .. code:: sql
    current_setting('request.jwt.claim.email', true);
 This allows JWT generation services to include extra information and your database code to react to it. For instance the RLS example could be modified to use this ``current_setting`` rather than ``current_user``. The second ``'true'`` argument tells ``current_setting`` to return NULL if the setting is missing from the current configuration.
 Hybrid User-Group Roles
 -----------------------
 You can mix the group and individual role policies. For instance we could still have a webuser role and individual users which inherit from it:
 .. code-block:: postgres
  CREATE ROLE webuser NOLOGIN;
  -- grant this role access to certain tables etc
  CREATE ROLE user000 NOLOGIN;
  GRANT webuser TO user000;
  -- now user000 can do whatever webuser can
  GRANT user000 TO authenticator;
  -- allow authenticator to switch into user000 role
  -- (the role itself has nologin)
 .. _schema_isolation:
 Schemas
 =======
 A PostgREST instance exposes all the tables, views, and stored procedures of the schemas configured in :ref:`db-schemas`. This means private data or implementation details can go inside private schemas and be invisible to HTTP clients.
 It is recommended that you don't expose tables on the schemas you expose, instead expose views and stored procedures which insulate the internal details from the outside world.
 This allows you to change the internals of your schema and maintain backwards compatibility. It also keeps your code easier to refactor, and provides a natural way to do API versioning.
 .. image:: ../_static/db.png
 You must explicitly allow roles to access the exposed schemas:
 .. code-block:: postgres
   GRANT USAGE ON SCHEMA api TO webuser;
 Tables
 ======
 To let web users access tables you must grant them privileges for the operations you want them to do.
 .. code-block:: postgres
  GRANT
    SELECT
  , INSERT
  , UPDATE(message_body)
  , DELETE
  ON chat TO webuser;
 You can also choose on which table columns the operation is valid. In the above example, the web user can only update the ``message_body`` column.
 .. _func_privs:
 Functions
 =========
 By default, when a function is created, the privilege to execute it is not restricted by role. The function access is ``PUBLIC`` — executable by all roles (more details at `PostgreSQL Privileges page <https://www.postgresql.org/docs/current/ddl-priv.html>`_). This is not ideal for an API schema. To disable this behavior, you can run the following SQL statement:
 .. code-block:: postgres
  ALTER DEFAULT PRIVILEGES REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;
 This will change the privileges for all functions created in the future in all schemas. Currently there is no way to limit it to a single schema. In our opinion it's a good practice anyway.
 .. note::
    It is however possible to limit the effect of this clause only to functions you define. You can put the above statement at the beginning of the API schema definition, and then at the end reverse it with:
    .. code-block:: postgres
        ALTER DEFAULT PRIVILEGES GRANT EXECUTE ON FUNCTIONS TO PUBLIC;
    This will work because the :code:`alter default privileges` statement has effect on function created *after* it is executed. See `PostgreSQL alter default privileges <https://www.postgresql.org/docs/current/sql-alterdefaultprivileges.html>`_ for more details.
 After that, you'll need to grant EXECUTE privileges on functions explicitly:
 .. code-block:: postgres
   GRANT EXECUTE ON FUNCTION login TO anonymous;
   GRANT EXECUTE ON FUNCTION signup TO anonymous;
 You can also grant execute on all functions in a schema to a higher privileged role:
 .. code-block:: postgres
    GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA api TO web_user;
 Security definer
 ----------------
 A function is executed with the privileges of the user who calls it. This means that the user has to have all permissions to do the operations the procedure performs.
 If the function accesses private database objects, your :ref:`API roles <roles>` won't be able to successfully execute the function.
 Another option is to define the function with the :code:`SECURITY DEFINER` option. Then only one permission check will take place, the permission to call the function, and the operations in the function will have the authority of the user who owns the function itself.
 .. code-block:: postgres
  -- login as a user wich has privileges on the private schemas
  -- create a sample function
  create or replace function login(email text, pass text) returns jwt_token as $$
  begin
    -- access to a private schema called 'auth'
    select auth.user_role(email, pass) into _role;
    -- other operations
    -- ...
  end;
  $$ language plpgsql security definer;
 Note the ``SECURITY DEFINER`` keywords at the end of the function. See `PostgreSQL documentation <https://www.postgresql.org/docs/current/sql-createfunction.html#SQL-CREATEFUNCTION-SECURITY>`_ for more details.
 Views
 =====
 Views are invoked with the privileges of the view owner, much like stored procedures with the ``SECURITY DEFINER`` option. When created by a SUPERUSER role, all `row-level security <https://www.postgresql.org/docs/current/ddl-rowsecurity.html>`_ policies will be bypassed.
 If you're on PostgreSQL >= 15, this behavior can be changed by specifying the ``security_invoker`` option.
 .. code-block:: postgres
  CREATE VIEW sample_view WITH (security_invoker = true) AS
  SELECT * FROM sample_table;
 On PostgreSQL < 15, you can create a non-SUPERUSER role and make this role the view's owner.
 .. code-block:: postgres
  CREATE ROLE api_views_owner NOSUPERUSER NOBYPASSRLS;
  ALTER VIEW sample_view OWNER TO api_views_owner;
@@ -0,0 +1,263 @@
 .. _install:
 Installation
 ############
 The release page has `pre-compiled binaries for Mac OS X, Windows, Linux and FreeBSD <https://github.com/PostgREST/postgrest/releases/latest>`_ .
 The Linux binary is a static executable that can be run on any Linux distribution.
 You can also use your OS package manager.
 .. tabs::
  .. group-tab:: Mac OSX
    You can install PostgREST from the `Homebrew official repo <https://formulae.brew.sh/formula/postgrest>`_.
    .. code:: bash
      brew install postgrest
  .. group-tab:: FreeBSD
    You can install PostgREST from the `official ports <https://www.freshports.org/www/hs-postgrest>`_.
    .. code:: bash
      pkg install hs-postgrest
  .. group-tab:: Linux
    .. tabs::
      .. tab:: Arch Linux
        You can install PostgREST from the `community repo <https://archlinux.org/packages/extra/x86_64/postgrest/>`_.
        .. code:: bash
          pacman -S postgrest
      .. tab:: Nix
        You can install PostgREST from nixpkgs.
        .. code:: bash
          nix-env -i haskellPackages.postgrest
  .. group-tab:: Windows
    You can install PostgREST using `Chocolatey <https://community.chocolatey.org/packages/postgrest>`_ or `Scoop <https://github.com/ScoopInstaller/Scoop>`_.
    .. code:: bash
      choco install postgrest
      scoop install postgrest
 .. _pg-dependency:
 Supported PostgreSQL versions
 =============================
 =============== =================================
 **Supported**   PostgreSQL >= 9.6
 =============== =================================
 PostgREST works with all PostgreSQL versions starting from 9.6.
 Running PostgREST
 =================
 If you downloaded PostgREST from the release page, first extract the compressed file to obtain the executable.
 .. code-block:: bash
  # For UNIX platforms
  tar Jxf postgrest-[version]-[platform].tar.xz
  # On Windows you should unzip the file
 Now you can run PostgREST with the :code:`--help` flag to see usage instructions:
 .. code-block:: bash
  # Running postgrest binary
  ./postgrest --help
  # Running postgrest installed from a package manager
  postgrest --help
  # You should see a usage help message
 The PostgREST server reads a configuration file as its only argument:
 .. code:: bash
  postgrest /path/to/postgrest.conf
  # You can also generate a sample config file with
  # postgrest -e > postgrest.conf
  # You'll need to edit this file and remove the usage parts for postgrest to read it
 For a complete reference of the configuration file, see :ref:`configuration`.
 .. note::
  If you see a dialog box like this on Windows, it may be that the :code:`pg_config` program is not in your system path.
  .. image:: ../_static/win-err-dialog.png
  It usually lives in :code:`C:\Program Files\PostgreSQL\<version>\bin`. See this `article <https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/>`_ about how to modify the system path.
  To test that the system path is set correctly, run ``pg_config`` from the command line. You should see it output a list of paths.
 Docker
 ======
 You can get the `official PostgREST Docker image <https://hub.docker.com/r/postgrest/postgrest>`_ with:
 .. code-block:: bash
  docker pull postgrest/postgrest
 To configure the container image, use :ref:`env_variables_config`.
 There are two ways to run the PostgREST container: with an existing external database, or through docker-compose.
 Containerized PostgREST with native PostgreSQL
 ----------------------------------------------
 The first way to run PostgREST in Docker is to connect it to an existing native database on the host.
 .. code-block:: bash
  # Run the server
  docker run --rm --net=host \
    -e PGRST_DB_URI="postgres://app_user:password@localhost/postgres" \
    postgrest/postgrest
 The database connection string above is just an example. Adjust the role and password as necessary. You may need to edit PostgreSQL's :code:`pg_hba.conf` to grant the user local login access.
 .. note::
  Docker on Mac does not support the :code:`--net=host` flag. Instead you'll need to create an IP address alias to the host. Requests for the IP address from inside the container are unable to resolve and fall back to resolution by the host.
  .. code-block:: bash
    sudo ifconfig lo0 10.0.0.10 alias
  You should then use 10.0.0.10 as the host in your database connection string. Also remember to include the IP address in the :code:`listen_address` within postgresql.conf. For instance:
  .. code-block:: bash
    listen_addresses = 'localhost,10.0.0.10'
  You might also need to add a new IPv4 local connection within pg_hba.conf. For instance:
  .. code-block:: bash
    host    all             all             10.0.0.10/32            trust
  The docker command will then look like this:
  .. code-block:: bash
    # Run the server
    docker run --rm -p 3000:3000 \
      -e PGRST_DB_URI="postgres://app_user:password@10.0.0.10/postgres" \
      postgrest/postgrest
 .. _pg-in-docker:
 Containerized PostgREST *and* db with docker-compose
 ----------------------------------------------------
 To avoid having to install the database at all, you can run both it and the server in containers and link them together with docker-compose. Use this configuration:
 .. code-block:: yaml
  # docker-compose.yml
  version: '3'
  services:
    server:
      image: postgrest/postgrest
      ports:
        - "3000:3000"
      environment:
        PGRST_DB_URI: postgres://app_user:password@db:5432/app_db
        PGRST_OPENAPI_SERVER_PROXY_URI: http://127.0.0.1:3000
      depends_on:
        - db
    db:
      image: postgres
      ports:
        - "5432:5432"
      environment:
        POSTGRES_DB: app_db
        POSTGRES_USER: app_user
        POSTGRES_PASSWORD: password
    # Uncomment this if you want to persist the data.
    # volumes:
    #   - "./pgdata:/var/lib/postgresql/data"
 Go into the directory where you saved this file and run :code:`docker-compose up`. You will see the logs of both the database and PostgREST, and be able to access the latter on port 3000.
 If you want to have a visual overview of your API in your browser you can add swagger-ui to your :code:`docker-compose.yml`:
 .. code-block:: yaml
  swagger:
    image: swaggerapi/swagger-ui
    ports:
      - "8080:8080"
    expose:
      - "8080"
    environment:
      API_URL: http://localhost:3000/
 With this you can see the swagger-ui in your browser on port 8080.
 .. _build_source:
 Building from Source
 ====================
 When a pre-built binary does not exist for your system you can build the project from source.
 .. note::
  We discourage building and using PostgREST on **Alpine Linux** because of a reported GHC memory leak on that platform.
 You can build PostgREST from source with `Stack <https://github.com/commercialhaskell/stack>`_. It will install any necessary Haskell dependencies on your system.
 * `Install Stack <https://docs.haskellstack.org/en/stable/#how-to-install-stack>`_ for your platform
 * Install Library Dependencies
  =====================  =======================================
  Operating System       Dependencies
  =====================  =======================================
  Ubuntu/Debian          libpq-dev, libgmp-dev, zlib1g-dev
  CentOS/Fedora/Red Hat  postgresql-devel, zlib-devel, gmp-devel
  BSD                    postgresql12-client
  OS X                   libpq, gmp
  =====================  =======================================
 * Build and install binary
  .. code-block:: bash
    git clone https://github.com/PostgREST/postgrest.git
    cd postgrest
    # adjust local-bin-path to taste
    stack build --install-ghc --copy-bins --local-bin-path /usr/local/bin
 .. note::
   - If building fails and your system has less than 1GB of memory, try adding a swap file.
   - `--install-ghc` flag is only needed for the first build and can be omitted in the subsequent builds.
 * Check that the server is installed: :code:`postgrest --help`.
@@ -0,0 +1,109 @@
 .. _nginx:
 Nginx
 =====
 PostgREST is a fast way to construct a RESTful API. Its default behavior is great for scaffolding in development. When it's time to go to production it works great too, as long as you take precautions.
 PostgREST is a small sharp tool that focuses on performing the API-to-database mapping. We rely on a reverse proxy like Nginx for additional safeguards.
 The first step is to create an Nginx configuration file that proxies requests to an underlying PostgREST server.
 .. code-block:: nginx
  http {
    # ...
    # upstream configuration
    upstream postgrest {
      server localhost:3000;
    }
    # ...
    server {
      # ...
      # expose to the outside world
      location /api/ {
        default_type  application/json;
        proxy_hide_header Content-Location;
        add_header Content-Location  /api/$upstream_http_content_location;
        proxy_set_header  Connection "";
        proxy_http_version 1.1;
        proxy_pass http://postgrest/;
      }
      # ...
    }
  }
 .. note::
  For ubuntu, if you already installed nginx through :code:`apt` you can add this to the config file in
  :code:`/etc/nginx/sites-enabled/default`.
 .. _https:
 HTTPS
 -----
 PostgREST aims to do one thing well: add an HTTP interface to a PostgreSQL database. To keep the code small and focused we do not implement HTTPS. Use a reverse proxy such as NGINX to add this, `here's how <https://nginx.org/en/docs/http/configuring_https_servers.html>`_. Note that some Platforms as a Service like Heroku also add SSL automatically in their load balancer.
 Rate Limiting
 -------------
 Nginx supports "leaky bucket" rate limiting (see `official docs <https://nginx.org/en/docs/http/ngx_http_limit_req_module.html>`_). Using standard Nginx configuration, routes can be grouped into *request zones* for rate limiting. For instance we can define a zone for login attempts:
 .. code-block:: nginx
  limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;
 This creates a shared memory zone called "login" to store a log of IP addresses that access the rate limited urls. The space reserved, 10 MB (:code:`10m`) will give us enough space to store a history of 160k requests. We have chosen to allow only allow one request per second (:code:`1r/s`).
 Next we apply the zone to certain routes, like a hypothetical stored procedure called :code:`login`.
 .. code-block:: nginx
  location /rpc/login/ {
    # apply rate limiting
    limit_req zone=login burst=5;
  }
 The burst argument tells Nginx to start dropping requests if more than five queue up from a specific IP.
 Nginx rate limiting is general and indiscriminate. To rate limit each authenticated request individually you will need to add logic in a :ref:`Custom Validation <custom_validation>` function.
 Alternate URL Structure
 -----------------------
 As discussed in :ref:`singular_plural`, there are no special URL forms for singular resources in PostgREST, only operators for filtering. Thus there are no URLs like :code:`/people/1`. It would be specified instead as
 .. tabs::
  .. code-tab:: http
    GET /people?id=eq.1 HTTP/1.1
    Accept: application/vnd.pgrst.object+json
  .. code-tab:: bash Curl
    curl "http://localhost:3000/people?id=eq.1" \
      -H "Accept: application/vnd.pgrst.object+json"
 This allows compound primary keys and makes the intent for singular response independent of a URL convention.
 Nginx rewrite rules allow you to simulate the familiar URL convention. The following example adds a rewrite rule for all table endpoints, but you'll want to restrict it to those tables that have a numeric simple primary key named "id."
 .. code-block:: nginx
  # support /endpoint/:id url style
  location ~ ^/([a-z_]+)/([0-9]+) {
    # make the response singular
    proxy_set_header Accept 'application/vnd.pgrst.object+json';
    # assuming an upstream named "postgrest"
    proxy_pass http://postgrest/$1?id=eq.$2;
  }
 .. TODO
 .. Administration
 ..   API Versioning
 ..   HTTP Caching
 ..   Upgrading
@@ -0,0 +1,33 @@
 { lib
 , buildPythonPackage
 , fetchFromGitHub
 , sphinx
 }:
 buildPythonPackage rec {
  pname = "sphinx-copybutton";
  version = "0.4.0";
  src = fetchFromGitHub {
    owner = "executablebooks";
    repo = "sphinx-copybutton";
    rev = "v${version}";
    sha256 = "sha256-vrEIvQeP7AMXSme1PBp0ox5k8Q1rz+1cbHIO+o17Jqc=";
    fetchSubmodules = true;
  };
  propagatedBuildInputs = [
    sphinx
  ];
  doCheck = false; # no tests
  pythonImportsCheck = [ "sphinx_copybutton" ];
  meta = with lib; {
    description = "A small sphinx extension to add a \"copy\" button to code blocks";
    homepage = "https://github.com/executablebooks/sphinx-copybutton";
    license = licenses.mit;
    maintainers = with maintainers; [ Luflosi ];
  };
 }
@@ -0,0 +1,29 @@
 { lib
 , buildPythonPackage
 , fetchPypi
 , sphinx
 }:
 buildPythonPackage rec {
  pname = "sphinx-tabs";
  version = "3.2.0";
  src = fetchPypi {
    inherit pname version;
    sha256 = "sha256:1970aahi6sa7c37cpz8nwgdb2xzf21rk6ykdd1m6w9wvxla7j4rk";
  };
  propagatedBuildInputs = [
    sphinx
  ];
  doCheck = false;
  pythonImportsCheck = [ "sphinx_tabs" ];
  meta = with lib; {
    description = "Create tabbed content in Sphinx documentation when building HTML";
    homepage = "https://sphinx-tabs.readthedocs.io";
    license = licenses.mit;
  };
 }
@@ -0,0 +1,222 @@
 .. _create_soap_endpoint:
 Create a SOAP endpoint
 ======================
 :author: `fjf2002 <https://github.com/fjf2002>`_
 PostgREST now has XML support. With a bit of work, SOAP endpoints become possible.
 Please note that PostgREST supports just ``text/xml`` MIME type in request/response headers ``Content-Type`` and ``Accept``.
 If you have to use other MIME types such as ``application/soap+xml``, you could manipulate the headers in your reverse proxy.
 Minimal Example
 ---------------
 This example will simply return the request body, inside a tag ``therequestbodywas``.
 Add the following function to your PostgreSQL database:
 .. code-block:: postgres
   CREATE OR REPLACE FUNCTION my_soap_endpoint(xml) RETURNS xml AS $$
   DECLARE
     nsarray CONSTANT text[][] := ARRAY[
       ARRAY['soapenv', 'http://schemas.xmlsoap.org/soap/envelope/']
     ];
   BEGIN
     RETURN xmlelement(
       NAME "soapenv:Envelope",
       XMLATTRIBUTES('http://schemas.xmlsoap.org/soap/envelope/' AS "xmlns:soapenv"),
       xmlelement(NAME "soapenv:Header"),
       xmlelement(
         NAME "soapenv:Body",
         xmlelement(
           NAME theRequestBodyWas,
           (xpath('/soapenv:Envelope/soapenv:Body', $1, nsarray))[1]
         )
       )
    );
   END;
   $$ LANGUAGE plpgsql;
 Do not forget to refresh the :ref:`PostgREST schema cache <schema_reloading>`.
 Use ``curl`` for a first test:
 .. code-block:: bash
    curl http://localhost:3000/rpc/my_soap_endpoint \
        --header 'Content-Type: text/xml' \
        --header 'Accept: text/xml' \
        --data-binary @- <<XML
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Header/>
      <soapenv:Body>
        <mySOAPContent>
          My SOAP Content
        </mySOAPContent>
      </soapenv:Body>
    </soapenv:Envelope>
    XML
 The output should contain the original request body within the ``therequestbodywas`` entity,
 and should roughly look like:
 .. code-block:: xml
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Header/>
      <soapenv:Body>
        <therequestbodywas>
          <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
            <mySOAPContent>
              My SOAP Content
            </mySOAPContent>
          </soapenv:Body>
        </therequestbodywas>
      </soapenv:Body>
    </soapenv:Envelope>
 Unfortunately the ``Accept: text/xml`` header is currently mandatory concerning PostgREST, otherwise it will respond
 with a ``Content-Type: application/json`` header and enclose the response with quotes.
 (You can check the returned headers by adding ``-v`` to the curl call.)
 If your SOAP clients do not send the ``Accept: text/xml`` header, you can fix that in your nginx reverse proxy
 by adding something like ...
 .. code-block:: nginx
    set $accept $http_accept;
    if ($contentType ~ "^text/xml($|;)") {
        set $accept "text/xml";
    }
    proxy_set_header Accept $accept;
 to your ``location`` nginx configuration.
 (The given example sets the ``Accept`` header for each request of Content-Type ``text/xml``.)
 A more elaborate example
 ------------------------
 Here we have a SOAP service that converts a fraction to a decimal value,
 with pass-through of PostgreSQL errors to the SOAP response.
 Please note that in production you probably should not pass through plain database errors
 potentially disclosing internals to the client, but instead handle the errors directly.
 .. code-block:: postgres
   -- helper function
   CREATE OR REPLACE FUNCTION _soap_envelope(body xml)
    RETURNS xml
    LANGUAGE sql
   AS $function$
     SELECT xmlelement(
       NAME "soapenv:Envelope",
       XMLATTRIBUTES('http://schemas.xmlsoap.org/soap/envelope/' AS "xmlns:soapenv"),
       xmlelement(NAME "soapenv:Header"),
       xmlelement(NAME "soapenv:Body", body)
     );
   $function$;
   -- helper function
   CREATE OR REPLACE FUNCTION _soap_exception(
     faultcode text,
     faultstring text
   )
    RETURNS xml
    LANGUAGE sql
   AS $function$
     SELECT _soap_envelope(
       xmlelement(NAME "soapenv:Fault",
         xmlelement(NAME "faultcode", faultcode),
         xmlelement(NAME "faultstring", faultstring)
       )
     );
   $function$;
   CREATE OR REPLACE FUNCTION fraction_to_decimal(xml)
    RETURNS xml
    LANGUAGE plpgsql
   AS $function$
   DECLARE
     nsarray CONSTANT text[][] := ARRAY[
       ARRAY['soapenv', 'http://schemas.xmlsoap.org/soap/envelope/']
     ];
     exc_msg text;
     exc_detail text;
     exc_hint text;
     exc_sqlstate text;
   BEGIN
     -- simulating a statement that results in an exception:
     RETURN _soap_envelope(xmlelement(
       NAME "decimalValue",
       (
         (xpath('/soapenv:Envelope/soapenv:Body/fraction/numerator/text()', $1, nsarray))[1]::text::int
         /
         (xpath('/soapenv:Envelope/soapenv:Body/fraction/denominator/text()', $1, nsarray))[1]::text::int
       )::text::xml
     ));
   EXCEPTION WHEN OTHERS THEN
     GET STACKED DIAGNOSTICS
       exc_msg := MESSAGE_TEXT,
       exc_detail := PG_EXCEPTION_DETAIL,
       exc_hint := PG_EXCEPTION_HINT,
       exc_sqlstate := RETURNED_SQLSTATE;
     RAISE WARNING USING
       MESSAGE = exc_msg,
       DETAIL = exc_detail,
       HINT = exc_hint;
     RETURN _soap_exception(faultcode => exc_sqlstate, faultstring => concat(exc_msg, ', DETAIL: ', exc_detail, ', HINT: ', exc_hint));
   END
   $function$;
 Let's test the ``fraction_to_decimal`` service with illegal values:
 .. code-block:: bash
    curl http://localhost:3000/rpc/fraction_to_decimal \
      --header 'Content-Type: text/xml' \
      --header 'Accept: text/xml' \
      --data-binary @- <<XML
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Header/>
      <soapenv:Body>
        <fraction>
          <numerator>42</numerator>
          <denominator>0</denominator>
        </fraction>
      </soapenv:Body>
    </soapenv:Envelope>
    XML
 The output should roughly look like:
 .. code-block:: xml
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
     <soapenv:Header/>
     <soapenv:Body>
       <soapenv:Fault>
         <faultcode>22012</faultcode>
         <faultstring>division by zero, DETAIL: , HINT: </faultstring>
       </soapenv:Fault>
     </soapenv:Body>
   </soapenv:Envelope>
 References
 ----------
 For more information concerning PostgREST, cf.
 - :ref:`s_proc_single_unnamed`
 - :ref:`scalar_return_formats`
 - :ref:`Nginx reverse proxy <admin>`
 For SOAP reference, visit
 - the specification at https://www.w3.org/TR/soap/
 - shorter more practical advice is available at https://www.w3schools.com/xml/xml_soap.asp
@@ -0,0 +1,96 @@
 .. _providing_img:
 Providing images for ``<img>``
 ==============================
 :author: `pkel <https://github.com/pkel>`_
 In this how-to, you will learn how to create an endpoint for providing images to HTML :code:`<img>` tags without client side JavaScript. In fact, the presented technique is suitable for providing not only images, but arbitrary files.
 We will start with a minimal example that highlights the general concept.
 Afterwards we present a more detailed solution that fixes a few shortcomings of the first approach.
 .. warning::
   Be careful when saving binaries in the database, having a separate storage service for these is preferable in most cases. See `Storing Binary files in the Database <https://wiki.postgresql.org/wiki/BinaryFilesInDB>`_.
 Minimal Example
 ---------------
 First, we need a public table for storing the files.
 .. code-block:: postgres
   create table files(
     id   int primary key
   , blob bytea
   );
 Let's assume this table contains an image of two cute kittens with id 42.
 We can retrieve this image in binary format from our PostgREST API by requesting :code:`/files?select=blob&id=eq.42` with the :code:`Accept: application/octet-stream` header.
 Unfortunately, putting the URL into the :code:`src` of an :code:`<img>` tag will not work.
 That's because browsers do not send the required :code:`Accept: application/octet-stream` header.
 Luckily we can specify the accepted media types in the :ref:`raw-media-types` configuration variable.
 In this case, the :code:`Accept: image/webp` header is sent by many web browsers by default, so let's add it to the configuration variable, like this: :code:`raw-media-types="image/webp"`.
 Now, the image will be displayed in the HTML page:
 .. code-block:: html
   <img src="http://localhost:3000/files?select=blob&id=eq.42" alt="Cute Kittens"/>
 Improved Version
 ----------------
 The basic solution has some shortcomings:
 1.  The response :code:`Content-Type` header is set to :code:`image/webp`.
    This might be a problem if you want to specify a different format for the file.
 2.  Download requests (e.g. Right Click -> Save Image As) to :code:`/files?select=blob&id=eq.42` will propose :code:`files` as filename.
    This might confuse users.
 3.  Requests to the binary endpoint are not cached.
    This will cause unnecessary load on the database.
 The following improved version addresses these problems.
 First, in addition to the minimal example, we need to store the media types and names of our files in the database.
 .. code-block:: postgres
   alter table files
     add column type text,
     add column name text;
 Next, we set up an RPC endpoint that sets the content type and filename.
 We use this opportunity to configure some basic, client-side caching.
 For production, you probably want to configure additional caches, e.g. on the :ref:`reverse proxy <admin>`.
 .. code-block:: postgres
   create function file(id int) returns bytea as
   $$
     declare headers text;
     declare blob bytea;
     begin
       select format(
         '[{"Content-Type": "%s"},'
          '{"Content-Disposition": "inline; filename=\"%s\""},'
          '{"Cache-Control": "max-age=259200"}]'
         , files.type, files.name)
       from files where files.id = file.id into headers;
       perform set_config('response.headers', headers, true);
       select files.blob from files where files.id = file.id into blob;
       if found
       then return(blob);
       else raise sqlstate 'PT404' using
         message = 'NOT FOUND',
         detail = 'File not found',
         hint = format('%s seems to be an invalid file id', file.id);
       end if;
     end
   $$ language plpgsql;
 With this, we can obtain the cat image from :code:`/rpc/file?id=42`. Thus, the resulting HTML will be:
 .. code-block:: html
   <img src="http://localhost:3000/rpc/file?id=42" alt="Cute Kittens"/>
@@ -0,0 +1,339 @@
 .. _sql-user-management-using-postgres-users-and-passwords:
 SQL User Management using postgres' users and passwords
 =======================================================
 :author: `fjf2002 <https://github.com/fjf2002>`_
 This is an alternative to chapter :ref:`sql_user_management`, solely using the PostgreSQL built-in table `pg_catalog.pg_authid <https://www.postgresql.org/docs/current/catalog-pg-authid.html>`_ for user management. This means
 - no dedicated user table (aside from :code:`pg_authid`) is required
 - PostgreSQL's users and passwords (i. e. the stuff in :code:`pg_authid`) are also used at the PostgREST level.
 .. note::
  Only PostgreSQL users with SCRAM-SHA-256 password hashes (the default since PostgreSQL v14) are supported.
 .. warning::
  This is experimental. We can't give you any guarantees, especially concerning security. Use at your own risk.
 Working with pg_authid and SCRAM-SHA-256 hashes
 -----------------------------------------------
 As in :ref:`sql_user_management`, we create a :code:`basic_auth` schema:
 .. code-block:: postgres
  -- We put things inside the basic_auth schema to hide
  -- them from public view. Certain public procs/views will
  -- refer to helpers and tables inside.
  CREATE SCHEMA IF NOT EXISTS basic_auth;
 As in :ref:`sql_user_management`, we create the :code:`pgcrypto` and :code:`pgjwt` extensions. Here we prefer to put the extensions in its own schemas:
 .. code-block:: postgres
  CREATE SCHEMA ext_pgcrypto;
  ALTER SCHEMA ext_pgcrypto OWNER TO postgres;
  CREATE EXTENSION IF NOT EXISTS pgcrypto WITH SCHEMA ext_pgcrypto;
 Concerning the `pgjwt extension <https://github.com/michelp/pgjwt>`_, please cf. to :ref:`client_auth`.
 .. code-block:: postgres
  CREATE SCHEMA ext_pgjwt;
  ALTER SCHEMA ext_pgjwt OWNER TO postgres;
  CREATE EXTENSION IF NOT EXISTS pgjwt WITH SCHEMA ext_pgjwt;
 In order to be able to work with postgres' SCRAM-SHA-256 password hashes, we also need the PBKDF2 key derivation function. Luckily there is `a PL/pgSQL implementation on stackoverflow <https://stackoverflow.com/q/47162200/2337147>`_:
 .. code-block:: plpgsql
  CREATE FUNCTION basic_auth.pbkdf2(salt bytea, pw text, count integer, desired_length integer, algorithm text) RETURNS bytea
      LANGUAGE plpgsql IMMUTABLE
      AS $$
  DECLARE
    hash_length integer;
    block_count integer;
    output bytea;
    the_last bytea;
    xorsum bytea;
    i_as_int32 bytea;
    i integer;
    j integer;
    k integer;
  BEGIN
    algorithm := lower(algorithm);
    CASE algorithm
    WHEN 'md5' then
      hash_length := 16;
    WHEN 'sha1' then
      hash_length = 20;
    WHEN 'sha256' then
      hash_length = 32;
    WHEN 'sha512' then
      hash_length = 64;
    ELSE
      RAISE EXCEPTION 'Unknown algorithm "%"', algorithm;
    END CASE;
    --
    block_count := ceil(desired_length::real / hash_length::real);
    --
    FOR i in 1 .. block_count LOOP
      i_as_int32 := E'\\000\\000\\000'::bytea || chr(i)::bytea;
      i_as_int32 := substring(i_as_int32, length(i_as_int32) - 3);
      --
      the_last := salt::bytea || i_as_int32;
      --
      xorsum := ext_pgcrypto.HMAC(the_last, pw::bytea, algorithm);
      the_last := xorsum;
      --
      FOR j IN 2 .. count LOOP
        the_last := ext_pgcrypto.HMAC(the_last, pw::bytea, algorithm);
        -- xor the two
        FOR k IN 1 .. length(xorsum) LOOP
          xorsum := set_byte(xorsum, k - 1, get_byte(xorsum, k - 1) # get_byte(the_last, k - 1));
        END LOOP;
      END LOOP;
      --
      IF output IS NULL THEN
        output := xorsum;
      ELSE
        output := output || xorsum;
      END IF;
    END LOOP;
    --
    RETURN substring(output FROM 1 FOR desired_length);
  END $$;
  ALTER FUNCTION basic_auth.pbkdf2(salt bytea, pw text, count integer, desired_length integer, algorithm text) OWNER TO postgres;
 Analogous to :ref:`sql_user_management` creates the function :code:`basic_auth.user_role`, we create a helper function to check the user's password, here with another name and signature (since we want the username, not an email address).
 But contrary to :ref:`sql_user_management`, this function does not use a dedicated :code:`users` table with passwords, but instead utilizes the built-in table `pg_catalog.pg_authid <https://www.postgresql.org/docs/current/catalog-pg-authid.html>`_:
 .. code-block:: plpgsql
  CREATE FUNCTION basic_auth.check_user_pass(username text, password text) RETURNS name
      LANGUAGE sql
      AS
  $$
    SELECT rolname AS username
    FROM pg_authid
    -- regexp-split scram hash:
    CROSS JOIN LATERAL regexp_match(rolpassword, '^SCRAM-SHA-256\$(.*):(.*)\$(.*):(.*)$') AS rm
    -- identify regexp groups with sane names:
    CROSS JOIN LATERAL (SELECT rm[1]::integer AS iteration_count, decode(rm[2], 'base64') as salt, decode(rm[3], 'base64') AS stored_key, decode(rm[4], 'base64') AS server_key, 32 AS digest_length) AS stored_password_part
    -- calculate pbkdf2-digest:
    CROSS JOIN LATERAL (SELECT basic_auth.pbkdf2(salt, check_user_pass.password, iteration_count, digest_length, 'sha256')) AS digest_key(digest_key)
    -- based on that, calculate hashed passwort part:
    CROSS JOIN LATERAL (SELECT ext_pgcrypto.digest(ext_pgcrypto.hmac('Client Key', digest_key, 'sha256'), 'sha256') AS stored_key, ext_pgcrypto.hmac('Server Key', digest_key, 'sha256') AS server_key) AS check_password_part
    WHERE rolpassword IS NOT NULL
      AND pg_authid.rolname = check_user_pass.username
      -- verify password:
      AND check_password_part.stored_key = stored_password_part.stored_key
      AND check_password_part.server_key = stored_password_part.server_key;
  $$;
  ALTER FUNCTION basic_auth.check_user_pass(username text, password text) OWNER TO postgres;
 Public User Interface
 ---------------------
 Analogous to :ref:`sql_user_management`, we create a login function which takes a username and password and returns a JWT if the credentials match a user in the internal table.
 Here we use the username instead of the email address to identify a user.
 Logins
 ~~~~~~
 As described in :ref:`client_auth`, we'll create a JWT token inside our login function. Note that you'll need to adjust the secret key which is hard-coded in this example to a secure (at least thirty-two character) secret of your choosing.
 .. code-block:: plpgsql
  CREATE TYPE basic_auth.jwt_token AS (
    token text
  );
  -- if you are not using psql, you need to replace :DBNAME with the current database's name.
  ALTER DATABASE :DBNAME SET "app.jwt_secret" to 'reallyreallyreallyreallyverysafe';
  CREATE FUNCTION public.login(username text, password text) RETURNS basic_auth.jwt_token
      LANGUAGE plpgsql security definer
      AS $$
  DECLARE
    _role name;
    result basic_auth.jwt_token;
  BEGIN
    -- check email and password
    SELECT basic_auth.check_user_pass(username, password) INTO _role;
    IF _role IS NULL THEN
      RAISE invalid_password USING message = 'invalid user or password';
    END IF;
    --
    SELECT ext_pgjwt.sign(
        row_to_json(r), current_setting('app.jwt_secret')
      ) AS token
      FROM (
        SELECT login.username as role,
          extract(epoch FROM now())::integer + 60*60 AS exp
      ) r
      INTO result;
    RETURN result;
  END;
  $$;
  ALTER FUNCTION public.login(username text, password text) OWNER TO postgres;
 Permissions
 ~~~~~~~~~~~
 Analogous to :ref:`sql_user_management`:
 Your database roles need access to the schema, tables, views and functions in order to service HTTP requests.
 Recall from the :ref:`roles` that PostgREST uses special roles to process requests, namely the authenticator and
 anonymous roles. Below is an example of permissions that allow anonymous users to attempt to log in.
 .. code-block:: postgres
  CREATE ROLE anon NOINHERIT;
  CREATE role authenticator NOINHERIT LOGIN PASSWORD 'secret';
  GRANT anon TO authenticator;
  GRANT EXECUTE ON FUNCTION public.login(username text, password text) TO anon;
 Since the above :code:`login` function is defined as `security definer <https://www.postgresql.org/docs/current/sql-createfunction.html#id-1.9.3.67.10.2>`_,
 the anonymous user :code:`anon` doesn't need permission to access the table :code:`pg_catalog.pg_authid` .
 :code:`grant execute on function` is included for clarity but it might not be needed, see :ref:`func_privs` for more details.
 Choose a secure password for role :code:`authenticator`.
 Do not forget to configure PostgREST to use the :code:`authenticator` user to connect, and to use the :code:`anon` user as anonymous user.
 Testing
 -------
 Let us create a sample user:
 .. code-block:: postgres
  CREATE ROLE foo PASSWORD 'bar';
 Test at the SQL level
 ~~~~~~~~~~~~~~~~~~~~~
 Execute:
 .. code-block:: postgres
  SELECT * FROM public.login('foo', 'bar');
 This should return a single scalar field like:
 ::
                                                              token
  -----------------------------------------------------------------------------------------------------------------------------
  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiZm9vIiwiZXhwIjoxNjY4MTg4ODQ3fQ.idBBHuDiQuN_S7JJ2v3pBOr9QypCliYQtCgwYOzAqEk
  (1 row)
 Test at the REST level
 ~~~~~~~~~~~~~~~~~~~~~~
 An API request to call this function would look like:
 .. tabs::
  .. code-tab:: http
    POST /rpc/login HTTP/1.1
    { "username": "foo", "password": "bar" }
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/login" \
      -X POST -H "Content-Type: application/json" \
      -d '{ "username": "foo", "password": "bar" }'
 The response would look like the snippet below. Try decoding the token at `jwt.io <https://jwt.io/>`_. (It was encoded with a secret of :code:`reallyreallyreallyreallyverysafe` as specified in the SQL code above. You'll want to change this secret in your app!)
 .. code:: json
  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoic2VwcCIsImV4cCI6MTY2ODE4ODQzN30.WSytcouNMQe44ZzOQit2AQsqTKFD5mIvT3z2uHwdoYY"
  }
 A more sophisticated test at the REST level
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Let's add a table, intended for the :code:`foo` user:
 .. code-block:: postgres
  CREATE TABLE public.foobar(foo int, bar text, baz float);
  ALTER TABLE public.foobar owner TO postgres;
 Now try to get the table's contents with:
 .. tabs::
  .. code-tab:: http
    GET /foobar HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/foobar"
 This should fail --- of course, we haven't specified the user, thus PostgREST falls back to the :code:`anon` user and denies access.
 Add an :code:`Authorization` header. Please use the token value from the login function call above instead of the one provided below.
 .. tabs::
  .. code-tab:: http
    GET /foobar HTTP/1.1
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiZm9vIiwiZXhwIjoxNjY4MTkyMjAyfQ.zzdHCBjfkqDQLQ8D7CHO3cIALF6KBCsfPTWgwhCiHCY
  .. code-tab:: bash Curl
    curl "http://localhost:3000/foobar" \
      -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiZm9vIiwiZXhwIjoxNjY4MTkyMjAyfQ.zzdHCBjfkqDQLQ8D7CHO3cIALF6KBCsfPTWgwhCiHCY"
 This will fail again --- we get :code:`Permission denied to set role`. We forgot to allow the authenticator role to switch into this user by executing:
 .. code-block:: postgres
  GRANT foo TO authenticator;
 Re-execute the last REST request. We fail again --- we also forgot to grant permissions for :code:`foo` on the table. Execute:
 .. code-block:: postgres
   GRANT SELECT ON TABLE public.foobar TO foo;
 Now the REST request should succeed. An empty JSON array :code:`[]` is returned.
@@ -0,0 +1,228 @@
 .. _sql_user_management:
 SQL User Management
 ===================
 As mentioned on :ref:`jwt_generation`, an external service can provide user management and coordinate with the PostgREST server using JWT. It’s also possible to support logins entirely through SQL. It’s a fair bit of work, so get ready.
 Storing Users and Passwords
 ---------------------------
 The following table, functions, and triggers will live in a :code:`basic_auth` schema that you shouldn't expose publicly in the API. The public views and functions will live in a different schema which internally references this internal information.
 First we'll need a table to keep track of our users:
 .. code:: sql
  -- We put things inside the basic_auth schema to hide
  -- them from public view. Certain public procs/views will
  -- refer to helpers and tables inside.
  create schema if not exists basic_auth;
  create table if not exists
  basic_auth.users (
    email    text primary key check ( email ~* '^.+@.+\..+$' ),
    pass     text not null check (length(pass) < 512),
    role     name not null check (length(role) < 512)
  );
 We would like the role to be a foreign key to actual database roles, however PostgreSQL does not support these constraints against the :code:`pg_roles` table. We'll use a trigger to manually enforce it.
 .. code-block:: plpgsql
  create or replace function
  basic_auth.check_role_exists() returns trigger as $$
  begin
    if not exists (select 1 from pg_roles as r where r.rolname = new.role) then
      raise foreign_key_violation using message =
        'unknown database role: ' || new.role;
      return null;
    end if;
    return new;
  end
  $$ language plpgsql;
  drop trigger if exists ensure_user_role_exists on basic_auth.users;
  create constraint trigger ensure_user_role_exists
    after insert or update on basic_auth.users
    for each row
    execute procedure basic_auth.check_role_exists();
 Next we'll use the pgcrypto extension and a trigger to keep passwords safe in the :code:`users` table.
 .. code-block:: plpgsql
  create extension if not exists pgcrypto;
  create or replace function
  basic_auth.encrypt_pass() returns trigger as $$
  begin
    if tg_op = 'INSERT' or new.pass <> old.pass then
      new.pass = crypt(new.pass, gen_salt('bf'));
    end if;
    return new;
  end
  $$ language plpgsql;
  drop trigger if exists encrypt_pass on basic_auth.users;
  create trigger encrypt_pass
    before insert or update on basic_auth.users
    for each row
    execute procedure basic_auth.encrypt_pass();
 With the table in place we can make a helper to check a password against the encrypted column. It returns the database role for a user if the email and password are correct.
 .. code-block:: plpgsql
  create or replace function
  basic_auth.user_role(email text, pass text) returns name
    language plpgsql
    as $$
  begin
    return (
    select role from basic_auth.users
     where users.email = user_role.email
       and users.pass = crypt(user_role.pass, users.pass)
    );
  end;
  $$;
 .. _public_ui:
 Public User Interface
 ---------------------
 In the previous section we created an internal table to store user information. Here we create a login function which takes an email address and password and returns JWT if the credentials match a user in the internal table.
 Permissions
 ~~~~~~~~~~~
 Your database roles need access to the schema, tables, views and functions in order to service HTTP requests.
 Recall from the :ref:`roles` that PostgREST uses special roles to process requests, namely the authenticator and
 anonymous roles. Below is an example of permissions that allow anonymous users to create accounts and attempt to log in.
 .. code-block:: postgres
  create role anon noinherit;
  create role authenticator noinherit;
  grant anon to authenticator;
 Then, add ``db-anon-role`` to the configuration file to allow anonymous requests.
 .. code:: ini
  db-anon-role = "anon"
 JWT from SQL
 ~~~~~~~~~~~~
 You can create JWT tokens in SQL using the `pgjwt extension <https://github.com/michelp/pgjwt>`_. It's simple and requires only pgcrypto. If you're on an environment like Amazon RDS which doesn't support installing new extensions, you can still manually run the `SQL inside pgjwt <https://github.com/michelp/pgjwt/blob/master/pgjwt--0.1.1.sql>`_ (you'll need to replace ``@extschema@`` with another schema or just delete it) which creates the functions you will need.
 Next write a stored procedure that returns the token. The one below returns a token with a hard-coded role, which expires five minutes after it was issued. Note this function has a hard-coded secret as well.
 .. code-block:: postgres
  CREATE TYPE jwt_token AS (
    token text
  );
  CREATE FUNCTION jwt_test() RETURNS public.jwt_token AS $$
    SELECT public.sign(
      row_to_json(r), 'reallyreallyreallyreallyverysafe'
    ) AS token
    FROM (
      SELECT
        'my_role'::text as role,
        extract(epoch from now())::integer + 300 AS exp
    ) r;
  $$ LANGUAGE sql;
 PostgREST exposes this function to clients via a POST request to ``/rpc/jwt_test``.
 .. note::
  To avoid hard-coding the secret in stored procedures, save it as a property of the database.
  .. code-block:: postgres
    -- run this once
    ALTER DATABASE mydb SET "app.jwt_secret" TO 'reallyreallyreallyreallyverysafe';
    -- then all functions can refer to app.jwt_secret
    SELECT sign(
      row_to_json(r), current_setting('app.jwt_secret')
    ) AS token
    FROM ...
 Logins
 ~~~~~~
 As described in `JWT from SQL`_, we'll create a JWT inside our login function. Note that you'll need to adjust the secret key which is hard-coded in this example to a secure (at least thirty-two character) secret of your choosing.
 .. code-block:: postgres
  -- add type
  CREATE TYPE basic_auth.jwt_token AS (
    token text
  );
  -- login should be on your exposed schema
  create or replace function
  login(email text, pass text) returns basic_auth.jwt_token as $$
  declare
    _role name;
    result basic_auth.jwt_token;
  begin
    -- check email and password
    select basic_auth.user_role(email, pass) into _role;
    if _role is null then
      raise invalid_password using message = 'invalid user or password';
    end if;
    select sign(
        row_to_json(r), 'reallyreallyreallyreallyverysafe'
      ) as token
      from (
        select _role as role, login.email as email,
           extract(epoch from now())::integer + 60*60 as exp
      ) r
      into result;
    return result;
  end;
  $$ language plpgsql security definer;
  grant execute on function login(text,text) to anon;
 Since the above :code:`login` function is defined as `security definer <https://www.postgresql.org/docs/current/sql-createfunction.html#id-1.9.3.67.10.2>`_,
 the anonymous user :code:`anon` doesn't need permission to read the :code:`basic_auth.users` table. It doesn't even need permission to access the :code:`basic_auth` schema.
 :code:`grant execute on function` is included for clarity but it might not be needed, see :ref:`func_privs` for more details.
 An API request to call this function would look like:
 .. tabs::
  .. code-tab:: http
    POST /rpc/login HTTP/1.1
    { "email": "foo@bar.com", "pass": "foobar" }
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/login" \
      -X POST -H "Content-Type: application/json" \
      -d '{ "email": "foo@bar.com", "pass": "foobar" }'
 The response would look like the snippet below. Try decoding the token at `jwt.io <https://jwt.io/>`_. (It was encoded with a secret of :code:`reallyreallyreallyreallyverysafe` as specified in the SQL code above. You'll want to change this secret in your app!)
 .. code:: json
  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImZvb0BiYXIuY29tIiwicGFzcyI6ImZvb2JhciJ9.37066TTRlh-1hXhnA9oO9Pj6lgL6zFuJU0iCHhuCFno"
  }
 Alternatives
 ~~~~~~~~~~~~
 See the how-to :ref:`sql-user-management-using-postgres-users-and-passwords` for a similar way that completely avoids the table :code:`basic_auth.users`.
@@ -0,0 +1,763 @@
 .. _working_with_types:
 Working with PostgreSQL data types
 ==================================
 :author: `Laurence Isla <https://github.com/laurenceisla>`_
 PostgREST makes use of PostgreSQL string representations to work with data types. Thanks to this, you can use special values, such as ``now`` for timestamps, ``yes`` for booleans or time values including the time zones. This page describes how you can take advantage of these string representations to perform operations on different PostgreSQL data types.
 .. contents::
  :local:
  :depth: 1
 Timestamps
 ----------
 You can use the **time zone** to filter or send data if needed.
 .. code-block:: postgres
  create table reports (
    id int primary key
    , due_date timestamptz
  );
 Suppose you are located in Sydney and want create a report with the date in the local time zone. Your request should look like this:
 .. tabs::
  .. code-tab:: http
    POST /reports HTTP/1.1
    Content-Type: application/json
    [{ "id": 1, "due_date": "2022-02-24 11:10:15 Australia/Sydney" },
     { "id": 2, "due_date": "2022-02-27 22:00:00 Australia/Sydney" }]
  .. code-tab:: bash Curl
    curl "http://localhost:3000/reports" \
      -X POST -H "Content-Type: application/json" \
      -d '[{ "id": 1, "due_date": "2022-02-24 11:10:15 Australia/Sydney" },{ "id": 2, "due_date": "2022-02-27 22:00:00 Australia/Sydney" }]'
 Someone located in Cairo can retrieve the data using their local time, too:
 .. tabs::
  .. code-tab:: http
    GET /reports?due_date=eq.2022-02-24+02:10:15+Africa/Cairo HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/reports?due_date=eq.2022-02-24+02:10:15+Africa/Cairo"
 .. code-block:: json
  [
    {
      "id": 1,
      "due_date": "2022-02-23T19:10:15-05:00"
    }
  ]
 The response has the date in the time zone configured by the server: ``UTC -05:00``.
 You can use other comparative filters and also all the `PostgreSQL special date/time input values <https://www.postgresql.org/docs/current/datatype-datetime.html#DATATYPE-DATETIME-SPECIAL-TABLE>`_ as illustrated in this example:
 .. tabs::
  .. code-tab:: http
    GET /reports?or=(and(due_date.gte.today,due_date.lte.tomorrow),and(due_date.gt.-infinity,due_date.lte.epoch)) HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/reports?or=(and(due_date.gte.today,due_date.lte.tomorrow),and(due_date.gt.-infinity,due_date.lte.epoch))"
 .. code-block:: json
  [
    {
      "id": 2,
      "due_date": "2022-02-27T06:00:00-05:00"
    }
  ]
 JSON
 ----
 To work with a ``json`` type column, you can handle the value as a JSON object.
 .. code-block:: postgres
  create table products (
    id int primary key,
    name text unique,
    extra_info json
  );
 You can insert a new product using a JSON object for the ``extra_info`` column:
 .. tabs::
  .. code-tab:: http
    POST /products HTTP/1.1
    Content-Type: application/json
    {
      "id": 1,
      "name": "Canned fish",
      "extra_info": {
        "expiry_date": "2025-12-31",
        "exportable": true
      }
    }
  .. code-tab:: bash Curl
    curl "http://localhost:3000/products" \
      -X POST -H "Content-Type: application/json" \
      -d @- << EOF
      {
        "id": 1,
        "name": "Canned fish",
        "extra_info": {
          "expiry_date": "2025-12-31",
          "exportable": true
        }
      }
    EOF
 To query and filter the data see :ref:`json_columns` for a complete reference.
 Arrays
 ------
 To handle `array types <https://www.postgresql.org/docs/current/arrays.html>`_ you can use string representation or JSON array format.
 .. code-block:: postgres
  create table movies (
    id int primary key,
    title text not null,
    tags text[],
    performance_times time[]
  );
 You can insert a new value using string representation.
 .. tabs::
  .. code-tab:: http
    POST /movies HTTP/1.1
    Content-Type: application/json
    {
      "id": 1,
      "title": "Paddington",
      "tags": "{family,comedy,not streamable}",
      "performance_times": "{12:40,15:00,20:00}"
    }
  .. code-tab:: bash Curl
    curl "http://localhost:3000/movies" \
      -X POST -H "Content-Type: application/json" \
      -d @- << EOF
      {
        "id": 1,
        "title": "Paddington",
        "tags": "{family,comedy,not streamable}",
        "performance_times": "{12:40,15:00,20:00}"
      }
    EOF
 Or you could send the same data using JSON array format:
 .. tabs::
  .. code-tab:: http
    POST /movies HTTP/1.1
    Content-Type: application/json
    {
      "id": 1,
      "title": "Paddington",
      "tags": ["family", "comedy", "not streamable"],
      "performance_times": ["12:40", "15:00", "20:00"]
    }
  .. code-tab:: bash Curl
    curl "http://localhost:3000/movies" \
      -X POST -H "Content-Type: application/json" \
      -d @- << EOF
      {
        "id": 1,
        "title": "Paddington",
        "tags": ["family", "comedy", "not streamable"],
        "performance_times": ["12:40", "15:00", "20:00"]
      }
    EOF
 To query the data you can use arrow operators. See :ref:`composite_array_columns`.
 Multidimensional Arrays
 ~~~~~~~~~~~~~~~~~~~~~~~
 Similarly to one-dimensional arrays, both the string representation and JSON array format are allowed.
 .. code-block:: postgres
  -- This new column stores the cinema, floor and auditorium numbers in that order
  alter table movies
  add column cinema_floor_auditorium int[][][];
 You can now update the item using JSON array format:
 .. tabs::
  .. code-tab:: http
    PATCH /movies?id=eq.1 HTTP/1.1
    Content-Type: application/json
    {
      "cinema_floor_auditorium": [ [ [1,2], [6,7] ], [ [3,5], [8,9] ] ]
    }
  .. code-tab:: bash Curl
    curl "http://localhost:3000/movies?id=eq.1" \
      -X PATCH -H "Content-Type: application/json" \
      -d @- << EOF
      {
        "cinema_floor_auditorium": [ [ [1,2], [6,7] ], [ [3,5], [8,9] ] ]
      }
    EOF
 Then, for example, to query the auditoriums that are located in the first cinema (position 0 in the array) and on the second floor (position 1 in the next inner array), we can use the arrow operators this way:
 .. tabs::
  .. code-tab:: http
    GET /movies?select=title,auditorium:cinema_floor_auditorium->0->1&id=eq.1 HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/movies?select=title,auditorium:cinema_floor_auditorium->0->1&id=eq.1"
 .. code-block:: json
  [
    {
      "title": "Paddington",
      "auditorium": [6,7]
    }
  ]
 Composite Types
 ---------------
 With PostgREST, you have two options to handle `composite type columns <https://www.postgresql.org/docs/current/rowtypes.html>`_.
 .. code-block:: postgres
  create type dimension as (
    length decimal(6,2),
    width decimal (6,2),
    height decimal (6,2),
    unit text
  );
  create table products (
    id int primary key,
    size dimension
  );
  insert into products (id, size)
  values (1, '(5.0,5.0,10.0,"cm")');
 On one hand you can insert values using string representation.
 .. tabs::
  .. code-tab:: http
    POST /products HTTP/1.1
    Content-Type: application/json
    { "id": 2, "size": "(0.7,0.5,1.8,\"m\")" }
  .. code-tab:: bash Curl
    curl "http://localhost:3000/products" \
      -X POST -H "Content-Type: application/json" \
      -d @- << EOF
      { "id": 2, "size": "(0.7,0.5,1.8,\"m\")" }
    EOF
 Or you could insert the same data in JSON format.
 .. tabs::
  .. code-tab:: http
    POST /products HTTP/1.1
    Content-Type: application/json
      {
        "id": 2,
        "size": {
          "length": 0.7,
          "width": 0.5,
          "height": 1.8,
          "unit": "m"
        }
      }
  .. code-tab:: bash Curl
    curl "http://localhost:3000/products" \
      -X POST -H "Content-Type: application/json" \
      -d @- << EOF
      {
        "id": 2,
        "size": {
          "length": 0.7,
          "width": 0.5,
          "height": 1.8,
          "unit": "m"
        }
      }
    EOF
 You can also query the data using arrow operators. See :ref:`composite_array_columns`.
 Ranges
 ------
 PostgREST allows you to handle `ranges <https://www.postgresql.org/docs/current/rangetypes.html>`_.
 .. code-block:: postgres
   create table events (
     id int primary key,
     name text unique,
     duration tsrange
   );
 To insert a new event, specify the ``duration`` value as a string representation of the ``tsrange`` type:
 .. tabs::
  .. code-tab:: http
    POST /events HTTP/1.1
    Content-Type: application/json
    {
      "id": 1,
      "name": "New Year's Party",
      "duration": "['2022-12-31 11:00','2023-01-01 06:00']"
    }
  .. code-tab:: bash Curl
    curl "http://localhost:3000/events" \
      -X POST -H "Content-Type: application/json" \
      -d @- << EOF
      {
        "id": 1,
        "name": "New Year's Party",
        "duration": "['2022-12-31 11:00','2023-01-01 06:00']"
      }
    EOF
 You can use range :ref:`operators <operators>` to filter the data. But, in this case, requesting a filter like ``events?duration=cs.2023-01-01`` will return an error, because PostgreSQL needs an explicit cast from string to timestamp. A workaround is to use a range starting and ending in the same date:
 .. tabs::
  .. code-tab:: http
    GET /events?duration=cs.[2023-01-01,2023-01-01] HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/events?duration=cs.\[2023-01-01,2023-01-01\]"
 .. code-block:: json
  [
    {
      "id": 1,
      "name": "New Year's Party",
      "duration": "[\"2022-12-31 11:00:00\",\"2023-01-01 06:00:00\"]"
    }
  ]
 .. _casting_range_to_json:
 Casting a Range to a JSON Object
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 As you may have noticed, the ``tsrange`` value is returned as a string literal. To return it as a JSON value, first you need to create a function that will do the conversion from a ``tsrange`` type:
 .. code-block:: postgres
   create or replace function tsrange_to_json(tsrange) returns json as $$
     select json_build_object(
       'lower', lower($1)
     , 'upper', upper($1)
     , 'lower_inc', lower_inc($1)
     , 'upper_inc', upper_inc($1)
     );
   $$ language sql;
 Then, create the cast using this function:
 .. code-block:: postgres
   create cast (tsrange as json) with function tsrange_to_json(tsrange) as assignment;
 Finally, do the request :ref:`casting the range column <casting_columns>`:
 .. tabs::
  .. code-tab:: http
    GET /events?select=id,name,duration::json HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/events?select=id,name,duration::json"
 .. code-block:: json
  [
    {
      "id": 1,
      "name": "New Year's Party",
      "duration": {
        "lower": "2022-12-31T11:00:00",
        "upper": "2023-01-01T06:00:00",
        "lower_inc": true,
        "upper_inc": true
      }
    }
  ]
 .. note::
   If you don't want to modify casts for built-in types, an option would be to `create a custom type <https://www.postgresql.org/docs/current/sql-createtype.html>`_
   for your own ``tsrange`` and add its own cast.
   .. code-block:: postgres
      create type mytsrange as range (subtype = timestamp, subtype_diff = tsrange_subdiff);
      -- define column types and casting function analogously to the above example
      -- ...
      create cast (mytsrange as json) with function mytsrange_to_json(mytsrange) as assignment;
 Bytea
 -----
 To send raw binary to PostgREST you need a function with a single unnamed parameter of `bytea type <https://www.postgresql.org/docs/current/datatype-binary.html>`_.
 .. code-block:: postgres
   create table files (
     id int primary key generated always as identity,
     file bytea
   );
   create function upload_binary(bytea) returns void as $$
     insert into files (file) values ($1);
   $$ language sql;
 Let's download the PostgREST logo for our test.
 .. code-block:: bash
   curl "https://postgrest.org/en/latest/_images/logo.png" -o postgrest-logo.png
 Now, to send the file ``postgrest-logo.png`` we need to set the ``Content-Type: application/octet-stream`` header in the request:
 .. tabs::
  .. code-tab:: http
    POST /rpc/upload_binary HTTP/1.1
    Content-Type: application/octet-stream
    postgrest-logo.png
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/upload_binary" \
      -X POST -H "Content-Type: application/octet-stream" \
      --data-binary "@postgrest-logo.png"
 To get the image from the database, set the ``Accept: application/octet-stream`` header and select only the
 ``bytea`` type column.
 .. tabs::
  .. code-tab:: http
    GET /files?select=file&id=eq.1 HTTP/1.1
    Accept: application/octet-stream
  .. code-tab:: bash Curl
    curl "http://localhost:3000/files?select=file&id=eq.1" \
      -H "Accept: application/octet-stream"
 Use more accurate headers according to the type of the files by using the :ref:`raw-media-types` configuration. For example, adding the ``raw-media-types="image/png"`` setting to the configuration file will allow you to use the ``Accept: image/png`` header:
 .. tabs::
  .. code-tab:: http
    GET /files?select=file&id=eq.1 HTTP/1.1
    Accept: image/png
  .. code-tab:: bash Curl
    curl "http://localhost:3000/files?select=file&id=eq.1" \
      -H "Accept: image/png"
 See :ref:`providing_img` for a step-by-step example on how to handle images in HTML.
 .. warning::
   Be careful when saving binaries in the database, having a separate storage service for these is preferable in most cases. See `Storing Binary files in the Database <https://wiki.postgresql.org/wiki/BinaryFilesInDB>`_.
 hstore
 ------
 You can work with data types belonging to additional supplied modules such as `hstore <https://www.postgresql.org/docs/current/hstore.html>`_.
 .. code-block:: postgres
  -- Activate the hstore module in the current database
  create extension if not exists hstore;
  create table countries (
    id int primary key,
    name hstore unique
  );
 The ``name`` column will have the name of the country in different formats. You can insert values using the string representation for that data type:
 .. tabs::
  .. code-tab:: http
    POST /countries HTTP/1.1
    Content-Type: application/json
    [
      { "id": 1, "name": "common => Egypt, official => \"Arab Republic of Egypt\", native => مصر" },
      { "id": 2, "name": "common => Germany, official => \"Federal Republic of Germany\", native => Deutschland" }
    ]
  .. code-tab:: bash Curl
    curl "http://localhost:3000/countries" \
      -X POST -H "Content-Type: application/json" \
      -d @- << EOF
      [
        { "id": 1, "name": "common => Egypt, official => \"Arab Republic of Egypt\", native => مصر" },
        { "id": 2, "name": "common => Germany, official => \"Federal Republic of Germany\", native => Deutschland" }
      ]
    EOF
 Notice that the use of ``"`` in the value of the ``name`` column needs to be escaped using a backslash ``\``.
 You can also query and filter the value of a ``hstore`` column using the arrow operators, as you would do for a :ref:`JSON column<json_columns>`. For example, if you want to get the native name of Egypt:
 .. tabs::
  .. code-tab:: http
    GET /countries?select=name->>native&name->>common=like.Egypt HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/countries?select=name->>native&name->>common=like.Egypt"
 .. code-block:: json
  [{ "native": "مصر" }]
 .. _ww_postgis:
 PostGIS
 -------
 You can use the string representation for `PostGIS <https://postgis.net/>`_ data types such as ``geometry`` or ``geography`` (you need to `install PostGIS <https://postgis.net/install/>`_ first).
 .. code-block:: postgres
  -- Activate the postgis module in the current database
  create extension if not exists postgis;
  create table coverage (
    id int primary key,
    name text unique,
    area geometry
  );
 To add areas in polygon format, you can use string representation:
 .. tabs::
  .. code-tab:: http
    POST /coverage HTTP/1.1
    Content-Type: application/json
    [
      { "id": 1, "name": "small", "area": "SRID=4326;POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))" },
      { "id": 2, "name": "big", "area": "SRID=4326;POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))" }
    ]
  .. code-tab:: bash Curl
    curl "http://localhost:3000/coverage" \
      -X POST -H "Content-Type: application/json" \
      -d @- << EOF
      [
        { "id": 1, "name": "small", "area": "SRID=4326;POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))" },
        { "id": 2, "name": "big", "area": "SRID=4326;POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))" }
      ]
    EOF
 Now, when you request the information, PostgREST will automatically cast the ``area`` column into a ``Polygon`` geometry type. Although this is useful, you may need the whole output to be in `GeoJSON <https://geojson.org/>`_ format out of the box, which can be done by including the ``Accept: application/geo+json`` in the request. This will work for PostGIS versions 3.0.0 and up and will return the output as a `FeatureCollection Object <https://www.rfc-editor.org/rfc/rfc7946#section-3.3>`_:
 .. tabs::
  .. code-tab:: http
    GET /coverage HTTP/1.1
    Accept: application/geo+json
  .. code-tab:: bash Curl
    curl "http://localhost:3000/coverage" \
      -H "Accept: application/geo+json"
 .. code-block:: json
  {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [[0,0],[1,0],[1,1],[0,1],[0,0]]
          ]
        },
        "properties": {
          "id": 1,
          "name": "small"
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [[0,0],[10,0],[10,10],[0,10],[0,0]]
          ]
        },
        "properties": {
          "id": 2,
          "name": "big"
        }
      }
    ]
  }
 If you need to add an extra property, like the area in square units by using ``st_area(area)``, you could add a generated column to the table and it will appear in the ``properties`` key of each ``Feature``.
 .. code-block:: postgres
  alter table coverage
    add square_units double precision generated always as ( st_area(area) ) stored;
 In the case that you are using older PostGIS versions, then creating a function is your best option:
 .. code-block:: postgres
  create or replace function coverage_geo_collection() returns json as $$
    select
      json_build_object(
        'type', 'FeatureCollection',
        'features', json_agg(
          json_build_object(
            'type', 'Feature',
            'geometry', st_AsGeoJSON(c.area)::json,
            'properties', json_build_object('id', c.id, 'name', c.name)
          )
        )
      )
    from coverage c;
  $$ language sql;
 Now this query will return the same results:
 .. tabs::
  .. code-tab:: http
    GET /rpc/coverage_geo_collection HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/coverage_geo_collection"
 .. code-block:: json
  {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [[0,0],[1,0],[1,1],[0,1],[0,0]]
          ]
        },
        "properties": {
          "id": 1,
          "name": "small"
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [[0,0],[10,0],[10,10],[0,10],[0,0]]
          ]
        },
        "properties": {
          "id": 2,
          "name": "big"
        }
      }
    ]
  }
@@ -0,0 +1,236 @@
 .. title:: PostgREST Documentation
 PostgREST Documentation
 =======================
 .. container:: image-container
  .. figure:: _static/logo.png
 .. image:: https://img.shields.io/github/stars/postgrest/postgrest.svg?style=social
  :target: https://github.com/PostgREST/postgrest
 .. image:: https://img.shields.io/github/v/release/PostgREST/postgrest.svg
  :target: https://github.com/PostgREST/postgrest/releases
 .. image:: https://img.shields.io/docker/pulls/postgrest/postgrest.svg
  :target: https://hub.docker.com/r/postgrest/postgrest/
 .. image:: https://img.shields.io/badge/Donate-Patreon-orange.svg?colorB=F96854
  :target: https://www.patreon.com/postgrest
 |
 PostgREST is a standalone web server that turns your PostgreSQL database directly into a RESTful API. The structural constraints and permissions in the database determine the API endpoints and operations.
 Sponsors
 --------
 .. container:: image-container
  .. image:: _static/cybertec-new.png
    :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest
    :width:  13em
  .. image:: _static/gnuhost.png
    :target: https://euronodes.com/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
  |
  .. image:: _static/supabase.png
    :target: https://supabase.com/?utm_source=postgrest%20backers&utm_medium=open%20source%20partner&utm_campaign=postgrest%20backers%20github&utm_term=homepage
    :width:  13em
  .. image:: _static/neon.jpg
    :target: https://neon.tech/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
  .. The static/empty.png(created with `convert -size 320x95 xc:#fcfcfc empty.png`) is an ugly workaround
     to create space and center the logos. It's not easy to layout with restructuredText.
  .. .. image:: _static/empty.png
       :target: #sponsors
       :width:  13em
 |
 Database as Single Source of Truth
 ----------------------------------
 Using PostgREST is an alternative to manual CRUD programming. Custom API servers suffer problems. Writing business logic often duplicates, ignores or hobbles database structure. Object-relational mapping is a leaky abstraction leading to slow imperative code. The PostgREST philosophy establishes a single declarative source of truth: the data itself.
 Declarative Programming
 -----------------------
 It's easier to ask PostgreSQL to join data for you and let its query planner figure out the details than to loop through rows yourself. It's easier to assign permissions to database objects than to add guards in controllers. (This is especially true for cascading permissions in data dependencies.) It's easier to set constraints than to litter code with sanity checks.
 Leak-proof Abstraction
 ----------------------
 There is no ORM involved. Creating new views happens in SQL with known performance implications. A database administrator can now create an API from scratch with no custom programming.
 One Thing Well
 --------------
 PostgREST has a focused scope. It works well with other tools like Nginx. This forces you to cleanly separate the data-centric CRUD operations from other concerns. Use a collection of sharp tools rather than building a big ball of mud.
 Getting Support
 ----------------
 The project has a friendly and growing community. For discussions, use the Github `discussions page <https://github.com/PostgREST/postgrest/discussions>`_. You can also report or search for bugs/features on the Github `issues <https://github.com/PostgREST/postgrest/issues>`_ page.
 .. toctree::
   :glob:
   :caption: Release Notes
   :reversed:
   :maxdepth: 1
   releases/*
 Tutorials
 ---------
 Are you new to PostgREST? This is the place to start!
 .. toctree::
   :glob:
   :caption: Tutorials
   :maxdepth: 1
   tutorials/*
 Also have a look at :ref:`install` and :ref:`community_tutorials`.
 References
 ----------
 Technical references for PostgREST's functionality.
 .. toctree::
   :glob:
   :caption: References
   :name: references
   :maxdepth: 1
   references/auth.rst
   references/api.rst
   references/transactions.rst
   references/connection_pool.rst
   references/schema_cache.rst
   references/errors.rst
   references/configuration.rst
   references/*
 Explanations
 ------------
 Key concepts in PostgREST.
 .. toctree::
   :glob:
   :caption: Explanations
   :name: explanations
   :maxdepth: 1
   explanations/*
 How-tos
 -------
 Recipes that'll help you address specific use-cases.
 .. toctree::
   :glob:
   :caption: How-to guides
   :name: how-tos
   :maxdepth: 1
   how-tos/sql-user-*
   how-tos/working-*
   how-tos/*
 .. _intgrs:
 Integrations
 ------------
 .. toctree::
   :glob:
   :caption: Integrations
   :name: integrations
   :maxdepth: 1
   integrations/*
 Ecosystem
 ---------
 PostgREST has a growing ecosystem of examples, libraries, and experiments. Here is a selection.
 .. toctree::
   :caption: Ecosystem
   :name: ecosystem
   :maxdepth: 1
   ecosystem.rst
 In Production
 -------------
 Here are some companies that use PostgREST in production.
 * `Catarse <https://www.catarse.me>`_
 * `Datrium <https://www.datrium.com>`_
 * `Drip Depot <https://www.dripdepot.com>`_
 * `Image-charts <https://www.image-charts.com>`_
 * `Netwo <https://www.netwo.io>`_
 * `Nimbus <https://www.nimbusforwork.com>`_
  - See how Nimbus uses PostgREST in `Paul Copplestone's blog post <https://paul.copplest.one/blog/nimbus-tech-2019-04.html>`_.
 * `OpenBooking <https://www.openbooking.ch>`_
 * `Supabase <https://supabase.com>`_
 Testimonials
 ------------
  "It's so fast to develop, it feels like cheating!"
  -- François-Guillaume Ribreau
  "I just have to say that, the CPU/Memory usage compared to our
  Node.js/Waterline ORM based API is ridiculous.  It's hard to even push
  it over 60/70 MB while our current API constantly hits 1GB running on 6
  instances (dynos)."
  -- Louis Brauer
  "I really enjoyed the fact that all of a sudden I was writing
  microservices in SQL DDL (and v8 JavaScript functions). I dodged so
  much boilerplate. The next thing I knew, we pulled out a full rewrite
  of a Spring+MySQL legacy app in 6 months. Literally 10x faster, and
  code was super concise. The old one took 3 years and a team of 4
  people to develop."
  -- Simone Scarduzio
  "I like the fact that PostgREST does one thing, and one thing well.
  While PostgREST takes care of bridging the gap between our HTTP server
  and PostgreSQL database, we can focus on the development of our API in
  a single language: SQL. This puts the database in the center of our
  architecture, and pushed us to improve our skills in SQL programming
  and database design."
  -- Eric Bréchemier, Data Engineer, eGull SAS
  "PostgREST is performant, stable, and transparent. It allows us to
  bootstrap projects really fast, and to focus on our data and application
  instead of building out the ORM layer. In our k8s cluster, we run a few
  pods per schema we want exposed, and we scale up/down depending on demand.
  Couldn't be happier."
  -- Anupam Garg, Datrium, Inc.
 Contributing
 ------------
 Please see the `Contributing guidelines <https://github.com/PostgREST/postgrest/blob/main/.github/CONTRIBUTING.md>`_ in the main PostgREST repository.
@@ -0,0 +1,122 @@
 .. _deploy_heroku:
 Heroku
 ======
 1.  Log into Heroku using the `Heroku CLI <https://devcenter.heroku.com/articles/heroku-cli>`_:
  .. code-block:: bash
    # If you have multiple Heroku accounts, use flag '--interactive' to switch between them
    heroku login --interactive
 2.  Create a new Heroku app using the PostgREST buildpack:
  .. code-block:: bash
    mkdir ${YOUR_APP_NAME}
    cd ${YOUR_APP_NAME}
    git init .
    heroku apps:create ${YOUR_APP_NAME} --buildpack https://github.com/PostgREST/postgrest-heroku.git
    heroku git:remote -a ${YOUR_APP_NAME}
 3.  Create a new Heroku PostgreSQL add-on attached to the app and keep notes of the assigned add-on name (e.g. :code:`postgresql-curly-58902`) referred later as ${HEROKU_PG_DB_NAME}
  .. code-block:: bash
    heroku addons:create heroku-postgresql:standard-0 -a ${YOUR_APP_NAME}
    # wait until the add-on is available
    heroku pg:wait -a ${YOUR_APP_NAME}
 4.  Create the necessary user roles according to the
    `PostgREST documentation <https://postgrest.org/en/stable/auth.html>`_:
  .. code-block:: bash
    heroku pg:credentials:create --name api_user -a ${YOUR_APP_NAME}
    # use the following command to ensure the new credential state is active before attaching it
    heroku pg:credentials -a ${YOUR_APP_NAME}
    heroku addons:attach ${HEROKU_PG_DB_NAME} --credential api_user -a ${YOUR_APP_NAME}
 5.  Connect to the PostgreSQL database and create some sample data:
  .. code-block:: bash
    heroku psql -a ${YOUR_APP_NAME}
  .. code-block:: postgres
    # from the psql command prompt execute the following commands:
    create schema api;
    create table api.todos (
    id serial primary key,
    done boolean not null default false,
    task text not null,
    due timestamptz
    );
    insert into api.todos (task) values
    ('finish tutorial 0'), ('pat self on back');
    grant usage on schema api to api_user;
    grant select on api.todos to api_user;
 6.  Create the :code:`Procfile`:
  .. code-block:: bash
    web: PGRST_SERVER_HOST=0.0.0.0 PGRST_SERVER_PORT=${PORT} PGRST_DB_URI=${PGRST_DB_URI:-${DATABASE_URL}} ./postgrest-${POSTGREST_VER}
  ..
  Set the following environment variables on Heroku:
  .. code-block:: bash
    heroku config:set POSTGREST_VER=10.0.0
    heroku config:set PGRST_DB_SCHEMA=api
    heroku config:set PGRST_DB_ANON_ROLE=api_user
  ..
  PGRST_DB_URI can be set if an external database is used or if it's different from the default Heroku DATABASE_URL. This latter is used if nothing is provided.
  POSTGREST_VER is mandatory to select and build the required PostgREST release.
  See https://postgrest.org/en/stable/configuration.html#environment-variables for the full list of environment variables.
 7.  Build and deploy your app:
  .. code-block:: bash
    git add Procfile
    git commit -m "PostgREST on Heroku"
    git push heroku master
  ..
  Your Heroku app should be live at :code:`${YOUR_APP_NAME}.herokuapp.com`
 8.  Test your app
    From a terminal display the application logs:
  .. code-block:: bash
    heroku logs -t
  ..
  From a different terminal retrieve with curl the records previously created:
  .. code-block:: bash
    curl https://${YOUR_APP_NAME}.herokuapp.com/todos
  ..
  and test that any attempt to modify the table via a read-only user is not allowed:
  .. code-block:: bash
    curl https://${YOUR_APP_NAME}.herokuapp.com/todos -X POST \
     -H "Content-Type: application/json" \
     -d '{"task": "do bad thing"}'
@@ -0,0 +1,31 @@
 .. _external_jwt:
 External JWT Generation
 -----------------------
 JWT from Auth0
 ~~~~~~~~~~~~~~
 An external service like `Auth0 <https://auth0.com/>`_ can do the hard work transforming OAuth from Github, Twitter, Google etc into a JWT suitable for PostgREST. Auth0 can also handle email signup and password reset flows.
 To use Auth0, create `an application <https://auth0.com/docs/get-started/applications>`_ for your app and `an API <https://auth0.com/docs/get-started/apis>`_ for your PostgREST server. Auth0 supports both HS256 and RS256 scheme for the issued tokens for APIs. For simplicity, you may first try HS256 scheme while creating your API on Auth0. Your application should use your PostgREST API's `API identifier <https://auth0.com/docs/get-started/apis/api-settings>`_ by setting it with the `audience parameter <https://auth0.com/docs/secure/tokens/access-tokens/get-access-tokens#control-access-token-audience>`_  during the authorization request. This will ensure that Auth0 will issue an access token for your PostgREST API. For PostgREST to verify the access token, you will need to set ``jwt-secret`` on PostgREST config file with your API's signing secret.
 .. note::
  Our code requires a database role in the JWT. To add it you need to save the database role in Auth0 `app metadata <https://auth0.com/docs/manage-users/user-accounts/metadata/manage-metadata-rules>`_. Then, you will need to write `a rule <https://auth0.com/docs/customize/rules>`_ that will extract the role from the user's app_metadata and set it as a `custom claim <https://auth0.com/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims#add-custom-claims-to-a-token>`_ in the access token. Note that, you may use Auth0's `core authorization feature <https://auth0.com/docs/manage-users/access-control/rbac>`_ for more complex use cases. Metadata solution is mentioned here for simplicity.
  .. code:: javascript
    function (user, context, callback) {
      // Follow the documentations at
      // https://postgrest.org/en/latest/configuration.html#db-role-claim-key
      // to set a custom role claim on PostgREST
      // and use it as custom claim attribute in this rule
      const myRoleClaim = 'https://myapp.com/role';
      user.app_metadata = user.app_metadata || {};
      context.accessToken[myRoleClaim] = user.app_metadata.role;
      callback(null, user, context);
    }
@@ -0,0 +1,42 @@
 pg-safeupdate
 #############
 .. _block_fulltable:
 Block Full-Table Operations
 ---------------------------
 If the :ref:`active role <user_impersonation>` can delete table rows then the DELETE verb is allowed for clients. Here's an API request to delete old rows from a hypothetical logs table:
 .. tabs::
  .. code-tab:: http
    DELETE /logs?time=lt.1991-08-06 HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/logs?time=lt.1991-08-06" -X DELETE
 Note that it's very easy to delete the **entire table** by omitting the query parameter!
 .. tabs::
  .. code-tab:: http
    DELETE /logs HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/logs" -X DELETE
 This can happen accidentally such as by switching a request from a GET to a DELETE. To protect against accidental operations use the `pg-safeupdate <https://github.com/eradman/pg-safeupdate>`_ PostgreSQL extension. It raises an error if UPDATE or DELETE are executed without specifying conditions. To install it you can use the `PGXN <https://pgxn.org/>`_ network:
 .. code-block:: bash
  sudo -E pgxn install safeupdate
  # then add this to postgresql.conf:
  # shared_preload_libraries='safeupdate';
 This does not protect against malicious actions, since someone can add a url parameter that does not affect the result set. To prevent this you must turn to database permissions, forbidding the wrong people from deleting rows, and using `row-level security <https://www.postgresql.org/docs/current/ddl-rowsecurity.html>`_ if finer access control is required.
@@ -0,0 +1,51 @@
 systemd
 =======
 For Linux distributions that use **systemd** (Ubuntu, Debian, Archlinux) you can create a daemon in the following way.
 First, create postgrest configuration in ``/etc/postgrest/config``
 .. code-block:: ini
  db-uri = "postgres://<your_user>:<your_password>@localhost:5432/<your_db>"
  db-schemas = "<your_exposed_schema>"
  db-anon-role = "<your_anon_role>"
  jwt-secret = "<your_secret>"
 Then create the systemd service file in ``/etc/systemd/system/postgrest.service``
 .. code-block:: ini
  [Unit]
  Description=REST API for any PostgreSQL database
  After=postgresql.service
  [Service]
  ExecStart=/bin/postgrest /etc/postgrest/config
  ExecReload=/bin/kill -SIGUSR1 $MAINPID
  [Install]
  WantedBy=multi-user.target
 After that, you can enable the service at boot time and start it with:
 .. code-block:: bash
  systemctl enable postgrest
  systemctl start postgrest
  ## For reloading the service
  ## systemctl restart postgrest
 .. _file_descriptors:
 File Descriptors
 ----------------
 File descriptors are kernel resources that are used by HTTP connections (among others). File descriptors are limited per process. The kernel default limit is 1024, which is increased in some Linux distributions.
 When under heavy traffic, PostgREST can reach this limit and start showing ``No file descriptors available`` errors. To clear these errors, you can increase the process' file descriptor limit.
 .. code-block:: ini
  [Service]
  LimitNOFILE=10000
@@ -0,0 +1,11 @@
 #!/usr/bin/env python
 from livereload import Server, shell
 from subprocess import call
 ## Build docs at startup
 call(["sphinx-build", "-b", "html", "-a", "-n", ".", "_build"])
 server = Server()
 server.watch("**/*.rst", shell("sphinx-build -b html -a -n . _build"))
 # For custom port and host
 # server.serve(root='_build/', host='192.168.1.2')
 server.serve(root="_build/")
@@ -0,0 +1,204 @@
 personal_ws-1.1 en 0 utf-8
 api
 API's
 APISIX
 Archlinux
 aud
 Auth
 auth
 authenticator
 backoff
 balancer
 booleans
 Bouscal
 buildpack
 Bytea
 Cardano
 cd
 centric
 changelog
 coercible
 conf
 Cloudflare
 config
 CORS
 CPUs
 cryptographically
 CSV
 DDL
 DevOps
 DiBiase
 dockerize
 eq
 ETH
 Ethereum
 EveryLayout
 Fenko
 Fernandes
 filename
 FreeBSD
 fts
 GC
 GeoJSON
 GHC
 Github
 Google
 grantor
 GraphQL
 gte
 GUC
 GUCs
 gucs
 Haskell
 Heroku
 HMAC
 Homebrew
 hstore
 HTTP
 HTTPS
 HV
 Ibarluzea
 Inlining
 inlined
 Integrations
 idletime
 IDLETIME
 ilike
 imatch
 io
 IP
 isdistinct
 JS
 js
 JSON
 JWK
 JWT
 jwt
 Kubernetes
 localhost
 login
 lookups
 Logins
 LIBPQ
 logins
 lon
 lt
 lte
 misprediction
 multi
 namespace
 namespaced
 Nanos
 neq
 nginx
 nixpkgs
 npm
 nxl
 nxr
 OAuth
 OpenAPI
 openapi
 ORM
 ov
 passphrase
 Pawel
 PBKDF
 Pelletier
 PgBouncer
 pgcrypto
 pgjwt
 pgrst
 pgrstX
 PGRSTX
 pgSQL
 authid
 phfts
 phraseto
 plainto
 plfts
 poolers
 POSIX
 PostGIS
 PostgreSQL
 PostgreSQL's
 PostgREST
 postgres
 postgrest
 PostgREST's
 pre
 preflight
 plpgsql
 psql
 Qin
 RabbitMQ
 Rafaj
 RDS
 reallyreallyreallyreallyverysafe
 Rechkemmer
 Redux
 refactor
 reloadable
 Reloadable
 Remo
 requester's
 RESTful
 RLS
 RPC
 RSA
 Saleeba
 safeupdate
 savepoint
 schemas
 schema's
 Severin
 SHA
 Sommer
 signup
 SIGUSR
 sl
 SQL
 sql
 sr
 SSL
 stateful
 stdout
 Stolarz
 supervisees
 SvelteKit
 SwaggerUI
 syslog
 systemd
 todo
 todos
 tos
 Tsingson
 tsquery
 tx
 Tyll
 TypeScript
 UI
 ui
 unicode
 unikernel
 unix
 updatable
 Untyped
 UPSERT
 Upsert
 upsert
 uri
 url
 urlencoded
 urls
 variadic
 verifier
 versioning
 Vondra
 Vue
 webhooks
 websearch
 Websockets
 webuser
 wfts
 www
 Zac
@@ -0,0 +1,280 @@
 .. _admin:
 Admin
 #####
 .. _pgrst_logging:
 Logging
 -------
 PostgREST logs basic request information to ``stdout``, including the authenticated user if available, the requesting IP address and user agent, the URL requested, and HTTP response status.
 .. code::
   127.0.0.1 - user [26/Jul/2021:01:56:38 -0500] "GET /clients HTTP/1.1" 200 - "" "curl/7.64.0"
   127.0.0.1 - anonymous [26/Jul/2021:01:56:48 -0500] "GET /unexistent HTTP/1.1" 404 - "" "curl/7.64.0"
 For diagnostic information about the server itself, PostgREST logs to ``stderr``.
 .. code::
   12/Jun/2021:17:47:39 -0500: Starting PostgREST 11.1.0...
   12/Jun/2021:17:47:39 -0500: Attempting to connect to the database...
   12/Jun/2021:17:47:39 -0500: Listening on port 3000
   12/Jun/2021:17:47:39 -0500: Connection successful
   12/Jun/2021:17:47:39 -0500: Config re-loaded
   12/Jun/2021:17:47:40 -0500: Schema cache loaded
 .. note::
   When running it in an SSH session you must detach it from stdout or it will be terminated when the session closes. The easiest technique is redirecting the output to a log file or to the syslog:
   .. code-block:: bash
     ssh foo@example.com \
       'postgrest foo.conf </dev/null >/var/log/postgrest.log 2>&1 &'
     # another option is to pipe the output into "logger -t postgrest"
 Currently PostgREST doesn't log the SQL commands executed against the underlying database.
 Database Logs
 ~~~~~~~~~~~~~
 To find the SQL operations, you can watch the database logs. By default PostgreSQL does not keep these logs, so you'll need to make the configuration changes below.
 Find :code:`postgresql.conf` inside your PostgreSQL data directory (to find that, issue the command :code:`show data_directory;`). Either find the settings scattered throughout the file and change them to the following values, or append this block of code to the end of the configuration file.
 .. code:: sql
  # send logs where the collector can access them
  log_destination = "stderr"
  # collect stderr output to log files
  logging_collector = on
  # save logs in pg_log/ under the pg data directory
  log_directory = "pg_log"
  # (optional) new log file per day
  log_filename = "postgresql-%Y-%m-%d.log"
  # log every kind of SQL statement
  log_statement = "all"
 Restart the database and watch the log file in real-time to understand how HTTP requests are being translated into SQL commands.
 .. note::
  On Docker you can enable the logs by using a custom ``init.sh``:
  .. code:: bash
    #!/bin/sh
    echo "log_statement = 'all'" >> /var/lib/postgresql/data/postgresql.conf
  After that you can start the container and check the logs with ``docker logs``.
  .. code:: bash
    docker run -v "$(pwd)/init.sh":"/docker-entrypoint-initdb.d/init.sh" -d postgres
    docker logs -f <container-id>
 Server Version
 --------------
 When debugging a problem it's important to verify the running PostgREST version. There are three ways to do this:
 - Look for the :code:`Server` HTTP response header that is returned on every request.
 .. code::
  HEAD /users HTTP/1.1
  Server: postgrest/11.0.1
 - Query ``application_name`` on `pg_stat_activity <https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW>`_.
 .. code-block:: psql
  select distinct application_name
  from pg_stat_activity
  where application_name ilike '%postgrest%';
        application_name
  ------------------------------
  PostgREST 11.1.0
 .. note::
  The server sets the `fallback_application_name <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-FALLBACK-APPLICATION-NAME>`_ for this query to work. To override the value set ``application_name`` on the connection string.
 - The ``stderr`` logs also contain the version, as noted on :ref:`pgrst_logging`.
 .. _trace_header:
 Trace Header
 ------------
 You can enable tracing HTTP requests by setting :ref:`server-trace-header`. Specify the set header in the request, and the server will include it in the response.
 .. code:: bash
  server-trace-header = "X-Request-Id"
 .. tabs::
  .. code-tab:: http
    GET /users HTTP/1.1
    X-Request-Id: 123
  .. code-tab:: bash Curl
    curl "http://localhost:3000/users" \
      -H "X-Request-Id: 123"
 .. code::
  HTTP/1.1 200 OK
  X-Request-Id: 123
 .. _explain_plan:
 Execution plan
 --------------
 You can get the `EXPLAIN execution plan <https://www.postgresql.org/docs/current/sql-explain.html>`_ of a request by adding the ``Accept: application/vnd.pgrst.plan`` header.
 This is enabled by :ref:`db-plan-enabled` (false by default).
 .. tabs::
  .. code-tab:: http
    GET /users?select=name&order=id HTTP/1.1
    Accept: application/vnd.pgrst.plan
  .. code-tab:: bash Curl
    curl "http://localhost:3000/users?select=name&order=id" \
      -H "Accept: application/vnd.pgrst.plan"
 .. code-block:: psql
  Aggregate  (cost=73.65..73.68 rows=1 width=112)
    ->  Index Scan using users_pkey on users  (cost=0.15..60.90 rows=850 width=36)
 The output of the plan is generated in ``text`` format by default but you can change it to JSON by using the ``+json`` suffix.
 .. tabs::
  .. code-tab:: http
    GET /users?select=name&order=id HTTP/1.1
    Accept: application/vnd.pgrst.plan+json
  .. code-tab:: bash Curl
    curl "http://localhost:3000/users?select=name&order=id" \
      -H "Accept: application/vnd.pgrst.plan+json"
 .. code-block:: json
  [
    {
      "Plan": {
        "Node Type": "Aggregate",
        "Strategy": "Plain",
        "Partial Mode": "Simple",
        "Parallel Aware": false,
        "Async Capable": false,
        "Startup Cost": 73.65,
        "Total Cost": 73.68,
        "Plan Rows": 1,
        "Plan Width": 112,
        "Plans": [
          {
            "Node Type": "Index Scan",
            "Parent Relationship": "Outer",
            "Parallel Aware": false,
            "Async Capable": false,
            "Scan Direction": "Forward",
            "Index Name": "users_pkey",
            "Relation Name": "users",
            "Alias": "users",
            "Startup Cost": 0.15,
            "Total Cost": 60.90,
            "Plan Rows": 850,
            "Plan Width": 36
          }
        ]
      }
    }
  ]
 By default the plan is assumed to generate the JSON representation of a resource(``application/json``), but you can obtain the plan for the :ref:`different representations that PostgREST supports <res_format>` by adding them to the ``for`` parameter. For instance, to obtain the plan for a ``text/xml``, you would use ``Accept: application/vnd.pgrst.plan; for="text/xml``.
 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``.
 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 It's recommended to only activate :ref:`db-plan-enabled` on testing environments since it reveals internal database details.
 However, if you choose to use it in production you can add a :ref:`db-pre-request` to filter the requests that can use this feature.
 For example, to only allow requests from an IP address to get the execution plans:
 .. code-block:: postgresql
 -- Assuming a proxy(Nginx, Cloudflare, etc) passes an "X-Forwarded-For" header(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)
 create or replace function filter_plan_requests()
 returns void as $$
 declare
   headers   json := current_setting('request.headers', true)::json;
   client_ip text := coalesce(headers->>'x-forwarded-for', '');
   accept    text := coalesce(headers->>'accept', '');
 begin
   if accept like 'application/vnd.pgrst.plan%' and client_ip != '144.96.121.73' then
     raise insufficient_privilege using
       message = 'Not allowed to use application/vnd.pgrst.plan';
   end if;
 end; $$ language plpgsql;
 -- set this function on your postgrest.conf
 -- db-pre-request = filter_plan_requests
 .. _health_check:
 Health Check
 ------------
 You can enable a health check to verify if PostgREST is available for client requests. Also to check the status of its internal state.
 To do this, set the configuration variable :ref:`admin-server-port` to the port number of your preference. Two endpoints ``live`` and ``ready`` will then be available.
 The ``live`` endpoint verifies if PostgREST is running on its configured port. A request will return ``200 OK`` if PostgREST is alive or ``503`` otherwise.
 The ``ready`` endpoint also checks the state of both the Database Connection and the :ref:`schema_cache`. A request will return ``200 OK`` if it is ready or ``503`` if not.
 For instance, to verify if PostgREST is running at ``localhost:3000`` while the ``admin-server-port`` is set to ``3001``:
 .. tabs::
  .. code-tab:: http
    GET localhost:3001/live HTTP/1.1
  .. code-tab:: bash Curl
    curl -I "http://localhost:3001/live"
 .. code-block:: http
  HTTP/1.1 200 OK
 If you have a machine with multiple network interfaces and multiple PostgREST instances in the same port, you need to specify a unique :ref:`hostname <server-host>` in the configuration of each PostgREST instance for the health check to work correctly. Don't use the special values(``!4``, ``*``, etc) in this case because the health check could report a false positive.
@@ -0,0 +1,120 @@
 .. _api:
 API
 ###
 PostgREST exposes three database objects of a schema as resources: tables, views and stored procedures.
 .. toctree::
   :glob:
   :maxdepth: 1
   api/tables_views.rst
   api/stored_procedures.rst
   api/schemas.rst
   api/computed_fields.rst
   api/domain_representations.rst
   api/resource_embedding.rst
   api/resource_representation.rst
   api/openapi.rst
   api/*
 .. raw:: html
  <script type="text/javascript">
    let hash = window.location.hash;
    const redirects = {
      // Tables and Views
      '#horizontal-filtering-rows': 'api/tables_views.html#horizontal-filtering-rows',
      '#operators': 'api/tables_views.html#operators',
      '#logical-operators': 'api/tables_views.html#logical-operators',
      '#pattern-matching': 'api/tables_views.html#pattern-matching',
      '#full-text-search': 'api/tables_views.html#full-text-search',
      '#vertical-filtering-columns': 'api/tables_views.html#vertical-filtering-columns',
      '#renaming-columns': 'api/tables_views.html#renaming-columns',
      '#casting-columns': 'api/tables_views.html#casting-columns',
      '#json-columns': 'api/tables_views.html#json-columns',
      '#composite-array-columns': 'api/tables_views.html#composite-array-columns',
      '#computed-virtual-columns': 'api/computed_fields.html#computed-fields',
      '#ordering': 'api/tables_views.html#ordering',
      '#limits-and-pagination': 'api/tables_views.html#limits-and-pagination',
      '#exact-count': 'api/tables_views.html#exact-count',
      '#planned-count': 'api/tables_views.html#planned-count',
      '#estimated-count': 'api/tables_views.html#estimated-count',
      '#updates': 'api/tables_views.html#update',
      '#insertions': 'api/tables_views.html#insert',
      '#bulk-insert': 'api/tables_views.html#bulk-insert',
      '#specifying-columns': 'api/tables_views.html#specifying-columns',
      '#upsert': 'api/tables_views.html#upsert',
      '#on-conflict': 'api/tables_views.html#on-conflict',
      '#put': 'api/tables_views.html#put',
      '#deletions': 'api/tables_views.html#delete',
      '#limited-updates-deletions': 'api/tables_views.html#limited-update-delete',
      // Stored procedures
      '#stored-procedures': 'api/stored_procedures.html#stored-procedures',
      '#calling-functions-with-a-single-json-parameter': 'api/stored_procedures.html#functions-with-a-single-json-parameter',
      '#calling-functions-with-a-single-unnamed-parameter': 'api/stored_procedures.html#functions-with-a-single-unnamed-parameter',
      '#calling-functions-with-array-parameters': 'api/stored_procedures.html#functions-with-array-parameters',
      '#calling-variadic-functions': 'api/stored_procedures.html#variadic-functions',
      '#scalar-functions': 'api/stored_procedures.html#scalar-functions',
      '#function-filters': 'api/stored_procedures.html#table-valued-functions',
      '#overloaded-functions': 'api/stored_procedures.html#overloaded-functions',
      // Schemas
      '#switching-schemas': 'api/schemas.html',
      // Resource Embedding
      '#resource-embedding': 'api/resource_embedding.html#resource-embedding',
      '#many-to-one-relationships': 'api/resource_embedding.html#many-to-one-relationships',
      '#one-to-many-relationships': 'api/resource_embedding.html#one-to-many-relationships',
      '#many-to-many-relationships': 'api/resource_embedding.html#many-to-many-relationships',
      '#one-to-one-relationships': 'api/resource_embedding.html#one-to-one-relationships',
      '#computed-relationships': 'api/resource_embedding.html#computed-relationships',
      '#nested-embedding': 'api/resource_embedding.html#nested-embedding',
      '#embedded-filters': 'api/resource_embedding.html#embedded-filters',
      '#embedding-with-top-level-filtering': 'api/resource_embedding.html#top-level-filtering',
      '#embedding-partitioned-tables': 'api/resource_embedding.html#embedding-partitioned-tables',
      '#embedding-views': 'api/resource_embedding.html#embedding-views',
      '#embedding-chains-of-views': 'api/resource_embedding.html#embedding-chains-of-views',
      '#embedding-on-stored-procedures': 'api/resource_embedding.html#embedding-on-stored-procedures',
      '#embedding-after-insertions-updates-deletions': 'api/resource_embedding.html#embedding-after-insertions-updates-deletions',
      '#embedding-disambiguation': 'api/resource_embedding.html#embedding-disambiguation',
      '#target-disambiguation': 'api/resource_embedding.html#target-disambiguation',
      '#hint-disambiguation': 'api/resource_embedding.html#hint-disambiguation',
      "#embedding-through-join-tables": "api/resource_embedding.html#many-to-many-relationships",
      // OpenAPI
      '#openapi-support': 'api/openapi.html',
      // Resource Representation
      '#response-format': 'api/resource_representation.html#response-format',
      '#singular-or-plural': 'api/resource_representation.html#singular-or-plural',
      '#response-formats-for-scalar-responses': 'api/resource_representation.html#scalar-function-response-format',
      // CORS
      '#cors': 'api/cors.html',
      // OPTIONS
      '#options': 'api/options.html',
      // URL Grammar
      '#custom-queries': 'api/url_grammar.html#custom-queries',
      '#unicode-support': 'api/url_grammar.html#unicode-support',
      '#table-columns-with-spaces': 'api/url_grammar.html#table-columns-with-spaces',
      '#reserved-characters': 'api/url_grammar.html#reserved-characters',
      // Transactions
      '#immutable-and-stable-functions': 'transactions.html#access-mode',
      '#http-context': 'transactions.html#transaction-scoped-settings',
      '#accessing-request-headers-cookies-and-jwt-claims': 'transactions.html#request-headers-cookies-and-jwt-claims',
      '#legacy-guc-variable-names': 'transactions.html#legacy-settings',
      '#accessing-request-path-and-method': 'transactions.html#request-path-and-method',
      '#setting-response-headers': 'transactions.html#response-headers',
      '#setting-headers-via-pre-request': 'transactions.html#setting-headers-via-pre-request',
      '#setting-response-status-code': 'transactions.html#response-status-code',
      '#raise-errors-with-http-status-codes': 'transactions.html#raise-errors-with-http-status-codes',
      // Admin
      '#execution-plan': 'admin.html#execution-plan',
      // Deprecated
      '#bulk-call': '../releases/v11.0.1.html#breaking-changes',
    };
    let willRedirectTo = redirects[hash];
    if (willRedirectTo) {
      window.location.href = willRedirectTo;
    }
  </script>
@@ -0,0 +1,93 @@
 .. _computed_cols:
 Computed Fields
 ###############
 Computed fields are virtual columns that are not stored in a table. PostgreSQL makes it possible to implement them using functions on table types.
 .. code-block:: postgres
  CREATE TABLE people (
    first_name text
  , last_name  text
  , job        text
  );
  -- a computed field that combines data from two columns
  CREATE FUNCTION full_name(people)
  RETURNS text AS $$
    SELECT $1.first_name || ' ' || $1.last_name;
  $$ LANGUAGE SQL;
 Horizontal Filtering on Computed Fields
 =======================================
 :ref:`h_filter` can be applied to computed fields. For example, we can do a :ref:`fts` on :code:`full_name`:
 .. code-block:: postgres
  -- (optional) you can add an index on the computed field to speed up the query
  CREATE INDEX people_full_name_idx ON people
    USING GIN (to_tsvector('english', full_name(people)));
 .. tabs::
  .. code-tab:: http
    GET /people?full_name=fts.Beckett HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/people?full_name=fts.Beckett"
 .. code-block:: json
  [
    {"first_name": "Samuel", "last_name": "Beckett", "job": "novelist"}
  ]
 Vertical Filtering on Computed Fields
 =====================================
 Computed fields won't appear on the response by default but you can use :ref:`v_filter` to include them:
 .. tabs::
  .. code-tab:: http
    GET /people?select=full_name,job HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/people?select=full_name,job"
 .. code-block:: json
  [
    {"full_name": "Samuel Beckett", "job": "novelist"}
  ]
 Ordering on Computed Fields
 ===========================
 :ref:`ordering` on computed fields is also possible:
 .. tabs::
  .. code-tab:: http
    GET /people?order=full_name.desc HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/people?order=full_name.desc"
 .. important::
  Computed columns must be created in the :ref:`exposed schema <db-schemas>` or in a schema in the :ref:`extra search path <db-extra-search-path>` to be used in this way. When placing the computed column in the :ref:`exposed schema <db-schemas>` you can use an **unnamed** parameter, as in the example above, to prevent it from being exposed as an :ref:`RPC <s_procs>` under ``/rpc``.
 .. note::
   - PostgreSQL 12 introduced `generated columns <https://www.postgresql.org/docs/12/ddl-generated-columns.html>`_, which can also compute a value based on other columns. However they're stored, not virtual.
   - "computed fields" are documented on https://www.postgresql.org/docs/current/rowtypes.html#ROWTYPES-USAGE (search for "computed fields")
   - On previous PostgREST versions this feature was documented with the name of "computed columns".
@@ -0,0 +1,34 @@
 CORS
 ====
 PostgREST sets highly permissive cross origin resource sharing, that is why it accepts Ajax requests from any domain.
 It also handles `preflight requests <https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request>`_ done by the browser, which are cached using the returned ``Access-Control-Max-Age: 86400`` header (86400 seconds = 24 hours). This is useful to reduce the latency of the subsequent requests.
 A ``POST`` preflight request would look like this:
 .. tabs::
  .. code-tab:: http
     OPTIONS /items HTTP/1.1
     Origin: http://example.com
     Access-Control-Allow-Method: POST
     Access-Control-Allow-Headers: Content-Type
  .. code-tab:: bash Curl
     curl -i "http://localhost:3000/items" \
       -X OPTIONS \
       -H "Origin: http://example.com" \
       -H "Access-Control-Request-Method: POST" \
       -H "Access-Control-Request-Headers: Content-Type"
 .. code-block:: http
  HTTP/1.1 200 OK
  Access-Control-Allow-Origin: http://example.com
  Access-Control-Allow-Credentials: true
  Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE, OPTIONS, HEAD
  Access-Control-Allow-Headers: Authorization, Content-Type, Accept, Accept-Language, Content-Language
  Access-Control-Max-Age: 86400
@@ -0,0 +1,200 @@
 .. _domain_reps:
 Domain Representations
 ######################
 Domain Representations separates "how the data is presented" from "how the data is stored". It works by creating `domains <https://www.postgresql.org/docs/current/sql-createdomain.html>`_ and `casts <https://www.postgresql.org/docs/current/sql-createcast.html>`_, the latter act on the former to present and receive the data in different formats.
 .. contents::
   :depth: 1
   :local:
   :backlinks: none
 Custom Domain
 =============
 Suppose you want to use a ``uuid`` type for a primary key and want to present it shortened to web users.
 For this, let's create a domain based on ``uuid``.
 .. code-block:: postgres
  create domain app_uuid as uuid;
  -- and use it as our table PK.
  create table profiles(
    id   app_uuid
  , name text
  );
  -- some data for the example
  insert into profiles values ('846c4ffd-92ce-4de7-8d11-8e29929f4ec4', 'John Doe');
 Domain Response Format
 ======================
 We can shorten the ``uuid`` with ``base64`` encoding. Let's use JSON as our response format for this example.
 To change the domain format for JSON, create a function that converts ``app_uuid`` to ``json``.
 .. code-block:: postgres
  -- the name of the function is arbitrary
  CREATE OR REPLACE FUNCTION json(app_uuid) RETURNS json AS $$
    select to_json(encode(uuid_send($1),'base64'));
  $$ LANGUAGE SQL IMMUTABLE;
  -- check it works
  select json('846c4ffd-92ce-4de7-8d11-8e29929f4ec4'::app_uuid);
              json
  ----------------------------
   "hGxP/ZLOTeeNEY4pkp9OxA=="
 Then create a CAST to tell PostgREST to convert it automatically whenever a JSON response is requested.
 .. code-block:: postgres
  CREATE CAST (app_uuid AS json) WITH FUNCTION json(app_uuid) AS IMPLICIT;
 With this you can obtain the data in the shortened format.
 .. tabs::
  .. code-tab:: http
    GET /profiles HTTP/1.1
    Accept: application/json
  .. code-tab:: bash Curl
    curl "http://localhost:3000/profiles" \
      -H "Accept: application/json"
 .. code-block:: json
  [{"id":"hGxP/ZLOTeeNEY4pkp9OxA==","name":"John Doe"}]
 .. note::
  - Casts on domains are ignored by PostgreSQL, their interpretation is left to the application. We're discussing the possibility of including the Domain Representations behavior on `pgsql-hackers <https://www.postgresql.org/message-id/flat/CAGRrpzZKa%2BGu91j1SOvN3tM1f-7Gh_w441c5nAX1QqdH3Q31Lg%40mail.gmail.com>`_.
  - It would make more sense to use ``base58`` encoding as it's URL friendly but for simplicity we use ``base64`` (supported natively in PostgreSQL).
 .. important::
  After creating a cast over a domain, you must refresh PostgREST schema cache. See :ref:`schema_reloading`.
 Domain Filter Format
 ====================
 For :ref:`h_filter` to work with the shortened format, you need a different conversion.
 PostgREST considers the URL query string to be, in the most generic sense, ``text``. So let's create a function that converts ``text`` to ``app_uuid``.
 .. code-block:: postgres
  -- the name of the function is arbitrary
  CREATE OR REPLACE FUNCTION app_uuid(text) RETURNS app_uuid AS $$
    select substring(decode($1,'base64')::text from 3)::uuid;
  $$ LANGUAGE SQL IMMUTABLE;
  -- plus a CAST to tell PostgREST to use this function
  CREATE CAST (text AS app_uuid) WITH FUNCTION app_uuid(text) AS IMPLICIT;
 Now you can filter as usual.
 .. tabs::
  .. code-tab:: http
    GET /profiles?id=eq.hGxP/ZLOTeeNEY4pkp9OxA== HTTP/1.1
    Accept: application/json
  .. code-tab:: bash Curl
    curl "http://localhost:3000/profiles?id=eq.ZLOTeeNEY4pkp9OxA==" \
      -H "Accept: application/json"
 .. code-block:: json
  [{"id":"hGxP/ZLOTeeNEY4pkp9OxA==","name":"John Doe"}]
 .. note::
  If there's no CAST from ``text`` to ``app_uuid`` defined, the filter will still work with the native uuid format (``846c4ffd-92ce-4de7-8d11-8e29929f4ec4``).
 Domain Request Body Format
 ==========================
 To accept the shortened format in a JSON request body, for example when creating a new record, define a ``json`` to ``app_uuid`` conversion.
 .. code-block:: postgres
  -- the name of the function is arbitrary
  CREATE OR REPLACE FUNCTION app_uuid(json) RETURNS public.app_uuid AS $$
    -- here we reuse the previous app_uuid(text) function
    select app_uuid($1 #>> '{}');
  $$ LANGUAGE SQL IMMUTABLE;
  CREATE CAST (json AS public.app_uuid) WITH FUNCTION app_uuid(json) AS IMPLICIT;
 Now we can :ref:`insert` (or :ref:`update`) as usual.
 .. tabs::
  .. code-tab:: http
    POST /profiles HTTP/1.1
    Content-Type: application/json
    Prefer: return=representation
    {"id":"zH7HbFJUTfy/GZpwuirpuQ==","name":"Jane Doe"}
  .. code-tab:: bash Curl
    curl "http://localhost:3000/profiles" \
      -H "Prefer: return=representation" \
      -H "Content-Type: application/json" \
      -d @- <<JSON
    {"id":"zH7HbFJUTfy/GZpwuirpuQ==","name":"Jane Doe"}
    JSON
 The response:
 .. code-block:: json
  [{"id":"zH7HbFJUTfy/GZpwuirpuQ==","name":"Jane Doe"}]
 Note that on the database side we have our regular ``uuid`` format.
 .. code-block:: postgres
  select * from profiles;
                    id                  |   name
  --------------------------------------+----------
   846c4ffd-92ce-4de7-8d11-8e29929f4ec4 | John Doe
   cc7ec76c-5254-4dfc-bf19-9a70ba2ae9b9 | Jane Doe
  (2 rows)
 .. note::
  If there's no CAST from ``json`` to ``app_uuid`` defined, the request body will still work with the native uuid format (``cc7ec76c-5254-4dfc-bf19-9a70ba2ae9b9``).
 Advantages over Views
 =====================
 `Views <https://www.postgresql.org/docs/current/sql-createview.html>`_ also allow us to change the format of the underlying type. However they come with drawbacks that increase complexity.
 1) Formatting the column in the view makes it `non-updatable <https://www.postgresql.org/docs/current/sql-createview.html#SQL-CREATEVIEW-UPDATABLE-VIEWS>`_ since Postgres doesn't know how to reverse the transform. This can be worked around using INSTEAD OF triggers.
 2) When filtering by this column, we get full table scans for the same reason (also applies to :ref:`computed_cols`) . The performance loss here can be avoided with a computed index, or using a materialized generated column.
 3) If the formatted column is used as a foreign key, PostgREST can no longer detect that relationship and :ref:`resource_embedding` breaks. This can be worked around with :ref:`computed_relationships`.
 Domain Representations avoid all the above drawbacks. Their only drawback is that for existing tables, you have to change the column types. But this should be a fast operation since domains are binary coercible with their underlying types. A table rewrite won't be required.
 .. note::
  Why not create a `base type <https://www.postgresql.org/docs/current/sql-createtype.html#id-1.9.3.94.5.8>`_ instead? ``CREATE TYPE app_uuid (INTERNALLENGTH = 22, INPUT = app_uuid_parser, OUTPUT = app_uuid_formatter)``.
  Creating base types need superuser, which is restricted on cloud hosted databases. Additionally this way lets “how the data is presented” dictate “how the data is stored” which would be backwards.
@@ -0,0 +1,104 @@
 .. _open-api:
 OpenAPI
 =======
 PostgREST automatically serves a full `OpenAPI <https://www.openapis.org/>`_ description on the root path. This provides a list of all endpoints (tables, foreign tables, views, functions), along with supported HTTP verbs and example payloads.
 .. note::
  By default, this output depends on the permissions of the role that is contained in the JWT role claim (or the :ref:`db-anon-role` if no JWT is sent). If you need to show all the endpoints disregarding the role's permissions, set the :ref:`openapi-mode` config to :code:`ignore-privileges`.
 For extra customization, the OpenAPI output contains a "description" field for every `SQL comment <https://www.postgresql.org/docs/current/sql-comment.html>`_ on any database object. For instance,
 .. code-block:: sql
  COMMENT ON SCHEMA mammals IS
    'A warm-blooded vertebrate animal of a class that is distinguished by the secretion of milk by females for the nourishment of the young';
  COMMENT ON TABLE monotremes IS
    'Freakish mammals lay the best eggs for breakfast';
  COMMENT ON COLUMN monotremes.has_venomous_claw IS
    'Sometimes breakfast is not worth it';
 These unsavory comments will appear in the generated JSON as the fields, ``info.description``, ``definitions.monotremes.description`` and ``definitions.monotremes.properties.has_venomous_claw.description``.
 Also if you wish to generate a ``summary`` field you can do it by having a multiple line comment, the ``summary`` will be the first line and the ``description`` the lines that follow it:
 .. code-block:: plpgsql
  COMMENT ON TABLE entities IS
    $$Entities summary
    Entities description that
    spans
    multiple lines$$;
 Similarly, you can override the API title by commenting the schema.
 .. code-block:: plpgsql
  COMMENT ON SCHEMA api IS
  $$FooBar API
  A RESTful API that serves FooBar data.$$;
 If you need to include the ``security`` and ``securityDefinitions`` options, set the :ref:`openapi-security-active` configuration to ``true``.
 You can use a tool like `Swagger UI <https://swagger.io/tools/swagger-ui/>`_ to create beautiful documentation from the description and to host an interactive web-based dashboard. The dashboard allows developers to make requests against a live PostgREST server, and provides guidance with request headers and example request bodies.
 .. important::
  The OpenAPI information can go out of date as the schema changes under a running server. See :ref:`schema_reloading`.
 .. _override_openapi:
 Overriding Full OpenAPI Response
 --------------------------------
 You can override the whole default response with a function result. To do this, set the function on :ref:`db-root-spec`.
 .. code:: bash
   db-root-spec = "root"
 .. code:: postgres
  create or replace function root() returns json as $_$
  declare
  openapi json = $$
    {
      "swagger": "2.0",
      "info":{
        "title":"Overridden",
        "description":"This is a my own API"
      }
    }
  $$;
  begin
    return openapi;
  end
  $_$ language plpgsql;
 .. tabs::
  .. code-tab:: http
    GET / HTTP/1.1
  .. code-tab:: bash Curl
    curl http://localhost:3000
 .. code-block:: http
  HTTP/1.1 200 OK
  {
    "swagger": "2.0",
    "info":{
      "title":"Overridden",
      "description":"This is a my own API"
    }
  }
@@ -0,0 +1,52 @@
 .. _options_requests:
 OPTIONS method
 ==============
 You can verify which HTTP methods are allowed on endpoints for tables and views by using an OPTIONS request. These methods are allowed depending on what operations *can* be done on the table or view, not on the database permissions assigned to them.
 For a table named ``people``, OPTIONS would show:
 .. tabs::
  .. code-tab:: http
    OPTIONS /people HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/people" -X OPTIONS -i
 .. code-block:: http
  HTTP/1.1 200 OK
  Allow: OPTIONS,GET,HEAD,POST,PUT,PATCH,DELETE
 For a view, the methods are determined by the presence of INSTEAD OF TRIGGERS.
 .. table::
   :widths: auto
   +--------------------+-------------------------------------------------------------------------------------------------+
   | Method allowed     | View's requirements                                                                             |
   +====================+=================================================================================================+
   | OPTIONS, GET, HEAD | None (Always allowed)                                                                           |
   +--------------------+-------------------------------------------------------------------------------------------------+
   | POST               | INSTEAD OF INSERT TRIGGER                                                                       |
   +--------------------+-------------------------------------------------------------------------------------------------+
   | PUT                | INSTEAD OF INSERT TRIGGER, INSTEAD OF UPDATE TRIGGER, also requires the presence of a           |
   |                    | primary key                                                                                     |
   +--------------------+-------------------------------------------------------------------------------------------------+
   | PATCH              | INSTEAD OF UPDATE TRIGGER                                                                       |
   +--------------------+-------------------------------------------------------------------------------------------------+
   | DELETE             | INSTEAD OF DELETE TRIGGER                                                                       |
   +--------------------+-------------------------------------------------------------------------------------------------+
   | All the above methods are allowed for                                                                                |
   | `auto-updatable views <https://www.postgresql.org/docs/current/sql-createview.html#SQL-CREATEVIEW-UPDATABLE-VIEWS>`_ |
   +--------------------+-------------------------------------------------------------------------------------------------+
 For functions, the methods depend on their volatility. ``VOLATILE`` functions allow only ``OPTIONS,POST``, whereas the rest also permit ``GET,HEAD``.
 .. important::
  Whenever you add or remove tables or views, or modify a view's INSTEAD OF TRIGGERS on the database, you must refresh PostgREST's schema cache for OPTIONS requests to work properly. See the section :ref:`schema_reloading`.
@@ -0,0 +1,210 @@
 Resource Representation
 #######################
 PostgREST uses proper HTTP content negotiation (`RFC7231 <https://datatracker.ietf.org/doc/html/rfc7231#section-5.3>`_) to deliver a resource representation.
 That is to say the same API endpoint can respond in different formats like JSON or CSV depending on the request.
 .. _res_format:
 Response Format
 ===============
 Use the Accept request header to specify the acceptable format (or formats) for the response:
 .. tabs::
  .. code-tab:: http
    GET /people HTTP/1.1
    Accept: application/json
  .. code-tab:: bash Curl
    curl "http://localhost:3000/people" \
      -H "Accept: application/json"
 For tables and views the current possibilities are:
 * ``*/*``
 * ``text/csv``
 * ``application/json``
 * ``application/openapi+json``
 * ``application/geo+json``
 The server will default to JSON for API endpoints and OpenAPI on the root.
 .. _singular_plural:
 Singular or Plural
 ------------------
 By default PostgREST returns all JSON results in an array, even when there is only one item. For example, requesting :code:`/items?id=eq.1` returns
 .. code:: json
  [
    { "id": 1 }
  ]
 This can be inconvenient for client code. To return the first result as an object unenclosed by an array, specify :code:`vnd.pgrst.object` as part of the :code:`Accept` header
 .. tabs::
  .. code-tab:: http
    GET /items?id=eq.1 HTTP/1.1
    Accept: application/vnd.pgrst.object+json
  .. code-tab:: bash Curl
    curl "http://localhost:3000/items?id=eq.1" \
      -H "Accept: application/vnd.pgrst.object+json"
 This returns
 .. code:: json
  { "id": 1 }
 with a :code:`Content-Type: application/vnd.pgrst.object+json`.
 When a singular response is requested but no entries are found, the server responds with an error message and 406 Not Acceptable status code rather than the usual empty array and 200 status:
 .. code-block:: json
  {
    "message": "JSON object requested, multiple (or no) rows returned",
    "details": "Results contain 0 rows, application/vnd.pgrst.object+json requires 1 row",
    "hint": null,
    "code": "PGRST505"
  }
 .. note::
  Many APIs distinguish plural and singular resources using a special nested URL convention e.g. `/stories` vs `/stories/1`. Why do we use `/stories?id=eq.1`? The answer is because a singular resource is (for us) a row determined by a primary key, and primary keys can be compound (meaning defined across more than one column). The more familiar nested urls consider only a degenerate case of simple and overwhelmingly numeric primary keys. These so-called artificial keys are often introduced automatically by Object Relational Mapping libraries.
  Admittedly PostgREST could detect when there is an equality condition holding on all columns constituting the primary key and automatically convert to singular. However this could lead to a surprising change of format that breaks unwary client code just by filtering on an extra column. Instead we allow manually specifying singular vs plural to decouple that choice from the URL format.
 Stripped Nulls
 --------------
 By default PostgREST returns all JSON null values. For example, requesting ``/projects?id=gt.10`` returns
 .. code:: json
  [
    { "id": 11, "name": "OSX",      "client_id": 1,    "another_col": "val" },
    { "id": 12, "name": "ProjectX", "client_id": null, "another_col": null },
    { "id": 13, "name": "Y",        "client_id": null, "another_col": null }
  ]
 On large result sets, the unused keys with ``null`` values can waste bandwith unnecessarily. To remove them, specify ``nulls=stripped`` as a parameter of ``application/vnd.pgrst.array``:
 .. tabs::
  .. code-tab:: http
    GET /projects?id=gt.10 HTTP/1.1
    Accept: application/vnd.pgrst.array+json;nulls=stripped
  .. code-tab:: bash Curl
    curl "http://localhost:3000/projects?id=gt.10" \
      -H "Accept: application/vnd.pgrst.array+json;nulls=stripped"
 This returns
 .. code:: json
  [
    { "id": 11, "name": "OSX", "client_id": 1, "another_col": "val" },
    { "id": 12, "name": "ProjectX" },
    { "id": 13, "name": "Y"}
  ]
 .. _scalar_return_formats:
 Scalar Function Response Format
 -------------------------------
 In the special case of a :ref:`scalar_functions` there are three additional formats:
 * ``application/octet-stream``
 * ``text/plain``
 * ``text/xml``
 Example 1: If you want to return raw binary data from a :code:`bytea` column, you must specify :code:`application/octet-stream` as part of the :code:`Accept` header
 and select a single column :code:`?select=bin_data`.
 .. tabs::
  .. code-tab:: http
    GET /items?select=bin_data&id=eq.1 HTTP/1.1
    Accept: application/octet-stream
  .. code-tab:: bash Curl
    curl "http://localhost:3000/items?select=bin_data&id=eq.1" \
      -H "Accept: application/octet-stream"
 Example 2: You can request XML output when having a scalar function that returns a type of ``text/xml``. You are not forced to use select for this case.
 .. code-block:: postgres
  CREATE FUNCTION generate_xml_content(..) RETURNS xml ..
 .. tabs::
  .. code-tab:: http
    POST /rpc/generate_xml_content HTTP/1.1
    Accept: text/xml
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/generate_xml_content" \
      -X POST -H "Accept: text/xml"
 Example 3: If the stored procedure returns non-scalar values, you need to do a :code:`select` in the same way as for GET binary output.
 .. code-block:: sql
  CREATE FUNCTION get_descriptions(..) RETURNS SETOF TABLE(id int, description text) ..
 .. tabs::
  .. code-tab:: http
    POST /rpc/get_descriptions?select=description HTTP/1.1
    Accept: text/plain
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/get_descriptions?select=description" \
      -X POST -H "Accept: text/plain"
 .. note::
  If more than one row would be returned the binary/plain-text/xml results will be concatenated with no delimiter.
 .. _req_body:
 Request Body
 ============
 The server handles the following request body media types:
 * ``application/json``
 * ``application/x-www-form-urlencoded``
 * ``text/csv``
 For :ref:`tables_views` this works on ``POST``, ``PATCH`` and ``PUT`` methods. For :ref:`s_procs`, it works on ``POST`` methods.
 For stored procedures there are three additional types:
 * ``application/octet-stream``
 * ``text/plain``
 * ``text/xml``
 See :ref:`s_proc_single_unnamed`.
@@ -0,0 +1,156 @@
 .. _schemas:
 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.
 Single schema
 -------------
 To expose a single schema, specify a single value in :ref:`db-schemas`.
 .. code:: bash
   db-schemas = "api"
 This schema is added to the `search_path <https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ of every request using :ref:`tx_settings`.
 .. _multiple-schemas:
 Multiple schemas
 ----------------
 To expose multiple schemas, specify a comma-separated list on :ref:`db-schemas`:
 .. code:: bash
   db-schemas = "tenant1, tenant2"
 To switch schemas, use the ``Accept-Profile`` and ``Content-Profile`` headers.
 If you don't specify a Profile header, the first schema in the list(``tenant1`` here) is selected as the default schema.
 Only the selected schema gets added to the `search_path <https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ of every request.
 .. note::
   These headers are based on the "Content Negotiation by Profile" spec: https://www.w3.org/TR/dx-prof-conneg
 GET/HEAD
 ~~~~~~~~
 For GET or HEAD, select the schema with ``Accept-Profile``.
 .. tabs::
  .. code-tab:: http
     GET /items HTTP/1.1
     Accept-Profile: tenant2
  .. code-tab:: bash Curl
     curl "http://localhost:3000/items" \
       -H "Accept-Profile: tenant2"
 Other methods
 ~~~~~~~~~~~~~
 For POST, PATCH, PUT and DELETE, select the schema with ``Content-Profile``.
 .. tabs::
  .. code-tab:: http
     POST /items HTTP/1.1
     Content-Profile: tenant2
     {...}
  .. code-tab:: bash Curl
     curl "http://localhost:3000/items" \
       -X POST -H "Content-Type: application/json" \
       -H "Content-Profile: tenant2" \
       -d '{...}'
 You can also select the schema for :ref:`s_procs` and :ref:`open-api`.
 Restricted schemas
 ~~~~~~~~~~~~~~~~~~
 You can only switch to a schema included in :ref:`db-schemas`. Using another schema will result in an error:
 .. tabs::
  .. code-tab:: http
     GET /items HTTP/1.1
     Accept-Profile: tenant3
     {...}
  .. code-tab:: bash Curl
     curl "http://localhost:3000/items" \
       -H "Accept-Profile: tenant3"
 .. code-block::
  {
    "code":"PGRST106",
    "details":null,
    "hint":null,
    "message":"The schema must be one of the following: tenant1, tenant2"
  }
 Dynamic schemas
 ~~~~~~~~~~~~~~~
 To add schemas dynamically, you can use :ref:`in_db_config` plus :ref:`config reloading <config_reloading_notify>` and :ref:`schema cache reloading <schema_reloading_notify>`. Here are some options for how to do this:
 - If the schemas' names have a pattern, like a ``tenant_`` prefix, do:
 .. code-block:: postgresql
  create or replace function postgrest.pre_config()
  returns void as $$
    select
      set_config('pgrst.db_schemas', string_agg(nspname, ','), true)
    from pg_namespace
    where nspname like 'tenant_%';
  $$ language sql;
 - If there's no name pattern but they're created with a particular role (``CREATE SCHEMA mine AUTHORIZATION joe``), do:
 .. code-block:: postgresql
  create or replace function postgrest.pre_config()
  returns void as $$
    select
      set_config('pgrst.db_schemas', string_agg(nspname, ','), true)
    from pg_namespace
    where nspowner = 'joe'::regrole;
  $$ language sql;
 - Otherwise, you might need to create a table that stores the allowed schemas.
 .. code-block:: postgresql
  create table postgrest.config (schemas text);
  create or replace function postgrest.pre_config()
  returns void as $$
    select
      set_config('pgrst.db_schemas', schemas, true)
    from postgrest.config;
  $$ language sql;
 Then each time you add an schema, do:
 .. code-block:: postgresql
   NOTIFY pgrst, 'reload config';
   NOTIFY pgrst, 'reload schema';
@@ -0,0 +1,489 @@
 .. _s_procs:
 Stored Procedures
 =================
 *"A single resource can be the equivalent of a database stored procedure, with the power to abstract state changes over any number of storage items"* -- `Roy T. Fielding <http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-743>`_
 Procedures can perform any operations allowed by PostgreSQL (read data, modify data, :ref:`raise errors <raise_error>`, and even DDL operations). Every stored procedure in the :ref:`exposed schema <schemas>` and accessible by the :ref:`active database role <roles>` is executable under the :code:`/rpc` prefix.
 If they return table types, Stored Procedures can:
 - Use all the same :ref:`read filters as Tables and Views <read>` (horizontal/vertical filtering, counts, limits, etc.).
 - Use :ref:`Resource Embedding <s_proc_embed>`, if the returned table type has relationships to other tables.
 .. note::
  Why the ``/rpc`` prefix? PostgreSQL allows a table or view to have the same name as a function. The prefix allows us to avoid routes collisions.
 Calling with POST
 -----------------
 To supply arguments in an API call, include a JSON object in the request payload. Each key/value of the object will become an argument.
 For instance, assume we have created this function in the database.
 .. code-block:: plpgsql
  CREATE FUNCTION add_them(a integer, b integer)
  RETURNS integer AS $$
   SELECT a + b;
  $$ LANGUAGE SQL IMMUTABLE;
 .. important::
  Whenever you create or change a function you must refresh PostgREST's schema cache. See the section :ref:`schema_reloading`.
 The client can call it by posting an object like
 .. tabs::
  .. code-tab:: http
    POST /rpc/add_them HTTP/1.1
    { "a": 1, "b": 2 }
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/add_them" \
      -X POST -H "Content-Type: application/json" \
      -d '{ "a": 1, "b": 2 }'
 .. code-block:: json
  3
 .. note::
  PostgreSQL converts identifier names to lowercase unless you quote them like:
  .. code-block:: postgres
    CREATE FUNCTION "someFunc"("someParam" text) ...
 Calling with GET
 ----------------
 If the function doesn't modify the database, it will also run under the GET method (see :ref:`access_mode`).
 .. tabs::
  .. code-tab:: http
    GET /rpc/add_them?a=1&b=2 HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/add_them?a=1&b=2"
 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``.
 .. _s_proc_single_json:
 Functions with a single JSON parameter
 --------------------------------------
 You can also call a function that takes a single parameter of type JSON by sending the header :code:`Prefer: params=single-object` with your request. That way the JSON request body will be used as the single argument.
 .. code-block:: plpgsql
  CREATE FUNCTION mult_them(param json) RETURNS int AS $$
    SELECT (param->>'x')::int * (param->>'y')::int
  $$ LANGUAGE SQL;
 .. tabs::
  .. code-tab:: http
    POST /rpc/mult_them HTTP/1.1
    Prefer: params=single-object
    { "x": 4, "y": 2 }
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/mult_them" \
      -X POST -H "Content-Type: application/json" \
      -H "Prefer: params=single-object" \
      -d '{ "x": 4, "y": 2 }'
 .. code-block:: json
  8
 .. _s_proc_single_unnamed:
 Functions with a single unnamed parameter
 -----------------------------------------
 You can make a POST request to a function with a single unnamed parameter to send raw ``json/jsonb``, ``bytea``, ``text`` or ``xml`` data.
 To send raw JSON, the function must have a single unnamed ``json`` or ``jsonb`` parameter and the header ``Content-Type: application/json`` must be included in the request.
 .. code-block:: plpgsql
  CREATE FUNCTION mult_them(json) RETURNS int AS $$
    SELECT ($1->>'x')::int * ($1->>'y')::int
  $$ LANGUAGE SQL;
 .. tabs::
  .. code-tab:: http
    POST /rpc/mult_them HTTP/1.1
    Content-Type: application/json
    { "x": 4, "y": 2 }
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/mult_them" \
      -X POST -H "Content-Type: application/json" \
      -d '{ "x": 4, "y": 2 }'
 .. code-block:: json
  8
 .. note::
  If an overloaded function has a single ``json`` or ``jsonb`` unnamed parameter, PostgREST will call this function as a fallback provided that no other overloaded function is found with the parameters sent in the POST request.
 To send raw XML, the parameter type must be ``xml`` and the header ``Content-Type: text/xml`` must be included in the request.
 To send raw binary, the parameter type must be ``bytea`` and the header ``Content-Type: application/octet-stream`` must be included in the request.
 .. code-block:: plpgsql
  CREATE TABLE files(blob bytea);
  CREATE FUNCTION upload_binary(bytea) RETURNS void AS $$
    INSERT INTO files(blob) VALUES ($1);
  $$ LANGUAGE SQL;
 .. tabs::
  .. code-tab:: http
    POST /rpc/upload_binary HTTP/1.1
    Content-Type: application/octet-stream
    file_name.ext
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/upload_binary" \
      -X POST -H "Content-Type: application/octet-stream" \
      --data-binary "@file_name.ext"
 .. code-block:: http
  HTTP/1.1 200 OK
  [ ... ]
 To send raw text, the parameter type must be ``text`` and the header ``Content-Type: text/plain`` must be included in the request.
 .. _s_procs_array:
 Functions with array parameters
 -------------------------------
 You can call a function that takes an array parameter:
 .. code-block:: postgres
   create function plus_one(arr int[]) returns int[] as $$
      SELECT array_agg(n + 1) FROM unnest($1) AS n;
   $$ language sql;
 .. tabs::
  .. code-tab:: http
     POST /rpc/plus_one HTTP/1.1
     Content-Type: application/json
     {"arr": [1,2,3,4]}
  .. code-tab:: bash Curl
     curl "http://localhost:3000/rpc/plus_one" \
       -X POST -H "Content-Type: application/json" \
       -d '{"arr": [1,2,3,4]}'
 .. code-block:: json
   [2,3,4,5]
 For calling the function with GET, you can pass the array as an `array literal <https://www.postgresql.org/docs/current/arrays.html#ARRAYS-INPUT>`_,
 as in ``{1,2,3,4}``. Note that the curly brackets have to be urlencoded(``{`` is ``%7B`` and ``}`` is ``%7D``).
 .. tabs::
  .. code-tab:: http
    GET /rpc/plus_one?arr=%7B1,2,3,4%7D' HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/plus_one?arr=%7B1,2,3,4%7D'"
 .. note::
   For versions prior to PostgreSQL 10, to pass a PostgreSQL native array on a POST payload, you need to quote it and use an array literal:
   .. tabs::
     .. code-tab:: http
       POST /rpc/plus_one HTTP/1.1
       { "arr": "{1,2,3,4}" }
     .. code-tab:: bash Curl
       curl "http://localhost:3000/rpc/plus_one" \
         -X POST -H "Content-Type: application/json" \
         -d '{ "arr": "{1,2,3,4}" }'
   In these versions we recommend using function parameters of type JSON to accept arrays from the client.
 .. _s_procs_variadic:
 Variadic functions
 ------------------
 You can call a variadic function by passing a JSON array in a POST request:
 .. code-block:: postgres
   create function plus_one(variadic v int[]) returns int[] as $$
      SELECT array_agg(n + 1) FROM unnest($1) AS n;
   $$ language sql;
 .. tabs::
  .. code-tab:: http
    POST /rpc/plus_one HTTP/1.1
    Content-Type: application/json
    {"v": [1,2,3,4]}
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/plus_one" \
      -X POST -H "Content-Type: application/json" \
      -d '{"v": [1,2,3,4]}'
 .. code-block:: json
   [2,3,4,5]
 In a GET request, you can repeat the same parameter name:
 .. tabs::
  .. code-tab:: http
     GET /rpc/plus_one?v=1&v=2&v=3&v=4 HTTP/1.1
  .. code-tab:: bash Curl
     curl "http://localhost:3000/rpc/plus_one?v=1&v=2&v=3&v=4"
 Repeating also works in POST requests with ``Content-Type: application/x-www-form-urlencoded``:
 .. tabs::
  .. code-tab:: http
    POST /rpc/plus_one HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    v=1&v=2&v=3&v=4
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/plus_one" \
      -X POST -H "Content-Type: application/x-www-form-urlencoded" \
      -d 'v=1&v=2&v=3&v=4'
 Table-Valued functions
 ----------------------
 A function that returns a table type can be filtered using the same filters as :ref:`tables and views <tables_views>`. They can also use :ref:`Resource Embedding <s_proc_embed>`.
 .. code-block:: postgres
  CREATE FUNCTION best_films_2017() RETURNS SETOF films ..
 .. tabs::
  .. code-tab:: http
    GET /rpc/best_films_2017?select=title,director:directors(*) HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/best_films_2017?select=title,director:directors(*)"
 .. tabs::
  .. code-tab:: http
    GET /rpc/best_films_2017?rating=gt.8&order=title.desc HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/best_films_2017?rating=gt.8&order=title.desc"
 .. _function_inlining:
 Function Inlining
 ~~~~~~~~~~~~~~~~~
 A function that follows the `rules for inlining <https://wiki.postgresql.org/wiki/Inlining_of_SQL_functions#Inlining_conditions_for_table_functions>`_ will also inline :ref:`filters <h_filter>`, :ref:`order <ordering>` and :ref:`limits <limits>`.
 For example, for the following function:
 .. code-block:: postgres
  create function getallprojects() returns setof projects
  language sql stable
  as $$
    select * from projects;
  $$;
 Let's get its :ref:`explain_plan` when calling it with filters applied:
 .. tabs::
  .. code-tab:: http
    GET /rpc/getallprojects?id=eq.1 HTTP/1.1
    Accept: application/vnd.pgrst.plan
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/getallprojects?id=eq.1" \
      -H "Accept: application/vnd.pgrst.plan"
 .. code-block:: psql
  Aggregate  (cost=8.18..8.20 rows=1 width=112)
    ->  Index Scan using projects_pkey on projects  (cost=0.15..8.17 rows=1 width=40)
          Index Cond: (id = 1)
 Notice there's no "Function Scan" node in the plan, which tells us it has been inlined.
 .. _scalar_functions:
 Scalar functions
 ----------------
 PostgREST will detect if the function is scalar or table-valued and will shape the response format accordingly:
 .. tabs::
  .. code-tab:: http
    GET /rpc/add_them?a=1&b=2 HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/add_them?a=1&b=2"
 .. code-block:: json
  3
 .. tabs::
  .. code-tab:: http
    GET /rpc/best_films_2017 HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/best_films_2017"
 .. code-block:: json
  [
    { "title": "Okja", "rating": 7.4},
    { "title": "Call me by your name", "rating": 8},
    { "title": "Blade Runner 2049", "rating": 8.1}
  ]
 To manually choose a return format such as binary, plain text or XML, see the section :ref:`scalar_return_formats`.
 .. _untyped_functions:
 Untyped functions
 -----------------
 Functions that return ``record`` or ``SETOF record`` are supported:
 .. code-block:: postgres
  create function projects_setof_record() returns setof record as $$
    select * from projects;
  $$ language sql;
 .. tabs::
  .. code-tab:: http
    GET /rpc/projects_setof_record HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/projects_setof_record"
 .. code-block:: json
  [{"id":1,"name":"Windows 7","client_id":1},
   {"id":2,"name":"Windows 10","client_id":1},
   {"id":3,"name":"IOS","client_id":2}]
 However note that they will fail when trying to use :ref:`v_filter` and :ref:`h_filter` on them.
 So while they can be used for quick tests, it's recommended to always choose a strict return type for the function.
 Overloaded functions
 --------------------
 You can call overloaded functions with different number of arguments.
 .. code-block:: postgres
  CREATE FUNCTION rental_duration(customer_id integer) ..
  CREATE FUNCTION rental_duration(customer_id integer, from_date date) ..
 .. tabs::
  .. code-tab:: http
    GET /rpc/rental_duration?customer_id=232 HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/rental_duration?customer_id=232"
 .. tabs::
  .. code-tab:: http
    GET /rpc/rental_duration?customer_id=232&from_date=2018-07-01 HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/rental_duration?customer_id=232&from_date=2018-07-01"
 .. important::
  Overloaded functions with the same argument names but different types are not supported.
@@ -0,0 +1,108 @@
 .. note::
  This page is a work in progress.
 URL Grammar
 ===========
 .. _custom_queries:
 Custom Queries
 --------------
 The PostgREST URL grammar limits the kinds of queries clients can perform. It prevents arbitrary, potentially poorly constructed and slow client queries. It's good for quality of service, but means database administrators must create custom views and stored procedures to provide richer endpoints. The most common causes for custom endpoints are
 * Table unions
 * More complicated joins than those provided by :ref:`resource_embedding`.
 * Geo-spatial queries that require an argument, like "points near (lat,lon)"
 Unicode support
 ---------------
 PostgREST supports unicode in schemas, tables, columns and values. To access a table with unicode name, use percent encoding.
 To request this:
 .. code-block:: http
  GET /موارد HTTP/1.1
 Do this:
 .. tabs::
  .. code-tab:: http
    GET /%D9%85%D9%88%D8%A7%D8%B1%D8%AF HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/%D9%85%D9%88%D8%A7%D8%B1%D8%AF"
 .. _tabs-cols-w-spaces:
 Table / Columns with spaces
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 You can request table/columns with spaces in them by percent encoding the spaces with ``%20``:
 .. tabs::
  .. code-tab:: http
    GET /Order%20Items?Unit%20Price=lt.200 HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/Order%20Items?Unit%20Price=lt.200"
 .. _reserved-chars:
 Reserved characters
 ~~~~~~~~~~~~~~~~~~~
 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.
 .. tabs::
  .. code-tab:: http
    GET /employees?name=in.(%22Hebdon,John%22,%22Williams,Mary%22) HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/employees?name=in.(%22Hebdon,John%22,%22Williams,Mary%22)"
 Here ``information.cpe`` is a column name.
 .. tabs::
  .. code-tab:: http
    GET /vulnerabilities?%22information.cpe%22=like.*MS* HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/vulnerabilities?%22information.cpe%22=like.*MS*"
 If the value filtered by the ``in`` operator has a double quote (``"``), you can escape it using a backslash ``"\""``. A backslash itself can be used with a double backslash ``"\\"``.
 Here ``Quote:"`` and ``Backslash:\`` are percent-encoded values. Note that ``%5C`` is the percent-encoded backslash.
 .. tabs::
  .. code-tab:: http
    GET /marks?name=in.(%22Quote:%5C%22%22,%22Backslash:%5C%5C%22) HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/marks?name=in.(%22Quote:%5C%22%22,%22Backslash:%5C%5C%22)"
 .. note::
   Some HTTP libraries might encode URLs automatically(e.g. :code:`axios`). In these cases you should use double quotes
   :code:`""` directly instead of :code:`%22`.
@@ -0,0 +1,216 @@
 .. _authn:
 Authentication
 ==============
 PostgREST is designed to keep the database at the center of API security. All :ref:`authorization happens in the database <db_authz>` . It is PostgREST's job to **authenticate** requests -- i.e. verify that a client is who they say they are -- and then let the database **authorize** client actions.
 .. _roles:
 Overview of role system
 -----------------------
 There are three types of roles used by PostgREST, the **authenticator**, **anonymous** and **user** roles. The database administrator creates these roles and configures PostgREST to use them.
 .. image:: ../_static/security-roles.png
 The authenticator role is used for connecting to the database and should be configured to have very limited access. It is a chameleon whose job is to "become" other users to service authenticated HTTP requests.
 .. code:: sql
  CREATE ROLE authenticator LOGIN NOINHERIT NOCREATEDB NOCREATEROLE NOSUPERUSER;
 .. note::
  The names "authenticator" and "anon" names are configurable and not sacred, we simply choose them for clarity. See :ref:`db-uri` and :ref:`db-anon-role`.
 .. _user_impersonation:
 User Impersonation
 ------------------
 The picture below shows how the server handles authentication. If auth succeeds, it switches into the user role specified by the request, otherwise it switches into the anonymous role (if it's set in :ref:`db-anon-role`).
 .. image:: ../_static/security-anon-choice.png
 This role switching mechanism is called **user impersonation**. In PostgreSQL it's done with the ``SET ROLE`` statement.
 .. _impersonated_settings:
 Impersonated Role Settings
 --------------------------
 The impersonated role has its settings applied. For example, if you do:
 .. code-block:: postgresql
  ALTER ROLE webuser SET statement_timeout TO '5s';
 Every ``webuser`` :ref:`transaction <transactions>` gets its queries executed with a ``statement_timeout`` of 5 seconds.
 .. note::
   Settings that have a high privilege context (like ``superuser``) won't be applied, only settings that have a ``user`` context will be. This is so we don't cause permission errors.
   For more details see `Understanding Postgres Parameter Context <https://www.enterprisedb.com/blog/understanding-postgres-parameter-context>`_.
 .. _jwt_impersonation:
 JWT-Based User Impersonation
 ----------------------------
 We use `JSON Web Tokens <https://jwt.io/>`_ to authenticate API requests, this allows us to be stateless and not require database lookups for verification. As you'll recall a JWT contains a list of cryptographically signed claims. All claims are allowed but PostgREST cares specifically about a claim called role.
 .. code:: json
  {
    "role": "user123"
  }
 When a request contains a valid JWT with a role claim PostgREST will switch to the database role with that name for the duration of the HTTP request.
 .. code:: sql
  SET LOCAL ROLE user123;
 Note that the database administrator must allow the authenticator role to switch into this user by previously executing
 .. code:: sql
  GRANT user123 TO authenticator;
  -- similarly for the anonymous role
  -- GRANT anonymous TO authenticator;
 If the client included no JWT (or one without a role claim) then PostgREST switches into the anonymous role. The database administrator must set the anonymous role permissions correctly to prevent anonymous users from seeing or changing things they shouldn't.
 .. _jwt_generation:
 JWT Generation
 ~~~~~~~~~~~~~~
 You can create a valid JWT either from inside your database (see :ref:`sql_user_management`) or via an external service (see :ref:`external_jwt`).
 .. _client_auth:
 Client Auth
 ~~~~~~~~~~~
 To make an authenticated request the client must include an :code:`Authorization` HTTP header with the value :code:`Bearer <jwt>`. For instance:
 .. tabs::
  .. code-tab:: http
    GET /foo HTTP/1.1
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiamRvZSIsImV4cCI6MTQ3NTUxNjI1MH0.GYDZV3yM0gqvuEtJmfpplLBXSGYnke_Pvnl0tbKAjB4
  .. code-tab:: bash Curl
    curl "http://localhost:3000/foo" \
      -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiamRvZSIsImV4cCI6MTQ3NTUxNjI1MH0.GYDZV3yM0gqvuEtJmfpplLBXSGYnke_Pvnl0tbKAjB4"
 The ``Bearer`` header value can be used with or without capitalization(``bearer``).
 Symmetric Keys
 ~~~~~~~~~~~~~~
 Each token is cryptographically signed with a secret key. In the case of symmetric cryptography the signer and verifier share the same secret passphrase, which can be configured with :ref:`jwt-secret`.
 If it is set to a simple string value like “reallyreallyreallyreallyverysafe” then PostgREST interprets it as an HMAC-SHA256 passphrase.
 .. _asym_keys:
 Asymmetric Keys
 ~~~~~~~~~~~~~~~
 In asymmetric cryptography the signer uses the private key and the verifier the public key.
 As described in the :ref:`configuration` section, PostgREST accepts a ``jwt-secret`` config file parameter. However you can also specify a literal JSON Web Key (JWK) or set. For example, you can use an RSA-256 public key encoded as a JWK:
 .. code-block:: json
  {
    "alg":"RS256",
    "e":"AQAB",
    "key_ops":["verify"],
    "kty":"RSA",
    "n":"9zKNYTaYGfGm1tBMpRT6FxOYrM720GhXdettc02uyakYSEHU2IJz90G_MLlEl4-WWWYoS_QKFupw3s7aPYlaAjamG22rAnvWu-rRkP5sSSkKvud_IgKL4iE6Y2WJx2Bkl1XUFkdZ8wlEUR6O1ft3TS4uA-qKifSZ43CahzAJyUezOH9shI--tirC028lNg767ldEki3WnVr3zokSujC9YJ_9XXjw2hFBfmJUrNb0-wldvxQbFU8RPXip-GQ_JPTrCTZhrzGFeWPvhA6Rqmc3b1PhM9jY7Dur1sjYWYVyXlFNCK3c-6feo5WlRfe1aCWmwZQh6O18eTmLeT4nWYkDzQ"
  }
 .. note::
  This could also be a JSON Web Key Set (JWKS) if it was contained within an array assigned to a `keys` member, e.g. ``{ keys: [jwk1, jwk2] }``.
 Just pass it in as a single line string, escaping the quotes:
 .. code-block:: ini
  jwt-secret = "{ \"alg\":\"RS256\", … }"
 To generate such a public/private key pair use a utility like `latchset/jose <https://github.com/latchset/jose>`_.
 .. code-block:: bash
  jose jwk gen -i '{"alg": "RS256"}' -o rsa.jwk
  jose jwk pub -i rsa.jwk -o rsa.jwk.pub
  # now rsa.jwk.pub contains the desired JSON object
 You can specify the literal value as we saw earlier, or reference a filename to load the JWK from a file:
 .. code-block:: ini
  jwt-secret = "@rsa.jwk.pub"
 JWT Claims Validation
 ~~~~~~~~~~~~~~~~~~~~~
 PostgREST honors the following `JWT claims <https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4>`_:
 - ``exp`` Expiration Time
 - ``iat`` Issued At
 - ``nbf`` Not Before
 - ``aud`` Audience, see :ref:`jwt-aud`
 .. note::
  PostgREST allows for a 30-second clock skew when validating the ``exp`` and ``iat`` claims. In other words, it gives an extra 30 seconds before the token is rejected if there is a slight discrepancy in the timestamps.
 JWT Security
 ~~~~~~~~~~~~
 There are at least three types of common critiques against using JWT: 1) against the standard itself, 2) against using libraries with known security vulnerabilities, and 3) against using JWT for web sessions. We'll briefly explain each critique, how PostgREST deals with it, and give recommendations for appropriate user action.
 The critique against the `JWT standard <https://datatracker.ietf.org/doc/html/rfc7519>`_ is voiced in detail `elsewhere on the web <https://web.archive.org/web/20230123041631/https://paragonie.com/blog/2017/03/jwt-json-web-tokens-is-bad-standard-that-everyone-should-avoid>`_. The most relevant part for PostgREST is the so-called :code:`alg=none` issue. Some servers implementing JWT allow clients to choose the algorithm used to sign the JWT. In this case, an attacker could set the algorithm to :code:`none`, remove the need for any signature at all and gain unauthorized access. The current implementation of PostgREST, however, does not allow clients to set the signature algorithm in the HTTP request, making this attack irrelevant. The critique against the standard is that it requires the implementation of the :code:`alg=none` at all.
 Critiques against JWT libraries are only relevant to PostgREST via the library it uses. As mentioned above, not allowing clients to choose the signature algorithm in HTTP requests removes the greatest risk. Another more subtle attack is possible where servers use asymmetric algorithms like RSA for signatures. Once again this is not relevant to PostgREST since it is not supported. Curious readers can find more information in `this article <https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/>`_. Recommendations about high quality libraries for usage in API clients can be found on `jwt.io <https://jwt.io/>`_.
 The last type of critique focuses on the misuse of JWT for maintaining web sessions. The basic recommendation is to `stop using JWT for sessions <http://cryto.net/~joepie91/blog/2016/06/13/stop-using-jwt-for-sessions/>`_ because most, if not all, solutions to the problems that arise when you do, `do not work <http://cryto.net/~joepie91/blog/2016/06/19/stop-using-jwt-for-sessions-part-2-why-your-solution-doesnt-work/>`_. The linked articles discuss the problems in depth but the essence of the problem is that JWT is not designed to be secure and stateful units for client-side storage and therefore not suited to session management.
 PostgREST uses JWT mainly for authentication and authorization purposes and encourages users to do the same. For web sessions, using cookies over HTTPS is good enough and well catered for by standard web frameworks.
 .. _custom_validation:
 Custom Validation
 -----------------
 PostgREST does not enforce any extra constraints besides JWT validation. An example of an extra constraint would be to immediately revoke access for a certain user. Using :ref:`db-pre-request` you can specify a stored procedure to call immediately after :ref:`user_impersonation` and before the main query itself runs.
 .. code:: ini
  db-pre-request = "public.check_user"
 In the function you can run arbitrary code to check the request and raise an exception(see :ref:`raise_error`) to block it if desired. Here you can take advantage of :ref:`guc_req_headers_cookies_claims` for
 doing custom logic based on the web user info.
 .. code-block:: postgres
  CREATE OR REPLACE FUNCTION check_user() RETURNS void AS $$
  DECLARE
    email text := current_setting('request.jwt.claims', true)::json->>'email';
  BEGIN
    IF email = 'evil.user@malicious.com' THEN
      RAISE EXCEPTION 'No, you are evil'
        USING HINT = 'Stop being so evil and maybe you can log in';
    END IF;
  END
  $$ LANGUAGE plpgsql;
@@ -0,0 +1,834 @@
 .. _configuration:
 Configuration
 #############
 Configuration parameters can be provided via:
 - :ref:`file_config`.
 - :ref:`env_variables_config`, overriding values from the config file.
 - :ref:`in_db_config`, overriding values from both the config file and environment variables.
 Using :ref:`config_reloading` you can modify the parameters without restarting the server.
 Minimum parameters
 ==================
 The server is able to start without any config parameters, but it won't be able to serve requests unless it has :ref:`a role to serve anonymous requests with <db-anon-role>` - or :ref:`a secret to use for JWT authentication <jwt-secret>`.
 .. _file_config:
 Config File
 ===========
 There is no predefined location for the config file, you must specify the file path as the one and only argument to the server:
 .. code:: bash
  ./postgrest /path/to/postgrest.conf
 The configuration file must contain a set of key value pairs:
 .. code::
  # postgrest.conf
  # The standard connection URI format, documented at
  # https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
  db-uri       = "postgres://user:pass@host:5432/dbname"
  # The database role to use when no client authentication is provided.
  # Should differ from authenticator
  db-anon-role = "anon"
  # The secret to verify the JWT for authenticated requests with.
  # Needs to be 32 characters minimum.
  jwt-secret           = "reallyreallyreallyreallyverysafe"
  jwt-secret-is-base64 = false
  # Port the postgrest process is listening on for http requests
  server-port = 3000
 You can run ``postgrest --example`` to display all possible configuration parameters and how to use them in a configuration file.
 .. _env_variables_config:
 Environment Variables
 =====================
 Environment variables are capitalized, have a ``PGRST_`` prefix, and use underscores. For example: ``PGRST_DB_URI`` corresponds to ``db-uri`` and ``PGRST_APP_SETTINGS_*`` to ``app.settings.*``.
 `libpq environment variables <https://www.postgresql.org/docs/current/libpq-envars.html>`_ are also supported for constructing the connection string, see :ref:`db-uri`.
 See the full list of environment variable names on :ref:`config_full_list`.
 .. _in_db_config:
 In-Database Configuration
 =========================
 You can also configure the server with database settings by using a :ref:`pre-config <db-pre-config>` function. For example, you can configure :ref:`db-schemas` and :ref:`jwt-secret` like this:
 .. code-block::
  # postgrest.conf
  db-pre-config  = "postgrest.pre_config"
  # or env vars
  PGRST_DB_PRE_CONFIG = "postgrest.pre_config"
 .. code-block:: postgresql
  -- create a dedicated schema, hidden from the API
  create schema postgrest;
  -- grant usage on this schema to the authenticator
  grant usage on schema postgrest to authenticator;
  -- the function can configure postgREST by using set_config
  create or replace function postgrest.pre_config()
  returns void as $$
    select
        set_config('pgrst.db_schemas', 'schema1, schema2', true)
      , set_config('pgrst.jwt_secret', 'REALLYREALLYREALLYREALLYVERYSAFE', true);
  $$ language sql;
 Note that underscores(``_``) need to be used instead of dashes(``-``) for the in-database config parameters. See the full list of in-database names on :ref:`config_full_list`.
 You can disable the in-database configuration by setting :ref:`db-config` to ``false``.
 .. note::
  For backwards compatibility, you can do in-db config by modifying the :ref:`authenticator role <roles>`. This is no longer recommended as it requires SUPERUSER.
  .. code:: postgresql
     ALTER ROLE authenticator SET pgrst.db_schemas = "tenant1, tenant2, tenant3"
     ALTER ROLE authenticator IN DATABASE <your_database_name> SET pgrst.db_schemas = "tenant4, tenant5" -- database-specific setting, overrides the previous setting
 .. _config_reloading:
 Configuration Reloading
 =======================
 It's possible to reload PostgREST's configuration without restarting the server. You can do this :ref:`via signal <config_reloading_signal>` or :ref:`via notification <config_reloading_notify>`.
 - Any modification to the :ref:`file_config` will be applied during reload.
 - Any modification to the :ref:`in_db_config` will be applied during reload.
 - Not all settings are reloadable, see the reloadable list on :ref:`config_full_list`.
 - It's not possible to change :ref:`env_variables_config` for a running process, hence reloading a Docker container configuration will not work. In these cases, you can restart the process or use :ref:`in_db_config`.
 .. _config_reloading_signal:
 Reload with signal
 ------------------
 To reload the configuration via signal, send a SIGUSR2 signal to the server process.
 .. code:: bash
  killall -SIGUSR2 postgrest
 .. _config_reloading_notify:
 Reload with NOTIFY
 ------------------
 To reload the configuration from within the database, you can use a NOTIFY command.
 .. code:: postgresql
   NOTIFY pgrst, 'reload config'
 The ``"pgrst"`` notification channel is enabled by default. You can name the channel with :ref:`db-channel` and enable or disable it with :ref:`db-channel-enabled`.
 .. _config_full_list:
 List of parameters
 ==================
 .. _admin-server-port:
 admin-server-port
 -----------------
  =============== =======================
  **Type**        Int
  **Default**     `n/a`
  **Reloadable**  N
  **Environment** PGRST_ADMIN_SERVER_PORT
  **In-Database** `n/a`
  =============== =======================
  Specifies the port for the :ref:`health_check` endpoints.
 .. _app.settings.*:
 app.settings.*
 --------------
  =============== =======================
  **Type**        String
  **Default**     `n/a`
  **Reloadable**  &
  **Environment** PGRST_APP_SETTINGS_*
  **In-Database** `n/a`
  =============== =======================
  Arbitrary settings that can be used to pass in secret keys directly as strings, or via OS environment variables. For instance: :code:`app.settings.jwt_secret = "$(MYAPP_JWT_SECRET)"` will take :code:`MYAPP_JWT_SECRET` from the environment and make it available to postgresql functions as :code:`current_setting('app.settings.jwt_secret')`.
 .. _db-anon-role:
 db-anon-role
 ------------
  =============== =======================
  **Type**        String
  **Default**     `n/a`
  **Reloadable**  Y
  **Environment** PGRST_DB_ANON_ROLE
  **In-Database** pgrst.db_anon_role
  =============== =======================
  The database role to use when executing commands on behalf of unauthenticated clients. For more information, see :ref:`roles`.
  When unset anonymous access will be blocked.
 .. _db-channel:
 db-channel
 ----------
  =============== =======================
  **Type**        String
  **Default**     pgrst
  **Reloadable**  Y
  **Environment** PGRST_DB_CHANNEL
  **In-Database** `n/a`
  =============== =======================
  The name of the notification channel that PostgREST uses for :ref:`schema_reloading` and configuration reloading.
 .. _db-channel-enabled:
 db-channel-enabled
 ------------------
  =============== =======================
  **Type**        Boolean
  **Default**     True
  **Reloadable**  Y
  **Environment** PGRST_DB_CHANNEL_ENABLED
  **In-Database** `n/a`
  =============== =======================
  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 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:
 db-config
 ---------
  =============== =======================
  **Type**        Boolean
  **Default**     True
  **Reloadable**  Y
  **Environment** PGRST_DB_CONFIG
  **In-Database** `n/a`
  =============== =======================
   Enables the in-database configuration.
 .. _db-pre-config:
 db-pre-config
 -------------
  =============== =======================
  **Type**        String
  **Default**     `n/a`
  **Reloadable**  Y
  **Environment** PGRST_DB_PRE_CONFIG
  **In-Database** pgrst.db_pre_config
  =============== =======================
   Name of the function that does :ref:`in_db_config`.
 .. _db-extra-search-path:
 db-extra-search-path
 --------------------
  =============== ==========================
  **Type**        String
  **Default**     public
  **Reloadable**  Y
  **Environment** PGRST_DB_EXTRA_SEARCH_PATH
  **In-Database** pgrst.db_extra_search_path
  =============== ==========================
  Extra schemas to add to the `search_path <https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ of every request. These schemas tables, views and stored procedures **don't get API endpoints**, they can only be referred from the database objects inside your :ref:`db-schemas`.
  This parameter was meant to make it easier to use **PostgreSQL extensions** (like PostGIS) that are outside of the :ref:`db-schemas`.
  Multiple schemas can be added in a comma-separated string, e.g. ``public, extensions``.
 .. _db-max-rows:
 db-max-rows
 -----------
  =============== ==========================
  **Type**        Int
  **Default**     ∞
  **Reloadable**  Y
  **Environment** PGRST_DB_MAX_ROWS
  **In-Database** pgrst.db_max_rows
  =============== ==========================
  *For backwards compatibility, this config parameter is also available without prefix as "max-rows".*
  A hard limit to the number of rows PostgREST will fetch from a view, table, or stored procedure. Limits payload size for accidental or malicious requests.
 .. _db-plan-enabled:
 db-plan-enabled
 ---------------
  =============== ==========================
  **Type**        Boolean
  **Default**     False
  **Reloadable**  Y
  **Environment** PGRST_DB_PLAN_ENABLED
  **In-Database** pgrst.db_plan_enabled
  =============== ==========================
  When this is set to :code:`true`, the execution plan of a request can be retrieved by using the :code:`Accept: application/vnd.pgrst.plan` header. See :ref:`explain_plan`.
 .. _db-pool:
 db-pool
 -------
  =============== ==========================
  **Type**        Int
  **Default**     10
  **Reloadable**  N
  **Environment** PGRST_DB_POOL
  **In-Database** n/a
  =============== ==========================
  Number of maximum connections to keep open in PostgREST's database pool.
 .. _db-pool-acquisition-timeout:
 db-pool-acquisition-timeout
 ---------------------------
  =============== =================================
  **Type**        Int
  **Default**     10
  **Reloadable**  N
  **Environment** PGRST_DB_POOL_ACQUISITION_TIMEOUT
  **In-Database** `n/a`
  =============== =================================
  Specifies the maximum time in seconds that the request will wait for the pool to free up a connection slot to the database.
 .. _db-pool-max-idletime:
 db-pool-max-idletime
 --------------------
  =============== =================================
  **Type**        Int
  **Default**     30
  **Reloadable**  N
  **Environment** PGRST_DB_POOL_MAX_IDLETIME
  **In-Database** `n/a`
  =============== =================================
   *For backwards compatibility, this config parameter is also available as “db-pool-timeout”.*
   Time in seconds to close idle pool connections.
 .. _db-pool-max-lifetime:
 db-pool-max-lifetime
 --------------------
  =============== =================================
  **Type**        Int
  **Default**     1800
  **Reloadable**  N
  **Environment** PGRST_DB_POOL_MAX_LIFETIME
  **In-Database** `n/a`
  =============== =================================
  Specifies the maximum time in seconds of an existing connection in the pool.
 .. _db-pre-request:
 db-pre-request
 --------------
  =============== =================================
  **Type**        String
  **Default**     `n/a`
  **Reloadable**  Y
  **Environment** PGRST_DB_PRE_REQUEST
  **In-Database** pgrst.db_pre_request
  =============== =================================
  *For backwards compatibility, this config parameter is also available without prefix as "pre-request".*
  A schema-qualified stored procedure name to call right after the :ref:`tx_settings` are set. See :ref:`pre-request`.
 .. _db-prepared-statements:
 db-prepared-statements
 ----------------------
  =============== =================================
  **Type**        Boolean
  **Default**     True
  **Reloadable**  Y
  **Environment** PGRST_DB_PREPARED_STATEMENTS
  **In-Database** pgrst.db_prepared_statements
  =============== =================================
  Enables or disables 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 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:
 db-root-spec
 ------------
  =============== =================================
  **Type**        String
  **Default**     `n/a`
  **Reloadable**  Y
  **Environment** PGRST_DB_ROOT_SPEC
  **In-Database** pgrst.db_root_spec
  =============== =================================
  Function to override the OpenAPI response. See :ref:`override_openapi`.
 .. _db-schemas:
 db-schemas
 ----------
  =============== =================================
  **Type**        String
  **Default**     public
  **Reloadable**  Y
  **Environment** PGRST_DB_SCHEMAS
  **In-Database** pgrst.db_schemas
  =============== =================================
  *For backwards compatibility, this config parameter is also available in singular as "db-schema".*
  The list of database schemas to expose to clients. See :ref:`schemas`.
 .. _db-tx-end:
 db-tx-end
 ---------
  =============== =================================
  **Type**        String
  **Default**     commit
  **Reloadable**  N
  **Environment** PGRST_DB_TX_END
  **In-Database** `n/a`
  =============== =================================
  Specifies how to terminate the database transactions.
  .. code:: bash
    # The transaction is always committed
    db-tx-end = "commit"
    # The transaction is committed unless a "Prefer: tx=rollback" header is sent
    db-tx-end = "commit-allow-override"
    # The transaction is always rolled back
    db-tx-end = "rollback"
    # The transaction is rolled back unless a "Prefer: tx=commit" header is sent
    db-tx-end = "rollback-allow-override"
 .. _db-uri:
 db-uri
 ------
  =============== =================================
  **Type**        String
  **Default**     postgresql://
  **Reloadable**  N
  **Environment** PGRST_DB_URI
  **In-Database** `n/a`
  =============== =================================
  The standard `PostgreSQL connection string <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>`_, there are different ways to specify it:
 URI Format
 ~~~~~~~~~~
  .. code::
    "postgres://authenticator:mysecretpassword@localhost:5433/postgres?parameters=val"
  - Under this format symbols and unusual characters in the password or other fields should be percent encoded to avoid a parse error.
  - If enforcing an SSL connection to the database is required you can use `sslmode <https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS>`_ in the URI, for example ``postgres://user:pass@host:5432/dbname?sslmode=require``.
  - The user with whom PostgREST connects to the database is also known as the ``authenticator`` role. For more information see :ref:`roles`.
  - When running PostgREST on the same machine as PostgreSQL, it is also possible to connect to the database using a `Unix socket <https://en.wikipedia.org/wiki/Unix_domain_socket>`_ and the `Peer Authentication method <https://www.postgresql.org/docs/current/auth-peer.html>`_ as an alternative to TCP/IP communication and authentication with a password, this also grants higher performance.  To do this you can omit the host and the password, e.g. ``postgres://user@/dbname``, see the `libpq connection string <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>`_ documentation for more details.
 Keyword/Value Format
 ~~~~~~~~~~~~~~~~~~~~
  .. code::
    "host=localhost port=5433 user=authenticator password=mysecretpassword dbname=postgres"
 LIBPQ Environment Variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  .. code::
    PGHOST=localhost PGPORT=5433 PGUSER=authenticator PGDATABASE=postgres
  Any parameter that is not set in the above formats is read from `libpq environment variables <https://www.postgresql.org/docs/current/libpq-envars.html>`_. The default connection string is ``postgresql://``, which reads **all** parameters from the environment.
 External config file
 ~~~~~~~~~~~~~~~~~~~~
  Choosing a value for this parameter beginning with the at sign such as ``@filename`` (e.g. ``@./configs/my-config``) loads the connection string out of an external file.
 .. _db-use-legacy-gucs:
 db-use-legacy-gucs
 ------------------
  =============== =================================
  **Type**        Boolean
  **Default**     True
  **Reloadable**  Y
  **Environment** PGRST_DB_USE_LEGACY_GUCS
  **In-Database** pgrst.db_use_legacy_gucs
  =============== =================================
  Determine if GUC request settings for headers, cookies and jwt claims use the :ref:`legacy names <guc_legacy_names>` (string with dashes, invalid starting from PostgreSQL v14) with text values instead of the :ref:`new names <guc_req_headers_cookies_claims>` (string without dashes, valid on all PostgreSQL versions) with json values.
  On PostgreSQL versions 14 and above, this parameter is ignored.
 .. _jwt-aud:
 jwt-aud
 -------
  =============== =================================
  **Type**        String
  **Default**     `n/a`
  **Reloadable**  Y
  **Environment** PGRST_JWT_AUD
  **In-Database** pgrst.jwt_aud
  =============== =================================
  Specifies the `JWT audience claim <https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3>`_. If this claim is present in the client provided JWT then you must set this to the same value as in the JWT, otherwise verifying the JWT will fail.
 .. _jwt-role-claim-key:
 jwt-role-claim-key
 ------------------
  =============== =================================
  **Type**        String
  **Default**     .role
  **Reloadable**  Y
  **Environment** PGRST_JWT_ROLE_CLAIM_KEY
  **In-Database** pgrst.jwt_role_claim_key
  =============== =================================
  *For backwards compatibility, this config parameter is also available without prefix as "role-claim-key".*
  A JSPath DSL that specifies the location of the :code:`role` key in the JWT claims. This can be used to consume a JWT provided by a third party service like Auth0, Okta or Keycloak. Usage examples:
  .. code:: bash
    # {"postgrest":{"roles": ["other", "author"]}}
    # 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 quotes(escaped in the config value)
    jwt-role-claim-key = ".\"https://www.example.com/role\".key"
 .. _jwt-secret:
 jwt-secret
 ----------
  =============== =================================
  **Type**        String
  **Default**     `n/a`
  **Reloadable**  Y
  **Environment** PGRST_JWT_SECRET
  **In-Database** pgrst.jwt_secret
  =============== =================================
  The secret or `JSON Web Key (JWK) (or set) <https://datatracker.ietf.org/doc/html/rfc7517>`_ used to decode JWT tokens clients provide for authentication. For security the key must be **at least 32 characters long**. If this parameter is not specified then PostgREST refuses authentication requests. Choosing a value for this parameter beginning with the at sign such as :code:`@filename` loads the secret out of an external file. This is useful for automating deployments. Note that any binary secrets must be base64 encoded. Both symmetric and asymmetric cryptography are supported. For more info see :ref:`asym_keys`.
  Choosing a value for this parameter beginning with the at sign such as ``@filename`` (e.g. ``@./configs/my-config``) loads the secret out of an external file.
  .. warning::
     Only when using the :ref:`file_config`, if the ``jwt-secret`` contains a ``$`` character by itself it will give errors. In this case, use ``$$`` and PostgREST will interpret it as a single ``$`` character.
 .. _jwt-secret-is-base64:
 jwt-secret-is-base64
 --------------------
  =============== =================================
  **Type**        Boolean
  **Default**     False
  **Reloadable**  Y
  **Environment** PGRST_JWT_SECRET_IS_BASE64
  **In-Database** pgrst.jwt_secret_is_base64
  =============== =================================
  When this is set to :code:`true`, the value derived from :code:`jwt-secret` will be treated as a base64 encoded secret.
 .. _log-level:
 log-level
 ---------
  =============== =================================
  **Type**        String
  **Default**     error
  **Reloadable**  N
  **Environment** PGRST_LOG_LEVEL
  **In-Database** `n/a`
  =============== =================================
  Specifies the level of information to be logged while running PostgREST.
  .. code:: bash
      # Only startup and db connection recovery messages are logged
      log-level = "crit"
      # All the "crit" level events plus server errors (status 5xx) are logged
      log-level = "error"
      # All the "error" level events plus request errors (status 4xx) are logged
      log-level = "warn"
      # All the "warn" level events plus all requests (every status code) are logged
      log-level = "info"
  Because currently there's no buffering for logging, the levels with minimal logging(``crit/error``) will increase throughput.
 .. _openapi-mode:
 openapi-mode
 ------------
  =============== =================================
  **Type**        String
  **Default**     follow-privileges
  **Reloadable**  Y
  **Environment** PGRST_OPENAPI_MODE
  **In-Database** pgrst.openapi_mode
  =============== =================================
  Specifies how the OpenAPI output should be displayed.
  .. code:: bash
    # Follows the privileges of the JWT role claim (or from db-anon-role if the JWT is not sent)
    # Shows information depending on the permissions that the role making the request has
    openapi-mode = "follow-privileges"
    # Ignores the privileges of the JWT role claim (or from db-anon-role if the JWT is not sent)
    # Shows all the exposed information, regardless of the permissions that the role making the request has
    openapi-mode = "ignore-privileges"
    # Disables the OpenApi output altogether.
    # Throws a `404 Not Found` error when accessing the API root path
    openapi-mode = "disabled"
 .. _openapi-security-active:
 openapi-security-active
 -----------------------
  =============== =================================
  **Type**        Boolean
  **Default**     False
  **Reloadable**  Y
  **Environment** PGRST_OPENAPI_SECURITY_ACTIVE
  **In-Database** pgrst.openapi_security_active
  =============== =================================
 When this is set to :code:`true`, security options are included in the :ref:`OpenAPI output <open-api>`.
 .. _openapi-server-proxy-uri:
 openapi-server-proxy-uri
 ------------------------
  =============== =================================
  **Type**        String
  **Default**     `n/a`
  **Reloadable**  N
  **Environment** PGRST_OPENAPI_SERVER_PROXY_URI
  **In-Database** pgrst.openapi_server_proxy_uri
  =============== =================================
  Overrides the base URL used within the OpenAPI self-documentation hosted at the API root path. Use a complete URI syntax :code:`scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]`. Ex. :code:`https://postgrest.com`
  .. code:: json
    {
      "swagger": "2.0",
      "info": {
        "version": "0.4.3.0",
        "title": "PostgREST API",
        "description": "This is a dynamic API generated by PostgREST"
      },
      "host": "postgrest.com:443",
      "basePath": "/",
      "schemes": [
        "https"
      ]
    }
 .. _raw-media-types:
 raw-media-types
 ---------------
  =============== =================================
  **Type**        String
  **Default**     `n/a`
  **Reloadable**  Y
  **Environment** PGRST_RAW_MEDIA_TYPES
  **In-Database** pgrst.raw_media_types
  =============== =================================
 This serves to extend the `Media Types <https://en.wikipedia.org/wiki/Media_type>`_ that PostgREST currently accepts through an ``Accept`` header.
 These media types can be requested by following the same rules as the ones defined in :ref:`scalar_return_formats`.
 As an example, the below config would allow you to request an **image** and a **XML** file by doing a request with ``Accept: image/png``
 or ``Accept: font/woff2``, respectively.
 .. code:: bash
   raw-media-types="image/png, font/woff2"
 .. _server-host:
 server-host
 -----------
  =============== =================================
  **Type**        String
  **Default**     !4
  **Reloadable**  N
  **Environment** PGRST_SERVER_HOST
  **In-Database** `n/a`
  =============== =================================
  Where to bind the PostgREST web server. In addition to the usual address options, PostgREST interprets these reserved addresses with special meanings:
  * :code:`*` - any IPv4 or IPv6 hostname
  * :code:`*4` - any IPv4 or IPv6 hostname, IPv4 preferred
  * :code:`!4` - any IPv4 hostname
  * :code:`*6` - any IPv4 or IPv6 hostname, IPv6 preferred
  * :code:`!6` - any IPv6 hostname
 .. _server-port:
 server-port
 -----------
  =============== =================================
  **Type**        Int
  **Default**     3000
  **Reloadable**  N
  **Environment** PGRST_SERVER_PORT
  **In-Database** `n/a`
  =============== =================================
  The TCP port to bind the web server.
 .. _server-trace-header:
 server-trace-header
 -------------------
  =============== =================================
  **Type**        String
  **Default**     `n/a`
  **Reloadable**  Y
  **Environment** PGRST_SERVER_TRACE_HEADER
  **In-Database** pgrst.server_trace_header
  =============== =================================
  The header name used to trace HTTP requests. See :ref:`trace_header`.
 .. _server-unix-socket:
 server-unix-socket
 ------------------
  =============== =================================
  **Type**        String
  **Default**     `n/a`
  **Reloadable**  N
  **Environment** PGRST_SERVER_UNIX_SOCKET
  **In-Database** `n/a`
  =============== =================================
  `Unix domain socket <https://en.wikipedia.org/wiki/Unix_domain_socket>`_ where to bind the PostgREST web server.
  If specified, this takes precedence over :ref:`server-port`. Example:
  .. code:: bash
    server-unix-socket = "/tmp/pgrst.sock"
 .. _server-unix-socket-mode:
 server-unix-socket-mode
 -----------------------
  =============== =================================
  **Type**        String
  **Default**     660
  **Reloadable**  N
  **Environment** PGRST_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:`server-unix-socket`
  Needs to be a valid octal between 600 and 777.
  .. code:: bash
    server-unix-socket-mode = "660"
@@ -0,0 +1,93 @@
 .. _connection_pool:
 Connection Pool
 ===============
 A connection pool is a cache of reusable database connections. It allows serving many HTTP requests using few database connections. Every request to an :doc:`API resource <api>` borrows a connection from the pool to start a :doc:`transaction <transactions>`.
 Minimizing connections is paramount to performance. Each PostgreSQL connection creates a process, having too many can exhaust available resources.
 Connection String
 -----------------
 For connecting to the database, the pool requires a connection string. You can can configure it using :ref:`db-uri`.
 .. _pool_growth_limit:
 .. _dyn_conn_pool:
 Dynamic Connection Pool
 -----------------------
 To conserve system resources, PostgREST uses a dynamic connection pool. This enables the number of connections in the pool to increase and decrease depending on request traffic.
 - If all the connections are being used, a new connection is added. The pool can grow until it reaches the :ref:`db-pool` size. Note that it’s pointless to set this higher than the ``max_connections`` setting in your database.
 - If a connection is unused for a period of time (:ref:`db-pool-max-idletime`), it will be released.
 Connection lifetime
 -------------------
 Long-lived PostgreSQL connections can consume considerable memory (see `here <https://www.postgresql.org/message-id/CAFj8pRCQN2B2vrVMH1-bd-8xtzjytWR%2BAjZ%2BMCj9J2wPxKPa9Q%40mail.gmail.com>`_ for more details).
 Under a busy system, the :ref:`db-pool-max-idletime` won't be reached and the connection pool can be full of long-lived connections.
 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.
 Acquisition Timeout
 -------------------
 If all the available connections in the pool are busy, an HTTP request will wait until reaching a timeout (:ref:`db-pool-acquisition-timeout`).
 If the request reaches the timeout, it will be aborted with the following response:
 .. code-block:: http
  HTTP/1.1 504 Gateway Timeout
  {"code":"PGRST003",
   "details":null,
   "hint":null,
   "message":"Timed out acquiring connection from connection pool."}
 .. important::
  Getting this error message is an indicator of a performance issue. To solve it, you can:
  - Reduce your queries execution time.
    - Check the request :ref:`explain_plan` to tune your query, this usually means adding indexes.
  - Reduce the amount of requests.
    - Reduce write requests. Do :ref:`bulk_insert` (or :ref:`upsert`) instead of inserting rows one by one.
    - Reduce read requests. Use :ref:`resource_embedding`. Combine unrelated data into a single request using custom database views or functions.
    - Use :ref:`s_procs` for combining read and write logic into a single request.
  - Increase the :ref:`db-pool` size.
    - Not a panacea since connections can't grow infinitely. Try the previous recommendations before this.
 .. _automatic_recovery:
 Automatic Recovery
 ------------------
 The server will retry reconnecting to the database if connection loss happens.
 - It will retry forever with exponential backoff, with a maximum backoff time of 32 seconds between retries. Each of these attempts are :ref:`logged <pgrst_logging>`.
 - It will only stop retrying if the server deems the error to be fatal. This can be a password authentication failure or an internal error.
 - The retries happen immediately after a connection loss, if :ref:`db-channel-enabled` is set to true (the default). Otherwise they'll happen once a request arrives.
 - To ensure a valid state, the server reloads the :ref:`schema_cache` and :ref:`configuration` when recovering.
 - To notify the client of the next retry, the server sends a ``503 Service Unavailable`` status with the ``Retry-After: x`` header. Where ``x`` is the number of seconds programmed for the next retry.
 .. _external_connection_poolers:
 Using External Connection Poolers
 ---------------------------------
 It's possible to use external connection poolers, such as PgBouncer. Session pooling is compatible, while transaction pooling requires :ref:`db-prepared-statements` set to ``false``. Statement pooling is not compatible with PostgREST.
 Also set :ref:`db-channel-enabled` to ``false`` since ``LISTEN`` is not compatible with transaction pooling. Although it should not give any errors if left enabled.
 .. note::
  It’s not recommended to use an external connection pooler. `Our benchmarks <https://github.com/PostgREST/postgrest/issues/2294#issuecomment-1139148672>`_ indicate it provides much lower performance than PostgREST built-in pool.
@@ -0,0 +1,379 @@
 .. _error_source:
 Errors
 ######
 PostgREST error messages follow the PostgreSQL error structure. It includes ``MESSAGE``, ``DETAIL``, ``HINT``, ``ERRCODE`` and will add an HTTP status code to the response.
 Errors from PostgreSQL
 ======================
 PostgREST will forward errors coming from PostgreSQL. For instance, when querying a nonexistent table:
 .. code-block:: http
  GET /nonexistent_table?id=eq.1 HTTP/1.1
 .. code-block:: http
  HTTP/1.1 404 Not Found
  Content-Type: application/json; charset=utf-8
 .. code-block:: json
  {
    "hint": null,
    "details": null,
    "code": "42P01",
    "message": "relation \"api.nonexistent_table\" does not exist"
  }
 .. _status_codes:
 HTTP Status Codes
 -----------------
 PostgREST translates `PostgreSQL error codes <https://www.postgresql.org/docs/current/errcodes-appendix.html>`_ into HTTP status as follows:
 +--------------------------+-------------------------+---------------------------------+
 | PostgreSQL error code(s) | HTTP status             | Error description               |
 +==========================+=========================+=================================+
 | 08*                      | 503                     | pg connection err               |
 +--------------------------+-------------------------+---------------------------------+
 | 09*                      | 500                     | triggered action exception      |
 +--------------------------+-------------------------+---------------------------------+
 | 0L*                      | 403                     | invalid grantor                 |
 +--------------------------+-------------------------+---------------------------------+
 | 0P*                      | 403                     | invalid role specification      |
 +--------------------------+-------------------------+---------------------------------+
 | 23503                    | 409                     | foreign key violation           |
 +--------------------------+-------------------------+---------------------------------+
 | 23505                    | 409                     | uniqueness violation            |
 +--------------------------+-------------------------+---------------------------------+
 | 25006                    | 405                     | read only sql transaction       |
 +--------------------------+-------------------------+---------------------------------+
 | 25*                      | 500                     | invalid transaction state       |
 +--------------------------+-------------------------+---------------------------------+
 | 28*                      | 403                     | invalid auth specification      |
 +--------------------------+-------------------------+---------------------------------+
 | 2D*                      | 500                     | invalid transaction termination |
 +--------------------------+-------------------------+---------------------------------+
 | 38*                      | 500                     | external routine exception      |
 +--------------------------+-------------------------+---------------------------------+
 | 39*                      | 500                     | external routine invocation     |
 +--------------------------+-------------------------+---------------------------------+
 | 3B*                      | 500                     | savepoint exception             |
 +--------------------------+-------------------------+---------------------------------+
 | 40*                      | 500                     | transaction rollback            |
 +--------------------------+-------------------------+---------------------------------+
 | 53*                      | 503                     | insufficient resources          |
 +--------------------------+-------------------------+---------------------------------+
 | 54*                      | 413                     | too complex                     |
 +--------------------------+-------------------------+---------------------------------+
 | 55*                      | 500                     | obj not in prerequisite state   |
 +--------------------------+-------------------------+---------------------------------+
 | 57*                      | 500                     | operator intervention           |
 +--------------------------+-------------------------+---------------------------------+
 | 58*                      | 500                     | system error                    |
 +--------------------------+-------------------------+---------------------------------+
 | F0*                      | 500                     | config file error               |
 +--------------------------+-------------------------+---------------------------------+
 | HV*                      | 500                     | foreign data wrapper error      |
 +--------------------------+-------------------------+---------------------------------+
 | P0001                    | 400                     | default code for "raise"        |
 +--------------------------+-------------------------+---------------------------------+
 | P0*                      | 500                     | PL/pgSQL error                  |
 +--------------------------+-------------------------+---------------------------------+
 | XX*                      | 500                     | internal error                  |
 +--------------------------+-------------------------+---------------------------------+
 | 42883                    | 404                     | undefined function              |
 +--------------------------+-------------------------+---------------------------------+
 | 42P01                    | 404                     | undefined table                 |
 +--------------------------+-------------------------+---------------------------------+
 | 42501                    | | if authenticated 403, | insufficient privileges         |
 |                          | | else 401              |                                 |
 +--------------------------+-------------------------+---------------------------------+
 | other                    | 400                     |                                 |
 +--------------------------+-------------------------+---------------------------------+
 .. _raise_error:
 RAISE errors with HTTP Status Codes
 -----------------------------------
 You can return custom HTTP status codes by raising SQL exceptions inside :ref:`functions <s_procs>`. For instance, here's a saucy function that always responds with an error:
 .. code-block:: postgresql
  CREATE OR REPLACE FUNCTION just_fail() RETURNS void
    LANGUAGE plpgsql
    AS $$
  BEGIN
    RAISE EXCEPTION 'I refuse!'
      USING DETAIL = 'Pretty simple',
            HINT = 'There is nothing you can do.';
  END
  $$;
 Calling the function returns HTTP 400 with the body
 .. code-block:: json
  {
    "message":"I refuse!",
    "details":"Pretty simple",
    "hint":"There is nothing you can do.",
    "code":"P0001"
  }
 One way to customize the HTTP status code is by raising particular exceptions according to the PostgREST :ref:`error to status code mapping <status_codes>`. For example, :code:`RAISE insufficient_privilege` will respond with HTTP 401/403 as appropriate.
 For even greater control of the HTTP status code, raise an exception of the ``PTxyz`` type. For instance to respond with HTTP 402, raise ``PT402``:
 .. code-block:: sql
  RAISE sqlstate 'PT402' using
    message = 'Payment Required',
    detail = 'Quota exceeded',
    hint = 'Upgrade your plan';
 Returns:
 .. code-block:: http
  HTTP/1.1 402 Payment Required
  Content-Type: application/json; charset=utf-8
  {
    "message": "Payment Required",
    "details": "Quota exceeded",
    "hint": "Upgrade your plan",
    "code": "PT402"
  }
 Errors from PostgREST
 =====================
 Errors that come from PostgREST itself maintain the same structure. But differ in the ``PGRST`` prefix in the ``code`` field. For instance, when querying a function that does not exist in the :doc:`schema cache <schema_cache>`:
 .. code-block:: http
  POST /rpc/nonexistent_function HTTP/1.1
 .. code-block:: http
  HTTP/1.1 404 Not Found
  Content-Type: application/json; charset=utf-8
 .. code-block:: json
  {
    "hint": "...",
    "details": null
    "code": "PGRST202",
    "message": "Could not find the api.nonexistent_function() function in the schema cache"
  }
 .. _pgrst_errors:
 PostgREST Error Codes
 ---------------------
 PostgREST error codes have the form ``PGRSTgxx``
 - ``PGRST`` is the prefix that differentiates the error from a PostgreSQL error.
 - ``g`` is the error group
 - ``xx`` is the error identifier in the group.
 .. _pgrst0**:
 Group 0 - Connection
 ~~~~~~~~~~~~~~~~~~~~
 Related to the connection with the database.
 +---------------+-------------+-------------------------------------------------------------+
 | Code          | HTTP status | Description                                                 |
 +===============+=============+=============================================================+
 | .. _pgrst000: | 503         | Could not connect with the database due to an incorrect     |
 |               |             | :ref:`db-uri` or due to the PostgreSQL service not running. |
 | PGRST000      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst001: | 503         | Could not connect with the database due to an internal      |
 |               |             | error.                                                      |
 | PGRST001      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst002: | 503         | Could not connect with the database when building the       |
 |               |             | :doc:`Schema Cache <schema_cache>`                          |
 | PGRST002      |             | due to the PostgreSQL service not running.                  |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst003: | 504         | The request timed out waiting for a pool connection         |
 |               |             | to be available. See :ref:`db-pool-acquisition-timeout`.    |
 | PGRST003      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 .. _pgrst1**:
 Group 1 - Api Request
 ~~~~~~~~~~~~~~~~~~~~~
 Related to the HTTP request elements.
 +---------------+-------------+-------------------------------------------------------------+
 | Code          | HTTP status | Description                                                 |
 +===============+=============+=============================================================+
 | .. _pgrst100: | 400         | Parsing error in the query string parameter.                |
 |               |             | See :ref:`h_filter`, :ref:`operators` and :ref:`ordering`.  |
 | PGRST100      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst101: | 405         | For :ref:`functions <s_procs>`, only ``GET`` and ``POST``   |
 |               |             | verbs are allowed. Any other verb will throw this error.    |
 | PGRST101      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst102: | 400         | An invalid request body was sent(e.g. an empty body or      |
 |               |             | malformed JSON).                                            |
 | PGRST102      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst103: | 416         | An invalid range was specified for :ref:`limits`.           |
 |               |             |                                                             |
 | PGRST103      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst105: | 405         | An invalid :ref:`PUT <upsert_put>` request was done         |
 |               |             |                                                             |
 | PGRST105      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst106: | 406         | The schema specified when                                   |
 |               |             | :ref:`switching schemas <multiple-schemas>` is not present  |
 | PGRST106      |             | in the :ref:`db-schemas` configuration variable.            |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst107: | 415         | The ``Content-Type`` sent in the request is invalid.        |
 |               |             |                                                             |
 | PGRST107      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst108: | 400         | The filter is applied to a embedded resource that is not    |
 |               |             | specified in the ``select`` part of the query string.       |
 | PGRST108      |             | See :ref:`embed_filters`.                                   |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst109: | 400         | Restricting a Deletion or an Update using limits must       |
 |               |             | include the ordering of a unique column.                    |
 | PGRST109      |             | See :ref:`limited_update_delete`.                           |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst110: | 400         | When restricting a Deletion or an Update using limits       |
 |               |             | modifies more rows than the maximum specified in the limit. |
 | PGRST110      |             | See :ref:`limited_update_delete`.                           |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst111: | 500         | An invalid ``response.headers`` was set.                    |
 |               |             | See :ref:`guc_resp_hdrs`.                                   |
 | PGRST111      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst112: | 500         | The status code must be a positive integer.                 |
 |               |             | See :ref:`guc_resp_status`.                                 |
 | PGRST112      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst113: | 406         | More than one column was returned for a scalar result.      |
 |               |             | See :ref:`scalar_return_formats`.                           |
 | PGRST113      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst114: | 400         | For an :ref:`UPSERT using PUT <upsert_put>`, when           |
 |               |             | :ref:`limits and offsets <limits>` are used.                |
 | PGRST114      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst115: | 400         | For an :ref:`UPSERT using PUT <upsert_put>`, when the       |
 |               |             | primary key in the query string and the body are different. |
 | PGRST115      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst116: | 406         | More than 1 or no items where returned when requesting      |
 |               |             | a singular response. See :ref:`singular_plural`.            |
 | PGRST116      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst117: | 405         | The HTTP verb used in the request in not supported.         |
 |               |             |                                                             |
 | PGRST117      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst118: | 400         | Could not order the result using the related table because  |
 |               |             | there is no many-to-one or one-to-one relationship between  |
 | PGRST118      |             | them.                                                       |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst119: | 400         | Could not use the spread operator on the related table      |
 |               |             | because there is no many-to-one or one-to-one relationship  |
 | PGRST119      |             | between them.                                               |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst120: | 400         | An embedded resource can only be filtered using the         |
 |               |             | ``is.null`` or ``not.is.null`` :ref:`operators <operators>`.|
 | PGRST120      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 .. _pgrst2**:
 Group 2 - Schema Cache
 ~~~~~~~~~~~~~~~~~~~~~~
 Related to a :ref:`stale schema cache <stale_schema>`. Most of the time, these errors are solved by :ref:`reloading the schema cache <schema_reloading>`.
 +---------------+-------------+-------------------------------------------------------------+
 | Code          | HTTP status | Description                                                 |
 +===============+=============+=============================================================+
 | .. _pgrst200: | 400         | Caused by stale foreign key relationships, otherwise any of |
 |               |             | the embedding resources or the relationship itself may not  |
 | PGRST200      |             | exist in the database.                                      |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst201: | 300         | An ambiguous embedding request was made.                    |
 |               |             | See :ref:`complex_rels`.                                    |
 | PGRST201      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst202: | 404         | Caused by a stale function signature, otherwise             |
 |               |             | the function may not exist in the database.                 |
 | PGRST202      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst203: | 300         | Caused by requesting overloaded functions with the same     |
 |               |             | argument names but different types, or by using a ``POST``  |
 | PGRST203      |             | verb to request overloaded functions with a ``JSON`` or     |
 |               |             | ``JSONB`` type unnamed parameter. The solution is to rename |
 |               |             | the function or add/modify the names of the arguments.      |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst204: | 400         | Caused when the :ref:`column specified <specify_columns>`   |
 |               |             | in the ``columns`` query parameter is not found.            |
 | PGRST204      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 .. _pgrst3**:
 Group 3 - JWT
 ~~~~~~~~~~~~~
 Related to the authentication process using JWT. You can follow the :ref:`tut1` for an example on how to implement authentication and the :doc:`Authentication page <auth>` for more information on this process.
 +---------------+-------------+-------------------------------------------------------------+
 | Code          | HTTP status | Description                                                 |
 +===============+=============+=============================================================+
 | .. _pgrst300: | 500         | A :ref:`JWT secret <jwt-secret>` is missing from the        |
 |               |             | configuration.                                              |
 | PGRST300      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst301: | 401         | Any error related to the verification of the JWT,           |
 |               |             | which means that the JWT provided is invalid in some way.   |
 | PGRST301      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
 | .. _pgrst302: | 401         | Attempted to do a request without                           |
 |               |             | :ref:`authentication <client_auth>` when the anonymous role |
 | PGRST302      |             | is disabled by not setting it in :ref:`db-anon-role`.       |
 +---------------+-------------+-------------------------------------------------------------+
 .. The Internal Errors Group X** is always at the end
 .. _pgrst_X**:
 Group X - Internal
 ~~~~~~~~~~~~~~~~~~
 Internal errors. If you encounter any of these, you may have stumbled on a PostgREST bug, please `open an issue <https://github.com/PostgREST/postgrest/issues>`_ and we'll be glad to fix it.
 +---------------+-------------+-------------------------------------------------------------+
 | Code          | HTTP status | Description                                                 |
 +===============+=============+=============================================================+
 | .. _pgrstX00: | 500         | Internal errors related to the library used for connecting  |
 |               |             | to the database.                                            |
 | PGRSTX00      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
@@ -0,0 +1,173 @@
 .. _schema_cache:
 Schema Cache
 ============
 Some PostgREST features need metadata from the database schema. Getting this metadata requires expensive queries. To avoid repeating this work, PostgREST uses a schema cache.
 +--------------------------------------------+-------------------------------------------------------------------------------+
 | Feature                                    | Required Metadata                                                             |
 +============================================+===============================================================================+
 | :ref:`resource_embedding`                  | Foreign key constraints                                                       |
 +--------------------------------------------+-------------------------------------------------------------------------------+
 | :ref:`Stored Functions <s_procs>`          | Function signature (parameters, return type, volatility and                   |
 |                                            | `overloading <https://www.postgresql.org/docs/current/xfunc-overload.html>`_) |
 +--------------------------------------------+-------------------------------------------------------------------------------+
 | :ref:`Upserts <upsert>`                    | Primary keys                                                                  |
 +--------------------------------------------+-------------------------------------------------------------------------------+
 | :ref:`Insertions <insert>`                 | Primary keys (optional: only if the Location header is requested)             |
 +--------------------------------------------+-------------------------------------------------------------------------------+
 | :ref:`OPTIONS requests <options_requests>` | View INSTEAD OF TRIGGERS and primary keys                                     |
 +--------------------------------------------+-------------------------------------------------------------------------------+
 | :ref:`open-api`                            | Table columns, primary keys and foreign keys                                  |
 +                                            +-------------------------------------------------------------------------------+
 |                                            | View columns and INSTEAD OF TRIGGERS                                          |
 +                                            +-------------------------------------------------------------------------------+
 |                                            | Function signature                                                            |
 +--------------------------------------------+-------------------------------------------------------------------------------+
 .. _stale_schema:
 Stale Schema Cache
 ------------------
 One operational problem that comes a cache is that it can go stale. This can happen for PostgREST when you make changes to the metadata before mentioned. Requests that depend on the metadata will fail.
 You can solve this by reloading the cache manually or automatically.
 .. _schema_reloading:
 Schema Cache Reloading
 ----------------------
 To manually reload the cache without restarting the PostgREST server, send a SIGUSR1 signal to the server process.
 .. code:: bash
  killall -SIGUSR1 postgrest
 For docker you can do:
 .. code:: bash
  docker kill -s SIGUSR1 <container>
  # or in docker-compose
  docker-compose kill -s SIGUSR1 <service>
 There’s no downtime when reloading the schema cache. The reloading will happen on a background thread while serving requests.
 .. _schema_reloading_notify:
 Reloading with NOTIFY
 ~~~~~~~~~~~~~~~~~~~~~
 PostgREST also allows you to reload its schema cache through PostgreSQL `NOTIFY <https://www.postgresql.org/docs/current/sql-notify.html>`_.
 .. code-block:: postgresql
  NOTIFY pgrst, 'reload schema'
 This is useful in environments where you can’t send the SIGUSR1 Unix Signal. Like on cloud managed containers or on Windows systems.
 The ``pgrst`` notification channel is enabled by default. For configuring the channel, see :ref:`db-channel` and :ref:`db-channel-enabled`.
 .. _auto_schema_reloading:
 Automatic Schema Cache Reloading
 --------------------------------
 You can do automatic schema cache reloading in a pure SQL way and forget about stale schema cache errors. For this use an `event trigger <https://www.postgresql.org/docs/current/event-trigger-definition.html>`_ and ``NOTIFY``.
 .. code-block:: postgresql
  -- Create an event trigger function
  CREATE OR REPLACE FUNCTION pgrst_watch() RETURNS event_trigger
    LANGUAGE plpgsql
    AS $$
  BEGIN
    NOTIFY pgrst, 'reload schema';
  END;
  $$;
  -- This event trigger will fire after every ddl_command_end event
  CREATE EVENT TRIGGER pgrst_watch
    ON ddl_command_end
    EXECUTE PROCEDURE pgrst_watch();
 Now, whenever the ``pgrst_watch`` trigger fires, PostgREST will auto-reload the schema cache.
 To disable auto reloading, drop the trigger.
 .. code-block:: postgresql
  DROP EVENT TRIGGER pgrst_watch
 Finer-Grained Event Trigger
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 You can refine the previous event trigger to only react to the events relevant to the schema cache. This also prevents unnecessary
 reloading when creating temporary tables inside functions.
 .. code-block:: postgresql
  -- watch CREATE and ALTER
  CREATE OR REPLACE FUNCTION pgrst_ddl_watch() RETURNS event_trigger AS $$
  DECLARE
    cmd record;
  BEGIN
    FOR cmd IN SELECT * FROM pg_event_trigger_ddl_commands()
    LOOP
      IF cmd.command_tag IN (
        'CREATE SCHEMA', 'ALTER SCHEMA'
      , 'CREATE TABLE', 'CREATE TABLE AS', 'SELECT INTO', 'ALTER TABLE'
      , 'CREATE FOREIGN TABLE', 'ALTER FOREIGN TABLE'
      , 'CREATE VIEW', 'ALTER VIEW'
      , 'CREATE MATERIALIZED VIEW', 'ALTER MATERIALIZED VIEW'
      , 'CREATE FUNCTION', 'ALTER FUNCTION'
      , 'CREATE TRIGGER'
      , 'CREATE TYPE', 'ALTER TYPE'
      , 'CREATE RULE'
      , 'COMMENT'
      )
      -- don't notify in case of CREATE TEMP table or other objects created on pg_temp
      AND cmd.schema_name is distinct from 'pg_temp'
      THEN
        NOTIFY pgrst, 'reload schema';
      END IF;
    END LOOP;
  END; $$ LANGUAGE plpgsql;
  -- watch DROP
  CREATE OR REPLACE FUNCTION pgrst_drop_watch() RETURNS event_trigger AS $$
  DECLARE
    obj record;
  BEGIN
    FOR obj IN SELECT * FROM pg_event_trigger_dropped_objects()
    LOOP
      IF obj.object_type IN (
        'schema'
      , 'table'
      , 'foreign table'
      , 'view'
      , 'materialized view'
      , 'function'
      , 'trigger'
      , 'type'
      , 'rule'
      )
      AND obj.is_temporary IS false -- no pg_temp objects
      THEN
        NOTIFY pgrst, 'reload schema';
      END IF;
    END LOOP;
  END; $$ LANGUAGE plpgsql;
  CREATE EVENT TRIGGER pgrst_ddl_watch
    ON ddl_command_end
    EXECUTE PROCEDURE pgrst_ddl_watch();
  CREATE EVENT TRIGGER pgrst_drop_watch
    ON sql_drop
    EXECUTE PROCEDURE pgrst_drop_watch();
@@ -0,0 +1,327 @@
 .. _transactions:
 Transactions
 ============
 After :ref:`user_impersonation`, every request to an :doc:`API resource <api>` runs inside a transaction. The sequence of the transaction is as follows:
 .. code-block:: postgresql
  BEGIN; -- <Access Mode> <Isolation Level>
  -- <Transaction-scoped settings>
  -- <Main Query>;
  END;
 .. _access_mode:
 Access Mode
 -----------
 The access mode on :ref:`tables_views` is determined by the HTTP method.
 .. list-table::
   :header-rows: 1
   * - HTTP Method
     - Access Mode
   * - GET, HEAD
     - READ ONLY
   * - POST, PATCH, PUT, DELETE
     - READ WRITE
 :ref:`s_procs` additionally depend on the function `volatility <https://www.postgresql.org/docs/current/xfunc-volatility.html>`_.
 .. list-table::
   :header-rows: 2
   * -
     - Access Mode
     -
     -
   * - HTTP Method
     - VOLATILE
     - STABLE
     - IMMUTABLE
   * - GET, HEAD
     - READ ONLY
     - READ ONLY
     - READ ONLY
   * - POST
     - READ WRITE
     - READ ONLY
     - READ ONLY
 Modifying the database inside READ ONLY transactions is not possible. PostgREST uses this fact to enforce HTTP semantics in GET and HEAD requests.
 .. note::
  The volatility marker is a promise about the behavior of the function.  PostgreSQL will let you mark a function that modifies the database as ``IMMUTABLE`` or ``STABLE`` without failure.  But, because of the READ ONLY transaction the function will fail under PostgREST.
 The :ref:`options_requests` method doesn't start a transaction, so it's not relevant here.
 .. _isolation_lvl:
 Isolation Level
 ---------------
 Every transaction uses the PostgreSQL default isolation level: READ COMMITTED. Unless you modify `default_transaction_isolation <https://www.postgresql.org/docs/15/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-ISOLATION>`_  for an impersonated role or function.
 Using :ref:`impersonated_settings`, change the isolation level for all the role's requests with:
 .. code-block:: postgresql
  ALTER ROLE webuser SET default_transaction_isolation TO 'repeatable read';
 Or to change the isolation level per function call.
 .. code-block:: postgresql
  CREATE OR REPLACE FUNCTION myfunc()
  RETURNS text as $$
    SELECT 'hello';
  $$
  LANGUAGE SQL
  SET default_transaction_isolation TO 'serializable';
 .. _tx_settings:
 Transaction-Scoped Settings
 ---------------------------
 PostgREST uses settings tied to the transaction lifetime. These can be used to get data about the HTTP request. Or to modify the HTTP response.
 You can get these with ``current_setting``
 .. code-block:: postgresql
  -- request settings use the ``request.`` prefix.
  SELECT
    current_setting('request.<setting>', true);
 And you can set them with ``set_config``
 .. code-block:: postgresql
  -- response settings use the ``response.`` prefix.
  SELECT
    set_config('response.<setting>', 'value1' ,true);
 .. _guc_req_headers_cookies_claims:
 Request Headers, Cookies and JWT claims
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 PostgREST stores the headers, cookies and headers as JSON. To get them:
 .. important::
  The headers names are lowercased. e.g. If the request sends ``User-Agent: x`` this will be obtainable as ``current_setting('request.headers', true)::json->>'user-agent'``.
 .. code-block:: postgresql
  -- To get all the headers sent in the request
  SELECT current_setting('request.headers', true)::json;
  -- To get a single header, you can use JSON arrow operators
  SELECT current_setting('request.headers', true)::json->>'user-agent';
  -- value of sessionId in a cookie
  SELECT current_setting('request.cookies', true)::json->>'sessionId';
  -- value of the email claim in a jwt
  SELECT current_setting('request.jwt.claims', true)::json->>'email';
 .. note::
  The ``role`` in ``request.jwt.claims`` defaults to the value of :ref:`db-anon-role`.
 .. _guc_legacy_names:
 Legacy settings
 ^^^^^^^^^^^^^^^
 For PostgreSQL versions below 14, PostgREST will take into consideration the :ref:`db-use-legacy-gucs` config, which is set to true by default.
 This means that the interface for accessing these GUCs is the same as in older versions (see below).
 You can opt in to use the JSON GUCs mentioned above by setting the ``db-use-legacy-gucs`` to false.
 .. raw:: html
  <p>
    <details>
      <summary>Old GUCs</summary>
 .. code-block:: postgresql
  -- To read the value of the User-Agent request header:
  SELECT current_setting('request.header.user-agent', true);
  -- To read the value of sessionId in a cookie:
  SELECT current_setting('request.cookie.sessionId', true);
  -- To read the value of the email claim in a jwt:
  SELECT current_setting('request.jwt.claim.email', true);
 .. note::
  ``request.jwt.claim.role`` defaults to the value of :ref:`db-anon-role`.
 .. raw:: html
    </details>
  </p>
 .. _guc_req_path_method:
 Request Path and Method
 ~~~~~~~~~~~~~~~~~~~~~~~
 The path and method are stored as ``text``.
 .. code-block:: postgresql
  SELECT current_setting('request.path', true);
  SELECT current_setting('request.method', true);
 Request Role and Search Path
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Because of :ref:`user_impersonation`, PostgREST sets the standard ``role``. You can get this in different ways:
 .. code-block:: postgresql
  SELECT current_role;
  SELECT current_user;
  SELECT current_setting('role', true);
 Additionally it also sets the ``search_path`` based on :ref:`db-schemas` and :ref:`db-extra-search-path`.
 .. _guc_resp_hdrs:
 Response Headers
 ~~~~~~~~~~~~~~~~
 You can set ``response.headers`` to add headers to the HTTP response. For instance, this statement would add caching headers to the response:
 .. code-block:: sql
  -- tell client to cache response for two days
  SELECT set_config('response.headers',
    '[{"Cache-Control": "public"}, {"Cache-Control": "max-age=259200"}]', true);
 .. code-block:: http
  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
  Cache-Control: no-cache, no-store, must-revalidate
 Notice that the ``response.headers`` should be set to an *array* of single-key objects rather than a single multiple-key object. This is because headers such as ``Cache-Control`` or ``Set-Cookie`` need repeating when setting many values. An object would not allow the repeated key.
 .. note::
  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 also set :ref:`raw-media-types` to something like ``text/html``.
 .. _guc_resp_status:
 Response Status Code
 ~~~~~~~~~~~~~~~~~~~~
 You can set the ``response.status`` to override the default status code PostgREST provides. For instance, the following function would replace the default ``200`` status code.
 .. code-block:: postgres
   create or replace function teapot() returns json as $$
   begin
     perform set_config('response.status', '418', true);
     return json_build_object('message', 'The requested entity body is short and stout.',
                              'hint', 'Tip it over and pour it out.');
   end;
   $$ language plpgsql;
 .. tabs::
  .. code-tab:: http
    GET /rpc/teapot HTTP/1.1
  .. code-tab:: bash Curl
    curl "http://localhost:3000/rpc/teapot" -i
 .. code-block:: http
  HTTP/1.1 418 I'm a teapot
  {
    "message" : "The requested entity body is short and stout.",
    "hint" : "Tip it over and pour it out."
  }
 If the status code is standard, PostgREST will complete the status message(**I'm a teapot** in this example).
 .. _main_query:
 Main query
 ----------
 The main query is generated by requesting :ref:`tables_views` or :ref:`s_procs`. All generated queries use prepared statements(:ref:`db-prepared-statements`).
 Transaction End
 ---------------
 If the transaction doesn't fail, it will always end in a COMMIT. Unless :ref:`db-tx-end` is configured to ROLLBACK in any case or conditionally with ``Prefer: tx=rollback``. This can be used for testing purposes.
 Aborting transactions
 ---------------------
 Any database failure(like a failed constraint) will result in a rollback of the transaction. You can also :ref:`RAISE an error inside a function <raise_error>` to cause a rollback.
 .. _pre-request:
 Pre-Request
 -----------
 The pre-request is a function that can run after the :ref:`tx_settings` are set and before the :ref:`main_query`. It's enabled with :ref:`db-pre-request`.
 This provides an opportunity to modify settings or raise an exception to prevent the request from completing.
 .. _pre_req_headers:
 Setting headers via pre-request
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 As an example, let's add some cache headers for all requests that come from an Internet Explorer(6 or 7) browser.
 .. code-block:: postgresql
   create or replace function custom_headers()
   returns void as $$
   declare
     user_agent text := current_setting('request.headers', true)::json->>'user-agent';
   begin
     if user_agent similar to '%MSIE (6.0|7.0)%' then
       perform set_config('response.headers',
         '[{"Cache-Control": "no-cache, no-store, must-revalidate"}]', false);
     end if;
   end; $$ language plpgsql;
   -- set this function on postgrest.conf
   -- db-pre-request = custom_headers
 Now when you make a GET request to a table or view, you'll get the cache headers.
 .. tabs::
  .. code-tab:: http
    GET /people HTTP/1.1
    User-Agent: Mozilla/4.01 (compatible; MSIE 6.0; Windows NT 5.1)
  .. code-tab:: bash Curl
    curl "http://localhost:3000/people" -i \
     -H "User-Agent: Mozilla/4.01 (compatible; MSIE 6.0; Windows NT 5.1)"
@@ -0,0 +1,130 @@
 9.0.0
 =====
 This major version is released with PostgreSQL 14 compatibility and is accompanied with new features and bug fixes. You can look at the detailed changelog and download the pre-compiled binaries on the `GitHub release page <https://github.com/PostgREST/postgrest/releases/tag/v9.0.0>`_.
 Features
 --------
 PostgreSQL 14 compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 PostgreSQL 14 Beta 1 tightened its GUC naming scheme making it impossible to use multiple dots (``.``) and dashes (``-``) on custom GUC parameters, this caused our :ref:`old HTTP Context <guc_legacy_names>` to fail across all requests. Thankfully, `@robertsosinski <https://github.com/robertsosinski>`_ got the PostgreSQL team to reconsider allowing multiple dots in the GUC name, allowing us to avoid a major breaking change. You can see the full discussion `here <https://www.postgresql.org/message-id/17045-6a4a9f0d1513f72b%40postgresql.org>`_.
 Still, dashes cannot be used on PostgreSQL 14 custom GUC parameters, so we changed our HTTP Context :ref:`to namespace using a mix of dots and JSON <guc_req_headers_cookies_claims>`. On older PostgreSQL versions we still use the settings legacy names. If you wish to use the new JSON GUCs on these versions, set the :ref:`db-use-legacy-gucs` config option to false.
 Resource Embedding with Top-level Filtering
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Historically, Resource Embedding was always done with a query that included the equivalent of a ``LEFT JOIN``, which meant you could not
 exclude any of the top-level resource rows. You can now use :ref:`embedding_top_level_filter` to do the equivalent of an ``INNER JOIN``, thus you can filter the top-level resource rows with any of the available operators.
 Partitioned Tables
 ~~~~~~~~~~~~~~~~~~
 Partitioned tables now integrate with all the feature set. You can :ref:`embed partitioned tables <embedding_partitioned_tables>`, UPSERT, INSERT(with a correctly generated Location header) and make OPTIONS requests on them. They're also included in the generated OpenAPI.
 Functions(RPC)
 ~~~~~~~~~~~~~~
 * Functions with a :ref:`single unnamed parameter <s_proc_single_unnamed>` can now be used to POST raw ``bytea``, ``text`` or ``json/jsonb``.
 Horizontal Filtering
 ~~~~~~~~~~~~~~~~~~~~
 * The ``unknown`` value for three-valued logic can now be used on the ``is`` :ref:`operator <operators>`.
 * Escaping double quotes(``"``) in double-quoted surrounded strings is now possible by using backslashes, e.g. ``?col=in.("Double\"Quote")``. Backslashes can be escaped with a preceding backslash, e.g. ``?col=in.("Back\\slash")``. See :ref:`reserved-chars`.
 Administration
 ~~~~~~~~~~~~~~
 * A ``Retry-After`` header is now added when PostgREST is doing :ref:`automatic_recovery`.
 Error messages
 ~~~~~~~~~~~~~~
 * :ref:`embed_disamb` now shows an improved error message that includes relevant hints for clearing out the ambiguous embedding.
 Documentation improvements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 * Added ``curl`` snippets to the :ref:`api` page.
 * Added the :ref:`automatic_recovery` section.
 * Added the :ref:`nested_embedding` section.
 * Added the :ref:`logical_operators` section.
 * Added the :ref:`templates` and :ref:`devops` sections to the :doc:`Ecosystem </ecosystem>`.
 Bug fixes
 ---------
 * Correct RPC return type handling for RETURNS TABLE with a single column (`#1930 <https://github.com/PostgREST/postgrest/issues/1930>`_).
 * Schema Cache query failing with ``standard_conforming_strings = off`` (`#1992 <https://github.com/PostgREST/postgrest/issues/1992>`_).
 * OpenAPI missing default values for String types (`#1871 <https://github.com/PostgREST/postgrest/issues/1871>`_).
 Breaking changes
 ----------------
 * Dropped support for PostgreSQL 9.5 as it already reached its end-of-life according to `PostgreSQL versioning policy <https://www.postgresql.org/support/versioning/>`_.
 * Partitions of a `partitioned table <https://www.postgresql.org/docs/current/ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE>`_ are no longer included in the :ref:`schema_cache`. This is so errors are not generated when doing resource embedding on partitioned tables.
 * Dropped support for doing :ref:`hint_disamb` using dots instead of exclamation marks, e.g. doing ``select=*,projects.client_id(*)`` instead of ``select=*,projects!client_id(*)``). Using dots was undocumented and deprecated back in `v6.0.2 <https://github.com/PostgREST/postgrest/releases/tag/v6.0.2>`_.
 Thanks
 ------
 Big thanks from the `PostgREST team <https://github.com/orgs/PostgREST/people>`_ to our sponsors!
 .. container:: image-container
  .. image:: ../_static/cybertec-new.png
    :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest
    :width:  13em
  .. image:: ../_static/2ndquadrant.png
    :target: https://www.2ndquadrant.com/en/?utm_campaign=External%20Websites&utm_source=PostgREST&utm_medium=Logo
    :width:  13em
  .. image:: ../_static/retool.png
    :target: https://retool.com/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
  .. image:: ../_static/gnuhost.png
    :target: https://gnuhost.eu/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
  .. image:: ../_static/supabase.png
    :target: https://supabase.com/?utm_source=postgrest%20backers&utm_medium=open%20source%20partner&utm_campaign=postgrest%20backers%20github&utm_term=homepage
    :width:  13em
  .. image:: ../_static/oblivious.jpg
    :target: https://oblivious.ai/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
 * Evans Fernandes
 * Jan Sommer
 * `Franz Gusenbauer <https://www.igutech.at/>`_
 * `Daniel Babiak <https://github.com/dbabiak>`_
 * Tsingson Qin
 * Michel Pelletier
 * Jay Hannah
 * Robert Stolarz
 * Nicholas DiBiase
 * Christopher Reid
 * Nathan Bouscal
 * Daniel Rafaj
 * David Fenko
 * Remo Rechkemmer
 * Severin Ibarluzea
 * Tom Saleeba
 * Pawel Tyll
 If you like to join them please consider `supporting PostgREST development <https://github.com/PostgREST/postgrest#user-content-supporting-development>`_.
@@ -0,0 +1,89 @@
 9.0.1
 =====
 This version includes important fixes for production environments and other miscellaneous fixes. You can download the pre-compiled binaries on the `GitHub release page <https://github.com/PostgREST/postgrest/releases/tag/v9.0.1>`_.
 Bug Fixes
 ---------
 * Keep working when ``EMFILE (Too many open files)`` is reached. (`#2042 <https://github.com/PostgREST/postgrest/issues/2042>`_)
 * Disable parallel GC for better performance on higher core CPUs (`#2294 <https://github.com/PostgREST/postgrest/issues/2294>`_). Thanks to `NoRedInk for their blog post <https://blog.noredink.com/post/666654908557180928/tuning-haskell-rts-for-kubernetes-part-2>`_ that lead us to this fix.
 * Fix using CPU while idle. (`#1076 <https://github.com/PostgREST/postgrest/issues/1076>`_)
 * Fix reading database configuration properly when ``=`` is present in the value. (`#2120 <https://github.com/PostgREST/postgrest/issues/2120>`_)
 * Fix ``is`` not working with upper or mixed case values like ``NULL``, ``TrUe``, ``FaLsE``. (`#2077 <https://github.com/PostgREST/postgrest/issues/2077>`_)
 * Execute deferred constraint triggers when using ``Prefer: tx=rollback``. (`#2020 <https://github.com/PostgREST/postgrest/issues/2020>`_)
 * Ignore ``Content-Type`` headers for ``GET`` requests when calling RPCs. (`#2147 <https://github.com/PostgREST/postgrest/issues/2147>`_)
   * Previously, ``GET`` without parameters, but with ``Content-Type: text/plain`` or ``Content-Type: application/octet-stream`` would fail with ``404 Not Found``, even if a function without arguments was available.
 * Fix wrong CORS header from ``Authentication`` to ``Authorization``. (`#1724 <https://github.com/PostgREST/postgrest/issues/1724>`_)
 * Fix ``json`` and ``jsonb`` columns showing a type in OpenAPI spec. (`#2165 <https://github.com/PostgREST/postgrest/issues/2165>`_)
 * Remove trigger functions from the schema cache and OpenAPI output, because they can't be called directly anyway. (`#2135 <https://github.com/PostgREST/postgrest/issues/2135>`_)
 * Remove aggregates, procedures and window functions from the schema cache and OpenAPI output. (`#2101 <https://github.com/PostgREST/postgrest/issues/2101>`_)
 * Fix schema cache loading when views with ``XMLTABLE`` and ``DEFAULT`` are present. (`#2024 <https://github.com/PostgREST/postgrest/issues/2024>`_)
 * Fix ``--dump-schema`` running with a wrong PG version. (`#2153 <https://github.com/PostgREST/postgrest/issues/2153>`_)
 * Fix misleading disambiguation error where the content of the ``relationship`` key looks like valid syntax. (`#2239 <https://github.com/PostgREST/postgrest/issues/2239>`_)
 Thanks
 ------
 Big thanks from the `PostgREST team <https://github.com/orgs/PostgREST/people>`_ to our sponsors!
 .. container:: image-container
  .. image:: ../_static/cybertec-new.png
    :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest
    :width:  13em
  .. image:: ../_static/2ndquadrant.png
    :target: https://www.2ndquadrant.com/en/?utm_campaign=External%20Websites&utm_source=PostgREST&utm_medium=Logo
    :width:  13em
  .. image:: ../_static/retool.png
    :target: https://retool.com/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
  .. image:: ../_static/gnuhost.png
    :target: https://gnuhost.eu/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
  .. image:: ../_static/supabase.png
    :target: https://supabase.com/?utm_source=postgrest%20backers&utm_medium=open%20source%20partner&utm_campaign=postgrest%20backers%20github&utm_term=homepage
    :width:  13em
  .. image:: ../_static/oblivious.jpg
    :target: https://oblivious.ai/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
 * Evans Fernandes
 * Jan Sommer
 * `Franz Gusenbauer <https://www.igutech.at/>`_
 * `Daniel Babiak <https://github.com/dbabiak>`_
 * Tsingson Qin
 * Michel Pelletier
 * Jay Hannah
 * Robert Stolarz
 * Nicholas DiBiase
 * Christopher Reid
 * Nathan Bouscal
 * Daniel Rafaj
 * David Fenko
 * Remo Rechkemmer
 * Severin Ibarluzea
 * Tom Saleeba
 * Pawel Tyll
 If you like to join them please consider `supporting PostgREST development <https://github.com/PostgREST/postgrest#user-content-supporting-development>`_.
@@ -0,0 +1,227 @@
 10.0.0
 ======
 Features
 --------
 XML/SOAP support for RPC
 ~~~~~~~~~~~~~~~~~~~~~~~~
 RPC now understands the ``text/xml`` media type, allowing SQL functions to send XML output(``Accept: text/xml``) and receive XML input(``Content-Type: text/xml``). This makes SOAP endpoints possible, check the :ref:`create_soap_endpoint` how-to and the :ref:`scalar_return_formats` reference for more details.
 GeoJSON support
 ~~~~~~~~~~~~~~~
 GeoJSON is supported across the board(reads, writes, RPC) with the ``Accept: application/geo+json`` header, this depends on PostGIS from the versions 3.0.0 and up. The :ref:`working with PostGIS section <ww_postgis>` has an example to get you started.
 Execution Plan
 ~~~~~~~~~~~~~~
 The :ref:`execution plan <explain_plan>` of a request is now obtainable with the ``Accept: application/vnd.pgrst.plan`` header. The result can be in ``text`` or ``json`` formats and is compatible with EXPLAIN vizualizers like `explain.depesz.com <https://explain.depesz.com>`_ or `explain.dalibo.com <https://explain.dalibo.com>`_.
 Resource Embedding
 ~~~~~~~~~~~~~~~~~~
 - A :ref:`one-to-one relationship <one-to-one>` is now detected when a foreign key is unique.
 - Using :ref:`computed_relationships`, you can add custom relationships or override automatically detected ones. This makes :ref:`resource_embedding` possible on Foreign Data Wrappers and complex SQL views.
 Horizontal/Vertical Filtering
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - :ref:`Accessing fields of a Composite type or elements of an Array type <composite_array_columns>` is now possible with the arrow operators(``->``, ``->>``) in the same way you would access a JSON type fields.
 - :ref:`pattern_matching` operators for `POSIX regular expressions <https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-POSIX-REGEXP>`_ are now available: ``match`` and ``imatch``, equivalent in PostgreSQL to ``~`` and ``~*`` respectively.
 Insertions/Updates
 ~~~~~~~~~~~~~~~~~~
 - ``limit`` can now affect the number of updated/deleted rows. See :ref:`limited_update_delete`.
 OpenAPI
 ~~~~~~~
 You can now activate the "Authorize" button in SwaggerUI by enabling the :ref:`openapi-security-active` configuration. Add your JWT token prepending :code:`Bearer` to it and you'll be able to request protected resources.
 Administration
 ~~~~~~~~~~~~~~
 - Two :ref:`health check endpoints <health_check>` are now exposed in a secondary port.
 - :ref:`pgrst_logging` now shows the database user.
 - It is now possible to execute PostgREST without specifying any configuration variable. The three that were mandatory on the previous versions, are no longer so.
  - If :ref:`db-uri` is not set, PostgREST will use the `libpq environment variables <https://www.postgresql.org/docs/current/libpq-envars.html>`_ for the database connection.
  - If :ref:`db-schemas` is not set, it will use the database ``public`` schema.
  - If :ref:`db-anon-role` is not set, it will not allow anonymous requests.
 Error messages
 ~~~~~~~~~~~~~~
 - To increase consistency, all the errors messages are now normalized. The ``hint``, ``details``, ``code`` and ``message`` fields will always be present in the body, each one defaulting to a ``null`` value. In the same way, the :ref:`errors that were raised <raise_error>` with ``SQLSTATE`` now include the ``message`` and ``code`` in the body.
 - To further clarify the source of an error, we now add a ``PGRST`` prefix to the error code of all the errors that are PostgREST-specific and don't come from the database. These errors have unique codes that identify them and are documented in the :ref:`pgrst_errors` section.
 Documentation improvements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 * Added a :doc:`/how-tos/working-with-postgresql-data-types` how-to, which contains explanations and examples on how to work with different PostgreSQL data types such as timestamps, ranges or PostGIS types, among others.
 * Added in-database and environment variable settings for each :ref:`configuration variable <config_full_list>`.
 * Added the :ref:`file_descriptors` subsection.
 * Added a reference page for :ref:`error_source`.
 * Moved the :ref:`error_source` and the :ref:`status_codes` sections to the :ref:`errors reference page <error_source>`.
 * Moved the *Casting type to custom JSON* how-to to the :ref:`casting_range_to_json` subsection.
 * Removed direct links for PostgREST versions older than 8.0 from the versions menu.
 * Removed the *Embedding table from another schema* how-to.
 * Restructured the :ref:`resource_embedding` section:
  - Added a :ref:`one-to-many` and :ref:`many-to-one` subsections.
  - Renamed the *Embedding through join tables* subsection to :ref:`many-to-many`.
 * Split up the *Insertions/Updates* section into :ref:`insert` and :ref:`update`.
 Breaking changes
 ----------------
 * Many-to-many relationships now require that foreign key columns be part of the join table composite key
  - This was needed to reduce :ref:`embed_disamb` errors in complex schemas(`#2070 <https://github.com/PostgREST/postgrest/issues/2070>`_).
  - For migrating to this version, the less invasive method is to use :ref:`computed_relationships` to replace the previous many-to-many relationships.
  - Otherwise you can change your join table primary key. For example with ``alter table permission_user drop constraint permission_user_pkey, add primary key (id, user_id, permission_id);``
 * Views now are not detected when embedding using :ref:`target_disamb`.
  - This embedding form was easily made ambiguous whenever a new view was added(`#2277 <https://github.com/PostgREST/postgrest/issues/2277>`_).
  - For migrating to this version, you can use :ref:`computed_relationships` to replace the previous view relationships.
  - :ref:`hint_disamb` works as usual on views.
 * ``limit/offset`` now limits the affected rows on ``UPDATE``/``DELETE``
  - Previously, ``limit``/``offset`` only limited the returned rows but not the actual updated rows(`#2156 <https://github.com/PostgREST/postgrest/issues/2156>`_)
 * ``max-rows`` is no longer applied on ``POST``, ``PATCH``, ``PUT`` and ``DELETE`` returned rows
  - This was misleading because the affected rows were not really affected by ``max-rows``, only the returned rows were limited(`#2155 <https://github.com/PostgREST/postgrest/issues/2155>`_)
 * Return ``204 No Content`` without ``Content-Type`` for RPCs returning ``VOID``
  - Previously, those RPCs would return ``null`` as a body with ``Content-Type: application/json`` (`#2001 <https://github.com/PostgREST/postgrest/issues/2001>`_).
 * Using ``Prefer: return=representation`` no longer returns a ``Location`` header
  - This reduces unnecessary computing for all insertions (`#2312 <https://github.com/PostgREST/postgrest/issues/2312>`_)
 Bug fixes
 ---------
 * Return ``204 No Content`` without ``Content-Type`` for ``PUT`` (`#2058 <https://github.com/PostgREST/postgrest/issues/2058>`_)
 * Clarify error for failed schema cache load. (`#2107 <https://github.com/PostgREST/postgrest/issues/2107>`_)
  - From ``Database connection lost. Retrying the connection`` to ``Could not query the database for the schema cache. Retrying.``
 * Fix silently ignoring filter on a non-existent embedded resource (`#1771 <https://github.com/PostgREST/postgrest/issues/1771>`_)
 * Remove functions, which are not callable due to unnamed arguments, from schema cache and OpenAPI output. (`#2152 <https://github.com/PostgREST/postgrest/issues/2152>`_)
 * Fix accessing JSON array fields with ``->`` and ``->>`` in ``?select=`` and ``?order=``. (`#2145 <https://github.com/PostgREST/postgrest/issues/2145>`_)
 * Ignore ``max-rows`` on ``POST``, ``PATCH``, ``PUT`` and ``DELETE`` (`#2155 <https://github.com/PostgREST/postgrest/issues/2155>`_)
 * Fix inferring a foreign key column as a primary key column on views (`#2254 <https://github.com/PostgREST/postgrest/issues/2254>`_)
 * Restrict generated many-to-many relationships (`#2070 <https://github.com/PostgREST/postgrest/issues/2070>`_)
  - Only adds many-to-many relationships when a table has foreign keys to two other tables and these foreign key columns are part of the table's primary key columns.
 * Allow casting to types with underscores and numbers (e.g. ``select=oid_array::_int4``) (`#2278 <https://github.com/PostgREST/postgrest/issues/2278>`_)
 * Prevent views from breaking one-to-many/many-to-one embeds when using column or foreign key as target (`#2277 <https://github.com/PostgREST/postgrest/issues/2277>`_, `#2238 <https://github.com/PostgREST/postgrest/issues/2238>`_, `#1643 <https://github.com/PostgREST/postgrest/issues/1643>`_)
  - When using a column or foreign key as target for embedding (``/tbl?select=*,col-or-fk(*)``), only tables are now detected and views are not.
  - You can still use a column or an inferred foreign key on a view to embed a table (``/view?select=*,col-or-fk(*)``)
 * Increase the ``db-pool-timeout`` to 1 hour to prevent frequent high connection latency (`#2317 <https://github.com/PostgREST/postgrest/issues/2317>`_)
 * The search path now correctly identifies schemas with uppercase and special characters in their names (regression) (`#2341 <https://github.com/PostgREST/postgrest/issues/2341>`_)
 * "404 Not Found" on nested routes and "405 Method Not Allowed" errors no longer start an empty database transaction (`#2364 <https://github.com/PostgREST/postgrest/issues/2364>`_)
 * Fix inaccurate result count when an inner embed was selected after a normal embed in the query string (`#2342 <https://github.com/PostgREST/postgrest/issues/2342>`_)
 * ``OPTIONS`` requests no longer start an empty database transaction (`#2376 <https://github.com/PostgREST/postgrest/issues/2376>`_)
 * Allow using columns with dollar sign ($) without double quoting in filters and ``select`` (`#2395 <https://github.com/PostgREST/postgrest/issues/2395>`_)
 * Fix loop crash error on startup in PostgreSQL 15 beta 3. ``Log: "UNION types \"char\" and text cannot be matched."`` (`#2410 <https://github.com/PostgREST/postgrest/issues/2410>`_)
 * Fix race conditions managing database connection helper (`#2397 <https://github.com/PostgREST/postgrest/issues/2397>`_)
 * Allow ``limit=0`` in the request query to return an empty array (`#2269 <https://github.com/PostgREST/postgrest/issues/2269>`_)
 Thanks
 ------
 Big thanks from the `PostgREST team <https://github.com/orgs/PostgREST/people>`_ to our sponsors!
 .. container:: image-container
  .. image:: ../_static/cybertec-new.png
    :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest
    :width:  13em
  .. image:: ../_static/2ndquadrant.png
    :target: https://www.2ndquadrant.com/en/?utm_campaign=External%20Websites&utm_source=PostgREST&utm_medium=Logo
    :width:  13em
  .. image:: ../_static/retool.png
    :target: https://retool.com/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
  .. image:: ../_static/gnuhost.png
    :target: https://gnuhost.eu/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
  .. image:: ../_static/supabase.png
    :target: https://supabase.com/?utm_source=postgrest%20backers&utm_medium=open%20source%20partner&utm_campaign=postgrest%20backers%20github&utm_term=homepage
    :width:  13em
  .. image:: ../_static/oblivious.jpg
    :target: https://oblivious.ai/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
 * Evans Fernandes
 * Jan Sommer
 * `Franz Gusenbauer <https://www.igutech.at/>`_
 * `Daniel Babiak <https://github.com/dbabiak>`_
 * Tsingson Qin
 * Michel Pelletier
 * Jay Hannah
 * Robert Stolarz
 * Nicholas DiBiase
 * Christopher Reid
 * Nathan Bouscal
 * Daniel Rafaj
 * David Fenko
 * Remo Rechkemmer
 * Severin Ibarluzea
 * Tom Saleeba
 * Pawel Tyll
 If you like to join them please consider `supporting PostgREST development <https://github.com/PostgREST/postgrest#user-content-supporting-development>`_.
@@ -0,0 +1,153 @@
 10.2.0
 ======
 This minor version adds bug fixes and some features that provide stability to v10.0.0. These release notes include the changes added in versions `10.1.0 <https://github.com/PostgREST/postgrest/releases/tag/v10.1.0>`_, `10.1.1 <https://github.com/PostgREST/postgrest/releases/tag/v10.1.1>`_ and `10.1.2 <https://github.com/PostgREST/postgrest/releases/tag/v10.1.2>`_. You can look at the detailed changelog and download the pre-compiled binaries on the `GitHub release page <https://github.com/PostgREST/postgrest/releases/tag/v10.2.0>`_.
 Features
 --------
 Pool Connection Lifetime
 ~~~~~~~~~~~~~~~~~~~~~~~~
 To prevent memory leaks caused by long-lived connections, PostgREST limits their lifetime in the pool through :ref:`db-pool-max-lifetime`.
 Pool Connection Acquisition Timeout
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 There is now a time limit to wait for pool connections to be acquired. If a new request cannot get a connection in the time specified in :ref:`db-pool-acquisition-timeout` then a response with a ``504`` status is returned.
 Documentation improvements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 * Added HTTP status codes to the :ref:`pgrst_errors`.
 * Added a how-to on :ref:`sql-user-management-using-postgres-users-and-passwords`.
 * Updated the :ref:`Heroku installation page <deploy_heroku>`.
 Changes
 -------
 * Removed ``db-pool-timeout`` option because it was removed in the ``hasql-pool`` library that PostgREST uses for SQL connections. (`#2444 <https://github.com/PostgREST/postgrest/issues/2444>`_)
 Deprecated
 ----------
 * Deprecate bulk-calls when including the ``Prefer: params=multiple-objects`` in the request. It is preferable to use a function with an :ref:`array <s_procs_array>` or JSON parameter for a better performance. (`#1385 <https://github.com/PostgREST/postgrest/issues/1385>`_)
 Bug fixes
 ---------
 * Reduce allocations communication with PostgreSQL, particularly for request bodies. (`#2261 <https://github.com/PostgREST/postgrest/issues/2261>`_, `#2349 <https://github.com/PostgREST/postgrest/issues/2349>`_, `#2467 <https://github.com/PostgREST/postgrest/issues/2467>`_)
 * Fix ``SIGUSR1`` to fully flush the connection pool. (`#2401 <https://github.com/PostgREST/postgrest/issues/2401>`_, `#2444 <https://github.com/PostgREST/postgrest/issues/2444>`_)
 * Fix opening an empty transaction on failed resource embedding. (`#2428 <https://github.com/PostgREST/postgrest/issues/2428>`_)
 * Fix embedding the same table multiple times. (`#2455 <https://github.com/PostgREST/postgrest/issues/2455>`_)
 * Fix a regression when embedding views where base tables have a different column order for foreign key columns (`#2518 <https://github.com/PostgREST/postgrest/issues/2518>`_)
 * Fix a regression with the ``Location`` header when :ref:`inserting <insert>` into views with primary keys from multiple tables (`#2458 <https://github.com/PostgREST/postgrest/issues/2458>`_)
 * Fix a regression in OpenAPI output with mode ``follow-privileges`` (`#2356 <https://github.com/PostgREST/postgrest/issues/2356>`_)
 * Fix infinite recursion when loading schema cache with self-referencing view (`#2283 <https://github.com/PostgREST/postgrest/issues/2283>`_)
 * Return status code ``200`` instead of ``404`` for ``PATCH`` requests which don't affect any rows (`#2343 <https://github.com/PostgREST/postgrest/issues/2343>`_)
 * Treat the :ref:`computed relationships <computed_relationships>` that do not return ``SETOF`` as M2O/O2O relationship (`#2481 <https://github.com/PostgREST/postgrest/issues/2481>`_)
 * Fix embedding a computed relationship with a normal relationship (`#2534 <https://github.com/PostgREST/postgrest/issues/2534>`_)
 * Fix error message when ``[]`` is used inside ``select`` (`#2362 <https://github.com/PostgREST/postgrest/issues/2362>`_)
 * Disallow ``!inner`` on computed columns (`#2475 <https://github.com/PostgREST/postgrest/issues/2475>`_)
 * Ignore leading and trailing spaces in column names when parsing the query string (`#2285 <https://github.com/PostgREST/postgrest/issues/2285>`_)
 * Fix ``UPSERT`` with PostgreSQL 15 (`#2545 <https://github.com/PostgREST/postgrest/issues/2545>`_)
 * Fix embedding views with multiple references to the same base column (`#2459 <https://github.com/PostgREST/postgrest/issues/2459>`_)
 * Fix regression when embedding views with partial references to multi column foreign keys (`#2548 <https://github.com/PostgREST/postgrest/issues/2548>`_)
 * Fix regression when requesting ``limit=0`` and ``db-max-row`` is set (`#2558 <https://github.com/PostgREST/postgrest/issues/2558>`_)
 * Return a clear error without hitting the database when trying to update or insert an unknown column with ``?columns`` (`#2542 <https://github.com/PostgREST/postgrest/issues/2542>`_)
 * Fix bad M2M embedding on RPC (`#2565 <https://github.com/PostgREST/postgrest/issues/2565>`_)
 * Replace misleading error message when no function is found with a hint containing functions/parameters names suggestions (`#2575 <https://github.com/PostgREST/postgrest/issues/2575>`_)
 * Move explanation about "single parameters" from the ``message`` to the ``details`` in the error output (`#2582 <https://github.com/PostgREST/postgrest/issues/2582>`_)
 * Replace misleading error message when no relationship is found with a hint containing parent/child names suggestions (`#2569 <https://github.com/PostgREST/postgrest/issues/2569>`_)
 * Add the required OpenAPI items object when the parameter is an array (`#1405 <https://github.com/PostgREST/postgrest/issues/1405>`_)
 * Add upsert headers for ``POST`` requests to the OpenAPI output (`#2592 <https://github.com/PostgREST/postgrest/issues/2592>`_)
 * Fix foreign keys pointing to ``VIEW`` instead of ``TABLE`` in OpenAPI output (`#2623 <https://github.com/PostgREST/postgrest/issues/2623>`_)
 * Consider any PostgreSQL authentication failure as fatal and exit immediately (`#2622 <https://github.com/PostgREST/postgrest/issues/2622>`_)
 * Fix ``NOTIFY pgrst`` not reloading the db connections catalog cache (`#2620 <https://github.com/PostgREST/postgrest/issues/2620>`_)
 * Fix ``db-pool-acquisition-timeout`` not logging to stderr when the timeout is reached (`#2667 <https://github.com/PostgREST/postgrest/issues/2667>`_)
 * Fix PostgreSQL resource leak with long-lived connections through the :ref:`db-pool-max-lifetime` configuration (`#2638 <https://github.com/PostgREST/postgrest/issues/2638>`_)
 * There is now a stricter parsing of the query string. Instead of silently ignoring, the parser now returns a :ref:`PostgREST error <pgrst100>` on invalid syntax. (`#2537 <https://github.com/PostgREST/postgrest/issues/2537>`_)
 Thanks
 ------
 Big thanks from the `PostgREST team <https://github.com/orgs/PostgREST/people>`_ to our sponsors!
 .. container:: image-container
  .. image:: ../_static/cybertec-new.png
    :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest
    :width:  13em
  .. image:: ../_static/2ndquadrant.png
    :target: https://www.2ndquadrant.com/en/?utm_campaign=External%20Websites&utm_source=PostgREST&utm_medium=Logo
    :width:  13em
  .. image:: ../_static/retool.png
    :target: https://retool.com/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
  .. image:: ../_static/gnuhost.png
    :target: https://gnuhost.eu/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
  .. image:: ../_static/supabase.png
    :target: https://supabase.com/?utm_source=postgrest%20backers&utm_medium=open%20source%20partner&utm_campaign=postgrest%20backers%20github&utm_term=homepage
    :width:  13em
  .. image:: ../_static/oblivious.jpg
    :target: https://oblivious.ai/?utm_source=sponsor&utm_campaign=postgrest
    :width:  13em
 * Evans Fernandes
 * Jan Sommer
 * `Franz Gusenbauer <https://www.igutech.at/>`_
 * `Daniel Babiak <https://github.com/dbabiak>`_
 * Tsingson Qin
 * Michel Pelletier
 * Jay Hannah
 * Robert Stolarz
 * Nicholas DiBiase
 * Christopher Reid
 * Nathan Bouscal
 * Daniel Rafaj
 * David Fenko
 * Remo Rechkemmer
 * Severin Ibarluzea
 * Tom Saleeba
 * Pawel Tyll
 If you like to join them please consider `supporting PostgREST development <https://github.com/PostgREST/postgrest#user-content-supporting-development>`_.
--- a/Show More
+++ b/Show More
		`@@ -0,0 +1,3 @@`
							`This repository follows the same contribution guidelines as the main PostgREST repository contribution guidelines:`

							`https://github.com/PostgREST/postgrest/blob/main/.github/CONTRIBUTING.md`