[ { "path": ".cirrus.yml", "content": "freebsd_instance:\n image_family: freebsd-14-3\n\nbuild_task:\n # Don't change this name without adjusting .github/workflows/build.yaml\n name: Build FreeBSD (Stack)\n install_script: pkg install -y postgresql16-client hs-stack git\n\n only_if: |\n $CIRRUS_TAG != '' || $CIRRUS_BRANCH == 'main' || $CIRRUS_BRANCH =~ 'v*' ||\n changesInclude(\n '.github/workflows/build.yaml',\n '.github/actions/artifact-from-cirrus/**',\n '.cirrus.yml',\n 'postgrest.cabal',\n 'stack.yaml*',\n '**.hs'\n )\n\n stack_cache:\n folders: /.stack\n fingerprint_script:\n - echo $CIRRUS_OS\n - stack --version\n - md5sum postgrest.cabal\n - md5sum stack.yaml.lock\n\n stack_work_cache:\n folders: .stack-work\n fingerprint_script:\n - echo $CIRRUS_OS\n - stack --version\n - md5sum postgrest.cabal\n - md5sum stack.yaml.lock\n - find main src -type f -iname '*.hs' -exec md5sum \"{}\" +\n\n build_script: |\n stack build -j 1 --local-bin-path . --copy-bins\n strip postgrest\n\n bin_artifacts:\n path: postgrest\n" }, { "path": ".editorconfig", "content": "root = true\n\n[*]\ncharset = utf-8\nend_of_line = lf\nindent_size = 2\nindent_style = space\ninsert_final_newline = true\ntrim_trailing_whitespace = true\n" }, { "path": ".gitattributes", "content": "/CHANGELOG.md merge=union\n" }, { "path": ".github/FUNDING.yml", "content": "# These are supported funding model platforms\n\npatreon: postgrest\n" }, { "path": ".github/ISSUE_TEMPLATE/bug_report.md", "content": "---\nname: Bug report\nabout: Create a bug report to help us improve\ntype: Bug\ntitle: ''\nlabels: ''\nassignees: ''\n\n---\n\n\n### Environment\n\n* PostgreSQL version: (if using docker, specify the image)\n* PostgREST version: (if using docker, specify the image)\n* Operating system:\n\n### Description of issue\n\nDescribe the behavior you expected vs the actual behavior. Include:\n\n- A minimal SQL definition.\n- How you make the request to PostgREST (curl command preferred).\n- The PostgREST response.\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: false\n" }, { "path": ".github/ISSUE_TEMPLATE/feature_request.md", "content": "---\nname: Feature request\nabout: Suggest an enhancement for this project\ntype: Feature\ntitle: ''\nlabels: ''\nassignees: ''\n\n---\n\n## Problem\n\nA clear and concise description of what the problem is.\n\n## Solution\n\nA clear and concise description of what you want to happen.\n" }, { "path": ".github/PULL_REQUEST_TEMPLATE.md", "content": "\n" }, { "path": ".github/actionlint.yml", "content": "# TODO: Remove this once a new actionlint release has been cut\n# and made its way to us through nixpkgs.\nself-hosted-runner:\n labels:\n - ubuntu-24.04-arm\n" }, { "path": ".github/actions/artifact-from-cirrus/action.yaml", "content": "name: Artifact from Cirrus\n\ndescription: Waits for a specific Cirrus CI run to complete, then downloads the artifact and uploads it to the current workflow. This will silently succeed if Cirrus CI did not schedule a task within 2 minutes.\n\ninputs:\n download:\n description: Name of Artifact to download from Cirrus CI\n required: true\n task:\n description: Name of Cirrus Task\n required: true\n token:\n description: GitHub Token\n required: true\n upload:\n description: Name of Artifact to upload on GitHub Actions\n required: true\n\nruns:\n using: composite\n steps:\n - shell: bash\n run: echo \"GH_TOKEN=${{ inputs.token }}\" >> \"$GITHUB_ENV\"\n - name: Wait for Check Suite to be created\n id: check-suite\n env:\n # GITHUB_SHA does weird things for pull request, so we roll our own:\n COMMIT: ${{ github.event.pull_request.head.sha || github.sha }}\n shell: bash\n run: |\n get_check_runs_url() {\n gh api \"repos/{owner}/{repo}/commits/${COMMIT}/check-suites\" \\\n | jq -r '.check_suites[] | select(.app.slug == \"cirrus-ci\") | .check_runs_url'\n }\n for _ in $(seq 1 12); do\n check_runs_url=\"$(get_check_runs_url)\"\n if [ -z \"$check_runs_url\" ]; then\n echo \"Cirrus CI task has not started, yet. Waiting...\"\n sleep 10\n else\n echo \"check_runs_url=$check_runs_url\" >> \"$GITHUB_OUTPUT\"\n exit 0\n fi\n done\n >&2 echo \"Cirrus CI check suite not found. Is Cirrus CI enabled for this repo?\"\n - name: Find task by name\n id: find-task\n if: steps.check-suite.outputs.check_runs_url\n shell: bash\n run: |\n get_number_of_tasks() {\n gh api \"${{ steps.check-suite.outputs.check_runs_url }}\" \\\n | jq -r '.check_runs | map(select(.name == \"${{ inputs.task }}\")) | length'\n }\n tasks=\"$(get_number_of_tasks)\"\n case \"$tasks\" in\n 0)\n echo \"Task not found, assuming it's skipped intentionally...\"\n exit 0\n ;;\n 1)\n echo \"task_found=1\" >> \"$GITHUB_OUTPUT\"\n exit 0\n ;;\n *)\n >&2 echo \"More than 1 task with the same name found. Don't know what to do...\"\n exit 1\n ;;\n esac\n - name: Wait for Cirrus CI to complete task\n if: steps.find-task.outputs.task_found\n shell: bash\n run: |\n get_conclusion() {\n gh api \"${{ steps.check-suite.outputs.check_runs_url }}\" \\\n | jq -r '.check_runs[] | select(.name == \"${{ inputs.task }}\" and .status == \"completed\") | .conclusion'\n }\n while true; do\n conclusion=\"$(get_conclusion)\"\n if [ -z \"$conclusion\" ]; then\n echo \"Cirrus CI task has not completed, yet. Waiting...\"\n sleep 30\n else\n if [ \"$conclusion\" == \"success\" ]; then\n break\n else\n exit 1\n fi\n fi\n done\n - name: Download artifact from Cirrus CI\n if: steps.find-task.outputs.task_found\n id: download\n shell: bash\n run: |\n get_external_id() {\n gh api \"${{ steps.check-suite.outputs.check_runs_url }}\" \\\n | jq -er '.check_runs[] | select(.name == \"${{ inputs.task }}\") | .external_id'\n }\n archive=\"$(mktemp)\"\n artifacts=\"$(mktemp -d)\"\n until curl --no-progress-meter --fail -o \"${archive}\" \\\n \"https://api.cirrus-ci.com/v1/artifact/task/$(get_external_id)/${{ inputs.download }}.zip\"\n do\n # This happens when a tag is pushed on the same commit. In this case the\n # job is immediately marked as \"completed\" for us, so we end up here after a few\n # seconds - but the actual Cirrus CI task is still running and didn't produce its artifact, yet.\n echo \"Artifact not found on Cirrus CI, yet. Waiting...\"\n sleep 30\n done\n unzip \"${archive}\" -d \"${artifacts}\"\n echo \"artifacts=${artifacts}\" >> \"$GITHUB_OUTPUT\"\n - name: Save artifact to GitHub Actions\n if: steps.find-task.outputs.task_found\n uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0\n with:\n name: ${{ inputs.upload }}\n path: ${{ steps.download.outputs.artifacts }}\n if-no-files-found: error\n" }, { "path": ".github/actions/cache-on-main/action.yaml", "content": "name: Cache on main\n\ndescription: Stores caches on main and release branches only, but restores them on all branches.\n\ninputs:\n path:\n description: Path(s) to cache\n required: true\n save-prs:\n description: Whether to additionally store the cache in a pull request, too. Should only be used for very small caches.\n type: boolean\n prefix:\n description: Cache key prefix to be used in both primary key and restore-keys.\n required: true\n suffix:\n description: Cache key suffix to be used only in primary key.\n required: true\n\nruns:\n using: composite\n steps:\n - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4\n if: ${{ startsWith(github.ref, 'refs/heads/') || (inputs.save-prs && startsWith(github.ref, 'refs/pull/')) }}\n with:\n path: ${{ inputs.path }}\n key: ${{ runner.os }}-${{ inputs.prefix }}-${{ inputs.suffix }}\n restore-keys: |\n ${{ runner.os }}-${{ inputs.prefix }}-\n - uses: actions/cache/restore@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4\n if: ${{ !startsWith(github.ref, 'refs/heads/') && !(inputs.save-prs && startsWith(github.ref, 'refs/pull/')) }}\n with:\n path: ${{ inputs.path }}\n key: ${{ runner.os }}-${{ inputs.prefix }}-${{ inputs.suffix }}\n restore-keys: |\n ${{ runner.os }}-${{ inputs.prefix }}-\n" }, { "path": ".github/actions/setup-nix/action.yaml", "content": "name: Setup Nix\n\ndescription: Installs nix, sets up cachix and installs a subset of tooling.\n\ninputs:\n authToken:\n description: Token to pass to cachix\n tools:\n description: Tools to install with nix-env -iA \n\nruns:\n using: composite\n steps:\n - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34\n with:\n nix_conf: |-\n always-allow-substitutes = true\n max-jobs = auto\n - uses: cachix/cachix-action@1eb2ef646ac0255473d23a5907ad7b04ce94065c # v17\n with:\n name: postgrest\n authToken: ${{ inputs.authToken }}\n skipPush: ${{ inputs.authToken == '' }}\n - if: ${{ inputs.tools }}\n run: nix-env -f default.nix -iA ${{ inputs.tools }}\n shell: bash\n" }, { "path": ".github/codecov.yml", "content": "codecov:\n branch: main\n require_ci_to_pass: false\n\ncomment: false\n\ncoverage:\n status:\n project:\n default:\n target: auto\n threshold: 1%\n only_pulls: false\n patch:\n default:\n target: auto\n threshold: 1%\n only_pulls: true\n" }, { "path": ".github/renovate.json", "content": "{\n \"$schema\": \"https://docs.renovatebot.com/renovate-schema.json\",\n \"extends\": [\n \"config:best-practices\"\n ],\n \"baseBranchPatterns\": [\n \"main\",\n \"/^v[0-9]+/\"\n ],\n \"rebaseWhen\": \"conflicted\",\n \"pip_requirements\": {\n \"enabled\": false\n },\n \"packageRules\": [\n {\n \"matchBaseBranches\": [\n \"/^v[0-9]+/\"\n ],\n \"matchManagers\": [\n \"haskell-cabal\"\n ],\n \"enabled\": false\n },\n {\n \"matchBaseBranches\": [\n \"/^v[0-9]+/\"\n ],\n \"groupName\": \"all dependencies\"\n },\n {\n \"matchManagers\": [\n \"haskell-cabal\"\n ],\n \"matchPackageNames\": [\n \"base\",\n \"bytestring\",\n \"containers\",\n \"directory\",\n \"mtl\",\n \"parsec\",\n \"process\",\n \"text\"\n ],\n \"groupName\": \"GHC dependencies\"\n },\n {\n \"matchManagers\": [\n \"haskell-cabal\"\n ],\n \"matchPackageNames\": [\n \"hasql\",\n \"hasql-dynamic-statements\",\n \"hasql-notifications\",\n \"hasql-transaction\",\n \"hasql-pool\"\n ],\n \"groupName\": \"hasql\"\n },\n {\n \"matchManagers\": [\n \"haskell-cabal\"\n ],\n \"matchPackageNames\": [\n \"fuzzyset\"\n ],\n \"allowedVersions\": \"<0.3\"\n }\n ]\n}\n" }, { "path": ".github/workflows/backport.yaml", "content": "name: Backport\n\non:\n pull_request_target:\n types:\n - closed\n - labeled\n\njobs:\n backport:\n name: Backport\n runs-on: ubuntu-24.04\n # It triggers only when PR is already merged on either:\n #\n # - The merge event itself (action != labeled) or\n # - A label event with the right label (backport ...).\n #\n # The result will be that we can add the label before or after merge,\n # but the workflow will only run once the PR had been merged.\n if: >\n github.event.pull_request.merged &&\n (\n github.event.action != 'labeled' ||\n startsWith(github.event.label.name, 'backport')\n )\n steps:\n\n # This actions creates the github token using the postgrest app secrets\n - name: Create Github App Token\n id: app-token\n uses: actions/create-github-app-token@f8d387b68d61c58ab83c6c016672934102569859 # v3.0.0\n with:\n app-id: ${{ vars.POSTGREST_CI_APP_ID }}\n private-key: ${{ secrets.POSTGREST_CI_PRIVATE_KEY }}\n permission-contents: write\n permission-pull-requests: write\n permission-workflows: write # required when backporting CI changes\n\n # This is required for backport action to cherry-pick the PR\n - name: Fetch PR ref\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n ref: ${{ github.event.pull_request.head.sha }}\n token: ${{ steps.app-token.outputs.token }}\n\n # Backport action that creates the PR with given settings\n - name: Create backport PR\n uses: korthout/backport-action@4aaf0e03a94ff0a619c9a511b61aeb42adea5b02 # v4.2.0\n with:\n github_token: ${{ steps.app-token.outputs.token }}\n pull_description: 'Backport for #${pull_number}.'\n pull_title: '${target_branch}: ${pull_title}'\n" }, { "path": ".github/workflows/build.yaml", "content": "name: Build\n\non:\n workflow_call:\n secrets:\n CACHIX_AUTH_TOKEN:\n required: false\n pull_request:\n branches:\n - main\n - v[0-9]+\n paths:\n - .github/workflows/build.yaml\n - .github/actions/**\n - .github/scripts/**\n - .github/*\n - '*.nix'\n - nix/**\n - .cirrus.yml\n - cabal.project*\n - postgrest.cabal\n - stack.yaml*\n - '**.hs'\n - '!**.md'\n\nconcurrency:\n # Terminate all previous runs of the same workflow for pull requests\n group: build-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\njobs:\n static:\n name: Nix - Linux x86-64 static\n runs-on: ubuntu-24.04\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - name: Setup Nix Environment\n uses: ./.github/actions/setup-nix\n with:\n authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'\n\n - name: Build static executable\n run: nix-build -A postgrestStatic -A postgrestStatic.tests\n - name: Save built executable as artifact\n uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0\n with:\n name: postgrest-linux-static-x86-64\n path: result/bin/postgrest\n if-no-files-found: error\n\n - name: Build Docker image\n run: nix-build -A docker.image --out-link postgrest-docker.tar.gz\n - name: Save built Docker image as artifact\n uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0\n with:\n name: postgrest-docker-x86-64\n path: postgrest-docker.tar.gz\n if-no-files-found: error\n\n\n macos:\n name: Nix - MacOS\n runs-on: macos-15\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - name: Setup Nix Environment\n uses: ./.github/actions/setup-nix\n with:\n authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'\n - name: Install gnu sed\n run: brew install gnu-sed\n\n - name: Build everything\n run: |\n # The --dry-run will give us a list of derivations to download from cachix and\n # derivations to build. We only take those that would have to be built and then build\n # those explicitly. This has the advantage that pure verification will not include\n # a download anymore, making it much faster. If something needs to be built, only\n # the dependencies required to do so will be downloaded, but not everything.\n nix-build --dry-run 2>&1 \\\n | gsed -e '1,/derivations will be built:$/d' -e '/paths will be fetched/Q' \\\n | xargs nix-build\n\n\n stack:\n strategy:\n fail-fast: false\n matrix:\n include:\n - name: Linux aarch64\n runs-on: ubuntu-24.04-arm\n cache: |\n ~/.stack/pantry\n ~/.stack/snapshots\n ~/.stack/stack.sqlite3\n artifact: postgrest-ubuntu-aarch64\n deps: sudo apt-get update && sudo apt-get install libpq-dev\n\n - name: MacOS aarch64\n runs-on: macos-14\n cache: |\n ~/.stack/pantry\n ~/.stack/snapshots\n ~/.stack/stack.sqlite3\n artifact: postgrest-macos-aarch64\n deps: brew link --force libpq\n\n - name: Windows\n runs-on: windows-2022\n cache: |\n C:\\sr\\pantry\n C:\\sr\\snapshots\n C:\\sr\\stack.sqlite3\n deps: Add-Content $env:GITHUB_PATH $env:PGBIN\n artifact: postgrest-windows-x86-64\n\n name: Stack - ${{ matrix.name }}\n runs-on: ${{ matrix.runs-on }}\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - uses: haskell-actions/setup@f9150cb1d140e9a9271700670baa38991e6fa25c # v2.10.3\n with:\n # This must match the version in stack.yaml's resolver\n ghc-version: 9.6.7\n enable-stack: true\n stack-no-global: true\n stack-setup-ghc: true\n - name: Cache ~/.stack\n uses: ./.github/actions/cache-on-main\n with:\n path: ${{ matrix.cache }}\n prefix: stack\n suffix: ${{ hashFiles('postgrest.cabal', 'stack.yaml.lock') }}\n - name: Cache .stack-work\n uses: ./.github/actions/cache-on-main\n with:\n path: .stack-work\n save-prs: true\n prefix: stack-work-${{ hashFiles('postgrest.cabal', 'stack.yaml.lock') }}\n suffix: ${{ hashFiles('main/**/*.hs', 'src/**/*.hs') }}\n - name: Install dependencies\n if: matrix.deps\n run: ${{ matrix.deps }}\n - name: Build with Stack\n run: stack build --lock-file error-on-write --local-bin-path result --copy-bins\n - name: Strip Executable\n run: strip result/postgrest*\n - name: Save built executable as artifact\n uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0\n with:\n name: ${{ matrix.artifact }}\n path: |\n result/postgrest\n result/postgrest.exe\n if-no-files-found: error\n\n\n freebsd:\n name: Stack - FreeBSD from CirrusCI\n runs-on: ubuntu-24.04\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - uses: ./.github/actions/artifact-from-cirrus\n with:\n token: ${{ github.token }}\n task: Build FreeBSD (Stack)\n download: bin\n upload: postgrest-freebsd-x86-64\n\n\n cabal:\n strategy:\n matrix:\n ghc: ['9.6.7', '9.8.4']\n fail-fast: false\n name: Cabal - Linux x86-64 - GHC ${{ matrix.ghc }}\n runs-on: ubuntu-24.04\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - uses: haskell-actions/setup@f9150cb1d140e9a9271700670baa38991e6fa25c # v2.10.3\n with:\n ghc-version: ${{ matrix.ghc }}\n - name: Cache .cabal\n uses: ./.github/actions/cache-on-main\n with:\n path: |\n ~/.cabal/packages\n ~/.cabal/store\n prefix: cabal-${{ matrix.ghc }}-${{ hashFiles('cabal.project.freeze') }}\n suffix: ${{ hashFiles('postgrest.cabal', 'cabal.project') }}\n - name: Cache dist-newstyle\n uses: ./.github/actions/cache-on-main\n with:\n path: dist-newstyle\n save-prs: true\n prefix: cabal-${{ matrix.ghc }}-dist-newstyle-${{ hashFiles('postgrest.cabal', 'cabal.project', 'cabal.project.freeze') }}\n suffix: ${{ hashFiles('**/*.hs') }}\n - name: Install dependencies\n run: cabal build --only-dependencies --enable-tests --enable-benchmarks\n - name: Build\n run: cabal build --enable-tests --enable-benchmarks all\n" }, { "path": ".github/workflows/check.yaml", "content": "name: Check\n\non:\n workflow_call:\n secrets:\n CACHIX_AUTH_TOKEN:\n required: false\n pull_request:\n branches:\n - main\n - v[0-9]+\n\nconcurrency:\n # Terminate all previous runs of the same workflow for pull requests\n group: style-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\njobs:\n lint-style:\n name: Lint & Style\n runs-on: ubuntu-24.04\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - name: Setup Nix Environment\n uses: ./.github/actions/setup-nix\n with:\n authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'\n tools: style.lint.bin style.styleCheck.bin\n - name: Run linter (check locally with `nix-shell --run postgrest-lint`)\n run: postgrest-lint\n - name: Run style check (auto-format with `nix-shell --run postgrest-style`)\n run: postgrest-style-check\n\n commit:\n if: github.event_name != 'push' # we don't run this on a push, a failure on push disrupts the release workflow\n name: Commit\n runs-on: ubuntu-24.04\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 100 # fetch history (last 100 commits) instead of default shallow clone history, this is deemed enough for a PR history\n - name: Setup Nix Environment\n uses: ./.github/actions/setup-nix\n with:\n authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'\n tools: gitTools.commitCheck.bin\n - name: Run commitlint (check locally with `nix-shell --run postgrest-commitlint`)\n run: |\n # Fetch target branch explicitly\n git fetch origin ${{ github.base_ref }}\n\n # Run commitlint\n postgrest-commitlint --from origin/${{ github.base_ref }} --to HEAD\n" }, { "path": ".github/workflows/ci.yaml", "content": "name: CI\n\non:\n push:\n branches:\n - main\n - v[0-9]+\n\njobs:\n check:\n name: Check\n uses: ./.github/workflows/check.yaml\n secrets:\n CACHIX_AUTH_TOKEN: ${{ secrets.CACHIX_AUTH_TOKEN }}\n\n\n docs:\n name: Docs\n uses: ./.github/workflows/docs.yaml\n secrets:\n CACHIX_AUTH_TOKEN: ${{ secrets.CACHIX_AUTH_TOKEN }}\n\n\n test:\n name: Test\n uses: ./.github/workflows/test.yaml\n secrets:\n CACHIX_AUTH_TOKEN: ${{ secrets.CACHIX_AUTH_TOKEN }}\n CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}\n\n\n build:\n name: Build\n uses: ./.github/workflows/build.yaml\n secrets:\n CACHIX_AUTH_TOKEN: ${{ secrets.CACHIX_AUTH_TOKEN }}\n\n\n tag:\n name: Tag\n concurrency:\n # Never tag outdated commits on the main branch by skipping superseded commits\n group: ci-tag-${{ (github.ref == 'refs/heads/main' && github.ref) || github.run_id }}\n # TODO: Enable this once https://github.com/orgs/community/discussions/13015 is solved\n cancel-in-progress: false\n if: vars.RELEASE_ENABLED\n runs-on: ubuntu-24.04\n needs:\n - docs\n - test\n - build\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n ssh-key: ${{ secrets.POSTGREST_SSH_KEY }}\n - name: Tag latest commit\n run: |\n cabal_version=\"$(grep -oP '^version:\\s*\\K.*' postgrest.cabal)\"\n\n if [[ \"$cabal_version\" == *.* ]]; then\n git fetch --tags\n\n if [ -z \"$(git tag --list \"v$cabal_version\")\" ]; then\n git tag \"v$cabal_version\"\n git push origin \"v$cabal_version\"\n fi\n else\n git tag -f \"devel\"\n git push -f origin \"devel\"\n fi\n" }, { "path": ".github/workflows/docs.yaml", "content": "name: Docs\n\non:\n workflow_call:\n secrets:\n CACHIX_AUTH_TOKEN:\n required: false\n pull_request:\n branches:\n - main\n - v[0-9]+\n paths:\n - .github/workflows/docs.yaml\n - .github/actions/setup-nix/**\n - default.nix\n - nix/**\n - docs/**\n - '!**.md'\n\nconcurrency:\n # Terminate all previous runs of the same workflow for pull requests\n group: docs-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\njobs:\n build:\n name: Build\n runs-on: ubuntu-24.04\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - name: Setup Nix Environment\n uses: ./.github/actions/setup-nix\n with:\n authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'\n tools: docs.build.bin\n - run: postgrest-docs-build\n - run: git diff --exit-code HEAD locales || echo \"Please commit changes to the locales/ folder after running postgrest-docs-build.\"\n\n\n spellcheck:\n name: Spellcheck\n runs-on: ubuntu-24.04\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - name: Setup Nix Environment\n uses: ./.github/actions/setup-nix\n with:\n authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'\n tools: docs.spellcheck.bin docs.dictcheck.bin\n - name: Run spellcheck\n run: postgrest-docs-spellcheck\n - name: Run dictcheck\n run: postgrest-docs-dictcheck\n" }, { "path": ".github/workflows/linkcheck.yaml", "content": "name: Linkcheck\n\non:\n schedule:\n - cron: '1 2 * * 3'\n workflow_dispatch:\n\njobs:\n linkcheck:\n runs-on: ubuntu-24.04\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - name: Setup Nix Environment\n uses: ./.github/actions/setup-nix\n with:\n authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'\n tools: docs.linkcheck.bin\n - run: postgrest-docs-linkcheck\n" }, { "path": ".github/workflows/release.yaml", "content": "name: Release\n\non:\n push:\n tags:\n - devel\n - v*\n\nconcurrency:\n # Terminate all previous runs of the same workflow for the same tag.\n group: release-${{ github.ref }}\n # TODO: Enable this once https://github.com/orgs/community/discussions/13015 is solved\n cancel-in-progress: false\n\njobs:\n build:\n name: Build\n uses: ./.github/workflows/build.yaml\n secrets:\n CACHIX_AUTH_TOKEN: ${{ secrets.CACHIX_AUTH_TOKEN }}\n\n\n prepare:\n name: Prepare\n runs-on: ubuntu-24.04\n needs:\n - build\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - name: Check the version to be released\n run: |\n cabal_version=\"$(grep -oP '^version:\\s*\\K.*' postgrest.cabal)\"\n\n if [ \"${GITHUB_REF_NAME}\" != \"devel\" ] && [ \"${GITHUB_REF_NAME}\" != \"v$cabal_version\" ]; then\n echo \"Tagged version ($GITHUB_REF_NAME) does not match the one in postgrest.cabal (v$cabal_version). Aborting release...\"\n exit 1\n fi\n - name: Identify changes from CHANGELOG.md\n run: |\n if [ \"${GITHUB_REF_NAME}\" == \"devel\" ]; then\n echo \"Getting unreleased changes...\"\n sed -n \"1,/## Unreleased/d;/## \\[/q;p\" CHANGELOG.md > CHANGES.md\n else\n version=\"$(grep -oP '^version:\\s*\\K.*' postgrest.cabal)\"\n echo \"Propper release, getting changes for version $version ...\"\n sed -n \"1,/## \\[$version\\]/d;/## \\[/q;p\" CHANGELOG.md > CHANGES.md\n fi\n\n echo \"Relevant extract from CHANGELOG.md:\"\n cat CHANGES.md\n - name: Save CHANGES.md as artifact\n uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0\n with:\n name: release-changes\n path: CHANGES.md\n if-no-files-found: error\n\n\n github:\n name: GitHub\n permissions:\n contents: write\n runs-on: ubuntu-24.04\n needs:\n - prepare\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - name: Download all artifacts\n uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1\n with:\n path: artifacts\n - name: Create release bundle with archives for all builds\n run: |\n find artifacts -type f -iname postgrest -exec chmod +x {} \\;\n\n mkdir -p release-bundle\n\n tar cJvf \"release-bundle/postgrest-${GITHUB_REF_NAME}-linux-static-x86-64.tar.xz\" \\\n -C artifacts/postgrest-linux-static-x86-64 postgrest\n\n tar cJvf \"release-bundle/postgrest-${GITHUB_REF_NAME}-macos-aarch64.tar.xz\" \\\n -C artifacts/postgrest-macos-aarch64 postgrest\n\n tar cJvf \"release-bundle/postgrest-${GITHUB_REF_NAME}-freebsd-x86-64.tar.xz\" \\\n -C artifacts/postgrest-freebsd-x86-64 postgrest\n\n tar cJvf \"release-bundle/postgrest-${GITHUB_REF_NAME}-ubuntu-aarch64.tar.xz\" \\\n -C artifacts/postgrest-ubuntu-aarch64 postgrest\n\n zip --junk-paths \"release-bundle/postgrest-${GITHUB_REF_NAME}-windows-x86-64.zip\" \\\n artifacts/postgrest-windows-x86-64/postgrest.exe\n\n - name: Save release bundle\n uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0\n with:\n name: release-bundle\n path: release-bundle\n if-no-files-found: error\n\n - name: Publish release on GitHub\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n run: |\n echo \"Releasing version ${GITHUB_REF_NAME} on GitHub...\"\n\n if [ \"${GITHUB_REF_NAME}\" == \"devel\" ]; then\n # To replace the existing release, we must first delete the old assets,\n # then modify the release, then add the new assets.\n gh release view devel --json assets \\\n | jq -r '.assets[] | .name' \\\n | xargs -rn1 \\\n gh release delete-asset -y devel\n gh release edit devel \\\n -t devel \\\n --verify-tag \\\n -F artifacts/release-changes/CHANGES.md \\\n --prerelease\n gh release upload --clobber devel release-bundle/*\n else\n gh release create \"${GITHUB_REF_NAME}\" \\\n -t \"${GITHUB_REF_NAME}\" \\\n --verify-tag \\\n -F artifacts/release-changes/CHANGES.md \\\n release-bundle/*\n fi\n\n\n docker:\n name: Docker Hub\n runs-on: ubuntu-24.04-arm\n needs:\n - prepare\n if: |\n vars.DOCKER_REPO && vars.DOCKER_USER\n env:\n DOCKER_REPO: ${{ vars.DOCKER_REPO }}\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - name: Download x86-64 Docker image\n uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1\n with:\n name: postgrest-docker-x86-64\n - name: Download aarch64 binary\n uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1\n with:\n name: postgrest-ubuntu-aarch64\n - uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0\n - uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0\n with:\n username: ${{ vars.DOCKER_USER }}\n password: ${{ secrets.DOCKER_PASS }}\n - name: Build aarch64 Docker image\n run: |\n # This only pushes the image via digest, not a tag. This will not appear\n # in the image list on Docker Hub, yet. It will be later added to the main\n # tag's manifest.\n docker buildx build \\\n -t \"$DOCKER_REPO/postgrest\" \\\n --platform linux/arm64 \\\n --output push-by-digest=true,type=image,push=true \\\n --metadata-file metadata.json \\\n .\n echo \"SHA256_ARM=$(jq -r '.\"containerimage.digest\"' metadata.json)\" >> \"$GITHUB_ENV\"\n - name: Publish images on Docker Hub\n run: |\n docker load -i postgrest-docker.tar.gz\n\n docker tag postgrest:latest \"$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}\"\n docker push \"$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}\"\n docker buildx imagetools create --append \\\n -t \"$DOCKER_REPO/postgrest:${GITHUB_REF_NAME}\" \\\n \"$DOCKER_REPO/postgrest@$SHA256_ARM\"\n\n # Only tag 'latest' for full releases\n if [ \"${GITHUB_REF_NAME}\" != \"devel\" ]; then\n echo \"Pushing to 'latest' tag for full release of ${GITHUB_REF_NAME} ...\"\n docker tag postgrest:latest \"$DOCKER_REPO\"/postgrest:latest\n docker push \"$DOCKER_REPO\"/postgrest:latest\n docker buildx imagetools create --append \\\n -t \"$DOCKER_REPO/postgrest:latest\" \\\n \"$DOCKER_REPO/postgrest@$SHA256_ARM\"\n else\n echo \"Skipping push to 'latest' tag for pre-release...\"\n fi\n\n\n docker-description:\n name: Docker Hub Description\n runs-on: ubuntu-24.04\n if: |\n vars.DOCKER_REPO && vars.DOCKER_USER &&\n github.ref == 'refs/tags/devel'\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - uses: peter-evans/dockerhub-description@1b9a80c056b620d92cedb9d9b5a223409c68ddfa # v5.0.0\n with:\n username: ${{ vars.DOCKER_USER }}\n password: ${{ secrets.DOCKER_PASS }}\n repository: ${{ vars.DOCKER_REPO }}/postgrest\n short-description: ${{ github.event.repository.description }}\n readme-filepath: ./docker-hub-readme.md\n\n" }, { "path": ".github/workflows/test.yaml", "content": "name: Test\n\non:\n workflow_call:\n secrets:\n CACHIX_AUTH_TOKEN:\n required: false\n CODECOV_TOKEN:\n required: false\n pull_request:\n branches:\n - main\n - v[0-9]+\n paths:\n - .github/workflows/test.yaml\n - .github/workflows/report.yaml\n - .github/actions/setup-nix/**\n - default.nix\n - nix/**\n - .stylish-haskell.yaml\n - cabal.project\n - postgrest.cabal\n - '**.hs'\n - test/**\n - '!**.md'\n\nconcurrency:\n # Terminate all previous runs of the same workflow for pull requests\n group: test-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\njobs:\n coverage:\n name: Coverage\n runs-on: ubuntu-24.04\n defaults:\n run:\n # Hack for enabling color output, see:\n # https://github.com/actions/runner/issues/241#issuecomment-842566950\n shell: script -qec \"bash --noprofile --norc -eo pipefail {0}\"\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - name: Setup Nix Environment\n uses: ./.github/actions/setup-nix\n with:\n authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'\n tools: tests.coverage.bin tests.testDoctests.bin tests.testSpecIdempotence.bin cabalTools.update.bin\n\n - run: postgrest-cabal-update\n\n - name: Run coverage (IO tests and Spec tests against latest supported PostgreSQL)\n run: postgrest-coverage\n - name: Upload coverage to codecov\n uses: codecov/codecov-action@1af58845a975a7985b0beb0cbe6fbbb71a41dbad # v5.5.3\n with:\n files: ./coverage/codecov.json\n token: ${{ secrets.CODECOV_TOKEN }}\n\n - name: Run doctests\n if: always()\n run: postgrest-test-doctests\n\n - name: Check the spec tests for idempotence\n if: always()\n run: postgrest-test-spec-idempotence\n\n\n postgres:\n strategy:\n fail-fast: false\n matrix:\n pgVersion: [13, 14, 15, 16, 17]\n name: PG ${{ matrix.pgVersion }}\n runs-on: ubuntu-24.04\n defaults:\n run:\n # Hack for enabling color output, see:\n # https://github.com/actions/runner/issues/241#issuecomment-842566950\n shell: script -qec \"bash --noprofile --norc -eo pipefail {0}\"\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - name: Setup Nix Environment\n uses: ./.github/actions/setup-nix\n with:\n authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'\n tools: tests.testSpec.bin tests.testObservability.bin tests.testIO.bin tests.testBigSchema.bin withTools.pg-${{ matrix.pgVersion }}.bin cabalTools.update.bin\n\n - run: postgrest-cabal-update\n\n - name: Run spec tests\n if: always()\n run: postgrest-with-pg-${{ matrix.pgVersion }} postgrest-test-spec\n\n - name: Run observability tests\n if: always()\n run: postgrest-with-pg-${{ matrix.pgVersion }} postgrest-test-observability\n\n - name: Run IO tests\n if: always()\n run: postgrest-with-pg-${{ matrix.pgVersion }} postgrest-test-io -vv\n\n - name: Run IO tests on a big schema\n if: always()\n run: postgrest-with-pg-${{ matrix.pgVersion }} postgrest-test-big-schema -vv\n\n\n memory:\n name: Memory\n runs-on: ubuntu-24.04\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n - name: Setup Nix Environment\n uses: ./.github/actions/setup-nix\n with:\n authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'\n tools: tests.testMemory.bin cabalTools.update.bin\n\n - run: postgrest-cabal-update\n\n - name: Run memory tests\n run: postgrest-test-memory\n\n\n loadtest:\n strategy:\n matrix:\n kind: ['mixed', 'errors', 'jwt-hs', 'jwt-hs-cache', 'jwt-hs-cache-worst', 'jwt-rsa', 'jwt-rsa-cache', 'jwt-rsa-cache-worst']\n name: Loadtest\n runs-on: ubuntu-24.04\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 0\n - name: Setup Nix Environment\n uses: ./.github/actions/setup-nix\n with:\n authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'\n tools: loadtest.loadtestAgainst.bin loadtest.report.bin cabalTools.update.bin\n\n - run: postgrest-cabal-update\n\n - name: Run loadtest\n env:\n TARGET_BRANCH: ${{ github.base_ref || github.ref_name }}\n run: |\n if [ \"$TARGET_BRANCH\" = \"main\" ]; then\n latest_tag=$(git tag --sort=-creatordate --list \"v*\" | head -n1)\n else\n latest_tag=$(git tag --merged HEAD --sort=-creatordate \"v*\" | head -n1)\n fi\n postgrest-loadtest-against -k ${{ matrix.kind }} \"$TARGET_BRANCH\" \"$latest_tag\"\n postgrest-loadtest-report -g ${{ matrix.kind }} >> \"$GITHUB_STEP_SUMMARY\"\n\n flake:\n strategy:\n fail-fast: false\n matrix:\n runs-on:\n - macos-14 # aarch64-darwin\n - ubuntu-24.04 # x86_64-linux\n - ubuntu-24.04-arm # aarch64-linux\n name: Flake Check\n runs-on: ${{ matrix.runs-on }}\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2\n with:\n fetch-depth: 0\n - name: Setup Nix Environment\n uses: ./.github/actions/setup-nix\n with:\n authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'\n - name: Run flake check\n run: |\n nix flake check\n" }, { "path": ".gitignore", "content": ".DS_Store\ndb\ndist\n.cabal-sandbox\ncabal.sandbox.config\nhscope.out\ncodex.tags\n.anvil\n.stack-work*\ntags\nsite\n*~\n*#*\n.#*\n*.swp\nresult*\ndist-*\npostgrest.hp\npostgrest.prof\n__pycache__\n*.tix\ncoverage\n.hpc\nloadtest\n.history\n.docs-build\ngen_targets.http\ngen_jwk.json\ngen_private.json\n" }, { "path": ".readthedocs.yaml", "content": "version: 2\nsphinx:\n configuration: docs/conf.py\npython:\n install:\n - requirements: docs/requirements.txt\nbuild:\n os: ubuntu-24.04\n tools:\n python: \"3.11\"\n" }, { "path": ".stylish-haskell.yaml", "content": "# stylish-haskell configuration file\n# ==================================\n\n# The stylish-haskell tool is mainly configured by specifying steps. These steps\n# are a list, so they have an order, and one specific step may appear more than\n# once (if needed). Each file is processed by these steps in the given order.\nsteps:\n # Convert some ASCII sequences to their Unicode equivalents. This is disabled\n # by default.\n # - unicode_syntax:\n # # In order to make this work, we also need to insert the UnicodeSyntax\n # # language pragma. If this flag is set to true, we insert it when it's\n # # not already present. You may want to disable it if you configure\n # # language extensions using some other method than pragmas. Default:\n # # true.\n # add_language_pragma: true\n\n # Align the right hand side of some elements. This is quite conservative\n # and only applies to statements where each element occupies a single\n # line.\n - simple_align:\n cases: true\n top_level_patterns: true\n records: true\n\n # Import cleanup\n - imports:\n # There are different ways we can align names and lists.\n #\n # - global: Align the import names and import list throughout the entire\n # file.\n #\n # - file: Like global, but don't add padding when there are no qualified\n # imports in the file.\n #\n # - group: Only align the imports per group (a group is formed by adjacent\n # import lines).\n #\n # - none: Do not perform any alignment.\n #\n # Default: global.\n align: group\n\n # The following options affect only import list alignment.\n #\n # List align has following options:\n #\n # - after_alias: Import list is aligned with end of import including\n # 'as' and 'hiding' keywords.\n #\n # > import qualified Data.List as List (concat, foldl, foldr, head,\n # > init, last, length)\n #\n # - with_alias: Import list is aligned with start of alias or hiding.\n #\n # > import qualified Data.List as List (concat, foldl, foldr, head,\n # > init, last, length)\n #\n # - new_line: Import list starts always on new line.\n #\n # > import qualified Data.List as List\n # > (concat, foldl, foldr, head, init, last, length)\n #\n # Default: after_alias\n list_align: after_alias\n\n # Right-pad the module names to align imports in a group:\n #\n # - true: a little more readable\n #\n # > import qualified Data.List as List (concat, foldl, foldr,\n # > init, last, length)\n # > import qualified Data.List.Extra as List (concat, foldl, foldr,\n # > init, last, length)\n #\n # - false: diff-safe\n #\n # > import qualified Data.List as List (concat, foldl, foldr, init,\n # > last, length)\n # > import qualified Data.List.Extra as List (concat, foldl, foldr,\n # > init, last, length)\n #\n # Default: true\n pad_module_names: true\n\n # Long list align style takes effect when import is too long. This is\n # determined by 'columns' setting.\n #\n # - inline: This option will put as much specs on same line as possible.\n #\n # - new_line: Import list will start on new line.\n #\n # - new_line_multiline: Import list will start on new line when it's\n # short enough to fit to single line. Otherwise it'll be multiline.\n #\n # - multiline: One line per import list entry.\n # Type with constructor list acts like single import.\n #\n # > import qualified Data.Map as M\n # > ( empty\n # > , singleton\n # > , ...\n # > , delete\n # > )\n #\n # Default: inline\n long_list_align: inline\n\n # Align empty list (importing instances)\n #\n # Empty list align has following options\n #\n # - inherit: inherit list_align setting\n #\n # - right_after: () is right after the module name:\n #\n # > import Vector.Instances ()\n #\n # Default: inherit\n empty_list_align: inherit\n\n # List padding determines indentation of import list on lines after import.\n # This option affects 'long_list_align'.\n #\n # - : constant value\n #\n # - module_name: align under start of module name.\n # Useful for 'file' and 'group' align settings.\n list_padding: 4\n\n # Separate lists option affects formatting of import list for type\n # or class. The only difference is single space between type and list\n # of constructors, selectors and class functions.\n #\n # - true: There is single space between Foldable type and list of it's\n # functions.\n #\n # > import Data.Foldable (Foldable (fold, foldl, foldMap))\n #\n # - false: There is no space between Foldable type and list of it's\n # functions.\n #\n # > import Data.Foldable (Foldable(fold, foldl, foldMap))\n #\n # Default: true\n separate_lists: true\n\n # Space surround option affects formatting of import lists on a single\n # line. The only difference is single space after the initial\n # parenthesis and a single space before the terminal parenthesis.\n #\n # - true: There is single space associated with the enclosing\n # parenthesis.\n #\n # > import Data.Foo ( foo )\n #\n # - false: There is no space associated with the enclosing parenthesis\n #\n # > import Data.Foo (foo)\n #\n # Default: false\n space_surround: false\n\n # Language pragmas\n - language_pragmas:\n # We can generate different styles of language pragma lists.\n #\n # - vertical: Vertical-spaced language pragmas, one per line.\n #\n # - compact: A more compact style.\n #\n # - compact_line: Similar to compact, but wrap each line with\n # `{-#LANGUAGE #-}'.\n #\n # Default: vertical.\n style: vertical\n\n # Align affects alignment of closing pragma brackets.\n #\n # - true: Brackets are aligned in same column.\n #\n # - false: Brackets are not aligned together. There is only one space\n # between actual import and closing bracket.\n #\n # Default: true\n align: true\n\n # stylish-haskell can detect redundancy of some language pragmas. If this\n # is set to true, it will remove those redundant pragmas. Default: true.\n remove_redundant: true\n\n # Replace tabs by spaces. This is disabled by default.\n # - tabs:\n # # Number of spaces to use for each tab. Default: 8, as specified by the\n # # Haskell report.\n # spaces: 8\n\n # Remove trailing whitespace\n - trailing_whitespace: {}\n\n# A common setting is the number of columns (parts of) code will be wrapped\n# to. Different steps take this into account. Default: 80.\ncolumns: 70\n\n# By default, line endings are converted according to the OS. You can override\n# preferred format here.\n#\n# - native: Native newline format. CRLF on Windows, LF on other OSes.\n#\n# - lf: Convert to LF (\"\\n\").\n#\n# - crlf: Convert to CRLF (\"\\r\\n\").\n#\n# Default: native.\nnewline: native\n\n# Sometimes, language extensions are specified in a cabal file or from the\n# command line instead of using language pragmas in the file. stylish-haskell\n# needs to be aware of these, so it can parse the file correctly.\n#\n# No language extensions are enabled by default.\nlanguage_extensions:\n - TemplateHaskell\n - QuasiQuotes\n - CPP\n" }, { "path": "BACKERS.md", "content": "# Sponsors & Backers\n\nPostgREST ongoing development is only possible thanks to our Sponsors and Backers, listed below. If you'd like to join them, you can do so by supporting the PostgREST organization on [Patreon](https://www.patreon.com/postgrest).\n\n## Sponsors\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n \n \n \n \n
\n\n## Lead Backers\n\n- [Roboflow](https://github.com/roboflow)\n- Evans Fernandes\n- [Jan Sommer](https://github.com/nerfpops)\n- [Franz Gusenbauer](https://www.igutech.at/)\n\n## Backers\n\n- Zac Miller\n- Tsingson Qin\n- Michel Pelletier\n- Jay Hannah\n- Robert Stolarz\n- Nicholas DiBiase\n- Christopher Reid\n- Nathan Bouscal\n- Daniel Rafaj\n- David Fenko\n- Remo Rechkemmer\n- Severin Ibarluzea\n- Tom Saleeba\n- Pawel Tyll\n\n## Former Backers\n\n\n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n\n- [Christiaan Westerbeek](https://devotis.nl)\n- [Daniel Babiak](https://github.com/dbabiak)\n- Kofi Gumbs\n" }, { "path": "CHANGELOG.md", "content": "# Change Log\n\nAll notable changes to this project will be documented in this file. From version `14.0` onwards PostgREST follows a `MAJOR.PATCH` two-part versioning. Only even-numbered MAJOR versions will be released, reserving odd-numbered MAJOR versions for development.\n\n## Unreleased\n\n### Added\n\n- Log error when `db-schemas` config contains schema `pg_catalog` or `information_schema` by @taimoorzaeem in #4359\n- Add a `HINT` when the LISTEN channel stops working due to a PostgreSQL bug by @laurenceisla in #4581\n- Add string slicing operator for `jwt-role-claim-key` by @taimoorzaeem in #4599\n- Log host, port and pg version of listener database connection by @mkleczek in #4617 #4618\n- Optimize requests with `Prefer: count=exact` that do not use ranges or `db-max-rows` by @laurenceisla in #3957\n + Removed unnecessary double count when building the `Content-Range`.\n- Add config `client_error_verbosity` to customize error verbosity by @taimoorzaeem in #4088, #3980, #3824\n- Add `Vary` header to responses by @develop7 in #4609\n\n### Changed\n\n- All responses now include a `Vary` header by @develop7 in #4609\n\n- Log error when `db-schemas` config contains schema `pg_catalog` or `information_schema` by @taimoorzaeem in #4359\n + Now fails at startup. Prior to this, it failed with `PGRST205` on requests related to these schemas.\n\n## [14.6] - 2026-03-06\n\n### Fixed\n\n- Fix leaking table and function names when calculating error hint by @taimoorzaeem in #4675\n\n## [14.5] - 2026-02-12\n\n### Fixed\n\n- Don't hide async exceptions in logs by @stevechavez in #4646\n\n## [14.4] - 2026-01-29\n\n### Fixed\n\n- Ensure Listener connections are released by @mkleczek in #4614\n- Fix incorrectly filtering the returned representation for PATCH requests when using `or/and` filters by @laurenceisla in #3707\n- Fix listener running with exception masked after first failure by @mkleczek in #4615\n\n## [14.3] - 2026-01-03\n\n### Fixed\n\n- Fix performance and high memory usage of relation hint calculation by @mkleczek in #4462, #4463\n\n## [14.2] - 2025-12-18\n\n### Fixed\n\n- Fix `hasSingleUnnamedParam` incorrectly matching functions with named parameters by @joelonsql in #4553\n + Functions with a single named parameter (e.g., `foo(data json)`) no longer incorrectly match the single-param fallback, returning a clean `PGRST202` error instead of a confusing PostgreSQL `42883` error.\n- Fix misleading logs on unsupported PostgreSQL versions by @taimoorzaeem in #4519\n- Fix regression where the `PGRST103` error response was truncated by @laurenceisla in #4455\n + Happened when an `offset` was greater than the rows requested and `Prefer: count=exact` was sent.\n- Fix not returning `Content-Length` on empty HTTP `201` responses by @laurenceisla in #4518\n- Fix inaccurate Server-Timing header durations by @steve-chavez in #4522\n- Fix inaccurate \"Schema cache queried\" logs by @steve-chavez in #4522\n\n## [14.1] - 2025-11-05\n\n## Fixed\n\n- Fix `db-pre-config` function failing when function names are pg reserved words by @taimoorzaeem in #4380\n- Fix `server-host=!6` incorrectly binds to IPv4 address by @taimoorzaeem in #3202\n\n## [14.0] - 2025-10-24\n\n### Added\n\n- Bounded JWT cache using the SIEVE algorithm by @mkleczek in #4084\n + It now uses a fixed size cache instead of arbitrary sized cache.\n- Add `--ready` flag for postgrest healthcheck by @taimoorzaeem in #4239\n\n### Fixed\n\n- Fix not logging OpenAPI queries when `log-query=main-query` is enabled by @steve-chavez in #4226\n- Fix not logging explain query when `log-query=main-query` is enabled by @steve-chavez in #4319\n- Fix not logging transaction variables and db-pre-request function when `log-query=main-query` is enabled by @steve-chavez in #3934\n- Fix not logging the JSON message to stderr on a `PGRST002` error by @laurenceisla in #4129\n- Fix reloading the Schema Cache unnecessarily on a `PGRST002` error by @laurenceisla in #4367\n- Fix schema cache loading taking a long time for large schemas by @mkleczek in #4360, #3704\n\n### Changed\n\n- Drop support for PostgreSQL EOL version 12 by @wolfgangwalther in #3865\n- From now on PostgREST will follow a `MAJOR.PATCH` two-part versioning. Only even-numbered MAJOR versions will be released, reserving odd-numbered MAJOR versions for development.\n- Replaced `jwt-cache-max-lifetime` config with `jwt-cache-max-entries` by @mkleczek in #4084\n- `log-query` config now takes a boolean instead of a string value by @steve-chavez in #3934\n\n## [13.0.8] - 2025-10-24\n\n### Fixed\n\n- Fix loading utf-8 config files with `ASCII` locale set by @taimoorzaeem in #4386\n\n## [13.0.7] - 2025-09-14\n\n### Added\n\n- Improve the `PGRST106` error when the requested schema is invalid by @laurenceisla in #4089\n + It now shows the invalid schema in the `message` field.\n + The exposed schemas are now listed in the `hint` instead of the `message` field.\n- Improve error details of `PGRST301` error by @taimoorzaeem in #4051\n\n## [13.0.6] - 2025-08-30\n\n### Fixed\n\n- Fix logging the Haskell type instead of the listener error message directly by @laurenceisla in #3588\n- Fix format of `IPv6` address logged at PostgREST startup by @taimoorzaeem in #4291\n- Fix empty enum in `preferParams` OpenAPI parameter by @laurenceisla in #4292\n\n## [13.0.5] - 2025-08-24\n\n### Fixed\n\n- Fix OpenAPI broken docs link by @taimoorzaeem in #4080\n- Fix OpenAPI specification incorrectly exposing GET methods for volatile functions by @joelonsql in #4174\n- Fix empty spread embeddings return unexpected SQL error by @taimoorzaeem in #3887\n- Fix `/metrics` endpoint not responding with `Content-Type` header by @taimoorzaeem in #4271\n\n## [13.0.4] - 2025-06-17\n\n### Fixed\n\n- Fix regression that makes full-text search not work on domain types based on `tsvector` by @laurenceisla in #4135\n- Fix `jwt-aud` config not failing when set to an invalid URI by @taimoorzaeem in #4132\n\n## [13.0.3] - 2025-06-16\n\n- Fix `max-affected` preference not failing with RPC when `handling=strict` by @taimoorzaeem in #4100\n- Fix a property definition's type in OpenAPI not showing the correct base type of a recursive domain by @laurenceisla in #4136\n\n### Fixed\n\n## [13.0.2] - 2025-06-02\n\n### Fixed\n\n- Fix regression that makes `ORDER BY` with nulls-order not work alongside limits by @laurenceisla in #4109\n\n## [13.0.1] - 2025-06-01\n\n### Fixed\n\n- Fix jwt error returning HTTP status `400` for invalid role by @taimoorzaeem in #3601\n- Fix `db-extra-search-path` cannot be set to nothing by @taimoorzaeem in #4074\n + It can now be disabled by setting it to empty string.\n + Schema Cache load error is now logged including `db-schemas` and `db-extra-search-path` config values.\n\n## [13.0.0] - 2025-05-08\n\n### Added\n\n - #3558, Add the `admin-server-host` config to set the host for the admin server - @develop7\n - #3607, Log to stderr when the JWT secret is less than 32 characters long - @laurenceisla\n - #2858, Performance improvements when calling RPCs via GET using indexes in more cases - @wolfgangwalther\n - #3560, Log resolved host in \"Listening on ...\" messages - @develop7\n - #3727, Log maximum pool size - @steve-chavez\n - #1536, Add string comparison feature for jwt-role-claim-key - @taimoorzaeem\n - #3747, Allow `not_null` value for the `is` operator - @taimoorzaeem\n - #2255, Apply `to_tsvector()` explicitly to the full-text search filtered column (excluding `tsvector` types) - @laurenceisla\n - #1578, Log the main SQL query to stderr at the current `log-level` when `log-query=main-query` - @laurenceisla\n - #3903, Log connection pool borrows on `log-level=debug` - @taimoorzaeem\n - #3041, Allow spreading one-to-many and many-to-many embedded resources - @laurenceisla\n + The selected columns in the embedded resources are aggregated into arrays\n + Aggregates are not supported\n - #2967, Add `Proxy-Status` header for better error response - @taimoorzaeem\n - #4016, Add `Content-Length` response header - @laurenceisla\n\n### Fixed\n\n - #3693, Prevent spread embedding to allow aggregates when they are disabled - @laurenceisla\n - #3693, A nested spread embedding now correctly groups by the fields of its top parent relationship - @laurenceisla\n - #3693, Fix spread embedding errors when using the `count()` aggregate without a field - @laurenceisla\n + Fixed `\"column reference is ambiguous\"` error when selecting `?select=...table(col,count())`\n + Fixed `\"column . does not exist\"` error when selecting `?select=...table(aias:count())`\n - #3727, Clarify \"listening\" logs - @steve-chavez\n - #3795, Clarify `Accept: vnd.pgrst.object` error message - @steve-chavez\n - #3697, #3602, Handle queries on non-existing table gracefully - @taimoorzaeem\n - #3600, #3926, Improve JWT errors - @taimoorzaeem\n - #3013, Fix `order=` with POST, PATCH, PUT and DELETE requests - @taimoorzaeem\n - #3965, Fix filter on unselected columns in a table-valued function - @taimoorzaeem\n - #4052, Fix schema cache load duplicate objects with different object type but same oid - @taimoorzaeem\n\n### Changed\n\n - #2052, Dropped support for PostgreSQL 9.6 - @wolfgangwalther\n - #2052, Dropped support for PostgreSQL 10 - @wolfgangwalther\n - #2052, Dropped support for PostgreSQL 11 - @wolfgangwalther\n - #3508, PostgREST now fails to start when `server-port` and `admin-server-port` config options are the same - @develop7\n - #3607, PostgREST now fails to start when the JWT secret is less than 32 characters long - @laurenceisla\n - #3644, Fail schema cache lookup with invalid `db-schemas` or `db-extra-search-path` config - @wolfgangwalther\n - Previously, this would silently return 200 - OK on the root endpoint, but don't provide any usable endpoints.\n - Note: This also applies when deleting the `public` schema - both config options default to that.\n - #3757, Remove support for `Prefer: params=single-object` - @joelonsql\n + This preference was deprecated in favor of Functions with an array of JSON objects\n - #3013, Drop support for Limited updates/deletes\n + The feature was complicated and largely unused.\n - #3956, Drop `/config` endpoint of admin server - @steve-chavez\n + The endpoint was at risk of being left unprotected when exposing it.\n + The accompanying `admin-server-config-enabled` config was also dropped.\n - #3598, PostgREST now validates the `kid` parameter of the JWT - @wolfgangwalther\n + If the JWT contains a ``kid`` parameter, then PostgREST will look for the JSON Web Key in the `jwt-secret`.\n + If the JWT doesn't contain a `kid`, the behavior should be backwards compatible. PostgREST will try each key in the `jwt-secret` one by one until it finds one that works.\n - #3697, #3602, Querying non-existent table now returns `PGRST205` error instead of empty json - @taimoorzaeem\n - #3600, #3926, Improve JWT errors - @taimoorzaeem\n + Return `PGRST301` error when `Bearer` in auth header is sent empty\n + Diagnostic error messages instead of exposed internals\n + Return new `PGRST303` error when jwt claims decoding fails\n - #3906, Return `PGRST125` and `PGRST126` errors instead of empty json - @taimoorzaeem\n\n## [12.2.12] - 2025-05-01\n\n### Fixed\n\n- #3956, Fix exposing admin server `/config` by default - @steve-chavez\n + The above endpoint is now disabled unless the `admin-server-config-enabled` config is set to `true`\n\n## [12.2.11] - 2025-04-22\n\n### Fixed\n\n - #4030, Fix regression with parameter `charset=utf-8` in mediatype - @taimoorzaeem\n\n## [12.2.10] - 2025-04-18\n\n### Fixed\n\n- #3889, Fix: JWT cache purging on every request decreases performance - @mkleczek\n\n## [12.2.9] - 2025-04-16\n\n### Fixed\n\n - #3498, Fix incorrect parsing of the `for` parameter of the `application/vnd.pgrst.plan` media type - @taimoorzaeem\n - #4014, Fix JWT cache allows old tokens after the jwt-secret is changed in a config reload - @taimoorzaeem\n\n## [12.2.8] - 2025-02-10\n\n### Fixed\n\n - #3841, Log `503` client error to stderr - @taimoorzaeem\n\n## [12.2.7] - 2025-02-03\n\n### Fixed\n\n - #2524, Fix schema reloading notice on windows - @diogob\n\n## [12.2.6] - 2025-01-29\n\n### Fixed\n\n - #3788, Fix jwt cache does not remove expired entries - @taimoorzaeem\n\n## [12.2.5] - 2025-01-20\n\n### Fixed\n\n - #3867, Fix startup for arm64 docker image - @wolfgangwalther\n\n## [12.2.4] - 2025-01-18\n\n### Fixed\n\n - #3779, Always log the schema cache load time - @steve-chavez\n - #3706, Fix insert with `missing=default` uses default value of domain instead of column - @taimoorzaeem\n\n## [12.2.3] - 2024-08-01\n\n### Fixed\n\n - #3091, Broken link in OpenAPI description `externalDocs` - @salim-b\n - #3659, Embed One-to-One relationship with different column order properly - @wolfgangwalther\n - #3504, Remove `format` from `rowFilter` parameters in OpenAPI - @dantheman2865\n - #3660, Fix regression that loaded the schema cache before the in-database configuration - @steve-chavez, @laurenceisla\n\n## [12.2.2] - 2024-07-10\n\n### Fixed\n\n - #3093, Nested empty embeds no longer show empty values and are correctly omitted - @laurenceisla\n - #3644, Make --dump-schema work with in-database pgrst.db_schemas setting - @wolfgangwalther\n - #3644, Show number of timezones in schema cache load report - @wolfgangwalther\n - #3644, List correct enum options in OpenApi output when multiple types with same name are present - @wolfgangwalther\n - #3523, Fix schema cache loading retry without backoff - @steve-chavez\n\n## [12.2.1] - 2024-06-27\n\n### Fixed\n\n - #3147, Don't reload schema cache on every listener failure - @steve-chavez\n\n### Documentation\n\n - #3592, Architecture diagram now supports dark mode and has links - @laurenceisla\n - #3616, The schema isolation diagram now supports dark mode and uses well-known schemas - @laurenceisla\n\n## [12.2.0] - 2024-06-11\n\n### Added\n\n - #2887, Add Preference `max-affected` to limit affected resources - @taimoorzaeem\n - #3171, Add an ability to dump config via admin API - @skywriter\n - #3171, #3046, Log schema cache stats to stderr - @steve-chavez\n - #3210, Dump schema cache through admin API - @taimoorzaeem\n - #2676, Performance improvement on bulk json inserts, around 10% increase on requests per second by removing `json_typeof` from write queries - @steve-chavez\n - #3435, Add log-level=debug, for development purposes - @steve-chavez\n - #1526, Add `/metrics` endpoint on admin server - @steve-chavez\n - Exposes connection pool metrics, schema cache metrics\n - #3404, Show the failed MESSAGE or DETAIL in the `details` field of the `PGRST121` (could not parse RAISE 'PGRST') error - @laurenceisla\n - #3404, Show extra information in the `PGRST121` (could not parse RAISE 'PGRST') error - @laurenceisla\n + Shows the failed MESSAGE or DETAIL in the `details` field\n + Shows the correct JSON format in the `hints` field\n - #3340, Log when the LISTEN channel gets a notification - @steve-chavez\n - #3184, Log full pg version to stderr on connection - @steve-chavez\n - #3242. Add config `db-hoisted-tx-settings` to apply only hoisted function settings - @taimoorzaeem\n - #3214, #3229 Log connection pool events on log-level=debug - @steve-chavez, @laurenceisla\n\n### Fixed\n\n - #3237, Dump media handlers and timezones with --dump-schema - @wolfgangwalther\n - #3323, #3324, Don't hide error on LISTEN channel failure - @steve-chavez\n - #3330, Incorrect admin server `/ready` response on slow schema cache loads - @steve-chavez\n - #3345, Fix in-database configuration values not loading for `pgrst.server_trace_header` and `pgrst.server_cors_allowed_origins` - @laurenceisla\n - #3404, Clarify the `PGRST121` (could not parse RAISE 'PGRST') error message - @laurenceisla\n - #3267, Fix wrong `503 Service Unavailable` on pg error `53400` - @taimoorzaeem\n - #2985, Fix not adding `application_name` on all connection strings - @steve-chavez\n - #3424, Admin `/live` and `/ready` now differentiates a failure as 500 status - @steve-chavez\n + 503 status is still given when postgREST is in a recovering state\n - #3478, Media Types are parsed case insensitively - @develop7\n - #3533, #3536, Fix listener silently failing on read replica - @steve-chavez\n + If the LISTEN connection fails, it's retried with exponential backoff\n - #3414, Force listener to connect to read-write instances using `target_session_attrs` - @steve-chavez\n - #3255, Fix incorrect `413 Request Entity Too Large` on pg errors `54*` - @taimoorzaeem\n - #3549, Remove verbosity from error logs starting with \"An error occurred...\" and replacing it with \"Failed to...\" - @laurenceisla\n\n### Deprecated\n\n - Support for PostgreSQL versions 9.6, 10 and 11 is deprecated. From this on version onwards, PostgREST will only support non-end-of-life PostgreSQL versions. See https://www.postgresql.org/support/versioning/.\n - `Prefer: params=single-object` is deprecated. Use [a function with a single unnamed JSON parameter](https://postgrest.org/en/latest/references/api/functions.html#function-single-json) instead. - @steve-chavez\n\n### Documentation\n\n - #3289, Add dark mode. Can be toggled by a button in the bottom right corner. - @laurenceisla\n - #3384, Add architecture diagram and documentation - @steve-chavez\n\n## [12.0.3] - 2024-05-09\n\n### Fixed\n\n - #3149, Misleading \"Starting PostgREST..\" logs on schema cache reloading - @steve-chavez\n - #3205, Fix wrong subquery error returning a status of 400 Bad Request - @steve-chavez\n - #3224, Return status code 406 for non-accepted media type instead of code 415 - @wolfgangwalther\n - #3160, Fix using select= query parameter for custom media type handlers - @wolfgangwalther\n - #3361, Clarify PGRST204(column not found) error message - @steve-chavez\n - #3373, Remove rejected mediatype `application/vnd.pgrst.object+json` from response - @taimoorzaeem\n - #3418, Fix OpenAPI not tagging a FK column correctly on O2O relationships - @laurenceisla\n - #3256, Fix wrong http status for pg error `42P17 infinite recursion` - @taimoorzaeem\n\n## [12.0.2] - 2023-12-20\n\n### Fixed\n\n - #3124, Fix table's media type handlers not working for all schemas - @steve-chavez\n - #3126, Fix empty row on media type handler function - @steve-chavez\n\n## [12.0.1] - 2023-12-12\n\n### Fixed\n\n - #3054, Fix not allowing special characters in JSON keys - @laurenceisla\n - #2344, Replace JSON parser error with a clearer generic message - @develop7\n - #3100, Add missing in-database configuration option for `jwt-cache-max-lifetime` - @laurenceisla\n - #3089, The any media type handler now sets `Content-Type: application/octet-stream` by default instead of `Content-Type: application/json` - @steve-chavez\n\n## [12.0.0] - 2023-12-01\n\n### Added\n\n - #1614, Add `db-pool-automatic-recovery` configuration to disable connection retrying - @taimoorzaeem\n - #2492, Allow full response control when raising exceptions - @taimoorzaeem, @laurenceisla\n - #2771, #2983, #3062, #3055 Add `Server-Timing` response header - @taimoorzaeem, @develop7, @laurenceisla\n - #2698, Add config `jwt-cache-max-lifetime` and implement JWT caching - @taimoorzaeem\n - #2943, Add `handling=strict/lenient` for Prefer header - @taimoorzaeem\n - #2441, Add config `server-cors-allowed-origins` to specify CORS origins - @taimoorzaeem\n - #2825, SQL handlers for custom media types - @steve-chavez\n + Solves #1548, #2699, #2763, #2170, #1462, #1102, #1374, #2901\n - #2799, Add timezone in Prefer header - @taimoorzaeem\n - #3001, Add `statement_timeout` set on functions - @taimoorzaeem\n - #3045, Apply superuser settings on impersonated roles if they have PostgreSQL 15 `GRANT SET ON PARAMETER` privilege - @steve-chavez\n - #915, Add support for aggregate functions - @timabdulla\n + The aggregate functions SUM(), MAX(), MIN(), AVG(), and COUNT() are now supported.\n + It's disabled by default, you can enable it with `db-aggregates-enabled`.\n - #3057, Log all internal database errors to stderr - @laurenceisla\n\n### Fixed\n\n - #3015, Fix unnecessary count() on RPC returning single - @steve-chavez\n - #1070, Fix HTTP status responses for upserts - @taimoorzaeem\n + `PUT` returns `201` instead of `200` when rows are inserted\n + `POST` with `Prefer: resolution=merge-duplicates` returns `200` instead of `201` when no rows are inserted\n - #3019, Transaction-Scoped Settings are now shown clearly in the Postgres logs - @laurenceisla\n + Shows `set_config('pgrst.setting_name', $1)` instead of `setconfig($1, $2)`\n + Does not apply to role settings and `app.settings.*`\n - #2420, Fix bogus message when listening on port 0 - @develop7\n - #3067, Fix Acquision Timeout errors logging to stderr when `log-level=crit` - @laurenceisla\n\n### Changed\n\n - Removed [raw-media-types config](https://postgrest.org/en/v11.1/references/configuration.html#raw-media-types) - @steve-chavez\n - Removed `application/octet-stream`, `text/plain`, `text/xml` [builtin support for scalar results](https://postgrest.org/en/v11.1/references/api/resource_representation.html#scalar-function-response-format) - @steve-chavez\n - Removed default `application/openapi+json` media type for [db-root-spec](https://postgrest.org/en/v11.1/references/configuration.html#db-root-spec) - @steve-chavez\n - Removed [db-use-legacy-gucs](https://postgrest.org/en/v11.2/references/configuration.html#db-use-legacy-gucs) - @laurenceisla\n + All PostgreSQL versions now use GUCs in JSON format for [Headers, Cookies and JWT claims](https://postgrest.org/en/v12/references/transactions.html#request-headers-cookies-and-jwt-claims).\n\n## [11.2.2] - 2023-10-25\n\n### Fixed\n\n - #2824, Fix regression by reverting fix that returned 206 when first position = length in a `Range` header - @laurenceisla, @strengthless\n\n## [11.2.1] - 2023-10-03\n\n### Fixed\n\n - #2899, Fix `application/vnd.pgrst.array` not accepted as a valid mediatype - @taimoorzaeem\n - #2524, Fix schema cache and configuration reloading with `NOTIFY` not working on Windows - @diogob, @laurenceisla\n - #2915, Fix duplicate headers in response - @taimoorzaeem\n - #2824, Fix range request with first position same as length return status 206 - @taimoorzaeem\n - #2939, Fix wrong `Preference-Applied` with `Prefer: tx=commit` when transaction is rollbacked - @steve-chavez\n - #2939, Fix `count=exact` not being included in `Preference-Applied` - @steve-chavez\n - #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\n - #2846, Fix error when requesting `Prefer: count=` and doing null filtering on embedded resources - @laurenceisla\n - #2959, Fix setting `default_transaction_isolation` unnecessarily - @steve-chavez\n - #2929, Fix arrow filtering on RPC returning dynamic TABLE with composite type - @steve-chavez\n - #2963, Fix RPCs not embedding correctly when using overloaded functions for computed relationships - @laurenceisla\n - #2970, Fix regression that rejects URI connection strings with certain unescaped characters in the password - @laurenceisla, @steve-chavez\n\n## [11.2.0] - 2023-08-10\n\n### Added\n\n - #2523, Data representations - @aljungberg\n + Allows for flexible API output formatting and input parsing on a per-column type basis using regular SQL functions configured in the database\n + Enables greater flexibility in the form and shape of your APIs, both for output and input, making PostgREST a more versatile general-purpose API server\n + Examples include base64 encode/decode your binary data (like a `bytea` column containing an image), choose whether to present a timestamp column as seconds since the Unix epoch or as an ISO 8601 string, or represent fixed precision decimals as strings, not doubles, to preserve precision\n + ...and accept the same in `POST/PUT/PATCH` by configuring the reverse transformation(s)\n + Other use-cases include custom representation of enums, arrays, nested objects, CSS hex colour strings, gzip compressed fields, metric to imperial conversions, and much more\n + Works when using the `select` parameter to select only a subset of columns, embedding through complex joins, renaming fields, with views and computed columns\n + Works when filtering on a formatted column without extra indexes by parsing to the canonical representation\n + Works for data `RETURNING` operations, such as requesting the full body in a POST/PUT/PATCH with `Prefer: return=representation`\n + Works for batch updates and inserts\n + Completely optional, define the functions in the database and they will be used automatically everywhere\n + Data representations preserve the ability to write to the original column and require no extra storage or complex triggers (compared to using `GENERATED ALWAYS` columns)\n + Note: data representations require Postgres 10 (Postgres 11 if using `IN` predicates); data representations are not implemented for RPC\n - #2647, Allow to verify the PostgREST version in SQL: `select distinct application_name from pg_stat_activity`. - @laurenceisla\n - #2856, Add the `--version` CLI option that prints the version information - @laurenceisla\n - #1655, Improve `details` field of the singular error response - @taimoorzaeem\n - #740, Add `Preference-Applied` in response for `Prefer: return=representation/headers-only/minimal` - @taimoorzaeem\n - #1601, Add optional `nulls=stripped` parameter for mediatypes `application/vnd.pgrst.array+json` and `application/vnd.pgrst.object+json` - @taimoorzaeem\n\n### Fixed\n\n - #2821, Fix OPTIONS not accepting all available media types - @steve-chavez\n - #2834, Fix compilation on Ubuntu by being compatible with GHC 9.0.2 - @steve-chavez\n - #2840, Fix `Prefer: missing=default` with DOMAIN default values - @steve-chavez\n - #2849, Fix HEAD unnecessarily executing aggregates - @steve-chavez\n - #2594, Fix unused index on jsonb/jsonb arrow filter and order (``/bets?data->>contractId=eq.1`` and ``/bets?order=data->>contractId``) - @steve-chavez\n - #2861, Fix character and bit columns with fixed length not inserting/updating properly - @laurenceisla\n + Fixes the error \"value too long for type character(1)\" when the char length of the column was bigger than one.\n - #2862, Fix null filtering on embedded resource when using a column name equal to the relation name - @steve-chavez\n - #1586, Fix function parameters of type character and bit not ignoring length - @laurenceisla\n + Fixes the error \"value too long for type character(1)\" when the char length of the parameter was bigger than one.\n - #2881, Fix error when a function returns `RECORD` or `SET OF RECORD` - @laurenceisla\n - #2896, Fix applying superuser settings for impersonated role - @steve-chavez\n\n### Deprecated\n\n - #2863, Deprecate resource embedding target disambiguation - @steve-chavez\n + The `/table?select=*,other!fk(*)` must be used to disambiguate\n + The server aids in choosing the `!fk` by sending a `hint` on the error whenever an ambiguous request happens.\n\n## [11.1.0] - 2023-06-07\n\n### Added\n\n - #2786, Limit idle postgresql connection lifetime - @robx\n + New option `db-pool-max-idletime` (default 30s).\n + This is equivalent to the old option `db-pool-timeout` of PostgREST 10.0.0.\n + A config alias for `db-pool-timeout` is included.\n - #2703, Add pre-config function - @steve-chavez\n + New config option `db-pre-config`(empty by default)\n + Allows using the in-database configuration without SUPERUSER\n - #2781, When `db-channel-enabled` is false, start automatic connection recovery on a new request when pool connections are closed with `pg_terminate_backend` - @steve-chavez\n + Mitigates the lack of LISTEN/NOTIFY for schema cache reloading on read replicas.\n\n### Fixed\n\n - #2791, Fix dropping schema cache reload notifications - @steve-chavez\n - #2801, Stop retrying connection when \"no password supplied\" - @steve-chavez\n\n## [11.0.1] - 2023-04-27\n\n### Fixed\n\n - #2762, Fixes \"permission denied for schema\" error during schema cache load - @steve-chavez\n - #2756, Fix bad error message on generated columns when using `Prefer: missing=default` - @steve-chavez\n - #1139, Allow a 30 second skew for JWT validation - @steve-chavez\n + It used to be 1 second, which was too strict\n\n## [11.0.0] - 2023-04-16\n\n### Added\n\n - #1414, Add related orders - @steve-chavez\n + On a many-to-one or one-to-one relationship, you can order a parent by a child column `/projects?select=*,clients(*)&order=clients(name).desc.nullsfirst`\n - #1233, #1907, #2566, Allow spreading embedded resources - @steve-chavez\n + On a many-to-one or one-to-one relationship, you can unnest a json object with `/projects?select=*,...clients(client_name:name)`\n + Allows including the join table columns when resource embedding\n + Allows disambiguating a recursive m2m embed\n + Allows disambiguating an embed that has a many-to-many relationship using two foreign keys on a junction\n - #2340, Allow embedding without selecting any column - @steve-chavez\n - #2563, Allow `is.null` or `not.is.null` on an embedded resource - @steve-chavez\n + Offers a more flexible replacement for `!inner`, e.g. `/projects?select=*,clients(*)&clients=not.is.null`\n + Allows doing an anti join, e.g. `/projects?select=*,clients(*)&clients=is.null`\n + Allows using or across related tables conditions\n - #1100, Customizable OpenAPI title - @AnthonyFisi\n - #2506, Add `server-trace-header` for tracing HTTP requests. - @steve-chavez\n + When the client sends the request header specified in the config it will be included in the response headers.\n - #2694, Make `db-root-spec` stable. - @steve-chavez\n + This can be used to override the OpenAPI spec with a custom database function\n - #1567, On bulk inserts, missing values can get the column DEFAULT by using the `Prefer: missing=default` header - @steve-chavez\n - #2501, Allow filtering by`IS DISTINCT FROM` using the `isdistinct` operator, e.g. `/people?alias=isdistinct.foo`\n - #1569, Allow `any/all` modifiers on the `eq,like,ilike,gt,gte,lt,lte,match,imatch` operators, e.g. `/tbl?id=eq(any).{1,2,3}` - @steve-chavez\n - This converts the input into an array type\n - #2561, Configurable role settings - @steve-chavez\n - Database roles that are members of the connection role get their settings applied, e.g. doing\n `ALTER ROLE anon SET statement_timeout TO '5s'` will result in that `statement_timeout` getting applied for that role.\n - Works when switching roles when a JWT is sent\n - Settings can be reloaded with `NOTIFY pgrst, 'reload config'`.\n - #2468, Configurable transaction isolation level with `default_transaction_isolation` - @steve-chavez\n - Can be set per function `create function .. set default_transaction_isolation = 'repeatable read'`\n - Or per role `alter role .. set default_transaction_isolation = 'serializable'`\n\n### Fixed\n\n - #2651, Add the missing `get` path item for RPCs to the OpenAPI output - @laurenceisla\n - #2648, Fix inaccurate error codes with new ones - @laurenceisla\n + `PGRST204`: Column is not found\n + `PGRST003`: Timed out when acquiring connection to db\n - #1652, Fix function call with arguments not inlining - @steve-chavez\n - #2705, Fix bug when using the `Range` header on `PATCH/DELETE` - @laurenceisla\n + Fix the`\"message\": \"syntax error at or near \\\"RETURNING\\\"\"` error\n + Fix doing a limited update/delete when an `order` query parameter was present\n - #2742, Fix db settings and pg version queries not getting prepared - @steve-chavez\n - #2618, Fix `PATCH` requests not recognizing embedded filters and using the top-level resource instead - @steve-chavez\n\n### Changed\n\n - #2705, The `Range` header is now only considered on `GET` requests and is ignored for any other method - @laurenceisla\n + Other methods should use the `limit/offset` query parameters for sub-ranges\n + `PUT` requests no longer return an error when this header is present (using `limit/offset` still triggers the error)\n - #2733, Remove bulk RPC call with the `Prefer: params=multiple-objects` header. A function with a JSON array or object parameter should be used instead.\n\n## [10.2.0] - 2023-04-12\n\n### Added\n\n - #2663, Limit maximal postgresql connection lifetime - @robx\n + New option `db-pool-max-lifetime` (default 30m)\n + `db-pool-acquisition-timeout` is no longer optional and defaults to 10s\n + Fixes postgresql resource leak with long-lived connections (#2638)\n\n### Fixed\n\n - #2667, Fix `db-pool-acquisition-timeout` not logging to stderr when the timeout is reached - @steve-chavez\n\n## [10.1.2] - 2023-02-01\n\n### Fixed\n\n - #2565, Fix bad M2M embedding on RPC - @steve-chavez\n - #2575, Replace misleading error message when no function is found with a hint containing functions/parameters names suggestions - @laurenceisla\n - #2582, Move explanation about \"single parameters\" from the `message` to the `details` in the error output - @laurenceisla\n - #2569, Replace misleading error message when no relationship is found with a hint containing parent/child names suggestions - @laurenceisla\n - #1405, Add the required OpenAPI items object when the parameter is an array - @laurenceisla\n - #2592, Add upsert headers for POST requests to the OpenAPI output - @laurenceisla\n - #2623, Fix FK pointing to VIEW instead of TABLE in OpenAPI output - @laurenceisla\n - #2622, Consider any PostgreSQL authentication failure as fatal and exit immediately - @michivi\n - #2620, Fix `NOTIFY pgrst` not reloading the db connections catalog cache - @steve-chavez\n\n## [10.1.1] - 2022-11-08\n\n### Fixed\n\n - #2548, Fix regression when embedding views with partial references to multi column FKs - @wolfgangwalther\n - #2558, Fix regression when requesting limit=0 and `db-max-row` is set - @laurenceisla\n - #2542, Return a clear error without hitting the database when trying to update or insert an unknown column with `?columns` - @aljungberg\n\n## [10.1.0] - 2022-10-28\n\n### Added\n\n - #2348, Add `db-pool-acquisition-timeout` configuration option, time in seconds to wait to acquire a connection. - @robx\n\n### Fixed\n\n - #2261, #2349, #2467, Reduce allocations communication with PostgreSQL, particularly for request bodies. - @robx\n - #2401, #2444, Fix SIGUSR1 to fully flush connections pool. - @robx\n - #2428, Fix opening an empty transaction on failed resource embedding - @steve-chavez\n - #2455, Fix embedding the same table multiple times - @steve-chavez\n - #2518, Fix a regression when embedding views where base tables have a different column order for FK columns - @wolfgangwalther\n - #2458, Fix a regression with the location header when inserting into views with PKs from multiple tables - @wolfgangwalther\n - #2356, Fix a regression in openapi output with mode follow-privileges - @wolfgangwalther\n - #2283, Fix infinite recursion when loading schema cache with self-referencing view - @wolfgangwalther\n - #2343, Return status code 200 for PATCH requests which don't affect any rows - @wolfgangwalther\n - #2481, Treat computed relationships not marked SETOF as M2O/O2O relationship - @wolfgangwalther\n - #2534, Fix embedding a computed relationship with a normal relationship - @steve-chavez\n - #2362, Fix error message when [] is used inside select - @wolfgangwalther\n - #2475, Disallow !inner on computed columns - @wolfgangwalther\n - #2285, Ignore leading and trailing spaces in column names when parsing the query string - @wolfgangwalther\n - #2545, Fix UPSERT with PostgreSQL 15 - @wolfgangwalther\n - #2459, Fix embedding views with multiple references to the same base column - @wolfgangwalther\n\n### Changed\n\n - #2444, Removed `db-pool-timeout` option, because this was removed upstream in hasql-pool. - @robx\n - #2343, PATCH requests that don't affect any rows no longer return 404 - @wolfgangwalther\n - #2537, Stricter parsing of query string. Instead of silently ignoring, the parser now throws on invalid syntax like json paths for embeddings, hints for regular columns, empty casts or fts languages, etc. - @wolfgangwalther\n\n### Deprecated\n\n - #1385, Deprecate bulk-calls when including the `Prefer: params=multiple-objects` in the request. A function with a JSON array or object parameter should be used instead for a better performance.\n\n## [10.0.0] - 2022-08-18\n\n### Added\n\n - #1933, #2109, Add a minimal health check endpoint - @steve-chavez\n + For enabling this, the `admin-server-port` config must be set explicitly\n + A `:/live` endpoint is available for checking if postgrest is running on its port/socket. 200 OK = alive, 503 = dead.\n + A `:/ready` endpoint is available for checking a correct internal state(the database connection plus the schema cache). 200 OK = ready, 503 = not ready.\n - #1988, Add the current user to the request log on stdout - @DavidLindbom, @wolfgangwalther\n - #1823, Add the ability to run postgrest without any configuration. - @wolfgangwalther\n + #1991, Add the ability to run without `db-uri` using libpq's PG environment variables to connect. - @wolfgangwalther\n + #1769, Add the ability to run without `db-schemas`, defaulting to `db-schemas=public`. - @wolfgangwalther\n + #1689, Add the ability to run without `db-anon-role` disabling anonymous access. - @wolfgangwalther\n - #1543, Allow access to fields of composite types in select=, order= and filters through JSON operators -> and ->>. - @wolfgangwalther\n - #2075, Allow access to array items in ?select=, ?order= and filters through JSON operators -> and ->>. - @wolfgangwalther\n - #2156, #2211, Allow applying `limit/offset` to UPDATE/DELETE to only affect a subset of rows - @steve-chavez\n + It requires an explicit `order` on a unique column(s)\n - #1917, Add error codes with the `\"PGRST\"` prefix to the error response body to differentiate PostgREST errors from PostgreSQL errors - @laurenceisla\n - #1917, Normalize the error response body by always having the `detail` and `hint` error fields with a `null` value if they are empty - @laurenceisla\n - #2176, Errors raised with `SQLSTATE` now include the message and the code in the response body - @laurenceisla\n - #2236, Support POSIX regular expression operators for row filtering - @enote-kane\n - #2202, Allow returning XML from RPCs - @fjf2002\n - #2268, Allow returning XML from single-column queries - @fjf2002\n - #2300, RPC POST for function w/single unnamed XML param #2300 - @fjf2002\n - #1564, Allow geojson output by specifying the `Accept: application/geo+json` media type - @steve-chavez\n + Requires postgis >= 3.0\n + Works for GET, RPC, POST/PATCH/DELETE with `Prefer: return=representation`.\n + Resource embedding works and the embedded rows will go into the `properties` key\n + In case of multiple geometries in the same table, you can choose which one will go into the `geometry` key with the usual `?select` query parameter.\n - #1082, Add security definitions to the OpenAPI output - @laurenceisla\n - #2378, Support http OPTIONS method on RPC and root path - @steve-chavez\n - #2354, Allow getting the EXPLAIN plan of a request by using the `Accept: application/vnd.pgrst.plan` header - @steve-chavez\n + Only allowed if the `db-plan-enabled` config is set to true\n + Can generate the plan for different media types using the `for` parameter: `Accept: application/vnd.pgrst.plan; for=\"application/vnd.pgrst.object\"`\n + Different options for the plan can be used with the `options` parameter: `Accept: application/vnd.pgrst.plan; options=analyze|verbose|settings|buffers|wal`\n + The plan can be obtained in text or json by using different media type suffixes: `Accept: application/vnd.pgrst.plan+text` and `Accept: application/vnd.pgrst.plan+json`.\n - #2144, Support computed relationships which allow extending and overriding relationships for resource embedding - @steve-chavez, @wolfgangwalther\n - #1984, Detect one-to-one relationships for resource embedding - @steve-chavez\n + Detected when there's a foreign key with a unique constraint or when a foreign key is also a primary key\n\n### Fixed\n\n - #2058, Return 204 No Content without Content-Type for PUT - @wolfgangwalther\n - #2107, Clarify error for failed schema cache load. - @steve-chavez\n + From `Database connection lost. Retrying the connection` to `Could not query the database for the schema cache. Retrying.`\n - #1771, Fix silently ignoring filter on a non-existent embedded resource - @steve-chavez\n - #2152, Remove functions, which are uncallable because of unnamend arguments from schema cache and OpenAPI output. - @wolfgangwalther\n - #2145, Fix accessing json array fields with -> and ->> in ?select= and ?order=. - @wolfgangwalther\n - #2155, Ignore `max-rows` on POST, PATCH, PUT and DELETE - @steve-chavez\n - #2254, Fix inferring a foreign key column as a primary key column on views - @steve-chavez\n - #2070, Restrict generated many-to-many relationships - @steve-chavez\n + Only adds many-to-many relationships when: a table has FKs to two other tables and these FK columns are part of the table's PK columns.\n - #2278, Allow casting to types with underscores and numbers(e.g. `select=oid_array::_int4`) - @steve-chavez\n - #2277, #2238, #1643, Prevent views from breaking one-to-many/many-to-one embeds when using column or FK as target - @steve-chavez\n + When using a column or FK as target for embedding(`/tbl?select=*,col-or-fk(*)`), only tables are now detected and views are not.\n + You can still use a column or an inferred FK on a view to embed a table(`/view?select=*,col-or-fk(*)`)\n - #2317, Increase the `db-pool-timeout` to 1 hour to prevent frequent high connection latency - @steve-chavez\n - #2341, The search path now correctly identifies schemas with uppercase and special characters in their names (regression) - @laurenceisla\n - #2364, \"404 Not Found\" on nested routes and \"405 Method Not Allowed\" errors no longer start an empty database transaction - @steve-chavez\n - #2342, Fix inaccurate result count when an inner embed was selected after a normal embed in the query string - @laurenceisla\n - #2376, OPTIONS requests no longer start an empty database transaction - @steve-chavez\n - #2395, Allow using columns with dollar sign($) without double quoting in filters and `select` - @steve-chavez\n - #2410, Fix loop crash error on startup in Postgres 15 beta 3. Log: \"UNION types \\\"char\\\" and text cannot be matched\". - @yevon\n - #2397, Fix race conditions managing database connection helper - @robx\n - #2269, Allow `limit=0` in the request query to return an empty array - @gautam1168, @laurenceisla\n - #2401, Ensure database connections can't outlive SIGUSR1 - @robx\n\n### Changed\n\n - #2001, Return 204 No Content without Content-Type for RPCs returning VOID - @wolfgangwalther\n + Previously, those RPCs would return \"null\" as a body with Content-Type: application/json.\n - #2156, `limit/offset` now limits the affected rows on UPDATE/DELETE - @steve-chavez\n + Previously, `limit/offset` only limited the returned rows but not the actual updated rows\n - #2155, `max-rows` is no longer applied on POST/PATCH/PUT/DELETE returned rows - @steve-chavez\n + This was misleading because the affected rows were not really affected by `max-rows`, only the returned rows were limited\n - #2070, Restrict generated many-to-many relationships - @steve-chavez\n + A primary key that contains the foreign key columns is now needed for generating many-to-many relationships.\n - #2277, Views now are not detected when embedding using the column or FK as target (`/view?select=*,column(*)`) - @steve-chavez\n + This embedding form was easily made ambiguous whenever a new view was added.\n + You can use computed relationships to keep this embedding form working\n - #2312, Using `Prefer: return=representation` no longer returns a `Location` header - @laurenceisla\n - #1984, For the cases where one to one relationships are detected, json objects will be returned instead of json arrays of length 1\n + If you wish to override this behavior, you can use computed relationships to return arrays again\n + You can get the newly detected one-to-one relationships by using the `--dump-schema` option and filtering with [jq](https://github.com/jqlang/jq).\n ```\n ./postgrest --dump-schema \\\n | jq '[.dbRelationships | .[] | .[1] | .[] | select(.relCardinality.tag == \"O2O\" and .relFTableIsView == false and .relTableIsView == false) | del(.relFTableIsView,.relTableIsView,.tag,.relIsSelf)]'\n ```\n\n## [9.0.1] - 2022-06-03\n\n### Fixed\n\n- #2165, Fix json/jsonb columns should not have type in OpenAPI spec - @clrnd\n- #2020, Execute deferred constraint triggers when using `Prefer: tx=rollback` - @wolfgangwalther\n- #2077, Fix `is` not working with upper or mixed case values like `NULL, TrUe, FaLsE` - @steve-chavez\n- #2024, Fix schema cache loading when views with XMLTABLE and DEFAULT are present - @wolfgangwalther\n- #1724, Fix wrong CORS header Authentication -> Authorization - @wolfgangwalther\n- #2120, Fix reading database configuration properly when `=` is present in value - @wolfgangwalther\n- #2135, Remove trigger functions from schema cache and OpenAPI output, because they can't be called directly anyway. - @wolfgangwalther\n- #2101, Remove aggregates, procedures and window functions from the schema cache and OpenAPI output. - @wolfgangwalther\n- #2153, Fix --dump-schema running with a wrong PG version. - @wolfgangwalther\n- #2042, Keep working when EMFILE(Too many open files) is reached. - @steve-chavez\n- #2147, Ignore `Content-Type` headers for `GET` requests when calling RPCs. - @laurenceisla\n + 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.\n- #2239, Fix misleading disambiguation error where the content of the `relationship` key looks like valid syntax - @laurenceisla\n- #2294, Disable parallel GC for better performance on higher core CPUs - @steve-chavez\n- #1076, Fix using CPU while idle - @steve-chavez\n\n## [9.0.0] - 2021-11-25\n\n### Added\n\n - #1783, Include partitioned tables into the schema cache. Allows embedding, UPSERT, INSERT with Location response, OPTIONS request and OpenAPI support for partitioned tables - @laurenceisla\n - #1878, Add Retry-After hint header when in recovery mode - @gautam1168\n - #1735, Allow calling function with single unnamed param through RPC POST. - @steve-chavez\n + Enables calling a function with a single json parameter without using `Prefer: params=single-object`\n + Enables uploading bytea to a function with `Content-Type: application/octet-stream`\n + Enables uploading raw text to a function with `Content-Type: text/plain`\n - #1938, Allow escaping inside double quotes with a backslash, e.g. `?col=in.(\"Double\\\"Quote\")`, `?col=in.(\"Back\\\\slash\")` - @steve-chavez\n - #1075, Allow filtering top-level resource based on embedded resources filters. This is enabled by adding `!inner` to the embedded resource, e.g. `/projects?select=*,clients!inner(*)&clients.id=eq.12`- @steve-chavez, @Iced-Sun\n - #1857, Make GUC names for headers, cookies and jwt claims compatible with PostgreSQL v14 - @laurenceisla, @robertsosinski\n + Getting the value for a header GUC on PostgreSQL 14 is done using `current_setting('request.headers')::json->>'name-of-header'` and in a similar way for `request.cookies` and `request.jwt.claims`\n + PostgreSQL versions below 14 can opt in to the new JSON GUCs by setting the `db-use-legacy-gucs` config option to false (true by default)\n - #1988, Allow specifying `unknown` for the `is` operator - @steve-chavez\n - #2031, Improve error message for ambiguous embedding and add a relevant hint that includes unambiguous embedding suggestions - @laurenceisla\n\n### Fixed\n\n - #1871, Fix OpenAPI missing default values for String types and identify Array types as \"array\" instead of \"string\" - @laurenceisla\n - #1930, Fix RPC return type handling for `RETURNS TABLE` with a single column. Regression of #1615. - @wolfgangwalther\n - #1938, Fix using single double quotes(`\"`) and backslashes(`/`) as values on the \"in\" operator - @steve-chavez\n - #1992, Fix schema cache query failing with standard_conforming_strings = off - @wolfgangwalther\n\n### Changed\n\n - #1949, Drop support for embedding hints used with '.'(`select=projects.client_id(*)`), '!' should be used instead(`select=projects!client_id(*)`) - @steve-chavez\n - #1783, Partitions (created using `PARTITION OF`) are no longer included in the schema cache. - @laurenceisla\n - #2038, Dropped support for PostgreSQL 9.5 - @wolfgangwalther\n\n## [8.0.0] - 2021-07-25\n\n### Added\n\n - #1525, Allow http status override through response.status guc - @steve-chavez\n - #1512, Allow schema cache reloading with NOTIFY - @steve-chavez\n - #1119, Allow config file reloading with SIGUSR2 - @steve-chavez\n - #1558, Allow 'Bearer' with and without capitalization as authentication schema - @wolfgangwalther\n - #1470, Allow calling RPC with variadic argument by passing repeated params - @wolfgangwalther\n - #1559, No downtime when reloading the schema cache with SIGUSR1 - @steve-chavez\n - #504, Add `log-level` config option. The admitted levels are: crit, error, warn and info - @steve-chavez\n - #1607, Enable embedding through multiple views recursively - @wolfgangwalther\n - #1598, Allow rollback of the transaction with Prefer tx=rollback - @wolfgangwalther\n - #1633, Enable prepared statements for GET filters. When behind a connection pooler, you can disable preparing with `db-prepared-statements=false`\n + This increases throughput by around 30% for simple GET queries(no embedding, with filters applied).\n - #1729, #1760, Get configuration parameters from the db and allow reloading config with NOTIFY - @steve-chavez\n - #1824, Allow OPTIONS to generate certain HTTP methods for a DB view - @laurenceisla\n - #1872, Show timestamps in startup/worker logs - @steve-chavez\n - #1881, Add `openapi-mode` config option that allows ignoring roles privileges when showing the OpenAPI output - @steve-chavez\n - CLI options(for debugging):\n + #1678, Add --dump-config CLI option that prints loaded config and exits - @wolfgangwalther\n + #1691, Add --example CLI option to show example config file - @wolfgangwalther\n + #1697, #1723, Add --dump-schema CLI option for debugging purposes - @monacoremo, @wolfgangwalther\n - #1794, (Experimental) Add `request.spec` GUC for db-root-spec - @steve-chavez\n\n### Fixed\n\n - #1592, Removed single column restriction to allow composite foreign keys in join tables - @goteguru\n - #1530, Fix how the PostgREST version is shown in the help text when the `.git` directory is not available - @monacoremo\n - #1094, Fix expired JWTs starting an empty transaction on the db - @steve-chavez\n - #1162, Fix location header for POST request with select= without PK - @wolfgangwalther\n - #1585, Fix error messages on connection failure for localized postgres on Windows - @wolfgangwalther\n - #1636, Fix `application/octet-stream` appending `charset=utf-8` - @steve-chavez\n - #1469, #1638 Fix overloading of functions with unnamed arguments - @wolfgangwalther\n - #1560, Return 405 Method not Allowed for GET of volatile RPC instead of 500 - @wolfgangwalther\n - #1584, Fix RPC return type handling and embedding for domains with composite base type (#1615) - @wolfgangwalther\n - #1608, #1635, Fix embedding through views that have COALESCE with subselect - @wolfgangwalther\n - #1572, Fix parsing of boolean config values for Docker environment variables, now it accepts double quoted truth values (\"true\", \"false\") and numbers(\"1\", \"0\") - @wolfgangwalther\n - #1624, Fix using `app.settings.xxx` config options in Docker, now they can be used as `PGRST_APP_SETTINGS_xxx` - @wolfgangwalther\n - #1814, Fix panic when attempting to run with unix socket on non-unix host and properly close unix domain socket on exit - @monacoremo\n - #1825, Disregard internal junction(in non-exposed schema) when embedding - @steve-chavez\n - #1846, Fix requests for overloaded functions from html forms to no longer hang (#1848) - @laurenceisla\n - #1858, Add a hint and clarification to the no relationship found error - @laurenceisla\n - #1841, Show comprehensive error when an RPC is not found in a stale schema cache - @laurenceisla\n - #1875, Fix Location headers in headers only representation for null PK inserts on views - @laurenceisla\n\n### Changed\n\n - #1522, #1528, #1535, Docker images are now built from scratch based on a the static PostgREST executable (#1494) and with Nix instead of a `Dockerfile`. This reduces the compressed image size from over 30mb to about 4mb - @monacoremo\n - #1461, Location header for POST request is only included when PK is available on the table - @wolfgangwalther\n - #1560, Volatile RPC called with GET now returns 405 Method not Allowed instead of 500 - @wolfgangwalther\n - #1584, #1849 Functions that declare `returns composite_type` no longer return a single object array by default, only functions with `returns setof composite_type` return an array of objects - @wolfgangwalther\n - #1604, Change the default logging level to `log-level=error`. Only requests with a status greater or equal than 500 will be logged. If you wish to go back to the previous behaviour and log all the requests, use `log-level=info` - @steve-chavez\n + Because currently there's no buffering for logging, defaulting to the `error` level(minimum logging) increases throughput by around 15% for simple GET queries(no embedding, with filters applied).\n - #1617, Dropped support for PostgreSQL 9.4 - @wolfgangwalther\n - #1679, Renamed config settings with fallback aliases. e.g. `max-rows` is now `db-max-rows`, but `max-rows` is still accepted - @wolfgangwalther\n - #1656, Allow `Prefer=headers-only` on POST requests and change default to `minimal` (#1813) - @laurenceisla\n - #1854, Dropped undocumented support for gzip compression (which was surprisingly slow and easily enabled by mistake). In some use-cases this makes Postgres up to 3x faster - @aljungberg\n - #1872, Send startup/worker logs to stderr to differentiate from access logs on stdout - @steve-chavez\n\n## [7.0.1] - 2020-05-18\n\n### Fixed\n\n- #1473, Fix overloaded computed columns on RPC - @wolfgangwalther\n- #1471, Fix POST, PATCH, DELETE with ?select= and return=minimal and PATCH with empty body - @wolfgangwalther\n- #1500, Fix missing `openapi-server-proxy-uri` config option - @steve-chavez\n- #1508, Fix `Content-Profile` not working for POST RPC - @steve-chavez\n- #1452, Fix PUT restriction for all columns - @steve-chavez\n\n### Changed\n\n- From this version onwards, the release page will only include a single Linux static executable that can be run on any Linux distribution.\n\n## [7.0.0] - 2020-04-03\n\n### Added\n\n- #1417, `Accept: application/vnd.pgrst.object+json` behavior is now enforced for POST/PATCH/DELETE regardless of `Prefer: return=representation/minimal` - @dwagin\n- #1415, Add support for user defined socket permission via `server-unix-socket-mode` config option - @Dansvidania\n- #1383, Add support for HEAD request - @steve-chavez\n- #1378, Add support for `Prefer: count=planned` and `Prefer: count=estimated` on GET /table - @steve-chavez, @LorenzHenk\n- #1327, Add support for optional query parameter `on_conflict` to upsert with specified keys for POST - @ykst\n- #1430, Allow specifying the foreign key constraint name(`/source?select=fk_constraint(*)`) to disambiguate an embedding - @steve-chavez\n- #1168, Allow access to the `Authorization` header through the `request.header.authorization` GUC - @steve-chavez\n- #1435, Add `request.method` and `request.path` GUCs - @steve-chavez\n- #1088, Allow adding headers to GET/POST/PATCH/PUT/DELETE responses through the `response.headers` GUC - @steve-chavez\n- #1427, Allow overriding provided headers(Location, Content-Type, etc) through the `response.headers` GUC - @steve-chavez\n- #1450, Allow multiple schemas to be exposed in one instance. The schema to use can be selected through the headers `Accept-Profile` for GET/HEAD and `Content-Profile` for POST/PATCH/PUT/DELETE - @steve-chavez, @mahmoudkassem\n\n### Fixed\n\n- #1301, Fix self join resource embedding on PATCH - @herulume, @steve-chavez\n- #1389, Fix many to many resource embedding on RPC/PATCH - @steve-chavez\n- #1355, Allow PATCH/DELETE without `return=minimal` on tables with no select privileges - @steve-chavez\n- #1361, Fix embedding a VIEW when its source foreign key is UNIQUE - @bwbroersma\n\n### Changed\n\n- #1385, bulk RPC call now should be done by specifying a `Prefer: params=multiple-objects` header - @steve-chavez\n- #1401, resource embedding now outputs an error when multiple relationships between two tables are found - @steve-chavez\n- #1423, default Unix Socket file mode from 755 to 660 - @dwagin\n- #1430, Remove embedding with duck typed column names `GET /projects?select=client(*)`- @steve-chavez\n + You can rename the foreign key to `client` to make this request work in the new version: `alter table projects rename constraint projects_client_id_fkey to client`\n- #1413, Change `server-proxy-uri` config option to `openapi-server-proxy-uri` - @steve-chavez\n\n## [6.0.2] - 2019-08-22\n\n### Fixed\n\n- #1369, Change `raw-media-types` to accept a string of comma separated MIME types - @Dansvidania\n- #1368, Fix long column descriptions being truncated at 63 characters in PostgreSQL 12 - @amedeedaboville\n- #1348, Go back to converting plus \"+\" to space \" \" in querystrings by default - @steve-chavez\n\n### Deprecated\n\n- #1348, Deprecate `.` symbol for disambiguating resource embedding(added in #918). The url-safe '!' should be used instead. We refrained from using `+` as part of our syntax because it conflicts with some http clients and proxies.\n\n## [6.0.1] - 2019-07-30\n\n### Added\n\n- #1349, Add user defined raw output media types via `raw-media-types` config option - @Dansvidania\n- #1243, Add websearch_to_tsquery support - @herulume\n\n### Fixed\n\n- #1336, Error when testing on Chrome/Firefox: text/html requested but a single column was not selected - @Dansvidania\n- #1334, Unable to compile v6.0.0 on windows - @steve-chavez\n\n## [6.0.0] - 2019-06-21\n\n### Added\n\n- #1186, Add support for user defined unix socket via `server-unix-socket` config option - @Dansvidania\n- #690, Add `?columns` query parameter for faster bulk inserts, also ignores unspecified json keys in a payload - @steve-chavez\n- #1239, Add support for resource embedding on materialized views - @vitorbaptista\n- #1264, Add support for bulk RPC call - @steve-chavez\n- #1278, Add db-pool-timeout config option - @qu4tro\n- #1285, Abort on wrong database password - @qu4tro\n- #790, Allow override of OpenAPI spec through `root-spec` config option - @steve-chavez\n- #1308, Accept `text/plain` and `text/html` for raw output - @steve-chavez\n\n\n### Fixed\n\n- #1223, Fix incorrect OpenAPI externalDocs url - @steve-chavez\n- #1221, Fix embedding other resources when having a self join - @steve-chavez\n- #1242, Fix embedding a view having a select in a where - @steve-chavez\n- #1238, Fix PostgreSQL to OpenAPI type mappings for numeric and character types - @fpusch\n- #1265, Fix query generated on bulk upsert with an empty array - @qu4tro\n- #1273, Fix RPC ignoring unknown arguments by default - @steve-chavez\n- #1257, Fix incorrect status when a PATCH request doesn't find rows to change - @qu4tro\n\n### Changed\n\n- #1288, Change server-host default of 127.0.0.1 to !4\n\n### Deprecated\n\n- #1288, Deprecate `.` symbol for disambiguating resource embedding(added in #918). '+' should be used instead. Though '+' is url safe, certain clients might need to encode it to '%2B'.\n\n### Removed\n\n- #1288, Removed support for schema reloading with SIGHUP, SIGUSR1 should be used instead - @steve-chavez\n\n## [5.2.0] - 2018-12-12\n\n### Added\n\n- #1205, Add support for parsing JSON Web Key Sets - @russelldavies\n- #1203, Add support for reading db-uri from a separate file - @zhoufeng1989\n- #1200, Add db-extra-search-path config for adding schemas to the search_path, solves issues related to extensions created on the public schema - @steve-chavez\n- #1219, Add ability to quote column names on filters - @steve-chavez\n\n### Fixed\n\n- #1182, Fix embedding on views with composite pks - @steve-chavez\n- #1180, Fix embedding on views with subselects in pg10 - @steve-chavez\n- #1197, Allow CORS for PUT - @bkylerussell\n- #1181, Correctly qualify function argument of custom type in public schema - @steve-chavez\n- #1008, Allow columns that contain spaces in filters - @steve-chavez\n\n## [5.1.0] - 2018-08-31\n\n### Added\n\n- #1099, Add support for getting json/jsonb by array index - @steve-chavez\n- #1145, Add materialized view columns to OpenAPI output - @steve-chavez\n- #709, Allow embedding on views with subselects/CTE - @steve-chavez\n- #1148, OpenAPI: add `required` section for the non-nullable columns - @laughedelic\n- #1158, Add summary to OpenAPI doc for RPC functions - @mdr1384\n\n### Fixed\n\n- #1113, Fix UPSERT failing when having a camel case PK column - @steve-chavez\n- #945, Fix slow start-up time on big schemas - @steve-chavez\n- #1129, Fix view embedding when table is capitalized - @steve-chavez\n- #1149, OpenAPI: Change `GET` response type to array - @laughedelic\n- #1152, Fix RPC failing when having arguments with reserved or uppercase keywords - @mdr1384\n- #905, Fix intermittent empty replies - @steve-chavez\n- #1139, Fix JWTIssuedAtFuture failure for valid iat claim - @steve-chavez\n- #1141, Fix app.settings resetting on pool timeout - @steve-chavez\n\n### Changed\n\n- #1099, Numbers in json path `?select=data->1->>key` now get treated as json array indexes instead of keys - @steve-chavez\n- #1128, Allow finishing a json path with a single arrow `->`. Now a json can be obtained without resorting to casting, Previously: `/json_arr?select=data->>2::json`, now: `/json_arr?select=data->2` - @steve-chavez\n- #724, Change server-host default of *4 to 127.0.0.1\n\n### Deprecated\n\n- #724, SIGHUP deprecated, SIGUSR1 should be used instead\n\n## [0.5.0.0] - 2018-05-14\n\n### Added\n\n- The configuration (e.g. `postgrest.conf`) now accepts arbitrary settings that will be passed through as session-local database settings. This can be used to pass in secret keys directly as strings, or via OS environment variables. For instance: `app.settings.jwt_secret = \"$(MYAPP_JWT_SECRET)\"` will take `MYAPP_JWT_SECRET` from the environment and make it available to postgresql functions as `current_setting('app.settings.jwt_secret')`. Only `app.settings.*` values in the configuration file are treated in this way. - @canadaduane\n- #256, Add support for bulk UPSERT with POST and single UPSERT with PUT - @steve-chavez\n- #1078, Add ability to specify source column in embed - @steve-chavez\n- #821, Allow embeds alias to be used in filters - @steve-chavez\n- #906, Add jspath configurable `role-claim-key` - @steve-chavez\n- #1061, Add foreign tables to OpenAPI output - @rhyamada\n\n### Fixed\n\n- #828, Fix computed column only working in public schema - @steve-chavez\n- #925, Fix RPC high memory usage by using parametrized query and avoiding json encoding - @steve-chavez\n- #987, Fix embedding with self-reference foreign key - @steve-chavez\n- #1044, Fix view parent embedding when having many views - @steve-chavez\n- #781, Fix accepting misspelled desc/asc ordering modificators - @onporat, @steve-chavez\n\n### Changed\n\n- #828, A `SET SCHEMA ` is done on each request, this has the following implications:\n - Computed columns now only work if they belong to the db-schema\n - Stored procedures might require a `search_path` to work properly, for further details see https://postgrest.org/en/v5.0/api.html#explicit-qualification\n- To use RPC now the `json_to_record/json_to_recordset` functions are needed, these are available starting from PostgreSQL 9.4 - @steve-chavez\n- Overloaded functions now depend on the `dbStructure`, restart/sighup may be needed for their correct functioning - @steve-chavez\n- #1098, Removed support for:\n + curly braces `{}` in embeds, i.e. `/clients?select=*,projects{*}` can no longer be used, from now on parens `()` should be used `/clients?select=*,projects(*)` - @steve-chavez\n + \"in\" operator without parens, i.e. `/clients?id=in.1,2,3` no longer supported, `/clients?id=in.(1,2,3)` should be used - @steve-chavez\n + \"@@\", \"@>\" and \"<@\" operators, from now on their mnemonic equivalents should be used \"fts\", \"cs\" and \"cd\" respectively - @steve-chavez\n\n## [0.4.4.0] - 2018-01-08\n\n### Added\n\n- #887, #601, #1007, Allow specifying dictionary and plain/phrase tsquery in full text search - @steve-chavez\n- #328, Allow doing GET on rpc - @steve-chavez\n- #917, Add ability to map RAISE errorcode/message to http status - @steve-chavez\n- #940, Add ability to map GUC to http response headers - @steve-chavez\n- #1022, Include git sha in version report - @begriffs\n- Faster queries using json_agg - @ruslantalpa\n\n### Fixed\n\n- #876, Read secret files as binary, discard final LF if any - @eric-brechemier\n- #968, Treat blank proxy uri as missing - @begriffs\n- #933, OpenAPI externals docs url to current version - @steve-chavez\n- #962, OpenAPI don't err on nonexistent schema - @steve-chavez\n- #954, make OpenAPI rpc output dependent on user privileges - @steve-chavez\n- #955, Support configurable aud claim - @statik\n- #996, Fix embedded column conflicts table name - @grotsev\n- #974, Fix RPC error when function has single OUT param - @steve-chavez\n- #1021, Reduce join size in allColumns for faster program start - @nextstopsun\n- #411, Remove the need for pk in &select for parent embed - @steve-chavez\n- #1016, Fix anonymous requests when configured with jwt-aud - @ruslantalpa\n\n## [0.4.3.0] - 2017-09-06\n\n### Added\n\n- #567, Support more JWT signing algorithms, including RSA - @begriffs\n- #889, Allow more than two conditions in a single and/or - @steve-chavez\n- #883, Binary output support for RPC - @steve-chavez\n- #885, Postgres COMMENTs on SCHEMA/TABLE/COLUMN are used for OpenAPI - @ldesgoui\n- #907, Ability to embed using a specific relation when there are multiple between tables - @ruslantalpa\n- #930, Split table comment on newline to get OpenAPI operation summary and description - @daurnimator\n- #938, Support for range operators - @russelldavies\n\n### Fixed\n\n- #877, Base64 secret read from a file ending with a newline - @eric-brechemier\n- #896, Boolean env var interpolation in config file - @begriffs\n- #885, OpenAPI repetition reduced by using more definitions- @ldesgoui\n- #924, Improve relations initialization time - @9too\n- #927, Treat blank pre-request as missing - @begriffs\n\n### Changed\n\n- #938, Deprecate symbol operators with mnemonic names. - @russelldavies\n\n## [0.4.2.0] - 2017-06-11\n\n### Added\n\n- #742, Add connection retrying on startup and SIGHUP - @steve-chavez\n- #652, Add and/or params for complex boolean logic - @steve-chavez\n- #808, Env var interpolation in config file (helps Docker) - @begriffs\n- #878 - CSV output support for RPC - @begriffs\n\n### Fixed\n\n- #822, Treat blank string JWT secret as no secret - @begriffs\n\n## [0.4.1.0] - 2017-04-25\n\n### Added\n- Allow requesting binary output on GET - @steve-chavez\n- Accept clients requesting `Content-Type: application/json` from / - @feynmanliang\n- #493, Updating with empty JSON object makes zero updates @koulakis\n- Make HTTP headers and cookies available as GUCs #800 - @ruslantalpa\n- #701, Ability to quote values on IN filters - @steve-chavez\n- #641, Allow IN filter to have no values - @steve-chavez\n\n### Fixed\n- #827, Avoid Warp reaper, extend socket timeout to 1 hour - @majorcode\n- #791, malformed nested JSON error - @diogob\n- Resource embedding in views referencing tables in public schema - @fab1an\n- #777, Empty body is allowed when calling a non-parameterized RPC - @koulakis\n- #831, Fix proc resource embedding issue with search_path - @steve-chavez\n- #547, Use read-only transaction for stable/immutable RPC - @begriffs\n\n## [0.4.0.0] - 2017-01-19\n\n### Added\n- Allow test database to be on another host - @dsimunic\n- `Prefer: params=single-object` to treat payload as single json argument in RPC - @dsimunic\n- Ability to generate an OpenAPI spec - @mainx07, @hudayou, @ruslantalpa, @begriffs\n- Ability to generate an OpenAPI spec behind a proxy - @hudayou\n- Ability to set addresses to listen on - @hudayou\n- Filtering, shaping and embedding with &select for the /rpc path - @ruslantalpa\n- Output names of used-defined types (instead of 'USER-DEFINED') - @martingms\n- Implement support for singular representation responses for POST/PATCH requests - @ehamberg\n- Include RPC endpoints in OpenAPI output - @begriffs, @LogvinovLeon\n- Custom request validation with `--pre-request` argument - @begriffs\n- Ability to order by jsonb keys - @steve-chavez\n- Ability to specify offset for a deeper level - @ruslantalpa\n- Ability to use binary base64 encoded secrets - @TrevorBasinger\n\n### Fixed\n- Do not apply limit to parent items - @ruslantalpa\n- Fix bug in relation detection when selecting parents two levels up by using the name of the FK - @ruslantalpa\n- Customize content negotiation per route - @begriffs\n- Allow using nulls order without explicit order direction - @steve-chavez\n- Fatal error on postgres unsupported version, format supported version in error message - @steve-chavez\n- Prevent database memory consumption by prepared statements caches - @ruslantalpa\n- Use specific columns in the RETURNING section - @ruslantalpa\n- Fix columns alias for RETURNING - @steve-chavez\n\n### Changed\n- Replace `Prefer: plurality=singular` with `Accept: application/vnd.pgrst.object` - @begriffs\n- Standardize arrays in responses for `Prefer: return=representation` - @begriffs\n- Calling unknown RPC gives 404, not 400 - @begriffs\n- Use HTTP 400 for raise\\_exception - @begriffs\n- Remove non-OpenAPI schema description - @begriffs\n- Use comma rather than semicolon to separate Prefer header values - @begriffs\n- Omit total query count by default - @begriffs\n- No more reserved `jwt_claims` return type - @begriffs\n- HTTP 401 rather than 400 for expired JWT - @begriffs\n- Remove default JWT secret - @begriffs\n- Use GUC request.jwt.claim.foo rather than postgrest.claims.foo - @begriffs\n- Use config file rather than command line arguments - @begriffs\n\n## [0.3.2.0] - 2016-06-10\n\n### Added\n- Reload database schema on SIGHUP - @begriffs\n- Support \"-\" in column names - @ruslantalpa\n- Support column/node renaming `alias:column` - @ruslantalpa\n- Accept posts from HTML forms - @begriffs\n- Ability to order embedded entities - @ruslantalpa\n- Ability to paginate using &limit and &offset parameters - @ruslantalpa\n- Ability to apply limits to embedded entities and enforce --max-rows on all levels - @ruslantalpa, @begriffs\n- Add allow response header in OPTIONS - @begriffs\n\n### Fixed\n- Return 401 or 403 for access denied rather than 404 - @begriffs\n- Omit Content-Type header for empty body - @begriffs\n- Prevent role from being changed twice - @begriffs\n- Use read-only transaction for read requests - @ruslantalpa\n- Include entities from the same parent table using two different foreign keys - @ruslantalpa\n- Ensure that Location header in 201 response is URL-encoded - @league\n- Fix garbage collector CPU leak - @ruslantalpa et al.\n- Return deleted items when return=representation header is sent - @ruslantalpa\n- Use table default values for empty object inserts - @begriffs\n\n## [0.3.1.1] - 2016-03-28\n\n### Fixed\n- Preserve unicode values in insert,update,rpc (regression) - @begriffs\n- Prevent duplicate call to stored procs (regression) - @begriffs\n- Allow SQL functions to generate registered JWT claims - @begriffs\n- Terminate gracefully on SIGTERM (for use in Docker) - @recmo\n- Relation detection fix for views that depend on multiple tables - @ruslantalpa\n- Avoid count on plurality=singular and allow multiple Prefer values - @ruslantalpa\n\n## [0.3.1.0] - 2016-02-28\n\n### Fixed\n- Prevent query error from infecting later connection - @begriffs, @ruslantalpa, @nikita-volkov, @jwiegley\n\n### Added\n- Applies range headers to RPC calls - @diogob\n\n## [0.3.0.4] - 2016-02-12\n\n### Fixed\n- Improved usage screen - @begriffs\n- Reject non-POSTs to rpc endpoints - @begriffs\n- Throw an error for OPTIONS on nonexistent tables - @calebmer\n- Remove deadlock on simultaneous contentious updates - @ruslantalpa, @begriffs\n\n## [0.3.0.3] - 2016-01-08\n\n### Fixed\n- Fix bug in many-many relation detection - @ruslantalpa\n- Inconsistent escaping of table names in read queries - @calebmer\n\n## [0.3.0.2] - 2015-12-16\n\n### Fixed\n- Miscalculation of time used for expiring tokens - @calebmer\n- Remove bcrypt dependency to fix Windows build - @begriffs\n- Detect relations event when authenticator does not have rights to intermediate tables - @ruslantalpa\n- Ensure db connections released on sigint - @begriffs\n- Fix #396 include records with missing parents - @ruslantalpa\n- `pgFmtIdent` always quotes #388 - @calebmer\n- Default schema, changed from `\"1\"` to `public` - @calebmer\n- #414 revert to separate count query - @ruslantalpa\n- Fix #399, allow inserting in tables with no select privileges using \"Prefer: representation=minimal\" - @ruslantalpa\n\n### Added\n- Allow order by computed columns - @diogob\n- Set max rows in response with --max-rows - @begriffs\n- Selection by column name (can detect if `_id` is not included) - @calebmer\n\n## [0.3.0.1] - 2015-11-27\n\n### Fixed\n- Filter columns on embedded parent items - @ruslantalpa\n\n## [0.3.0.0] - 2015-11-24\n\n### Fixed\n- Use reasonable amount of memory during bulk inserts - @begriffs\n\n### Added\n- Ensure JWT expires - @calebmer\n- Postgres connection string argument - @calebmer\n- Encode JWT for procs that return type `jwt_claims` - @diogob\n- Full text operators `@>`,`<@` - @ruslantalpa\n- Shaping of the response body (filter columns, embed relations) with &select parameter for POST/PATCH - @ruslantalpa\n- Detect relationships between public views and private tables - @calebmer\n- `Prefer: plurality=singular` for selecting single objects - @calebmer\n\n### Removed\n- API versioning feature - @calebmer\n- `--db-x` command line arguments - @calebmer\n- Secure flag - @calebmer\n- PUT request handling - @ruslantalpa\n\n### Changed\n- Embed foreign keys with {} rather than () - @begriffs\n- Remove version number from binary filename in release - @begriffs\n\n## [0.2.12.1] - 2015-11-12\n\n### Fixed\n- Correct order for -> and ->> in a json path - @ruslantalpa\n- Return empty array instead of 500 when a set returning function returns an empty result set - @diogob\n\n## [0.2.12.0] - 2015-10-25\n\n### Added\n- Embed associations, e.g. `/film?select=*,director(*)` - @ruslantalpa\n- Filter columns, e.g. `?select=col1,col2` - @ruslantalpa\n- Does not execute the count total if header \"Prefer: count=none\" - @diogob\n\n### Fixed\n- Tolerate a missing role in user creation - @calebmer\n- Avoid unnecessary text re-encoding - @ruslantalpa\n\n## [0.2.11.1] - 2015-09-01\n\n### Fixed\n- Accepts `*/*` in Accept header - @diogob\n\n## [0.2.11.0] - 2015-08-28\n### Added\n- Negate any filter in a uniform way, e.g. `?col=not.eq=foo` - @diogob\n- Call stored procedures\n- Filter NOT IN values, e.g. `?col=notin.1,2,3` - @rall\n- CSV responses to GET requests with `Accept: text/csv` - @diogob\n- Debian init scripts - @mkhon\n- Allow filters by computed columns - @diogob\n\n### Fixed\n- Reset user role on error\n- Compatible with Stack\n- Add materialized views to results in GET / - @diogob\n- Indicate insertable=true for views that are insertable through triggers - @diogob\n- Builds under GHC 7.10\n- Allow the use of columns named \"count\" in relations queried - @diogob\n\n## [0.2.10.0] - 2015-06-03\n### Added\n- Full text search, eg `/foo?text_vector=@@.bar`\n- Include auth id as well as db role to views (for row-level security)\n\n## [0.2.9.1] - 2015-05-20\n### Fixed\n- Put -Werror behind a cabal flag (for CI) so Hackage accepts package\n\n## [0.2.9.0] - 2015-05-20\n### Added\n- Return range headers in PATCH\n- Return PATCHed resources if header \"Prefer: return=representation\"\n- Allow nested objects and arrays in JSON post for jsonb columns\n- JSON Web Tokens - [Federico Rampazzo](https://github.com/framp)\n- Expose PostgREST as a Haskell package\n\n### Fixed\n- Return 404 if no records updated by PATCH\n\n## [0.2.8.0] - 2015-04-17\n### Added\n- Option to specify nulls first or last, eg `/people?order=age.desc.nullsfirst`\n- Filter nulls, `?col=is.null` and `?col=isnot.null`\n- Filter within jsonb, `?col->a->>b=eq.c`\n- Accept CSV in post body for bulk inserts\n\n### Fixed\n- Allow NULL values in posts\n- Show full command line usage on param errors\n\n## [0.2.7.0] - 2015-03-03\n### Added\n- Server response logging\n- Filter IN values, e.g. `?col=in.1,2,3`\n- Return POSTed resource if header \"Prefer: return=representation\"\n- Allow override of default (v1) schema\n\n## [0.2.6.0] - 2015-02-18\n### Added\n- A changelog\n- Filter by substring match, e.g. `?col=like.*hello*` (or ilike for\n case insensitivity).\n- Access-Control-Expose-Headers for CORS\n\n### Fixed\n- Make filter position match docs, e.g. `?order=col.asc` rather\n than `?order=asc.col`.\n" }, { "path": "CODE_OF_CONDUCT.md", "content": "\n# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nWe as members, contributors, and leaders pledge to make participation in our\ncommunity a harassment-free experience for everyone, regardless of age, body\nsize, visible or invisible disability, ethnicity, sex characteristics, gender\nidentity and expression, level of experience, education, socio-economic status,\nnationality, personal appearance, race, caste, color, religion, or sexual identity\nand orientation.\n\nWe pledge to act and interact in ways that contribute to an open, welcoming,\ndiverse, inclusive, and healthy community.\n\n## Our Standards\n\nExamples of behavior that contributes to a positive environment for our\ncommunity include:\n\n* Demonstrating empathy and kindness toward other people\n* Being respectful of differing opinions, viewpoints, and experiences\n* Giving and gracefully accepting constructive feedback\n* Accepting responsibility and apologizing to those affected by our mistakes,\n and learning from the experience\n* Focusing on what is best not just for us as individuals, but for the\n overall community\n\nExamples of unacceptable behavior include:\n\n* The use of sexualized language or imagery, and sexual attention or\n advances of any kind\n* Trolling, insulting or derogatory comments, and personal or political attacks\n* Public or private harassment\n* Publishing others' private information, such as a physical or email\n address, without their explicit permission\n* Other conduct which could reasonably be considered inappropriate in a\n professional setting\n\n## Enforcement Responsibilities\n\nCommunity leaders are responsible for clarifying and enforcing our standards of\nacceptable behavior and will take appropriate and fair corrective action in\nresponse to any behavior that they deem inappropriate, threatening, offensive,\nor harmful.\n\nCommunity leaders have the right and responsibility to remove, edit, or reject\ncomments, commits, code, wiki edits, issues, and other contributions that are\nnot aligned to this Code of Conduct, and will communicate reasons for moderation\ndecisions when appropriate.\n\n## Scope\n\nThis Code of Conduct applies within all community spaces, and also applies when\nan individual is officially representing the community in public spaces.\nExamples of representing our community include using an official e-mail address,\nposting via an official social media account, or acting as an appointed\nrepresentative at an online or offline event.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be\nreported to the community leaders responsible for enforcement at support@postgrest.org.\nAll complaints will be reviewed and investigated promptly and fairly.\n\nAll community leaders are obligated to respect the privacy and security of the\nreporter of any incident.\n\n## Enforcement Guidelines\n\nCommunity leaders will follow these Community Impact Guidelines in determining\nthe consequences for any action they deem in violation of this Code of Conduct:\n\n### 1. Correction\n\n**Community Impact**: Use of inappropriate language or other behavior deemed\nunprofessional or unwelcome in the community.\n\n**Consequence**: A private, written warning from community leaders, providing\nclarity around the nature of the violation and an explanation of why the\nbehavior was inappropriate. A public apology may be requested.\n\n### 2. Warning\n\n**Community Impact**: A violation through a single incident or series\nof actions.\n\n**Consequence**: A warning with consequences for continued behavior. No\ninteraction with the people involved, including unsolicited interaction with\nthose enforcing the Code of Conduct, for a specified period of time. This\nincludes avoiding interactions in community spaces as well as external channels\nlike social media. Violating these terms may lead to a temporary or\npermanent ban.\n\n### 3. Temporary Ban\n\n**Community Impact**: A serious violation of community standards, including\nsustained inappropriate behavior.\n\n**Consequence**: A temporary ban from any sort of interaction or public\ncommunication with the community for a specified period of time. No public or\nprivate interaction with the people involved, including unsolicited interaction\nwith those enforcing the Code of Conduct, is allowed during this period.\nViolating these terms may lead to a permanent ban.\n\n### 4. Permanent Ban\n\n**Community Impact**: Demonstrating a pattern of violation of community\nstandards, including sustained inappropriate behavior, harassment of an\nindividual, or aggression toward or disparagement of classes of individuals.\n\n**Consequence**: A permanent ban from any sort of public interaction within\nthe community.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage],\nversion 2.0, available at\n[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0].\n\nCommunity Impact Guidelines were inspired by\n[Mozilla's code of conduct enforcement ladder][Mozilla CoC].\n\nFor answers to common questions about this code of conduct, see the FAQ at\n[https://www.contributor-covenant.org/faq][FAQ]. Translations are available\nat [https://www.contributor-covenant.org/translations][translations].\n\n[homepage]: https://www.contributor-covenant.org\n[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html\n[Mozilla CoC]: https://github.com/mozilla/diversity\n[FAQ]: https://www.contributor-covenant.org/faq\n[translations]: https://www.contributor-covenant.org/translations\n" }, { "path": "CONTRIBUTING.md", "content": "# Contributing to PostgREST\n\n## Issues\n\nFor questions on how to use PostgREST, please use\n[GitHub discussions](https://github.com/PostgREST/postgrest/discussions).\n\n### Reporting an Issue\n\n* Make sure you test against the latest [stable release](https://github.com/PostgREST/postgrest/releases/latest)\n and also against the latest [devel release](https://github.com/PostgREST/postgrest/releases/tag/devel).\n It is possible we already fixed the bug you're experiencing.\n\n* Provide steps to reproduce the issue, including your OS version and\n the specific database schema that you are using.\n\n* Please include SQL logs for issues involving runtime problems. To obtain logs first\n [enable logging all statements](http://www.microhowto.info/howto/log_all_queries_to_a_postgresql_server.html),\n then [find your logs](http://blog.endpoint.com/2014/11/dear-postgresql-where-are-my-logs.html).\n\n* If your database schema has changed while the PostgREST server is running,\n [send the server a `SIGUSR1` signal](http://postgrest.org/en/latest/admin.html#schema-reloading) or restart it to ensure the schema cache\n is not stale. This sometimes fixes apparent bugs.\n\n## Code\n\nWe have a fully nix-based development environment with many tools for a smooth development workflow available.\nCheck the [development docs](https://github.com/PostgREST/postgrest/blob/main/nix/README.md) on how to set it up and use it.\n\n* All contributions must pass the tests before being merged. When\n you create a pull request your code will automatically be tested.\n\n* All fixes or features must have a test proving the improvement.\n\n* All code must also pass a [linter](http://community.haskell.org/~ndm/hlint/) and [styler](https://github.com/jaspervdj/stylish-haskell)\n with no warnings. This helps enforce a uniform style for all committers. Continuous integration will check this as well on every\n pull request. There are useful tools in the nix-shell that help with checking this locally. You can run `postgrest-check` to do this manually but\n we recommend adding it to `.git/hooks/pre-commit` as `nix-shell --run postgrest-check` to automatically check this before doing a commit.\n\n### Running Tests\n\nFor instructions on running tests, see the [development docs](https://github.com/PostgREST/postgrest/blob/main/nix/README.md#testing).\n\n### Structuring commits in pull requests\n\nTo simplify reviews, make it easy to split pull requests if deemed necessary, and to maintain clean and meaningful history of changes, you will be asked to update your PR if it does not follow the below rules:\n\n* It must be possible to merge the PR branch into target using `git merge --ff-only`, ie. the source branch must be rebased on top of target.\n* No merge commits in the source branch.\n* All commits in the source branch must be self contained, meaning: it should be possible to treat each commit as a separate PR.\n* Commits in the source branch must contain only related changes (related means the changes target a single problem/goal). For example, any refactorings should be isolated from the actual change implementation into separate commits.\n* Tests, documentation, and changelog updates should be contained in the same commits as the actual code changes they relate to. An exception to this rule is when test or documentation changes are made in separate PR.\n* Commit messages must be prefixed with one of the prefixes defined in [the list used by commit verification scripts](https://github.com/PostgREST/postgrest/blob/main/nix/tools/gitTools.nix#L11).\n* Commit messages should contain a longer description of the purpose of the changes contained in the commit and, for non-trivial changes, a description of the changes themselves.\n\n## AI Policy\n\nWe adhere to [Gentoo's AI policy](https://wiki.gentoo.org/wiki/Project:Council/AI_policy):\n\n> It is expressly forbidden to contribute [...] any content that has been created with the assistance of Natural Language Processing artificial intelligence tools. This motion can be revisited, should a case been made over such a tool that does not pose copyright, ethical and quality concerns.\n\nYou can find more about its rationale [here](https://wiki.gentoo.org/wiki/Project:Council/AI_policy#Rationale).\n" }, { "path": "Dockerfile", "content": "# PostgREST Docker Hub image for aarch64.\n# The x86-64 is a single-static-binary image built via Nix, see:\n# nix/tools/docker/README.md\n\nFROM ubuntu:noble@sha256:186072bba1b2f436cbb91ef2567abca677337cfc786c86e107d25b7072feef0c AS postgrest\n\nRUN apt-get update -y \\\n && apt install -y --no-install-recommends libpq-dev zlib1g-dev jq gcc libnuma-dev \\\n && apt-get clean \\\n && rm -rf /var/lib/apt/lists/*\n\nCOPY postgrest /usr/bin/postgrest\nRUN chmod +x /usr/bin/postgrest\n\nEXPOSE 3000\n\nUSER 1000\n\n# Use the array form to avoid running the command using bash, which does not handle `SIGTERM` properly. \n# See https://docs.docker.com/compose/faq/#why-do-my-services-take-10-seconds-to-recreate-or-stop \nCMD [\"postgrest\"]\n" }, { "path": "LICENSE", "content": "Copyright (c) 2014-2026 The PostgREST contributors\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n\"Software\"), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be included\nin all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n" }, { "path": "README.md", "content": "![Logo](static/postgrest.png \"Logo\")\n\n[![Donate](https://img.shields.io/badge/Donate-Patreon-orange.svg?colorB=F96854)](https://www.patreon.com/postgrest)\n[![Docs](https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat)](http://postgrest.org)\n[![Docker Stars](https://img.shields.io/docker/pulls/postgrest/postgrest.svg)](https://hub.docker.com/r/postgrest/postgrest/)\n[![Build Status](https://github.com/postgrest/postgrest/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/PostgREST/postgrest/actions?query=branch%3Amain)\n[![Coverage Status](https://img.shields.io/codecov/c/github/postgrest/postgrest/main)](https://app.codecov.io/gh/PostgREST/postgrest)\n[![Hackage docs](https://img.shields.io/hackage/v/postgrest.svg?label=hackage)](http://hackage.haskell.org/package/postgrest)\n\nPostgREST serves a fully RESTful API from any existing PostgreSQL\ndatabase. It provides a cleaner, more standards-compliant, faster\nAPI than you are likely to write from scratch.\n\n## Sponsors\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n \n \n \n \n
\n\nBig thanks to our sponsors! You can join them by supporting PostgREST on [Patreon](https://www.patreon.com/postgrest).\n\n## Usage\n\n1. See the docs for [how to install PostgREST on your platform](https://docs.postgrest.org/en/stable/explanations/install.html). You can also [use Docker](https://docs.postgrest.org/en/stable/explanations/install.html#docker).\n\n2. Invoke for help:\n\n ```bash\n postgrest --help\n ```\n## [Documentation](http://postgrest.org)\n\nLatest documentation is at [postgrest.org](http://postgrest.org). You can contribute to the docs in [PostgREST/postgrest/docs](https://github.com/PostgREST/postgrest/tree/main/docs).\n\n## Performance\n\nTLDR; subsecond response times for up to 2000 requests/sec on Heroku\nfree tier. If you're used to servers written in interpreted languages,\nprepare to be pleasantly surprised by PostgREST performance.\n\nThree factors contribute to the speed. First the server is written\nin [Haskell](https://www.haskell.org/) using the\n[Warp](http://www.yesodweb.com/blog/2011/03/preliminary-warp-cross-language-benchmarks)\nHTTP server (aka a compiled language with lightweight threads).\nNext it delegates as much calculation as possible to the database\nincluding\n\n* Serializing JSON responses directly in SQL\n* Data validation\n* Authorization\n* Combined row counting and retrieval\n* Data post in single command (`returning *`)\n\nFinally it uses the database efficiently with the\n[Hasql](https://nikita-volkov.github.io/hasql-benchmarks/) library\nby\n\n* Keeping a pool of db connections\n* Using the PostgreSQL binary protocol\n* Being stateless to allow horizontal scaling\n\n## Security\n\nPostgREST [handles\nauthentication](http://postgrest.org/en/stable/auth.html) (via JSON Web\nTokens) and delegates authorization to the role information defined in\nthe database. This ensures there is a single declarative source of truth\nfor security. When dealing with the database the server assumes the\nidentity of the currently authenticated user, and for the duration of\nthe connection cannot do anything the user themselves couldn't. Other\nforms of authentication can be built on top of the JWT primitive. See\nthe docs for more information.\n\n## Versioning\n\nA robust long-lived API needs the freedom to exist in multiple\nversions. PostgREST does versioning through database schemas. This\nallows you to expose tables and views without making the app brittle.\nUnderlying tables can be superseded and hidden behind public facing\nviews.\n\n## Self-documentation\n\nPostgREST uses the [OpenAPI](https://openapis.org/) standard to\ngenerate up-to-date documentation for APIs. You can use a tool like\n[Swagger-UI](https://github.com/swagger-api/swagger-ui) to render\ninteractive documentation for demo requests against the live API server.\n\nThis project uses HTTP to communicate other metadata as well. For\ninstance the number of rows returned by an endpoint is reported by -\nand limited with - range headers. More about\n[that](http://begriffs.com/posts/2014-03-06-beyond-http-header-links.html).\n\n## Data Integrity\n\nRather than relying on an Object Relational Mapper and custom\nimperative coding, this system requires you to put declarative constraints\ndirectly into your database. Hence no application can corrupt your\ndata (including your API server).\n\nThe PostgREST exposes HTTP interface with safeguards to prevent\nsurprises, such as enforcing idempotent PUT requests.\n\nSee examples of [PostgreSQL\nconstraints](http://www.tutorialspoint.com/postgresql/postgresql_constraints.htm)\nand the [API guide](http://postgrest.org/en/stable/api.html).\n\n## Supporting development\n\nYou can help PostgREST ongoing maintenance and development by making a regular donation through Patreon https://www.patreon.com/postgrest\n\nEvery donation will be spent on making PostgREST better for the whole community.\n\n## Contributing\n\nContributions are always welcome and appreciated. Please see the [Contributing guidelines](https://github.com/PostgREST/postgrest/blob/main/CONTRIBUTING.md).\n\n## Thanks\n\nThe PostgREST organization is grateful to:\n\n- The project [sponsors and backers](https://github.com/PostgREST/postgrest/blob/main/BACKERS.md) who support PostgREST's development.\n- The project [contributors](https://github.com/PostgREST/postgrest/graphs/contributors) who have improved PostgREST immensely with their code\n and good judgement. See more details in the [changelog](https://github.com/PostgREST/postgrest/blob/main/CHANGELOG.md).\n\nThe cool logo came from [Mikey Casalaina](https://github.com/casalaina).\n" }, { "path": "Setup.hs", "content": "-- This file is required by Hackage.\nimport Distribution.Simple\nmain = defaultMain\n" }, { "path": "cabal.project", "content": "packages: postgrest.cabal\ntests: true\n" }, { "path": "cabal.project.freeze", "content": "index-state: hackage.haskell.org 2025-10-29T04:02:18Z\n" }, { "path": "default.nix", "content": "{ system ? builtins.currentSystem\n\n, compiler ? \"ghc948\"\n\n, # Commit of the Nixpkgs repository that we want to use.\n # It defaults to reading the inputs from flake.lock, which serves\n # as a compatibility layer for non-flake builds / default.nix / shell.nix.\n nixpkgsVersion ? let\n lock = builtins.fromJSON (builtins.readFile ./flake.lock);\n in\n {\n inherit (lock.nodes.nixpkgs.locked) owner repo rev;\n tarballHash = lock.nodes.nixpkgs.locked.narHash;\n }\n\n, # Nix files that describe the Nixpkgs repository. We evaluate the expression\n # using `import` below.\n nixpkgs ? let inherit (nixpkgsVersion) owner repo rev tarballHash; in\n builtins.fetchTarball {\n url = \"https://github.com/${owner}/${repo}/archive/${rev}.tar.gz\";\n sha256 = tarballHash;\n }\n}:\n\nlet\n name =\n \"postgrest\";\n\n # PostgREST source files, filtered based on the rules in the .gitignore files\n # and file extensions. We want to include as little as possible, as the files\n # added here will increase the space used in the Nix store and trigger the\n # build of new Nix derivations when changed.\n src =\n pkgs.lib.sourceFilesBySuffices\n (pkgs.gitignoreSource ./.)\n [ \".cabal\" \".hs\" \".lhs\" \"LICENSE\" ];\n\n allOverlays =\n import nix/overlays;\n\n overlays =\n [\n allOverlays.build-toolbox\n allOverlays.checked-shell-script\n allOverlays.gitignore\n (allOverlays.haskell-packages { inherit compiler; })\n ];\n\n # Evaluated expression of the Nixpkgs repository.\n pkgs =\n import nixpkgs { inherit overlays system; };\n\n postgresqlVersions =\n [\n { name = \"pg-17\"; postgresql = pkgs.postgresql_17.withPackages (p: [ p.postgis p.pg_safeupdate ]); }\n { name = \"pg-16\"; postgresql = pkgs.postgresql_16.withPackages (p: [ p.postgis p.pg_safeupdate ]); }\n { name = \"pg-15\"; postgresql = pkgs.postgresql_15.withPackages (p: [ p.postgis p.pg_safeupdate ]); }\n { name = \"pg-14\"; postgresql = pkgs.postgresql_14.withPackages (p: [ p.postgis p.pg_safeupdate ]); }\n { name = \"pg-13\"; postgresql = pkgs.postgresql_13.withPackages (p: [ p.postgis p.pg_safeupdate ]); }\n ];\n\n haskellPackages = pkgs.haskell.packages.\"${compiler}\";\n\n # Dynamic derivation for PostgREST\n postgrest = pkgs.lib.pipe (haskellPackages.callCabal2nix name src { }) [\n # To allow ghc-datasize to be used.\n lib.disableLibraryProfiling\n # We are never going to use dynamic haskell libraries anyway. \"Dynamic\" refers to how\n # non-haskell deps are linked. All haskell dependencies are always statically linked.\n lib.disableSharedLibraries\n ];\n\n staticHaskellPackage = import nix/static.nix { inherit compiler name pkgs src; };\n\n # Options passed to cabal in dev tools and tests\n devCabalOptions =\n \"-f dev --test-show-detail=direct\";\n\n inherit (pkgs.haskell) lib;\nin\nrec {\n inherit nixpkgs pkgs;\n\n # Derivation for the PostgREST Haskell package, including the executable,\n # libraries and documentation. We disable running the test suite on Nix\n # builds, as they require a database to be set up. We split the binary\n # into a separate output, so that the default distribution via flake.nix\n # has a much smaller closure size.\n postgrestPackage = pkgs.lib.pipe postgrest [\n lib.dontCheck\n lib.enableSeparateBinOutput\n (haskellPackages.generateOptparseApplicativeCompletions [ \"postgrest\" ])\n ];\n\n # Profiled dynamic executable.\n postgrestProfiled = pkgs.lib.pipe postgrestPackage [\n lib.enableExecutableProfiling\n lib.enableLibraryProfiling\n lib.dontHaddock\n ];\n\n inherit (postgrest) env;\n\n # Tooling for analyzing Haskell imports and exports.\n hsie =\n pkgs.callPackage nix/hsie {\n inherit (pkgs.haskell.packages.\"${compiler}\") ghcWithPackages;\n };\n\n ### Tools\n\n cabalTools =\n pkgs.callPackage nix/tools/cabalTools.nix { inherit devCabalOptions postgrest; };\n\n withTools =\n pkgs.callPackage nix/tools/withTools.nix { inherit postgresqlVersions postgrest; };\n\n # Development tools.\n devTools =\n pkgs.callPackage nix/tools/devTools.nix { inherit tests style devCabalOptions hsie withTools; };\n\n # Documentation tools.\n docs =\n pkgs.callPackage nix/tools/docs.nix { };\n\n # Git tools.\n gitTools =\n pkgs.callPackage nix/tools/gitTools.nix { };\n\n # Load testing tools.\n loadtest =\n pkgs.callPackage nix/tools/loadtest.nix { inherit withTools; };\n\n # Utility for updating the pinned version of Nixpkgs.\n nixpkgsTools =\n pkgs.callPackage nix/tools/nixpkgsTools.nix { };\n\n # Scripts for publishing new releases.\n release =\n pkgs.callPackage nix/tools/release.nix { };\n\n # Linting and styling tools.\n style =\n pkgs.callPackage nix/tools/style.nix { inherit hsie; };\n\n # Scripts for running tests.\n tests =\n pkgs.callPackage nix/tools/tests.nix {\n inherit postgrest devCabalOptions withTools;\n ghc = pkgs.haskell.compiler.\"${compiler}\";\n inherit (pkgs.haskell.packages.\"${compiler}\") hpc-codecov;\n inherit (pkgs.haskell.packages.\"${compiler}\") weeder;\n };\n} // pkgs.lib.optionalAttrs pkgs.stdenv.isLinux rec {\n # Static executable.\n inherit (staticHaskellPackage) postgrestStatic;\n inherit (staticHaskellPackage) packagesStatic;\n\n # Docker images and loading script.\n docker =\n pkgs.callPackage nix/tools/docker { postgrest = postgrestStatic; };\n}\n" }, { "path": "docker-hub-readme.md", "content": "# PostgREST\n\n[![Donate](https://img.shields.io/badge/Donate-Patreon-orange.svg?colorB=F96854)](https://www.patreon.com/postgrest)\n[![Docs](https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat)](http://postgrest.org)\n[![Build Status](https://github.com/postgrest/postgrest/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/PostgREST/postgrest/actions?query=branch%3Amain)\n\nPostgREST serves a fully RESTful API from any existing PostgreSQL database. It\nprovides a cleaner, more standards-compliant, faster API than you are likely to\nwrite from scratch.\n\n## Sponsors\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n \n \n \n \n
\n\n# Usage\n\nTo learn how to use this container, see the [PostgREST Docker\ndocumentation](https://postgrest.org/en/stable/install.html#docker).\n\nYou can configure the PostgREST image by setting\n[environment variables](https://postgrest.org/en/stable/configuration.html).\n\n# How this image is built\n\nThe image is built from scratch using\n[Nix](https://nixos.org/nixpkgs/manual/#sec-pkgs-dockerTools) instead of a\n`Dockerfile`, which yields a highly secure and optimized image. This is also why\nno commands are listed in the image history. See the [PostgREST\nrepository](https://github.com/PostgREST/postgrest/tree/main/nix/tools/docker) for\ndetails on the build process and how to inspect the image.\n\nThis does not apply to the arm64 variant, which is based on Ubuntu.\n" }, { "path": "docs/.gitignore", "content": "_build\nPipfile.lock\n*.aux\n*.log\n_diagrams/db.pdf\nmisspellings\nunuseddict\n*.mo\n" }, { "path": "docs/README.md", "content": "# PostgREST documentation https://postgrest.org/\n\nPostgREST docs use the reStructuredText format, check this [cheatsheet](https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst) to get acquainted with it.\n\nTo build the docs locally, see [the Nix development readme](/nix/README.md#documentation).\n\n## Documentation structure\n\nThis documentation is structured according to tutorials-howtos-topics-references. For more details on the rationale of this structure, \nsee https://www.divio.com/blog/documentation.\n\n## Translating\n\nTo create `.po` files for translation into a new language pass the language code as the first argument to `postgrest-docs-build`.\n\nExample to add German/de:\n\n```\npostgrest-docs-build de\n```\n\nThe livereload server also supports a language/locale argument to show the translated docs during translation:\n\n```\npostgrest-docs-serve de\n```\n\nSpellcheck is currently only available for the default language.\n" }, { "path": "docs/_diagrams/README.md", "content": "## ERD\n\nThe ER diagrams were created with https://github.com/BurntSushi/erd/.\n\nYou can go download erd from https://github.com/BurntSushi/erd/releases and then do:\n\n```bash\n./erd_static-x86-64 -i ./er/film.er -o ../_static/film.png\n```\n\nThe fonts used belong to the GNU FreeFont family. You can download them here: http://ftp.gnu.org/gnu/freefont/\n\n## UML\n\nThe UML diagrams are created with https://plantuml.com/.\n\nPlantUML only creates one diagram per file.\nThat's why we need to create another one for dark mode.\nFor example, for the file [uml/arch.uml](uml/arch.uml) there's [uml/dark/arch-dark.uml](uml/dark/arch-dark.uml) which includes the first one:\n\n```bash\nplantuml -tsvg uml/arch.uml -o ../../_static\nplantuml -tsvg -darkmode uml/dark/arch-dark.uml -o ../../../_static\n```\n" }, { "path": "docs/_diagrams/er/boxoffice.er", "content": "entity {font: \"FreeSans\"}\nrelationship {font: \"FreeMono\"}\n\n[Box_Office]\n*bo_date\n*+film_id\ngross_revenue\n\n[Films]\n*id\n+director_id\ntitle\n`...`\n\nBox_Office +--1 Films\n" }, { "path": "docs/_diagrams/er/employees.er", "content": "# Build using: -e ortho\n\nentity {font: \"FreeSans\"}\nrelationship {font: \"FreeMono\"}\n\n[Employees]\n*id\nfirst_name\nlast_name\n+supervisor_id\n\nEmployees 1--* Employees\n" }, { "path": "docs/_diagrams/er/film.er", "content": "entity {font: \"FreeSans\"}\nrelationship {font: \"FreeSerif\"}\n\n[Films]\n*id\n+director_id\ntitle\nyear\nrating\nlanguage\n\n[Directors]\n*id\nfirst_name\nlast_name\n\n[Actors]\n*id\nfirst_name\nlast_name\n\n[Roles]\n*+film_id\n*+actor_id\ncharacter\n\n[Competitions]\n*id\nname\nyear\n\n[Nominations]\n*+competition_id\n*+film_id\nrank\n\n[Technical_Specs]\n*+film_id\nruntime\ncamera\nsound\n\nRoles *--1 Actors\nRoles *--1 Films\n\nNominations *--1 Competitions\nNominations *--1 Films\n\nFilms *--1 Directors\n\nFilms 1--1 Technical_Specs\n" }, { "path": "docs/_diagrams/er/orders.er", "content": "# Build using: -e ortho\n\nentity {font: \"FreeSans\"}\nrelationship {font: \"FreeMono\"}\n\n[Addresses]\n*id\nname\ncity\nstate\npostal_code\n\n[Orders]\n*id\nname\n+billing_address_id\n+shipping_address_id\n\nOrders *--1 Addresses\nOrders *--1 Addresses\n" }, { "path": "docs/_diagrams/er/premieres.er", "content": "entity {font: \"FreeSans\"}\nrelationship {font: \"FreeMono\"}\n\n[Premieres]\n*id\nlocation\ndate\n+film_id\n\n[Films]\n*id\n+director_id\ntitle\n`...`\n\nPremieres *--1 Films\n" }, { "path": "docs/_diagrams/er/presidents.er", "content": "# Build using: -e ortho\n\nentity {font: \"FreeSans\"}\nrelationship {font: \"FreeMono\"}\n\n[Presidents]\n*id\nfirst_name\nlast_name\n+predecessor_id\n\nPresidents 1--? Presidents\n" }, { "path": "docs/_diagrams/er/users.er", "content": "# Build using: -e ortho\n\nentity {font: \"FreeSans\"}\nrelationship {font: \"FreeMono\"}\n\n[Users]\n*id\nfirst_name\nlast_name\nusername\n\n[Subscriptions]\n*+subscriber_id\n*+subscribed_id\ntype\n\nUsers 1--* Subscriptions\nSubscriptions *--1 Users\n" }, { "path": "docs/_diagrams/uml/arch.uml", "content": "@startuml\n\nskinparam backgroundColor transparent\n\npackage \"PostgREST\" {\n () HTTP as HTTPAPI\n HTTPAPI - [Auth]\n [Auth] -r.> [ApiRequest]\n [ApiRequest] -r.> [Plan]\n [Plan] -r.> [Query]\n [Query] - () \"Connection Pool\" : \"\\t\"\n [Plan] -u-> [Schema Cache]:uses\n [Schema Cache] <- () Listener : reloads\n\n () HTTP as HTTPADMIN\n [Admin] -r- () HTTPADMIN\n [Config] -l- () CLI\n\n [Config] <-r~ Listener\n\n HTTPADMIN -[hidden]r- CLI\n [Schema Cache] -l[hidden]- [Config]\n [Schema Cache] -l[hidden]- [Admin]\n [Schema Cache] -l[hidden]- CLI\n}\n\n\ndatabase \"PostgreSQL\" {\n node Authorization {\n rectangle \"Roles, GRANT, RLS\"\n }\n node \"API schema\" as API {\n rectangle \"Functions, Views\"\n }\n rectangle \"Tables, extensions\" as tbs\n API -d- tbs\n\n API -l[hidden]- Authorization\n}\n\n:user:\nhexagon Proxy\n:user: .r-> Proxy : request with JWT\nHTTPAPI <.l- Proxy\n\nhexagon ExternalAuth\nExternalAuth -u[hidden]- Proxy\n:user: .r-> ExternalAuth : login\n:user: <.r- ExternalAuth : JWT\n\n:operator: .d-> HTTPADMIN\n:operator: .d-> CLI\n\n\nPostgreSQL <.developer : \"\\t\"\nListener -r.> \"PostgreSQL\"\n\"Connection Pool\" -r.> \"PostgreSQL\" : \"\\t\\t\"\n\nnote bottom of Auth\n Validates the JWT\nend note\n\nnote bottom of ApiRequest\n Parses the URL syntax\nend note\n\nnote bottom of Plan\n Generates internal AST\nend note\n\nnote bottom of Query\n Generates the SQL\nend note\n\nnote top of Listener\n LISTEN session\nend note\n\nurl of ExternalAuth is [[../explanations/external_auth.html]]\nurl of Admin is [[../references/admin_server.html#admin-server]]\nurl of API is [[../explanations/schema_isolation.html]]\nurl of Auth is [[../references/auth.html#authn]]\nurl of ApiRequest is [[../explanations/architecture.html#api-request]]\nurl of Plan is [[../explanations/architecture.html#plan]]\nurl of Query is [[../explanations/architecture.html#query]]\nurl of Authorization is [[../explanations/db_authz.html]]\nurl of CLI is [[../references/cli.html#cli]]\nurl of \"Connection Pool\" is [[../references/connection_pool.html]]\nurl of Config is [[../references/configuration.html#configuration]]\nurl of HTTPADMIN is [[../explanations/architecture.html#http]]\nurl of HTTPAPI is [[../explanations/architecture.html#http]]\nurl of Listener is [[../references/listener.html#listener]]\nurl of Proxy is [[../explanations/nginx.html]]\nurl of \"Schema Cache\" is [[../references/schema_cache.html#schema-cache]]\n\n@enduml\n" }, { "path": "docs/_diagrams/uml/dark/arch-dark.uml", "content": "@startuml\n!include ../arch.uml\n@enduml\n" }, { "path": "docs/_diagrams/uml/dark/sch-iso-dark.uml", "content": "@startuml\n!include ../sch-iso.uml\n@enduml\n" }, { "path": "docs/_diagrams/uml/sch-iso.uml", "content": "@startuml\n\nskinparam backgroundColor transparent\nskinparam linetype ortho\n\nskinparam node {\n backgroundColor transparent\n borderThickness 1\n}\n\ndatabase \"PostgreSQL\" {\n node public {\n rectangle tables_public as \"tables\"\n }\n\n node extensions as \"**extensions**\" {\n }\n\n node API as \"api\" {\n rectangle vf_api as \"views + functions\"\n }\n\n tables_public <-- vf_api\n extensions <-- vf_api\n}\n\nvf_api <-[thickness=3]-> () PostgREST\n\n@enduml\n" }, { "path": "docs/_static/css/custom.css", "content": ".wy-nav-content {\n max-width: initial;\n}\n\n#postgrest-documentation > h1 {\n display: none;\n}\n\ndiv.wy-menu.rst-pro {\n display: none !important;\n}\n\ndiv.highlight {\n background: #fff !important;\n}\n\ndiv.line-block {\n margin-bottom: 0px !important;\n}\n\n#sponsors {\n text-align: center;\n}\n\n#sponsors h2 {\n text-align: left;\n}\n\n#sponsors img{\n margin: 10px;\n width: 13em; /* \".. image::\" does not apply width properly to SVGs */\n}\n\n#thanks{\n text-align: center;\n}\n\n#thanks img{\n margin: 10px;\n}\n\n#thanks h2{\n text-align: left;\n}\n\n#thanks p{\n text-align: left;\n}\n\n#thanks ul{\n text-align: left;\n}\n\n.image-container {\n max-width: 800px;\n display: block;\n margin-left: auto;\n margin-right: auto;\n margin-bottom: 24px;\n}\n\n.wy-table-responsive table td {\n white-space: normal !important;\n}\n\n.wy-table-responsive {\n overflow: visible !important;\n}\n\n#tutorials span.caption-text {\n display: none;\n}\n\n#references span.caption-text {\n display: none;\n}\n\n#explanations span.caption-text {\n display: none;\n}\n\n#how-tos span.caption-text {\n display: none;\n}\n\n#ecosystem span.caption-text {\n display: none;\n}\n\n#integrations span.caption-text {\n display: none;\n}\n\n#api span.caption-text {\n display: none;\n}\n\n/* Tweaks for dark mode from extension: sphinx-rtd-dark-theme */\n\nhtml[data-theme=\"dark\"] .highlight {\n background-color: #17181c !important;\n}\n\nhtml[data-theme=\"dark\"] .sphinx-tabs-tab {\n color: var(--dark-link-color);\n}\n\nhtml[data-theme=\"dark\"] .sphinx-tabs-panel {\n border: 1px solid #404040;\n border-top: 0;\n background: #141414;\n}\n\nhtml[data-theme=\"dark\"] .sphinx-tabs-tab[aria-selected=\"true\"] {\n border: 1px solid #404040;\n border-bottom: 1px solid #141414;\n background-color: #141414;\n}\n\nhtml[data-theme=\"dark\"] [role=\"tablist\"] {\n border-bottom: 1px solid #404040;\n}\n\nhtml[data-theme=\"dark\"] .btn-neutral {\n color: white !important;\n}\n\nhtml[data-theme=\"dark\"] .img-dark {\n display: inline;\n}\n\nhtml:not([data-theme=\"dark\"]) .img-dark {\n display: none;\n}\n\nhtml[data-theme=\"dark\"] .img-light {\n display: none;\n}\n\nhtml:not([data-theme=\"dark\"]) .img-light {\n display: inline;\n}\n\nhtml[data-theme=\"dark\"] .img-translucent img {\n background-color: #cccccc;\n}\n\n.img-translucent img {\n transition: background-color 0.3s;\n margin-bottom: 24px;\n}\n\n.svg-container-md {\n max-width: 400px;\n}\n" }, { "path": "docs/conf.py", "content": "# -*- coding: utf-8 -*-\n#\n# PostgREST documentation build configuration file, created by\n# sphinx-quickstart on Sun Oct 9 16:53:00 2016.\n#\n# This file is execfile()d with the current directory set to its\n# containing dir.\n#\n# Note that not all possible configuration values are present in this\n# autogenerated file.\n#\n# All configuration values have a default; values that are commented out\n# serve to show the default.\n\nimport os\n\n# If extensions (or modules to document with autodoc) are in another directory,\n# add these directories to sys.path here. If the directory is relative to the\n# documentation root, use os.path.abspath to make it absolute, like shown here.\n# sys.path.insert(0, os.path.abspath('.'))\n\n# -- General configuration ------------------------------------------------\n\n# If your documentation needs a minimal Sphinx version, state it here.\n# needs_sphinx = '1.0'\n\n# Add any Sphinx extension module names here, as strings. They can be\n# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom\n# ones.\nextensions = [\n \"sphinx_tabs.tabs\",\n \"sphinx_copybutton\",\n \"sphinxext.opengraph\",\n \"sphinx_rtd_dark_mode\",\n]\n\n# Add any paths that contain templates here, relative to this directory.\ntemplates_path = [\"_templates\"]\n\n# The suffix(es) of source filenames.\n# You can specify multiple suffix as a list of string:\n# source_suffix = ['.rst', '.md']\nsource_suffix = \".rst\"\n\n# The encoding of source files.\n# source_encoding = 'utf-8-sig'\n\n# The master toctree document.\nmaster_doc = \"index\"\n\n# This is overridden by readthedocs with the version tag anyway\nversion = \"devel\"\n# To avoid repetition in we set this to an empty string.\nrelease = \"\"\n\n# General information about the project.\nproject = \"PostgREST \" + version\nauthor = \"The PostgREST contributors\"\ncopyright = \"2017, \" + author\n\n# The language for content autogenerated by Sphinx. Refer to documentation\n# for a list of supported languages.\n#\n# This is also used if you do content translation via gettext catalogs.\n# Usually you set \"language\" from the command line for these cases.\nlanguage = \"en\"\n\n# There are two options for replacing |today|: either, you set today to some\n# non-false value, then it is used:\n# today = ''\n# Else, today_fmt is used as the format for a strftime call.\n# today_fmt = '%B %d, %Y'\n\n# List of patterns, relative to source directory, that match files and\n# directories to ignore when looking for source files.\n# This patterns also effect to html_static_path and html_extra_path\nexclude_patterns = [\"_build\", \"Thumbs.db\", \".DS_Store\", \"shared/*.rst\"]\n\n# The reST default role (used for this markup: `text`) to use for all\n# documents.\n# default_role = None\n\n# If true, '()' will be appended to :func: etc. cross-reference text.\n# add_function_parentheses = True\n\n# If true, the current module name will be prepended to all description\n# unit titles (such as .. function::).\n# add_module_names = True\n\n# If true, sectionauthor and moduleauthor directives will be shown in the\n# output. They are ignored by default.\n# show_authors = False\n\n# The name of the Pygments (syntax highlighting) style to use.\npygments_style = \"sphinx\"\n\n# A list of ignored prefixes for module index sorting.\n# modindex_common_prefix = []\n\n# If true, keep warnings as \"system message\" paragraphs in the built documents.\n# keep_warnings = False\n\n# If true, `todo` and `todoList` produce output, else they produce nothing.\ntodo_include_todos = False\n\n\n# -- Options for HTML output ----------------------------------------------\n\n# The theme to use for HTML and HTML Help pages. See the documentation for\n# a list of builtin themes.\nhtml_theme = \"sphinx_rtd_theme\"\n\n# Theme options are theme-specific and customize the look and feel of a theme\n# further. For a list of options available for each theme, see the\n# documentation.\nhtml_theme_options = {}\n\n# Add any paths that contain custom themes here, relative to this directory.\n# html_theme_path = []\n\n# The name for this set of Sphinx documents.\n# \"<project> v<release> documentation\" by default.\n# html_title = u'PostgREST v0.4.0.0'\n\n# A shorter title for the navigation bar. Default is the same as html_title.\n# html_short_title = None\n\n# The name of an image file (relative to this directory) to place at the top\n# of the sidebar.\n# html_logo = None\n\n# The name of an image file (relative to this directory) to use as a favicon of\n# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32\n# pixels large.\nhtml_favicon = \"_static/favicon.ico\"\n\n# Add any paths that contain custom static files (such as style sheets) here,\n# relative to this directory. They are copied after the builtin static files,\n# so a file named \"default.css\" will overwrite the builtin \"default.css\".\nhtml_static_path = [\"_static\"]\n\n# Add any extra paths that contain custom files (such as robots.txt or\n# .htaccess) here, relative to this directory. These files are copied\n# directly to the root of the documentation.\n# html_extra_path = []\n\n# If not None, a 'Last updated on:' timestamp is inserted at every page\n# bottom, using the given strftime format.\n# The empty string is equivalent to '%b %d, %Y'.\n# html_last_updated_fmt = None\n\n# If true, SmartyPants will be used to convert quotes and dashes to\n# typographically correct entities.\n# html_use_smartypants = True\n\n# Custom sidebar templates, maps document names to template names.\n# html_sidebars = {}\n\n# Additional templates that should be rendered to pages, maps page names to\n# template names.\n# html_additional_pages = {}\n\n# If false, no module index is generated.\n# html_domain_indices = True\n\n# If false, no index is generated.\n# html_use_index = True\n\n# If true, the index is split into individual pages for each letter.\n# html_split_index = False\n\n# If true, links to the reST sources are added to the pages.\n# html_show_sourcelink = True\n\n# If true, \"Created using Sphinx\" is shown in the HTML footer. Default is True.\n# html_show_sphinx = True\n\n# If true, \"(C) Copyright ...\" is shown in the HTML footer. Default is True.\n# html_show_copyright = True\n\n# If true, an OpenSearch description file will be output, and all pages will\n# contain a <link> tag referring to it. The value of this option must be the\n# base URL from which the finished HTML is served.\n# html_use_opensearch = ''\n\n# This is the file name suffix for HTML files (e.g. \".xhtml\").\n# html_file_suffix = None\n\n# Language to be used for generating the HTML full-text search index.\n# Sphinx supports the following languages:\n# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'\n# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'\n# html_search_language = 'en'\n\n# A dictionary with options for the search language support, empty by default.\n# 'ja' uses this config value.\n# 'zh' user can custom change `jieba` dictionary path.\n# html_search_options = {'type': 'default'}\n\n# The name of a javascript file (relative to the configuration directory) that\n# implements a search results scorer. If empty, the default will be used.\n# html_search_scorer = 'scorer.js'\n\n# Output file base name for HTML help builder.\nhtmlhelp_basename = \"PostgRESTdoc\"\n\n# -- Options for LaTeX output ---------------------------------------------\n\nlatex_elements = {\n # The paper size ('letterpaper' or 'a4paper').\n #'papersize': 'letterpaper',\n # The font size ('10pt', '11pt' or '12pt').\n #'pointsize': '10pt',\n # Additional stuff for the LaTeX preamble.\n #'preamble': '',\n # Latex figure (float) alignment\n #'figure_align': 'htbp',\n}\n\n# Grouping the document tree into LaTeX files. List of tuples\n# (source start file, target name, title,\n# author, documentclass [howto, manual, or own class]).\nlatex_documents = [\n (master_doc, \"PostgREST.tex\", \"PostgREST Documentation\", author, \"manual\"),\n]\n\n# The name of an image file (relative to this directory) to place at the top of\n# the title page.\n# latex_logo = None\n\n# For \"manual\" documents, if this is true, then toplevel headings are parts,\n# not chapters.\n# latex_use_parts = False\n\n# If true, show page references after internal links.\n# latex_show_pagerefs = False\n\n# If true, show URL addresses after external links.\n# latex_show_urls = False\n\n# Documents to append as an appendix to all manuals.\n# latex_appendices = []\n\n# If false, no module index is generated.\n# latex_domain_indices = True\n\n\n# -- Options for manual page output ---------------------------------------\n\n# One entry per manual page. List of tuples\n# (source start file, name, description, authors, manual section).\nman_pages = [(master_doc, \"postgrest\", \"PostgREST Documentation\", [author], 1)]\n\n# If true, show URL addresses after external links.\n# man_show_urls = False\n\n\n# -- Options for Texinfo output -------------------------------------------\n\n# Grouping the document tree into Texinfo files. List of tuples\n# (source start file, target name, title, author,\n# dir menu entry, description, category)\ntexinfo_documents = [\n (\n master_doc,\n \"PostgREST\",\n \"PostgREST Documentation\",\n author,\n \"PostgREST\",\n \"REST API for any PostgreSQL database\",\n \"Web\",\n ),\n]\n\n# Documents to append as an appendix to all manuals.\n# texinfo_appendices = []\n\n# If false, no module index is generated.\n# texinfo_domain_indices = True\n\n# How to display URL addresses: 'footnote', 'no', or 'inline'.\n# texinfo_show_urls = 'footnote'\n\n# If true, do not generate a @detailmenu in the \"Top\" node's menu.\n# texinfo_no_detailmenu = False\n\n# -- Custom setup ---------------------------------------------------------\n\n\ndef setup(app):\n app.add_css_file(\"css/custom.css\")\n\n\nuser_agent = (\n \"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:135.0) Gecko/20100101 Firefox/135.0\"\n)\n\nlinkcheck_ignore = [\n # 403 only in CI / GitHub Actions\n r\"https://www.patreon.com/postgrest\",\n r\"https://blog.frankel.ch/poor-man-api\",\n r\"https://www.cybertec-postgresql.com/.*\",\n # Odd SSL error\n r\"https://www.dripdepot.com\",\n r\"https://www.euronodes.com\",\n # New GitHub UI delays comment load, so anchor fails\n r\"https://github.com/.*#issuecomment\",\n # Random 500 Internal Server Error\n r\"https://jwt.io\",\n]\n\n# sphinx-tabs configuration\nsphinx_tabs_disable_tab_closing = True\n\n# sphinx_rtd_dark_mode configuration\ndefault_dark_mode = False\n\n# sphinxext-opengraph configuration\n\nogp_image = \"_images/logo.png\"\nogp_use_first_image = True\nogp_enable_meta_description = True\nogp_description_length = 300\n\n## RTD sets html_baseurl, ensures we use the correct env for canonical URLs\n## Useful to generate correct meta tags for Open Graph\n## Refs: https://github.com/readthedocs/readthedocs.org/issues/10226, https://github.com/urllib3/urllib3/pull/3064\nhtml_baseurl = os.environ.get(\"READTHEDOCS_CANONICAL_URL\", \"/\")\n" }, { "path": "docs/ecosystem.rst", "content": ".. _community_tutorials:\n\nCommunity Tutorials\n-------------------\n\n* `Building a Contacts List with PostgREST and Vue.js <https://www.youtube.com/watch?v=iHtsALtD5-U>`_ -\n 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.\n\n* `PostgREST + Auth0: Create REST API in minutes, and add social login using Auth0 <https://samkhawase.com/blog/postgrest/>`_ - A step-by-step tutorial to show how to dockerize and integrate Auth0 to PostgREST service.\n\n* `\"CodeLess\" backend using postgres, postgrest and oauth2 authentication with keycloak <https://www.mathieupassenaud.fr/codeless_backend/>`_ -\n A step-by-step tutorial for using PostgREST with KeyCloak(hosted on a managed service).\n\n* `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.\n\n* `REST Data Service on YugabyteDB / PostgreSQL <https://dev.to/yugabyte/rest-data-service-on-yugabytedb-postgresql-5f2h>`_\n\n* `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.\n\n* `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.\n\n.. * `Accessing a PostgreSQL database in Godot 4 via PostgREST <https://peterkingsbury.com/2022/08/16/godot-postgresql-postgrest/>`_\n\n.. _templates:\n\nTemplates\n---------\n\n* `compose-postgrest <https://github.com/mattddowney/compose-postgrest>`_ - docker-compose setup with Nginx and HTML example\n* `svelte-postgrest-template <https://github.com/guyromm/svelte-postgrest-template>`_ - Svelte/SvelteKit, PostgREST, EveryLayout and social auth\n\n.. _eco_example_apps:\n\nExample Apps\n------------\n\n* `archtika <https://github.com/thiloho/archtika>`_ - self-hosted CMS\n* `delibrium-postgrest <https://gitlab.com/delibrium/delibrium-postgrest/>`_ - example school API and front-end in Vue.js\n* `ETH-transactions-storage <https://github.com/Adamant-im/ETH-transactions-storage>`_ - indexer for Ethereum to get transaction list by ETH address\n* `fullstack template <https://github.com/jenstroeger/fullstack-webapp-template>`_ - a complete fullstack webapp template using PG as db and message queue, Python and Dramatiq to implement async jobs, db migrations, test runners, and more.\n* `general <https://github.com/PierreRochard/general>`_ - example auth back-end\n* `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\n* `PostGUI <https://github.com/priyank-purohit/PostGUI>`_ - React Material UI admin panel\n* `prospector <https://github.com/sfcta/prospector>`_ - data warehouse and visualization platform\n\n.. _devops:\n\nDevOps\n------\n\n* `cloudgov-demo-postgrest <https://github.com/GSA/cloudgov-demo-postgrest>`_ - demo for a federally-compliant REST API on cloud.gov\n* `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\n* `cyril-sabourault/postgrest-cloud-run <https://github.com/cyril-sabourault/postgrest-cloud-run>`_ - expose a PostgreSQL database on Cloud SQL using Cloud Run\n* `eyberg/postgrest <https://repo.ops.city/v2/packages/eyberg/postgrest/10.1.1/x86_64/show>`_ - run PostgREST as a Nanos unikernel\n* `jbkarle/postgrest <https://github.com/jbkarle/postgrest>`_ - helm chart with a demo database for development and test purposes\n\n.. _eco_external_notification:\n\nExternal Notification\n---------------------\n\nThese are PostgreSQL bridges that propagate LISTEN/NOTIFY to external queues for further processing. This allows functions to initiate actions outside the database such as sending emails.\n\n* `pg-notify-stdout <https://github.com/mkleczek/pg-notify-stdout>`_ - writes notifications to standard output (use in shell scripts etc.)\n* `pg-notify-webhook <https://github.com/vbalasu/pg-notify-webhook>`_ - trigger webhooks from PostgreSQL's LISTEN/NOTIFY\n* `pgsql-listen-exchange <https://github.com/gmr/pgsql-listen-exchange>`_ - RabbitMQ\n* `postgres-websockets <https://github.com/diogob/postgres-websockets>`_ - expose web sockets for PostgreSQL's LISTEN/NOTIFY\n* `postgresql2websocket <https://github.com/frafra/postgresql2websocket>`_ - Websockets\n\n\n.. _eco_extensions:\n\nExtensions\n----------\n\n* `aiodata <https://github.com/Exahilosys/aiodata>`_ - Python, event-based proxy and caching client.\n* `pg-safeupdate <https://github.com/eradman/pg-safeupdate>`_ - prevent full-table updates or deletes\n* `postgrest-node <https://github.com/seveibar/postgrest-node>`_ - Run a PostgREST server in Node.js via npm module\n* `PostgREST-writeAPI <https://github.com/ppKrauss/PostgREST-writeAPI>`_ - generate Nginx rewrite rules to fit an OpenAPI spec\n\n.. _clientside_libraries:\n\nClient-Side Libraries\n---------------------\n\n* `postgrest-csharp <https://github.com/supabase-community/postgrest-csharp>`_ - C#\n* `postgrest-dart <https://github.com/supabase/postgrest-dart>`_ - Dart\n* `postgrest-ex <https://github.com/supabase-community/postgrest-ex>`_ - Elixir\n* `postgrest-go <https://github.com/supabase-community/postgrest-go>`_ - Go\n* `postgrest-js <https://github.com/supabase/postgrest-js>`_ - TypeScript/JavaScript\n* `postgrest-kt <https://github.com/supabase-community/postgrest-kt>`_ - Kotlin\n* `postgrest-py <https://github.com/supabase/postgrest-py>`_ - Python\n* `postgrest-rs <https://github.com/supabase-community/postgrest-rs>`_ - Rust\n* `postgrest-swift <https://github.com/supabase-community/postgrest-swift>`_ - Swift\n* `redux-postgrest <https://github.com/andytango/redux-postgrest>`_ - TypeScript/JS, client integrated with (React) Redux.\n* `vue-postgrest <https://github.com/technowledgy/vue-postgrest>`_ - Vue.js\n\n" }, { "path": "docs/explanations/architecture.rst", "content": "Architecture\n############\n\nThis page describes the architecture of PostgREST.\n\nBird's Eye View\n===============\n\nYou can click on the components to navigate to their respective documentation.\n\n .. container:: img-dark\n\n .. See https://github.com/sphinx-doc/sphinx/issues/2240#issuecomment-187366626\n\n .. raw:: html\n\n <object width=\"100%\" data=\"../_static/arch-dark.svg\" type=\"image/svg+xml\"></object>\n\n .. container:: img-light\n\n .. raw:: html\n\n <object width=\"100%\" data=\"../_static/arch.svg\" type=\"image/svg+xml\"></object>\n\n\nCode Map\n========\n\nThis section talks briefly about various important modules.\n\nMain\n----\n\nThe starting point of the program is `Main.hs <https://github.com/PostgREST/postgrest/blob/main/main/Main.hs>`_.\n\nCLI\n---\n\nMain then calls `CLI.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/CLI.hs>`_, which is in charge of :ref:`cli`.\n\nApp\n---\n\n`App.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/App.hs>`_ is then in charge of composing the different modules.\n\nAuth\n----\n\n`Auth.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/Auth.hs>`_ is in charge of :ref:`authn`.\n\nApi Request\n-----------\n\n`ApiRequest.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/ApiRequest.hs>`_ is in charge of parsing the URL query string (following PostgREST syntax), the request headers, and the request body.\n\nA request might be rejected at this level if it's invalid. For example when providing an unknown media type to PostgREST or using an unknown HTTP method.\n\nPlan\n----\n\nUsing the Schema Cache, `Plan.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/Plan.hs>`_ generates an internal AST, filling out-of-band SQL details (like an ``ON CONFLICT (pk)`` clause) required to complete the user request.\n\nA request might be rejected at this level if it's invalid. For example when doing resource embedding on a nonexistent resource.\n\nQuery\n-----\n\n`Query.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/Query.hs>`_ generates the SQL queries (parametrized and prepared) required to satisfy the user request.\n\nOnly at this stage a connection from the pool might be used.\n\nSchema Cache\n------------\n\n`SchemaCache.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/SchemaCache.hs>`_ is in charge of :ref:`schema_cache`.\n\nConfig\n------\n\n`Config.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/Config.hs>`_ is in charge of :ref:`configuration`.\n\nAdmin\n-----\n\n`Admin.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/Admin.hs>`_ is in charge of the :ref:`admin_server`.\n\nHTTP\n----\n\nThe HTTP server is provided by `Warp <https://aosabook.org/en/posa/warp.html>`_.\n\nListener\n--------\n\n`Listener.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/Listener.hs>`_ is in charge of the :ref:`listener`.\n" }, { "path": "docs/explanations/db_authz.rst", "content": ".. _db_authz:\n\nDatabase Authorization\n######################\n\nDatabase authorization is the process of granting and verifying database access permissions. PostgreSQL manages permissions using the concept of roles.\n\nUsers and Groups\n================\n\nA role can be thought of as either a database user, or a group of database users, depending on how the role is set up.\n\nRoles for Each Web User\n-----------------------\n\nPostgREST can accommodate either viewpoint. If you treat a role as a single user then :ref:`user_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.\n\nYou 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.\n\n.. code-block:: postgres\n\n CREATE TABLE chat (\n message_uuid UUID PRIMARY KEY DEFAULT uuid_generate_v4(),\n message_time TIMESTAMP NOT NULL DEFAULT now(),\n message_from NAME NOT NULL DEFAULT current_user,\n message_to NAME NOT NULL,\n message_subject VARCHAR(64) NOT NULL,\n message_body TEXT\n );\n\n ALTER TABLE chat ENABLE ROW LEVEL SECURITY;\n\nWe 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.\n\nPostgreSQL allows us to set this policy with row-level security:\n\n.. code-block:: postgres\n\n CREATE POLICY chat_policy ON chat\n USING ((message_to = current_user) OR (message_from = current_user))\n WITH CHECK (message_from = current_user)\n\nAnyone accessing the generated API endpoint for the chat table will see exactly the rows they should, without our needing custom imperative server-side coding.\n\n.. warning::\n\n Roles are namespaced per-cluster rather than per-database so they may be prone to collision.\n\nWeb Users Sharing Role\n----------------------\n\nAlternately 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.\n\n.. code:: json\n\n {\n \"role\": \"webuser\",\n \"email\": \"john@doe.com\"\n }\n\nSQL code can access claims through PostgREST :ref:`tx_settings`. For instance to get the email claim, call this function:\n\n.. code:: sql\n\n current_setting('request.jwt.claims', true)::json->>'email';\n\n.. note::\n\n For PostgreSQL < 14\n\n .. code:: sql\n\n current_setting('request.jwt.claim.email', true);\n\nThis 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.\n\nHybrid User-Group Roles\n-----------------------\n\nYou can mix the group and individual role policies. For instance we could still have a webuser role and individual users which inherit from it:\n\n.. code-block:: postgres\n\n CREATE ROLE webuser NOLOGIN;\n -- grant this role access to certain tables etc\n\n CREATE ROLE user000 NOLOGIN;\n GRANT webuser TO user000;\n -- now user000 can do whatever webuser can\n\n GRANT user000 TO authenticator;\n -- allow authenticator to switch into user000 role\n -- (the role itself has nologin)\n\nSchemas\n=======\n\nYou must explicitly allow roles to access the exposed schemas in :ref:`db-schemas`.\n\n.. code-block:: postgres\n\n GRANT USAGE ON SCHEMA api TO webuser;\n\nTables\n======\n\nTo let web users access tables you must grant them privileges for the operations you want them to do.\n\n.. code-block:: postgres\n\n GRANT\n SELECT\n , INSERT\n , UPDATE(message_body)\n , DELETE\n ON chat TO webuser;\n\nYou 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.\n\n.. _func_privs:\n\nFunctions\n=========\n\nBy 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:\n\n.. code-block:: postgres\n\n ALTER DEFAULT PRIVILEGES REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;\n\nThis 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.\n\n.. note::\n\n 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:\n\n .. code-block:: postgres\n\n ALTER DEFAULT PRIVILEGES GRANT EXECUTE ON FUNCTIONS TO PUBLIC;\n\n 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.\n\nAfter that, you'll need to grant EXECUTE privileges on functions explicitly:\n\n.. code-block:: postgres\n\n GRANT EXECUTE ON FUNCTION login TO anonymous;\n GRANT EXECUTE ON FUNCTION signup TO anonymous;\n\nYou can also grant execute on all functions in a schema to a higher privileged role:\n\n.. code-block:: postgres\n\n GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA api TO web_user;\n\nSecurity definer\n----------------\n\nA 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 function performs.\nIf the function accesses private database objects, your :ref:`API roles <roles>` won't be able to successfully execute the function.\n\nAnother 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.\n\n.. code-block:: postgres\n\n -- login as a user which has privileges on the private schemas\n\n -- create a sample function\n create or replace function login(email text, pass text, out token text) as $$\n begin\n -- access to a private schema called 'auth'\n select auth.user_role(email, pass) into _role;\n -- other operations\n -- ...\n end;\n $$ language plpgsql security definer;\n\nNote 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.\n\nViews\n=====\n\nViews are invoked with the privileges of the view owner, much like functions 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.\n\nIf you're on PostgreSQL >= 15, this behavior can be changed by specifying the ``security_invoker`` option.\n\n.. code-block:: postgres\n\n CREATE VIEW sample_view WITH (security_invoker = true) AS\n SELECT * FROM sample_table;\n\nOn PostgreSQL < 15, you can create a non-SUPERUSER role and make this role the view's owner.\n\n.. code-block:: postgres\n\n CREATE ROLE api_views_owner NOSUPERUSER NOBYPASSRLS;\n ALTER VIEW sample_view OWNER TO api_views_owner;\n\n" }, { "path": "docs/explanations/external_auth.rst", "content": ".. _external_auth:\n\nExternal Authentication\n-----------------------\n\nJWT from Auth0\n~~~~~~~~~~~~~~\n\nAn 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.\n\nTo 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.\n" }, { "path": "docs/explanations/install.rst", "content": ".. _install:\n\nInstallation\n############\n\nThe release page has `pre-compiled binaries for macOS, Windows, Linux and FreeBSD <https://github.com/PostgREST/postgrest/releases/latest>`_.\nThe Linux binary is a static executable that can be run on any Linux distribution.\n\nYou can also use your OS package manager.\n\n.. include:: ../shared/installation.rst\n\n.. _pg-dependency:\n\nSupported PostgreSQL versions\n=============================\n\n=============== =================================\n**Supported** PostgreSQL >= 13\n=============== =================================\n\nPostgREST works with all PostgreSQL versions still `officially supported <https://www.postgresql.org/support/versioning/>`_.\n\n\nRunning PostgREST\n=================\n\nIf you downloaded PostgREST from the release page, first extract the compressed file to obtain the executable.\n\n.. code-block:: bash\n\n # For UNIX platforms\n tar Jxf postgrest-[version]-[platform].tar.xz\n\n # On Windows you should unzip the file\n\nNow you can run PostgREST with the :code:`--help` flag to see usage instructions:\n\n.. code-block:: bash\n\n # Running postgrest binary\n ./postgrest --help\n\n # Running postgrest installed from a package manager\n postgrest --help\n\n # You should see a usage help message\n\nThe PostgREST server reads a configuration file as its only argument:\n\n.. code:: bash\n\n postgrest /path/to/postgrest.conf\n\n # You can also generate a sample config file with\n # postgrest -e > postgrest.conf\n # You'll need to edit this file and remove the usage parts for postgrest to read it\n\nFor a complete reference of the configuration file, see :ref:`configuration`.\n\n.. note::\n\n 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.\n\n .. image:: ../_static/win-err-dialog.png\n\n 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.\n\n 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.\n\nDocker\n======\n\nYou can get the `official PostgREST Docker image <https://hub.docker.com/r/postgrest/postgrest>`_ with:\n\n.. code-block:: bash\n\n # pull the latest version\n docker pull postgrest/postgrest\n\n # to pull a particular version, use one of the versions on https://hub.docker.com/r/postgrest/postgrest/tags\n docker pull postgrest/postgrest:<version>\n\nTo configure the container image, use :ref:`env_variables_config`.\n\nThere are two ways to run the PostgREST container: with an existing external database, or through docker-compose.\n\nContainerized PostgREST with native PostgreSQL\n----------------------------------------------\n\nThe first way to run PostgREST in Docker is to connect it to an existing native database on the host.\n\n.. code-block:: bash\n\n # Run the server\n docker run --rm --net=host \\\n -e PGRST_DB_URI=\"postgres://app_user:password@localhost/postgres\" \\\n postgrest/postgrest\n\nThe 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.\n\n.. note::\n\n 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.\n\n .. code-block:: bash\n\n sudo ifconfig lo0 10.0.0.10 alias\n\n 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:\n\n .. code-block:: bash\n\n listen_addresses = 'localhost,10.0.0.10'\n\n You might also need to add a new IPv4 local connection within pg_hba.conf. For instance:\n\n .. code-block:: bash\n\n host all all 10.0.0.10/32 trust\n\n The docker command will then look like this:\n\n .. code-block:: bash\n\n # Run the server\n docker run --rm -p 3000:3000 \\\n -e PGRST_DB_URI=\"postgres://app_user:password@10.0.0.10/postgres\" \\\n postgrest/postgrest\n\n.. _pg-in-docker:\n\nContainerized PostgREST *and* db with docker-compose\n----------------------------------------------------\n\nTo 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:\n\n.. code-block:: yaml\n\n # docker-compose.yml\n\n version: '3'\n services:\n server:\n image: postgrest/postgrest\n ports:\n - \"3000:3000\"\n environment:\n PGRST_SERVER_HOST: 0.0.0.0 # necessary for `postgrest --ready` flag to work\n PGRST_DB_URI: postgres://app_user:password@db:5432/app_db\n PGRST_OPENAPI_SERVER_PROXY_URI: http://127.0.0.1:3000\n depends_on:\n - db\n db:\n image: postgres\n ports:\n - \"5432:5432\"\n environment:\n POSTGRES_DB: app_db\n POSTGRES_USER: app_user\n POSTGRES_PASSWORD: password\n # Uncomment this if you want to persist the data.\n # volumes:\n # - \"./pgdata:/var/lib/postgresql/data\"\n\nGo 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.\n\nIf you want to have a visual overview of your API in your browser you can add swagger-ui to your :code:`docker-compose.yml`:\n\n.. code-block:: yaml\n\n # in services:\n swagger:\n image: swaggerapi/swagger-ui\n ports:\n - \"8080:8080\"\n expose:\n - \"8080\"\n environment:\n API_URL: http://localhost:3000/\n\nWith this you can see the swagger-ui in your browser on port 8080.\n\n.. _docker_cpu_contraint:\n\nDocker Resource Constraints\n---------------------------\n\nPostgREST does not support ``--cpus`` `constraint option <https://docs.docker.com/engine/containers/resource_constraints/#configure-the-default-cfs-scheduler>`_.\n\nAs a workaround, you may use the `GHC RTS <https://ghc.gitlab.haskell.org/ghc/doc/users_guide/runtime_control.html#runtime-system-rts-options>`_ ``-N`` option. For instance, to limit it to 2 CPU cores, do:\n\n.. code::\n\n # Set environment variable GHCRTS set to \"-N2\"\n docker run --rm -p 3000:3000 \\\n -e PGRST_DB_URI=\"postgres://app_user:password@10.0.0.10/postgres\" \\\n -e GHCRTS=\"-N2\"\n postgrest/postgrest\n\n.. _build_source:\n\nBuilding from Source\n====================\n\nWhen a pre-built binary does not exist for your system you can build the project from source.\n\nYou can build PostgREST from source with `Stack <https://github.com/commercialhaskell/stack>`_. It will install any necessary Haskell dependencies on your system.\n\n* `Install Stack <https://docs.haskellstack.org/en/stable/#how-to-install-stack>`_ for your platform\n* Install Library Dependencies\n\n ===================== =======================================\n Operating System Dependencies\n ===================== =======================================\n Ubuntu/Debian libpq-dev, libgmp-dev, zlib1g-dev\n CentOS/Fedora/Red Hat postgresql-devel, zlib-devel, gmp-devel\n BSD postgresql12-client\n macOS libpq, gmp\n ===================== =======================================\n\n* Build and install binary\n\n .. code-block:: bash\n\n git clone https://github.com/PostgREST/postgrest.git\n cd postgrest\n\n # adjust local-bin-path to taste\n stack build --install-ghc --copy-bins --local-bin-path /usr/local/bin\n\n.. note::\n\n - If building fails and your system has less than 1GB of memory, try adding a swap file.\n - `--install-ghc` flag is only needed for the first build and can be omitted in the subsequent builds.\n\n* Check that the server is installed: :code:`postgrest --help`.\n" }, { "path": "docs/explanations/nginx.rst", "content": ".. _nginx:\n\nNginx\n=====\n\nPostgREST 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.\nPostgREST 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.\n\nThe first step is to create an Nginx configuration file that proxies requests to an underlying PostgREST server.\n\n.. code-block:: nginx\n\n http {\n # ...\n # upstream configuration\n upstream postgrest {\n server localhost:3000;\n }\n # ...\n server {\n # ...\n # expose to the outside world\n location /api/ {\n default_type application/json;\n proxy_hide_header Content-Location;\n add_header Content-Location /api/$upstream_http_content_location;\n proxy_set_header Connection \"\";\n proxy_http_version 1.1;\n proxy_pass http://postgrest/;\n }\n # ...\n }\n }\n\n.. note::\n\n For ubuntu, if you already installed nginx through :code:`apt` you can add this to the config file in\n :code:`/etc/nginx/sites-enabled/default`.\n\n.. _https:\n\nHTTPS\n-----\n\nPostgREST 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>`_.\n\nRate Limiting\n-------------\n\nNginx 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:\n\n.. code-block:: nginx\n\n limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;\n\nThis 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`).\n\nNext we apply the zone to certain routes, like a hypothetical function called :code:`login`.\n\n.. code-block:: nginx\n\n location /rpc/login/ {\n # apply rate limiting\n limit_req zone=login burst=5;\n }\n\nThe burst argument tells Nginx to start dropping requests if more than five queue up from a specific IP.\n\nNginx 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.\n\nAlternate URL Structure\n-----------------------\n\nAs 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\n\n.. code-block:: bash\n\n curl \"http://localhost:3000/people?id=eq.1\" \\\n -H \"Accept: application/vnd.pgrst.object+json\"\n\nThis allows compound primary keys and makes the intent for singular response independent of a URL convention.\n\nNginx 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.\"\n\n.. code-block:: nginx\n\n # support /endpoint/:id url style\n location ~ ^/([a-z_]+)/([0-9]+) {\n\n # make the response singular\n proxy_set_header Accept 'application/vnd.pgrst.object+json';\n\n # assuming an upstream named \"postgrest\"\n proxy_pass http://postgrest/$1?id=eq.$2;\n\n }\n\n.. TODO\n.. Administration\n.. API Versioning\n.. HTTP Caching\n.. Upgrading\n" }, { "path": "docs/explanations/schema_isolation.rst", "content": ".. _schema_isolation:\n\nSchema Isolation\n================\n\nA PostgREST instance exposes all the tables, views, and functions of a single `PostgreSQL schema <https://www.postgresql.org/docs/current/ddl-schemas.html>`_ (a namespace of database objects). This means private data or implementation details can go inside different private schemas and be invisible to HTTP clients.\n\nIt is recommended that you don't expose tables on your API schema. Instead expose views and functions which insulate the internal details from the outside world.\nThis 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.\n\n.. container:: svg-container-md\n\n .. container:: img-dark\n\n .. See https://github.com/sphinx-doc/sphinx/issues/2240#issuecomment-187366626\n\n .. raw:: html\n\n <object width=\"100%\" data=\"../_static/sch-iso-dark.svg\" type=\"image/svg+xml\"></object>\n\n .. container:: img-light\n\n .. raw:: html\n\n <object width=\"100%\" data=\"../_static/sch-iso.svg\" type=\"image/svg+xml\"></object>\n" }, { "path": "docs/how-tos/create-soap-endpoint.rst", "content": ".. _create_soap_endpoint:\n\nCreate a SOAP endpoint\n======================\n\n:author: `fjf2002 <https://github.com/fjf2002>`_\n\nPostgREST supports :ref:`custom_media`. With a bit of work, SOAP endpoints become possible.\n\nMinimal Example\n---------------\n\nThis example will simply return the request body, inside a tag ``therequestbodywas``.\n\nAdd the following function to your PostgreSQL database:\n\n.. code-block:: postgres\n\n create domain \"text/xml\" as pg_catalog.xml;\n\n CREATE OR REPLACE FUNCTION my_soap_endpoint(xml) RETURNS \"text/xml\" AS $$\n DECLARE\n nsarray CONSTANT text[][] := ARRAY[\n ARRAY['soapenv', 'http://schemas.xmlsoap.org/soap/envelope/']\n ];\n BEGIN\n RETURN xmlelement(\n NAME \"soapenv:Envelope\",\n XMLATTRIBUTES('http://schemas.xmlsoap.org/soap/envelope/' AS \"xmlns:soapenv\"),\n xmlelement(NAME \"soapenv:Header\"),\n xmlelement(\n NAME \"soapenv:Body\",\n xmlelement(\n NAME theRequestBodyWas,\n (xpath('/soapenv:Envelope/soapenv:Body', $1, nsarray))[1]\n )\n )\n );\n END;\n $$ LANGUAGE plpgsql;\n\nDo not forget to refresh the :ref:`PostgREST schema cache <schema_reloading>`.\n\nUse ``curl`` for a first test:\n\n.. code-block:: bash\n\n curl http://localhost:3000/rpc/my_soap_endpoint \\\n --header 'Content-Type: text/xml' \\\n --header 'Accept: text/xml' \\\n --data-binary @- <<XML\n <soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\">\n <soapenv:Header/>\n <soapenv:Body>\n <mySOAPContent>\n My SOAP Content\n </mySOAPContent>\n </soapenv:Body>\n </soapenv:Envelope>\n XML\n\nThe output should contain the original request body within the ``therequestbodywas`` entity,\nand should roughly look like:\n\n.. code-block:: xml\n\n <soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\">\n <soapenv:Header/>\n <soapenv:Body>\n <therequestbodywas>\n <soapenv:Body xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\">\n <mySOAPContent>\n My SOAP Content\n </mySOAPContent>\n </soapenv:Body>\n </therequestbodywas>\n </soapenv:Body>\n </soapenv:Envelope>\n\nA more elaborate example\n------------------------\n\nHere we have a SOAP service that converts a fraction to a decimal value,\nwith pass-through of PostgreSQL errors to the SOAP response.\nPlease note that in production you probably should not pass through plain database errors\npotentially disclosing internals to the client, but instead handle the errors directly.\n\n\n.. code-block:: postgres\n\n -- helper function\n CREATE OR REPLACE FUNCTION _soap_envelope(body xml)\n RETURNS xml\n LANGUAGE sql\n AS $function$\n SELECT xmlelement(\n NAME \"soapenv:Envelope\",\n XMLATTRIBUTES('http://schemas.xmlsoap.org/soap/envelope/' AS \"xmlns:soapenv\"),\n xmlelement(NAME \"soapenv:Header\"),\n xmlelement(NAME \"soapenv:Body\", body)\n );\n $function$;\n\n -- helper function\n CREATE OR REPLACE FUNCTION _soap_exception(\n faultcode text,\n faultstring text\n )\n RETURNS xml\n LANGUAGE sql\n AS $function$\n SELECT _soap_envelope(\n xmlelement(NAME \"soapenv:Fault\",\n xmlelement(NAME \"faultcode\", faultcode),\n xmlelement(NAME \"faultstring\", faultstring)\n )\n );\n $function$;\n\n CREATE OR REPLACE FUNCTION fraction_to_decimal(xml)\n RETURNS \"text/xml\"\n LANGUAGE plpgsql\n AS $function$\n DECLARE\n nsarray CONSTANT text[][] := ARRAY[\n ARRAY['soapenv', 'http://schemas.xmlsoap.org/soap/envelope/']\n ];\n exc_msg text;\n exc_detail text;\n exc_hint text;\n exc_sqlstate text;\n BEGIN\n -- simulating a statement that results in an exception:\n RETURN _soap_envelope(xmlelement(\n NAME \"decimalValue\",\n (\n (xpath('/soapenv:Envelope/soapenv:Body/fraction/numerator/text()', $1, nsarray))[1]::text::int\n /\n (xpath('/soapenv:Envelope/soapenv:Body/fraction/denominator/text()', $1, nsarray))[1]::text::int\n )::text::xml\n ));\n EXCEPTION WHEN OTHERS THEN\n GET STACKED DIAGNOSTICS\n exc_msg := MESSAGE_TEXT,\n exc_detail := PG_EXCEPTION_DETAIL,\n exc_hint := PG_EXCEPTION_HINT,\n exc_sqlstate := RETURNED_SQLSTATE;\n RAISE WARNING USING\n MESSAGE = exc_msg,\n DETAIL = exc_detail,\n HINT = exc_hint;\n RETURN _soap_exception(faultcode => exc_sqlstate, faultstring => concat(exc_msg, ', DETAIL: ', exc_detail, ', HINT: ', exc_hint));\n END\n $function$;\n\nLet's test the ``fraction_to_decimal`` service with illegal values:\n\n.. code-block:: bash\n\n curl http://localhost:3000/rpc/fraction_to_decimal \\\n --header 'Content-Type: text/xml' \\\n --header 'Accept: text/xml' \\\n --data-binary @- <<XML\n <soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\">\n <soapenv:Header/>\n <soapenv:Body>\n <fraction>\n <numerator>42</numerator>\n <denominator>0</denominator>\n </fraction>\n </soapenv:Body>\n </soapenv:Envelope>\n XML\n\nThe output should roughly look like:\n\n.. code-block:: xml\n\n <soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\">\n <soapenv:Header/>\n <soapenv:Body>\n <soapenv:Fault>\n <faultcode>22012</faultcode>\n <faultstring>division by zero, DETAIL: , HINT: </faultstring>\n </soapenv:Fault>\n </soapenv:Body>\n </soapenv:Envelope>\n\nReferences\n----------\n\nFor more information concerning PostgREST, cf.\n\n- :ref:`function_single_unnamed`\n- :ref:`custom_media`. See :ref:`any_handler`, if you need to support an ``application/soap+xml`` media type or if you want to respond with XML without sending a media type.\n- :ref:`Nginx reverse proxy <nginx>`\n\nFor SOAP reference, visit\n\n- the specification at https://www.w3.org/TR/soap/\n- shorter more practical advice is available at https://www.w3schools.com/xml/xml_soap.asp\n" }, { "path": "docs/how-tos/providing-html-content-using-htmx.rst", "content": "\n.. _providing_html_htmx:\n\nProviding HTML Content Using Htmx\n=================================\n\n:author: `Laurence Isla <https://github.com/laurenceisla>`_\n\nThis how-to shows a way to return HTML content and use the `htmx library <https://htmx.org/>`_ to handle the AJAX requests.\nHtmx expects an HTML response and uses it to replace an element inside the DOM (see the `htmx introduction <https://htmx.org/docs/#introduction>`_ in the docs).\n\n.. image:: ../_static/how-tos/htmx-demo.gif\n\n.. warning::\n\n This is a proof of concept showing what can be achieved using both technologies.\n We are working on `plmustache <https://github.com/PostgREST/plmustache>`_ which will further improve the HTML aspect of this how-to.\n\nPreparatory Configuration\n-------------------------\n\nWe will make a to-do app based on the :ref:`tut0`, so make sure to complete it before continuing.\n\nTo simplify things, we won't be using authentication, so grant all permissions on the ``todos`` table to the ``web_anon`` user.\n\n.. code-block:: postgres\n\n grant all on api.todos to web_anon;\n grant usage, select on sequence api.todos_id_seq to web_anon;\n\nNext, add the ``text/html`` as a :ref:`custom_media`. With this, PostgREST can identify the request made by your web browser (with the ``Accept: text/html`` header)\nand return a raw HTML document file.\n\n.. code-block:: postgres\n\n create domain \"text/html\" as text;\n\nCreating an HTML Response\n-------------------------\n\nLet's create a function that returns a basic HTML file, using `Pico CSS <https://picocss.com>`_ for styling and\n`Ionicons <https://ionic.io/ionicons>`_ to show some icons later.\n\n.. code-block:: postgres\n\n create or replace function api.index() returns \"text/html\" as $$\n select $html$\n <!DOCTYPE html>\n <html>\n <head>\n <meta charset=\"utf-8\">\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n <title>PostgREST + HTMX To-Do List\n \n \n \n \n
\n
\n
\n PostgREST + HTMX To-Do List\n
\n
\n
\n \n \n \n \n \n $html$;\n $$ language sql;\n\nThe web browser will open the web page at ``http://localhost:3000/rpc/index``.\n\n.. image:: ../_static/how-tos/htmx-simple.jpg\n\n.. _html_htmx_list_create:\n\nListing and Creating To-Dos\n---------------------------\n\nNow, let's show a list of the to-dos already inserted in the database.\nFor that, we'll also need a function to help us sanitize the HTML content that may be present in the task.\n\n.. code-block:: postgres\n\n create or replace function api.sanitize_html(text) returns text as $$\n select replace(replace(replace(replace(replace($1, '&', '&'), '\"', '"'),'>', '>'),'<', '<'), '''', ''')\n $$ language sql;\n\n create or replace function api.html_todo(api.todos) returns text as $$\n select format($html$\n
\n <%2$s>\n %3$s\n \n
\n $html$,\n $1.id,\n case when $1.done then 's' else 'span' end,\n api.sanitize_html($1.task)\n );\n $$ language sql stable;\n\n create or replace function api.html_all_todos() returns text as $$\n select coalesce(\n string_agg(api.html_todo(t), '
' order by t.id),\n '

There is nothing else to do.

'\n )\n from api.todos t;\n $$ language sql;\n\nThese two functions are used to build the to-do list template. We won't use them as PostgREST endpoints.\n\n- The ``api.html_todo`` function uses the table ``api.todos`` as a parameter and formats each item into a list element ``
  • ``.\n The PostgreSQL `format `_ is useful to that end.\n It replaces the values according to the position in the template, e.g. ``%1$s`` will be replaced with the value of ``$1.id`` (the first parameter).\n\n- The ``api.html_all_todos`` function returns the ``
      `` wrapper for all the list elements.\n It uses `string_arg `_ to concatenate all the to-dos in a single text value.\n It also returns an alternative message, instead of a list, when the ``api.todos`` table is empty.\n\nNext, let's add an endpoint to register a to-do in the database and modify the ``/rpc/index`` page accordingly.\n\n.. code-block:: postgres\n\n create or replace function api.add_todo(_task text) returns \"text/html\" as $$\n insert into api.todos(task) values (_task);\n select api.html_all_todos();\n $$ language sql;\n\n create or replace function api.index() returns \"text/html\" as $$\n select $html$\n \n \n \n \n \n PostgREST + HTMX To-Do List\n \n \n \n \n \n \n
      \n
      \n
      \n PostgREST + HTMX To-Do List\n
      \n
      \n \n
      \n
      \n $html$\n || api.html_all_todos() ||\n $html$\n
      \n
      \n
      \n \n \n \n \n \n $html$;\n $$ language sql;\n\n- The ``/rpc/add_todo`` endpoint allows us to add a new to-do using the ``_task`` parameter and returns an ``html`` with all the to-dos in the database.\n\n- The ``/rpc/index`` now adds the ``hx-headers='{\"Accept\": \"text/html\"}'`` tag to the ````.\n This will make sure that all htmx elements inside the body send this header, otherwise PostgREST won't recognize it as HTML.\n\n There is also a ``
      `` element that uses the htmx library. Let's break it down:\n\n + ``hx-post=\"/rpc/add_todo\"``: sends an AJAX POST request to the ``/rpc/add_todo`` endpoint, with the value of the ``_task`` from the ```` element.\n\n + ``hx-target=\"#todo-list-area\"``: the HTML content returned from the request will go inside ``
      `` (which is the list of to-dos).\n\n + ``hx-trigger=\"submit\"``: htmx will do this request when submitting the form (by pressing enter while inside the ````).\n\n + ``hx-on=\"htmx:afterRequest: this.reset()\">``: this is a Javascript command that clears the form `after the request is done `_.\n\nWith this, the ``http://localhost:3000/rpc/index`` page lists all the todos and adds new ones by submitting tasks in the input element.\nDon't forget to refresh the :ref:`schema cache `.\n\n.. image:: ../_static/how-tos/htmx-insert.gif\n\nEditing and Deleting To-Dos\n---------------------------\n\nNow, let's modify ``api.html_todo`` and make it more functional.\n\n.. code-block:: postgres\n\n create or replace function api.html_todo(api.todos) returns text as $$\n select format($html$\n
      \n
      \n \n <%2$s style=\"cursor: pointer\">\n %3$s\n \n \n
      \n
      \n \n \n
      \n
      \n $html$,\n $1.id,\n case when $1.done then 's' else 'span' end,\n api.sanitize_html($1.task),\n (not $1.done)::text\n );\n $$ language sql stable;\n\nLet's deconstruct the new htmx features added:\n\n- The ``
      `` element is configured as follows:\n\n + ``hx-post=\"/rpc/change_todo_state\"``: does an AJAX POST request to that endpoint. It will toggle the ``done`` state of the to-do.\n\n + ``hx-vals='{\"_id\": %1$s, \"_done\": %4$s}'``: adds the parameters to the request.\n This is an alternative to using hidden inputs inside the ````.\n\n + ``hx-trigger=\"click\"``: htmx does the request after clicking on the element.\n\n- For the first ``