bump version to 12.2.1

Revert "prevent GSSAPI error between Listener and pool"

This reverts commit 4beac10d3d.

.github/scripts/arm/docker-env/Dockerfile

@@ -1,6 +1,6 @@
 # PostgREST docker hub image
 
-FROM ubuntu:noble@sha256:3f85b7caad41a95462cf5b787d8a04604c8262cdcdf9a472b8c52ef83375fe15 AS postgrest
+FROM ubuntu:noble@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30 AS postgrest
 
 RUN apt-get update -y \
     && apt install -y --no-install-recommends libpq-dev zlib1g-dev jq gcc libnuma-dev \

.github/workflows/build.yaml

@@ -33,7 +33,7 @@ jobs:
     name: Nix - Linux static
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Setup Nix Environment
         uses: ./.github/actions/setup-nix
         with:
@@ -62,7 +62,7 @@ jobs:
     name: Nix - MacOS
     runs-on: macos-12
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Setup Nix Environment
         uses: ./.github/actions/setup-nix
         with:
@@ -118,7 +118,7 @@ jobs:
     name: Stack - ${{ matrix.name }}
     runs-on: ${{ matrix.runs-on }}
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - uses: haskell-actions/setup@33585e1a16afa5875e124b0ebc89dd0c2f872c21 # v2.7.3
         with:
           # This must match the version in stack.yaml's resolver
@@ -161,7 +161,7 @@ jobs:
     name: Stack - FreeBSD from CirrusCI
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - uses: ./.github/actions/artifact-from-cirrus
         with:
           token: ${{ github.token }}
@@ -178,7 +178,7 @@ jobs:
     name: Cabal - Linux GHC ${{ matrix.ghc }}
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - uses: haskell-actions/setup@33585e1a16afa5875e124b0ebc89dd0c2f872c21 # v2.7.3
         with:
           ghc-version: ${{ matrix.ghc }}

.github/workflows/check.yaml

@@ -20,7 +20,7 @@ jobs:
     name: Lint & Style
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Setup Nix Environment
         uses: ./.github/actions/setup-nix
         with:

.github/workflows/ci.yaml

@@ -59,7 +59,7 @@ jobs:
       GITHUB_COMMIT: ${{ github.sha }}
       GHC_VERSION: '9.4.8'
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - id: Remote-Dir
         name: Unique directory name for the remote build
         run: echo "remotepath=postgrest-build-$(uuidgen)" >> "$GITHUB_OUTPUT"
@@ -129,7 +129,7 @@ jobs:
       - build
       - arm
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
         with:
           ssh-key: ${{ secrets.POSTGREST_SSH_KEY }}
       - name: Tag latest commit
@@ -160,7 +160,7 @@ jobs:
       - build
       - arm
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Check the version to be released
         run: |
           cabal_version="$(grep -oP '^version:\s*\K.*' postgrest.cabal)"
@@ -199,7 +199,7 @@ jobs:
       - prepare
     if: success() || needs.prepare.result == 'success'
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Download all artifacts
         uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e # v4.1.7
         with:
@@ -273,7 +273,7 @@ jobs:
       DOCKER_USER: ${{ vars.DOCKER_USER }}
       DOCKER_PASS: ${{ secrets.DOCKER_PASS }}
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Download Docker image
         uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e # v4.1.7
         with:
@@ -303,7 +303,7 @@ jobs:
       vars.DOCKER_REPO && vars.DOCKER_USER &&
       github.ref == 'refs/tags/devel'
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - uses: peter-evans/dockerhub-description@e98e4d1628a5f3be2be7c231e50981aee98723ae # v4.0.0
         with:
           username: ${{ vars.DOCKER_USER }}
@@ -325,7 +325,7 @@ jobs:
       DOCKER_USER: ${{ vars.DOCKER_USER }}
       DOCKER_PASS: ${{ secrets.DOCKER_PASS }}
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Publish images for ARM builds on Docker Hub
         uses: appleboy/ssh-action@master
         env:
@@ -350,7 +350,7 @@ jobs:
     env:
       REMOTE_DIR: ${{ needs.arm.outputs.remotepath }}
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Remove uploaded files from server
         uses: appleboy/ssh-action@master
         with:

.github/workflows/docs.yaml

@@ -27,7 +27,7 @@ jobs:
     name: Build
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
     - name: Setup Nix Environment
       uses: ./.github/actions/setup-nix
       with:
@@ -41,7 +41,7 @@ jobs:
     name: Spellcheck
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
     - name: Setup Nix Environment
       uses: ./.github/actions/setup-nix
       with:
@@ -58,7 +58,7 @@ jobs:
     if: github.base_ref == 'main'
     runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
     - name: Setup Nix Environment
       uses: ./.github/actions/setup-nix
       with:

.github/workflows/test.yaml

@@ -39,7 +39,7 @@ jobs:
         # https://github.com/actions/runner/issues/241#issuecomment-842566950
         shell: script -qec "bash --noprofile --norc -eo pipefail {0}"
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Setup Nix Environment
         uses: ./.github/actions/setup-nix
         with:
@@ -49,7 +49,7 @@ jobs:
       - name: Run coverage (IO tests and Spec tests against PostgreSQL 15)
         run: postgrest-coverage
       - name: Upload coverage to codecov
-        uses: codecov/codecov-action@125fc84a9a348dbcf27191600683ec096ec9021c # v4.4.1
+        uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673 # v4.5.0
         with:
           files: ./coverage/codecov.json
           token: ${{ secrets.CODECOV_TOKEN }}
@@ -76,7 +76,7 @@ jobs:
         # https://github.com/actions/runner/issues/241#issuecomment-842566950
         shell: script -qec "bash --noprofile --norc -eo pipefail {0}"
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Setup Nix Environment
         uses: ./.github/actions/setup-nix
         with:
@@ -100,7 +100,7 @@ jobs:
     name: Memory
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - name: Setup Nix Environment
         uses: ./.github/actions/setup-nix
         with:
@@ -114,7 +114,7 @@ jobs:
     name: Loadtest
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
         with:
           fetch-depth: 0
       - name: Setup Nix Environment

CHANGELOG.md

@@ -5,6 +5,17 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+## [12.2.1] - 2024-06-27
+
+### Fixed
+
+ - #3147, Don't reload schema cache on every listener failure - @steve-chavez
+
+### Documentation
+
+ - #3592, Architecture diagram now supports dark mode and has links - @laurenceisla
+ - #3616, The schema isolation diagram now supports dark mode and uses well-known schemas - @laurenceisla
+
 ## [12.2.0] - 2024-06-11
 
 ### Added

docs/_diagrams/README.md

@@ -5,35 +5,20 @@ The ER diagrams were created with https://github.com/BurntSushi/erd/.
 You can go download erd from https://github.com/BurntSushi/erd/releases and then do:
 
 ```bash
-./erd_static-x86-64 -i film.er -o ../_static/film.png
+./erd_static-x86-64 -i ./er/film.er -o ../_static/film.png
 ```
 
 The fonts used belong to the GNU FreeFont family. You can download them here: http://ftp.gnu.org/gnu/freefont/
 
-## LaTeX
+## UML
 
-The schema structure diagram is done with LaTeX. You can use a GUI like https://www.mathcha.io/editor to create the .tex file.
+The UML diagrams are created with https://plantuml.com/.
 
-Then use this command to generate the png file.
+PlantUML only creates one diagram per file.
+That's why we need to create another one for dark mode.
+For 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:
 
 ```bash
-postgrest-docs-render
-```
-
-LaTeX is used because it's a tweakable plain text format.
-
-You can install the full latex suite with `nix`:
-
-```
-nix-env -iA texlive.combined.scheme-full
-```
-
-To tweak the file with a live reload environment use:
-
-```bash
-# open the pdf(zathura used as an example)
-zathura db.pdf &
-
-# live reload with entr
-echo db.tex | entr pdflatex --shell-escape -halt-on-error db.tex
+plantuml -tsvg uml/arch.uml -o ../../_static
+plantuml -tsvg -darkmode uml/dark/arch-dark.uml -o ../../../_static
 ```

docs/_diagrams/db.tex

@@ -1,71 +0,0 @@
-\documentclass[convert]{standalone}
-\usepackage{amsmath}
-\usepackage{tikz}
-\usepackage{mathdots}
-\usepackage{yhmath}
-\usepackage{cancel}
-\usepackage{color}
-\usepackage{siunitx}
-\usepackage{array}
-\usepackage{multirow}
-\usepackage{amssymb}
-\usepackage{gensymb}
-\usepackage{tabularx}
-\usepackage{booktabs}
-\usetikzlibrary{fadings}
-\usetikzlibrary{patterns}
-\usetikzlibrary{shadows.blur}
-\usetikzlibrary{shapes}
-
-\begin{document}
-
-\newcommand\customScale{0.35}
-
-\begin{tikzpicture}[x=0.75pt,y=0.75pt,yscale=-1,xscale=1, scale=\customScale, every node/.style={scale=\customScale}]
-
-%Shape: Can [id:dp7234864758664346]
-\draw  [fill={rgb, 255:red, 47; green, 97; blue, 144 }  ,fill opacity=1 ] (497.5,51.5) -- (497.5,255.5) .. controls (497.5,275.66) and (423.18,292) .. (331.5,292) .. controls (239.82,292) and (165.5,275.66) .. (165.5,255.5) -- (165.5,51.5) .. controls (165.5,31.34) and (239.82,15) .. (331.5,15) .. controls (423.18,15) and (497.5,31.34) .. (497.5,51.5) .. controls (497.5,71.66) and (423.18,88) .. (331.5,88) .. controls (239.82,88) and (165.5,71.66) .. (165.5,51.5) ;
-%Shape: Rectangle [id:dp7384065579958246]
-\draw  [fill={rgb, 255:red, 236; green, 227; blue, 227 }  ,fill opacity=1 ] (189,115) -- (252.5,115) -- (252.5,155) -- (189,155) -- cycle ;
-%Shape: Rectangle [id:dp24763906430298177]
-\draw  [fill={rgb, 255:red, 236; green, 227; blue, 227 }  ,fill opacity=1 ] (292,118) -- (362,118) -- (362,158) -- (292,158) -- cycle ;
-%Shape: Rectangle [id:dp3775601612537265]
-\draw  [fill={rgb, 255:red, 236; green, 227; blue, 227 }  ,fill opacity=1 ] (397,114) -- (467,114) -- (467,154) -- (397,154) -- cycle ;
-%Shape: Rectangle [id:dp7071457022893852]
-\draw  [fill={rgb, 255:red, 248; green, 231; blue, 28 }  ,fill opacity=1 ] (269,199) -- (397.5,199) -- (397.5,273) -- (269,273) -- cycle ;
-%Straight Lines [id:da8846759047437789]
-\draw    (268,234) -- (226.44,155.77) ;
-\draw [shift={(225.5,154)}, rotate = 422.02] [color={rgb, 255:red, 0; green, 0; blue, 0 }  ][line width=0.75]    (10.93,-3.29) .. controls (6.95,-1.4) and (3.31,-0.3) .. (0,0) .. controls (3.31,0.3) and (6.95,1.4) .. (10.93,3.29)   ;
-%Straight Lines [id:da6908444738113828]
-\draw    (309.5,198) -- (307.6,161) ;
-\draw [shift={(307.5,159)}, rotate = 447.06] [color={rgb, 255:red, 0; green, 0; blue, 0 }  ][line width=0.75]    (10.93,-3.29) .. controls (6.95,-1.4) and (3.31,-0.3) .. (0,0) .. controls (3.31,0.3) and (6.95,1.4) .. (10.93,3.29)   ;
-%Straight Lines [id:da7168757864413169]
-\draw    (398.5,233) -- (431.72,154.84) ;
-\draw [shift={(432.5,153)}, rotate = 473.03] [color={rgb, 255:red, 0; green, 0; blue, 0 }  ][line width=0.75]    (10.93,-3.29) .. controls (6.95,-1.4) and (3.31,-0.3) .. (0,0) .. controls (3.31,0.3) and (6.95,1.4) .. (10.93,3.29)   ;
-%Up Down Arrow [id:dp14059754167108496]
-\draw  [fill={rgb, 255:red, 126; green, 211; blue, 33 }  ,fill opacity=1 ] (312.5,288.5) -- (330,273) -- (347.5,288.5) -- (338.75,288.5) -- (338.75,319.5) -- (347.5,319.5) -- (330,335) -- (312.5,319.5) -- (321.25,319.5) -- (321.25,288.5) -- cycle ;
-
-% Text Node
-\draw (201,129) node [anchor=north west][inner sep=0.75pt]   [align=left] {tables};
-% Text Node
-\draw (307,130) node [anchor=north west][inner sep=0.75pt]   [align=left ] {tables};
-% Text Node
-\draw (414,127) node [anchor=north west][inner sep=0.75pt]   [align=left] {tables};
-% Text Node
-\draw (300,203) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 0; green, 0; blue, 0 }  ,opacity=1 ] [align=center] { \\ views \\ + \\ \ \ functions};
-
-% Text Node
-\draw (322,178) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 255; green, 255; blue, 255 }  ,opacity=1 ] [align=left] {\large\textbf{api}};
-% Text Node
-\draw (190,97) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 255; green, 255; blue, 255 }  ,opacity=1 ] [align=left] {\large\textbf{internal}};
-% Text Node
-\draw (300,99) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 255; green, 255; blue, 255 }  ,opacity=1 ] [align=left] {\large\textbf{private}};
-% Text Node
-\draw (417,101) node [anchor=north west][inner sep=0.75pt]  [color={rgb, 255:red, 255; green, 255; blue, 255 }  ,opacity=1 ] [align=left] {\large\textbf{core}};
-% Text Node
-\draw (358,306) node [anchor=north west][inner sep=0.75pt]   [align=left] {REST};
-
-\end{tikzpicture}
-
-
-\end{document}

docs/_diagrams/uml/arch.uml

@@ -1,5 +1,7 @@
 @startuml
 
+skinparam backgroundColor transparent
+
 package "PostgREST" {
   () HTTP as HTTPAPI
   HTTPAPI  - [Auth]
@@ -14,11 +16,9 @@ package "PostgREST" {
   [Admin]  -r- () HTTPADMIN
   [Config] -l- () CLI
 
-  [Config] <-l~ Listener
+  [Config] <-r~ Listener
 
   HTTPADMIN -[hidden]r- CLI
-  Listener -[hidden]r- [Schema Cache]
-  Listener -[hidden]r- [Config]
   [Schema Cache] -l[hidden]- [Config]
   [Schema Cache] -l[hidden]- [Admin]
   [Schema Cache] -l[hidden]- CLI
@@ -26,16 +26,16 @@ package "PostgREST" {
 
 
 database "PostgreSQL" {
-  node "API schema" as API {
-    rectangle "Functions, Views"
-  }
   node Authorization {
     rectangle "Roles, GRANT, RLS"
   }
+  node "API schema" as API {
+    rectangle "Functions, Views"
+  }
   rectangle "Tables, extensions" as tbs
   API -d- tbs
 
- API -[hidden]l- Authorization
+  API -l[hidden]- Authorization
 }
 
 :user:
@@ -67,4 +67,18 @@ end note
 note top of Listener
   LISTEN session
 end note
+
+url of Admin is [[../references/admin_server.html#admin-server]]
+url of API is [[../explanations/schema_isolation.html]]
+url of Auth is [[../references/auth.html#authn]]
+url of Authorization is [[../explanations/db_authz.html]]
+url of CLI is [[../references/cli.html#cli]]
+url of "Connection Pool" is [[../references/connection_pool.html]]
+url of Config is [[../references/configuration.html#configuration]]
+url of HTTPADMIN is [[https://aosabook.org/en/posa/warp.html]]
+url of HTTPAPI is [[https://aosabook.org/en/posa/warp.html]]
+url of Listener is [[../references/listener.html#listener]]
+url of Proxy is [[../explanations/nginx.html]]
+url of "Schema Cache" is [[../references/schema_cache.html#schema-cache]]
+
 @enduml

docs/_diagrams/uml/dark/arch-dark.uml

@@ -0,0 +1,3 @@
+@startuml
+!include ../arch.uml
+@enduml

docs/_diagrams/uml/dark/sch-iso-dark.uml

@@ -0,0 +1,3 @@
+@startuml
+!include ../sch-iso.uml
+@enduml

docs/_diagrams/uml/sch-iso.uml

@@ -0,0 +1,29 @@
+@startuml
+
+skinparam backgroundColor transparent
+skinparam linetype ortho
+
+skinparam node {
+  backgroundColor transparent
+  borderThickness 1
+}
+
+database "PostgreSQL" {
+  node public {
+    rectangle tables_public as "tables"
+  }
+
+  node extensions as "**extensions**" {
+  }
+
+  node API as "<size:20>api" {
+    rectangle vf_api as "views + functions"
+  }
+
+  tables_public <-- vf_api
+  extensions <-- vf_api
+}
+
+vf_api <-[thickness=3]-> () PostgREST
+
+@enduml

docs/_static/css/custom.css

@@ -149,3 +149,7 @@ html[data-theme="dark"] .img-translucent img {
   transition: background-color 0.3s;
   margin-bottom: 24px;
 }
+
+.svg-container-md {
+  max-width: 400px;
+}

docs/_static/sch-iso-dark.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="411px" preserveAspectRatio="none" style="width:315px;height:411px;" version="1.1" viewBox="0 0 315 411" width="315px" zoomAndPan="magnify"><defs/><g><!--cluster PostgreSQL--><g id="cluster_PostgreSQL"><path d="M6,16 C6,6 152,6 152,6 C152,6 298,6 298,16 L298,309.14 C298,319.14 152,319.14 152,319.14 C152,319.14 6,319.14 6,309.14 L6,16 " fill="none" style="stroke:#E7E7E7;stroke-width:1.0;"/><path d="M6,16 C6,26 152,26 152,26 C152,26 298,26 298,16 " fill="none" style="stroke:#E7E7E7;stroke-width:1.0;"/><text fill="#FFFFFF" font-family="sans-serif" font-size="14" font-weight="bold" lengthAdjust="spacing" textLength="81.375" x="111.3125" y="42.9659">PostgreSQL</text></g><!--cluster public--><g id="cluster_public"><polygon fill="none" points="30,77,40,67,150,67,150,155.07,140,165.07,30,165.07,30,77" style="stroke:#E7E7E7;stroke-width:1.0;"/><line style="stroke:#E7E7E7;stroke-width:1.0;" x1="140" x2="150" y1="77" y2="67"/><line style="stroke:#E7E7E7;stroke-width:1.0;" x1="30" x2="140" y1="77" y2="77"/><line style="stroke:#E7E7E7;stroke-width:1.0;" x1="140" x2="140" y1="77" y2="165.07"/><text fill="#FFFFFF" font-family="sans-serif" font-size="14" font-weight="bold" lengthAdjust="spacing" textLength="44.625" x="63.6875" y="94.9659">public</text></g><!--cluster API--><g id="cluster_API"><polygon fill="none" points="68,199.07,78,189.07,236,189.07,236,285.14,226,295.14,68,295.14,68,199.07" style="stroke:#E7E7E7;stroke-width:1.0;"/><line style="stroke:#E7E7E7;stroke-width:1.0;" x1="226" x2="236" y1="199.07" y2="189.07"/><line style="stroke:#E7E7E7;stroke-width:1.0;" x1="68" x2="226" y1="199.07" y2="199.07"/><line style="stroke:#E7E7E7;stroke-width:1.0;" x1="226" x2="226" y1="199.07" y2="295.14"/><text fill="#FFFFFF" font-family="sans-serif" font-size="20" font-weight="bold" lengthAdjust="spacing" textLength="29.875" x="133.0625" y="223.45">api</text></g><!--entity tables_public--><g id="elem_tables_public"><rect fill="#313139" height="39.0679" rx="2.5" ry="2.5" style="stroke:#E7E7E7;stroke-width:0.5;" width="61" x="69.5" y="110"/><text fill="#FFFFFF" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="41" x="79.5" y="134.9659">tables</text></g><!--entity extensions--><g id="elem_extensions"><polygon fill="none" points="165.81,115,175.81,105,282.185,105,282.185,144.0679,272.185,154.0679,165.81,154.0679,165.81,115" style="stroke:#E7E7E7;stroke-width:1.0;"/><line style="stroke:#E7E7E7;stroke-width:1.0;" x1="272.185" x2="282.185" y1="115" y2="105"/><line style="stroke:#E7E7E7;stroke-width:1.0;" x1="165.81" x2="272.185" y1="115" y2="115"/><line style="stroke:#E7E7E7;stroke-width:1.0;" x1="272.185" x2="272.185" y1="115" y2="154.0679"/><text fill="#FFFFFF" font-family="sans-serif" font-size="14" font-weight="bold" lengthAdjust="spacing" textLength="76.375" x="180.81" y="139.9659">extensions</text></g><!--entity vf_api--><g id="elem_vf_api"><rect fill="#313139" height="39.0679" rx="2.5" ry="2.5" style="stroke:#E7E7E7;stroke-width:0.5;" width="136" x="84" y="240.07"/><text fill="#FFFFFF" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="116" x="94" y="265.0359">views + functions</text></g><!--entity PostgREST--><g id="elem_PostgREST"><ellipse cx="152" cy="371.14" fill="#313139" rx="8" ry="8" style="stroke:#E7E7E7;stroke-width:0.5;"/><text fill="#FFFFFF" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="70" x="117" y="403.1059">PostgREST</text></g><!--reverse link tables_public to vf_api--><g id="link_tables_public_vf_api"><path d="M107.25,155.29 C107.25,179.74 107.25,215.13 107.25,239.67 " fill="none" id="tables_public-backto-vf_api" style="stroke:#E7E7E7;stroke-width:1.0;"/><polygon fill="#E7E7E7" points="107.25,149.29,103.25,158.29,107.25,154.29,111.25,158.29,107.25,149.29" style="stroke:#E7E7E7;stroke-width:1.0;"/></g><!--reverse link extensions to vf_api--><g id="link_extensions_vf_api"><path d="M192.91,160.31 C192.91,185.07 192.91,216.68 192.91,239.61 " fill="none" id="extensions-backto-vf_api" style="stroke:#E7E7E7;stroke-width:1.0;"/><polygon fill="#E7E7E7" points="192.91,154.31,188.91,163.31,192.91,159.31,196.91,163.31,192.91,154.31" style="stroke:#E7E7E7;stroke-width:1.0;"/></g><!--link vf_api to PostgREST--><g id="link_vf_api_PostgREST"><path d="M152,285.55 C152,309.98 152,338.34 152,356.18 " fill="none" id="vf_api-PostgREST" style="stroke:#E7E7E7;stroke-width:3.0;"/><polygon fill="#E7E7E7" points="152,279.55,148,288.55,152,284.55,156,288.55,152,279.55" style="stroke:#E7E7E7;stroke-width:3.0;"/><polygon fill="#E7E7E7" points="152,362.18,156,353.18,152,357.18,148,353.18,152,362.18" style="stroke:#E7E7E7;stroke-width:3.0;"/></g><!--SRC=[KypCIyufJKbLqDFJBqxEqCqipjShpSq10000]--></g></svg>

docs/conf.py

@@ -50,7 +50,7 @@ source_suffix = ".rst"
 master_doc = "index"
 
 # This is overriden by readthedocs with the version tag anyway
-version = "devel"
+version = "12.2"
 # To avoid repetition in <title> we set this to an empty string.
 release = ""
 
@@ -295,10 +295,7 @@ def setup(app):
 # taken from https://github.com/sphinx-doc/sphinx/blob/82dad44e5bd3776ecb6fd8ded656bc8151d0e63d/sphinx/util/requests.py#L42
 user_agent = "Mozilla/5.0 (X11; Linux x86_64; rv:25.0) Gecko/20100101 Firefox/25.0"
 
-# TODO: these pages are returning 403 right now. Verify if they can be fixed by addressing the issue:
-# https://github.com/PostgREST/postgrest/issues/3544
 linkcheck_ignore = [
-    r"https://stackoverflow.com/",
     r"https://www.patreon.com/postgrest",
     r"https://blog.frankel.ch/poor-man-api",
 ]

docs/ecosystem.rst

@@ -62,6 +62,7 @@ External Notification
 
 These 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.
 
+* `pg-notify-stdout <https://github.com/mkleczek/pg-notify-stdout>`_ - writes notifications to standard output (use in shell scripts etc.)
 * `pg-notify-webhook <https://github.com/vbalasu/pg-notify-webhook>`_ - trigger webhooks from PostgreSQL's LISTEN/NOTIFY
 * `pgsql-listen-exchange <https://github.com/gmr/pgsql-listen-exchange>`_ - RabbitMQ
 * `postgres-websockets <https://github.com/diogob/postgres-websockets>`_ - expose web sockets for PostgreSQL's LISTEN/NOTIFY

docs/explanations/architecture.rst

@@ -6,7 +6,22 @@ This page describes the architecture of PostgREST.
 Bird's Eye View
 ===============
 
-.. image:: ../_static/arch.png
+You can click on the components to navigate to their respective documentation.
+
+  .. container:: img-dark
+
+    .. See https://github.com/sphinx-doc/sphinx/issues/2240#issuecomment-187366626
+
+    .. raw:: html
+
+      <object width="100%" data="../_static/arch-dark.svg" type="image/svg+xml"></object>
+
+  .. container:: img-light
+
+    .. raw:: html
+
+      <object width="100%" data="../_static/arch.svg" type="image/svg+xml"></object>
+
 
 Code Map
 ========
@@ -77,5 +92,4 @@ The HTTP server is provided by `Warp <https://aosabook.org/en/posa/warp.html>`_.
 Listener
 --------
 
-`Listener.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/Listener.hs>`_ is in charge of maintaining a `LISTEN session <https://www.postgresql.org/docs/current/sql-listen.html>`_
-that keeps the :ref:`schema_cache` and the :ref:`in_db_config` up to date.
+`Listener.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/Listener.hs>`_ is in charge of the :ref:`listener`.

docs/explanations/install.rst

@@ -190,7 +190,7 @@ When a pre-built binary does not exist for your system you can build the project
 
 You can build PostgREST from source with `Stack <https://github.com/commercialhaskell/stack>`_. It will install any necessary Haskell dependencies on your system.
 
-* `Install Stack <https://docs.haskellstack.org/en/stable/README/#how-to-install-stack>`_ for your platform
+* `Install Stack <https://docs.haskellstack.org/en/stable/#how-to-install-stack>`_ for your platform
 * Install Library Dependencies
 
   =====================  =======================================

docs/explanations/schema_isolation.rst

@@ -1,7 +1,3 @@
-.. note::
-
-  This page is a work in progress.
-
 .. _schema_isolation:
 
 Schema Isolation
@@ -12,6 +8,18 @@ A PostgREST instance exposes all the tables, views, and functions of a single `P
 It 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.
 This allows you to change the internals of your schema and maintain backwards compatibility. It also keeps your code easier to refactor, and provides a natural way to do API versioning.
 
-.. container:: img-translucent
+.. container:: svg-container-md
 
-  .. image:: ../_static/db.png
+  .. container:: img-dark
+
+    .. See https://github.com/sphinx-doc/sphinx/issues/2240#issuecomment-187366626
+
+    .. raw:: html
+
+      <object width="100%" data="../_static/sch-iso-dark.svg" type="image/svg+xml"></object>
+
+  .. container:: img-light
+
+    .. raw:: html
+
+      <object width="100%" data="../_static/sch-iso.svg" type="image/svg+xml"></object>

docs/index.rst

@@ -218,7 +218,7 @@ Here are some companies that use PostgREST in production.
 * `Datrium <https://www.datrium.com>`_
 * `Drip Depot <https://www.dripdepot.com>`_
 * `Image-charts <https://www.image-charts.com>`_
-* `Moat <https://www.oracle.com/advertising/measurement/>`_
+* `Moat <https://www.oracle.com/advertising/>`_
 * `Netwo <https://www.netwo.io>`_
 * `Nimbus <https://www.nimbusfacility.com/sg/home>`_
   - See how Nimbus uses PostgREST in `Paul Copplestone's blog post <https://paul.copplest.one/blog/nimbus-tech-2019-04.html>`_.

docs/references/api/functions.rst

@@ -3,7 +3,7 @@
 Functions as RPC
 ================
 
-*"A single resource can be the equivalent of a database function, with the power to abstract state changes over any number of storage items"* -- `Roy T. Fielding <http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-743>`_
+*"A single resource can be the equivalent of a database function, with the power to abstract state changes over any number of storage items"* -- `Roy T. Fielding <https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-743>`_
 
 Functions can perform any operation allowed by PostgreSQL (read data, modify data, :ref:`raise errors <raise_error>`, and even DDL operations). Every function in the :ref:`exposed schema <schemas>` and accessible by the :ref:`active database role <roles>` is executable under the :code:`/rpc` prefix.
 

docs/references/configuration.rst

@@ -135,14 +135,12 @@ To reload the configuration via signal, send a SIGUSR2 signal to the server proc
 Configuration Reload with NOTIFY
 --------------------------------
 
-To reload the configuration from within the database, you can use a NOTIFY command.
+To reload the configuration from within the database, you can use the ``NOTIFY`` command. See :ref:`listener`.
 
 .. code:: postgresql
 
    NOTIFY pgrst, 'reload config'
 
-The ``"pgrst"`` notification channel is enabled by default. You can name the channel with :ref:`db-channel` and enable or disable it with :ref:`db-channel-enabled`.
-
 .. _config_full_list:
 
 List of parameters
@@ -696,6 +694,7 @@ log-level
       log-level = "info"
 
       # All the above plus events for development purposes are logged
+      # Logs connection pool events and the schema cache parsing time
       log-level = "debug"
 
   Because currently there's no buffering for logging, the levels with minimal logging(``crit/error``) will increase throughput.

docs/references/listener.rst

@@ -0,0 +1,60 @@
+.. _listener:
+
+Listener
+########
+
+PostgREST uses `LISTEN <https://www.postgresql.org/docs/current/sql-listen.html>`_ to reload its :ref:`Schema Cache <schema_reloading_notify>` and :ref:`Configuration <config_reloading_notify>` via `NOTIFY <https://www.postgresql.org/docs/current/sql-notify.html>`_.
+This is useful in environments where you can’t send SIGUSR1 or SIGUSR2 Unix Signals.
+Like on cloud managed containers or on Windows systems.
+
+.. code:: postgresql
+
+  NOTIFY pgrst, 'reload schema'; -- reload schema cache
+  NOTIFY pgrst, 'reload config'; -- reload config
+  NOTIFY pgrst;                  -- reload both
+
+By default, the LISTEN channel is enabled (:ref:`db-channel-enabled`) and named ``pgrst`` (:ref:`db-channel`).
+
+Listener on Read Replicas
+=========================
+
+
+The ``LISTEN`` and ``NOTIFY`` commands do not work on PostgreSQL read replicas.
+Thus, if you connect PostgREST to a read replica the Listener will fail to start.
+
+.. code:: psql
+
+  -- check if the instance is a replica
+  postgres=# select pg_is_in_recovery();
+   pg_is_in_recovery
+  -------------------
+   t
+  (1 row)
+
+  postgres=# LISTEN pgrst;
+  ERROR:  cannot execute LISTEN during recovery
+
+To work around this, you can connect the Listener to the primary while still using the :ref:`connection_pool` on the replica.
+
+This can be done by using the standard `libpq multiple hosts <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-MULTIPLE-HOSTS>`_ and `target_session_attrs <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-TARGET-SESSION-ATTRS>`_ in your :ref:`connection string <db-uri>`.
+
+.. code:: bash
+
+  db-uri = "postgres://read_replica.host,primary.host/mydb?target_session_attrs=read-only"
+
+This will cause the :ref:`connection_pool` to connect to the read replica host and ``LISTEN`` on the fallback primary host.
+
+.. note::
+
+  Under the hood, PostgREST forces `target_session_attrs=read-write <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-TARGET-SESSION-ATTRS>`_ for the ``LISTEN`` session.
+
+.. _listener_automatic_recovery:
+
+Automatic Recovery
+==================
+
+The listener will retry reconnecting to the database if connection loss happens.
+
+- It will retry forever with exponential backoff, with a maximum backoff time of 32 seconds between retries. Each of these attempts are :ref:`logged <pgrst_logging>`.
+- Automatic recovery can be disabled by setting :ref:`db-pool-automatic-recovery` to ``false``.
+- To ensure a valid state, the listener reloads the :ref:`schema_cache` and :ref:`configuration` when recovering.

docs/references/observability.rst

@@ -22,7 +22,11 @@ PostgREST logs basic request information to ``stdout``, including the authentica
    127.0.0.1 - user [26/Jul/2021:01:56:38 -0500] "GET /clients HTTP/1.1" 200 - "" "curl/7.64.0"
    127.0.0.1 - anonymous [26/Jul/2021:01:56:48 -0500] "GET /unexistent HTTP/1.1" 404 - "" "curl/7.64.0"
 
-For diagnostic information about the server itself, PostgREST logs to ``stderr``. It includes the server version and also the version of the connected PostgreSQL.
+For diagnostic information about the server itself, PostgREST logs to ``stderr``:
+
+  - The full version of the connected PostgreSQL database.
+  - :ref:`schema_cache` statistics.
+  - The messages received by the :ref:`listener`.
 
 .. code::
 
@@ -30,6 +34,12 @@ For diagnostic information about the server itself, PostgREST logs to ``stderr``
    06/May/2024:08:16:11 -0500: Attempting to connect to the database...
    06/May/2024:08:16:11 -0500: Successfully connected to PostgreSQL 14.10 (Ubuntu 14.10-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0, 64-bit
    06/May/2024:08:16:11 -0500: Listening on port 3000
+   06/May/2024:08:16:11 -0500: Listening for notifications on the "pgrst" channel
+   06/May/2024:08:16:11 -0500: Config reloaded
+   06/May/2024:08:16:11 -0500: Schema cache queried in 3.8 milliseconds
+   06/May/2024:08:16:11 -0500: Schema cache loaded 15 Relations, 8 Relationships, 8 Functions, 0 Domain Representations, 4 Media Type Handlers
+   06/May/2024:14:11:27 -0500: Received a config reload message on the "pgrst" channel
+   06/May/2024:14:11:27 -0500: Config reloaded
 
 Database Logs
 -------------

docs/references/schema_cache.rst

@@ -47,16 +47,12 @@ For docker you can do:
 Schema Cache Reloading with NOTIFY
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-PostgREST also allows you to reload its schema cache through PostgreSQL `NOTIFY <https://www.postgresql.org/docs/current/sql-notify.html>`_.
+To reload the schema cache from within the database, you can use the ``NOTIFY`` command. See :ref:`listener`.
 
 .. code-block:: postgres
 
   NOTIFY pgrst, 'reload schema'
 
-This is useful in environments where you can’t send the SIGUSR1 Unix Signal. Like on cloud managed containers or on Windows systems.
-
-The ``pgrst`` notification channel is enabled by default. For configuring the channel, see :ref:`db-channel` and :ref:`db-channel-enabled`.
-
 .. _auto_schema_reloading:
 
 Automatic Schema Cache Reloading

docs/requirements.txt

@@ -6,4 +6,4 @@ sphinx-rtd-dark-mode>=1.3.0
 sphinx-tabs>=3.2.0
 sphinx>=5.0.2
 sphinxext-opengraph==0.9.1
-urllib3==2.2.1
+urllib3==2.2.2

nix/tools/docs.nix

@@ -2,10 +2,8 @@
 , aspellDicts
 , buildToolbox
 , checkedShellScript
-, imagemagick
 , python3
 , python3Packages
-, texlive
 , writers
 , plantuml
 }:
@@ -61,36 +59,15 @@ let
       '';
 
   render =
-    let
-      pdflatex = texlive.combine {
-        inherit (texlive)
-          amsmath
-          booktabs
-          cancel
-          gensymb
-          mathdots
-          multirow
-          pgf
-          pgf-blur
-          scheme-basic
-          siunitx
-          standalone
-          yhmath
-          ;
-      };
-    in
     checkedShellScript
       {
         name = "postgrest-docs-render";
         docs = "Render the diagrams.";
         workingDir = "/docs/_diagrams";
-        withTmpDir = true;
       }
       ''
-        ${pdflatex}/bin/pdflatex -halt-on-error -output-directory="$tmpdir" db.tex
-        ${imagemagick}/bin/convert -density 300 "$tmpdir/db.pdf" ../_static/db.png
-
-        ${plantuml}/bin/plantuml arch.uml -o ../_static
+        ${plantuml}/bin/plantuml -tsvg uml/*.uml -o ../../_static
+        ${plantuml}/bin/plantuml -tsvg -darkmode uml/dark/*.uml -o ../../../_static
       '';
 
   server =

postgrest.cabal

@@ -1,5 +1,5 @@
 name:               postgrest
-version:            12.2.0
+version:            12.2.1
 synopsis:           REST API for any Postgres database
 description:        Reads the schema of a PostgreSQL database and creates RESTful routes
                     for tables, views, and functions, supporting all HTTP methods that security

src/PostgREST/AppState.hs

@@ -29,7 +29,6 @@ module PostgREST.AppState
   , getObserver
   , isLoaded
   , isPending
-  , waitForListenerCanStart
   ) where
 
 import qualified Data.Aeson                 as JSON
@@ -99,8 +98,6 @@ data AppState = AppState
   , stateIsListenerOn         :: IORef Bool
   -- | starts the connection worker with a debounce
   , debouncedConnectionWorker :: IO ()
-  -- | Binary semaphore used to sync the listener with the connectionWorker.
-  , stateListenerCanStart     :: MVar ()
   -- | Config that can change at runtime
   , stateConf                 :: IORef AppConfig
   -- | Time used for verifying JWT expiration
@@ -159,7 +156,6 @@ initWithPool (sock, adminSock) pool conf loggerState metricsState observer = do
     <*> newIORef ConnPending
     <*> newIORef False
     <*> pure (pure ())
-    <*> newEmptyMVar
     <*> newIORef conf
     <*> mkAutoUpdate defaultUpdateSettings { updateAction = getCurrentTime }
     <*> myThreadId
@@ -321,26 +317,6 @@ getNextListenerDelay = readIORef . stateNextListenerDelay
 putNextListenerDelay :: AppState -> Int -> IO ()
 putNextListenerDelay = atomicWriteIORef . stateNextListenerDelay
 
---------------------------------------------------------------------------------------
--------------------------------------------IMPORTANT----------------------------------
---------------------------------------------------------------------------------------
--- Both of these function ensure there's no parallel connection attempts between the listener and the connection pool.
--- Doing that raised an error with GSSAPI as discussed on https://github.com/PostgREST/postgrest/issues/3569.
--- Until the root cause is found and solved, we need to prevent parallel connection attempts.
-
--- tryPutMVar doesn't lock the thread. It should always succeed since
--- the connectionWorker is the only mvar producer.
-setListenerCanStart :: AppState -> IO ()
-setListenerCanStart appState = void $ tryPutMVar (stateListenerCanStart appState) ()
-
--- | As this IO action uses `takeMVar` internally, it will only return once
--- `stateListenerCanStart` has been set using `setListenerCanStart`.
-waitForListenerCanStart :: AppState -> IO ()
-waitForListenerCanStart = takeMVar . stateListenerCanStart
-
---------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------
-
 getConfig :: AppState -> IO AppConfig
 getConfig = readIORef . stateConf
 
@@ -460,9 +436,6 @@ internalConnectionWorker appState@AppState{stateObserver=observer, stateMainThre
             observer $ ExitUnsupportedPgVersion actualPgVersion minimumPgVersion
             killThread mainThreadId
           observer (DBConnectedObs $ pgvFullName actualPgVersion)
-          -- Wake up the Listener
-          when configDbChannelEnabled $
-            setListenerCanStart appState
           -- this could be fail because the connection drops, but the loadSchemaCache will pick the error and retry again
           -- We cannot retry after it fails immediately, because db-pre-config could have user errors. We just log the error and continue.
           when configDbConfig $ reReadConfig False appState

src/PostgREST/Listener.hs

@@ -27,16 +27,10 @@ runListener appState = do
 -- | Starts a LISTEN connection and handles notifications. It recovers with exponential backoff with a cap of 32 seconds, if the LISTEN connection is lost.
 retryingListen :: AppState -> IO ()
 retryingListen appState = do
-  AppState.waitForListenerCanStart appState
   AppConfig{..} <- AppState.getConfig appState
   let
     dbChannel = toS configDbChannel
     handleFinally err = do
-      -- assume we lost notifications, call the connection worker which will also reload the schema cache
-      -- and will setListenerCanStart again
-      -- TODO: When the connection error is only on the Listener, it's wasteful to call the connectionWorker everytime.
-      AppState.connectionWorker appState
-
       AppState.putIsListenerOn appState False
       observer $ DBListenFail dbChannel (Right err)
       unless configDbPoolAutomaticRecovery $
@@ -60,6 +54,8 @@ retryingListen appState = do
 
         delay <- AppState.getNextListenerDelay appState
         when (delay > 1) $ do -- if we did a retry
+          -- assume we lost notifications, call the connection worker which will also reload the schema cache
+          AppState.connectionWorker appState
           -- reset the delay
           AppState.putNextListenerDelay appState 1
 

src/PostgREST/Version.hs

@@ -15,7 +15,7 @@ import Protolude
 
 
 -- | User friendly version number such as '1.1.1'.
--- Pre-release versions are tagged as such, e.g., '1.1.1.1 (pre-release)'.
+-- Pre-release versions are tagged as such, e.g., '1.1 (pre-release)'.
 -- If a git hash is available, it's added to the version, e.g., '1.1.1 (abcdef0)'.
 prettyVersion :: ByteString
 prettyVersion =
@@ -31,14 +31,14 @@ prettyVersion =
 
 -- | Version number used in docs.
 -- Pre-release versions link to the latest docs
--- Uses only the two first components of the version. Example: 'v1.1'
+-- Uses only the first component of the version. Example: 'v1'
 docsVersion :: Text
 docsVersion
   | isPreRelease = "latest"
-  | otherwise    =  "v" <> (T.intercalate "." . map show . take 2 $ versionBranch version)
+  | otherwise    =  "v" <> (T.intercalate "." . map show . take 1 $ versionBranch version)
 
 
--- | Versions with four components (e.g., '1.1.1.1') are treated as pre-releases.
+-- | Versions with two components (e.g., '1.1') are treated as pre-releases.
 isPreRelease :: Bool
 isPreRelease =
-  length (versionBranch version) == 4
+  length (versionBranch version) == 2