bump version to 14.11

fix: functions count in startup logs not counting overloaded functions
Renames the "Functions" in the logs to "RPCs". This clarifies that we log number of callable functions and not the number of SQL objects. Signed-off-by: Taimoor Zaeem <taimoorzaeem@gmail.com>
2026-05-04 22:59:24 +05:00 · 2026-05-04 22:08:06 +05:00 · 2026-05-04 22:08:06 +05:00 · 2026-05-04 22:08:06 +05:00 · 2026-04-27 19:53:52 +00:00 · 2026-04-27 19:51:56 +00:00
42 changed files with 653 additions and 242 deletions
@@ -2,4 +2,5 @@
 # and made its way to us through nixpkgs.
 self-hosted-runner:
  labels:
+    - macos-15-intel
    - ubuntu-24.04-arm
@@ -112,7 +112,7 @@ runs:
        echo "artifacts=${artifacts}" >> "$GITHUB_OUTPUT"
    - name: Save artifact to GitHub Actions
      if: steps.find-task.outputs.task_found
-      uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
      with:
        name: ${{ inputs.upload }}
        path: ${{ steps.download.outputs.artifacts }}
@@ -19,14 +19,14 @@ inputs:
 runs:
  using: composite
  steps:
-    - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+    - uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
      if: ${{ startsWith(github.ref, 'refs/heads/') || (inputs.save-prs && startsWith(github.ref, 'refs/pull/')) }}
      with:
        path: ${{ inputs.path }}
        key: ${{ runner.os }}-${{ inputs.prefix }}-${{ inputs.suffix }}
        restore-keys: |
          ${{ runner.os }}-${{ inputs.prefix }}-
-    - uses: actions/cache/restore@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+    - uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
      if: ${{ !startsWith(github.ref, 'refs/heads/') && !(inputs.save-prs && startsWith(github.ref, 'refs/pull/'))  }}
      with:
        path: ${{ inputs.path }}
@@ -28,7 +28,7 @@ jobs:
      # This actions creates the github token using the postgrest app secrets
      - name: Create Github App Token
        id: app-token
-        uses: actions/create-github-app-token@f8d387b68d61c58ab83c6c016672934102569859 # v3.0.0
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
        with:
          app-id: ${{ vars.POSTGREST_CI_APP_ID }}
          private-key: ${{ secrets.POSTGREST_CI_PRIVATE_KEY }}
@@ -45,7 +45,7 @@ jobs:

      # Backport action that creates the PR with given settings
      - name: Create backport PR
-        uses: korthout/backport-action@4aaf0e03a94ff0a619c9a511b61aeb42adea5b02 # v4.2.0
+        uses: korthout/backport-action@7c3f6cd5843cac11bc59a04a1b7699af93261670 # v4.5
        with:
          github_token: ${{ steps.app-token.outputs.token }}
          pull_description: 'Backport for #${pull_number}.'
@@ -42,7 +42,7 @@ jobs:
      - name: Build static executable
        run: nix-build -A postgrestStatic -A postgrestStatic.tests
      - name: Save built executable as artifact
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: postgrest-linux-static-x86-64
          path: result/bin/postgrest
@@ -51,7 +51,7 @@ jobs:
      - name: Build Docker image
        run: nix-build -A docker.image --out-link postgrest-docker.tar.gz
      - name: Save built Docker image as artifact
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: postgrest-docker-x86-64
          path: postgrest-docker.tar.gz
@@ -105,6 +105,15 @@ jobs:
            artifact: postgrest-macos-aarch64
            deps: brew link --force libpq

+          - name: MacOS x86-64
+            runs-on: macos-15-intel
+            cache: |
+              ~/.stack/pantry
+              ~/.stack/snapshots
+              ~/.stack/stack.sqlite3
+            artifact: postgrest-macos-x86-64
+            deps: brew link --force libpq
+
          - name: Windows
            runs-on: windows-2022
            cache: |
@@ -118,7 +127,7 @@ jobs:
    runs-on: ${{ matrix.runs-on }}
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: haskell-actions/setup@f9150cb1d140e9a9271700670baa38991e6fa25c # v2.10.3
+      - uses: haskell-actions/setup@cd0d9bdd65b20557f41bea4dbe43d0b5fbbfe553 # v2.11.0
        with:
          # This must match the version in stack.yaml's resolver
          ghc-version: 9.6.7
@@ -146,7 +155,7 @@ jobs:
      - name: Strip Executable
        run: strip result/postgrest*
      - name: Save built executable as artifact
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: ${{ matrix.artifact }}
          path: |
@@ -177,7 +186,7 @@ jobs:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: haskell-actions/setup@f9150cb1d140e9a9271700670baa38991e6fa25c # v2.10.3
+      - uses: haskell-actions/setup@cd0d9bdd65b20557f41bea4dbe43d0b5fbbfe553 # v2.11.0
        with:
          ghc-version: ${{ matrix.ghc }}
      - name: Cache .cabal
@@ -49,7 +49,7 @@ jobs:
          echo "Relevant extract from CHANGELOG.md:"
          cat CHANGES.md
      - name: Save CHANGES.md as artifact
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: release-changes
          path: CHANGES.md
@@ -81,6 +81,9 @@ jobs:
          tar cJvf "release-bundle/postgrest-${GITHUB_REF_NAME}-macos-aarch64.tar.xz" \
            -C artifacts/postgrest-macos-aarch64 postgrest

+          tar cJvf "release-bundle/postgrest-${GITHUB_REF_NAME}-macos-x86-64.tar.xz" \
+            -C artifacts/postgrest-macos-x86-64 postgrest
+
          tar cJvf "release-bundle/postgrest-${GITHUB_REF_NAME}-freebsd-x86-64.tar.xz" \
            -C artifacts/postgrest-freebsd-x86-64 postgrest

@@ -91,7 +94,7 @@ jobs:
            artifacts/postgrest-windows-x86-64/postgrest.exe

      - name: Save release bundle
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: release-bundle
          path: release-bundle
@@ -145,7 +148,7 @@ jobs:
        with:
          name: postgrest-ubuntu-aarch64
      - uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
-      - uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
+      - uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
        with:
          username: ${{ vars.DOCKER_USER }}
          password: ${{ secrets.DOCKER_PASS }}
@@ -51,7 +51,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@1af58845a975a7985b0beb0cbe6fbbb71a41dbad # v5.5.3
+        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
        with:
          files: ./coverage/codecov.json
          token: ${{ secrets.CODECOV_TOKEN }}
@@ -156,6 +156,7 @@ jobs:
      fail-fast: false
      matrix:
        runs-on:
+          - macos-15-intel # x86_64-darwin
          - macos-14 # aarch64-darwin
          - ubuntu-24.04 # x86_64-linux
          - ubuntu-24.04-arm # aarch64-linux
@@ -4,6 +4,45 @@ All notable changes to this project will be documented in this file. From versio

 ## Unreleased

+## [14.11] - 2026-05-04
+
+### Fixed
+
+- Fix login with uppercase and mixed case role names by @taimoorzaeem in #4678
+- Restore Listener query shape so it can be found in `pg_stat_activity` by @mkleczek in #4857 #4859
+- The LISTEN channel now automatically recovers when it stops working due to a PostgreSQL bug @laurenceisla in #3147
+- Fix misleading "Functions" name on schema cache summary in startup logs by @taimoorzaeem in #4821
+
+## [14.10] - 2026-04-16
+
+### Added
+
+- Log when the pool is released during schema cache reload on `log-level=debug` by @mkleczek in #4668
+
+### Fixed
+
+- Fix unnecessary connection pool flushes during schema cache reloading by @mkleczek in #4645
+
+## [14.9] - 2026-04-10
+
+### Added
+
+- Log host, port and pg version of listener database connection by @mkleczek in #4617 #4618
+
+### Fixed
+
+- Remove red herring warp logs on default log-level, only emit them on `log-level=debug` by @steve-chavez in #4799
+
+## [14.8] - 2026-04-03
+
+### Added
+
+- Log a `HINT` when the LISTEN channel stops working due to a PostgreSQL bug by @laurenceisla in #4581
+
+### Fixed
+
+- Fix invalid OpenAPI 2.0 format for integer types (`smallint`, `integer`, `bigint`) by @arturbent0 in #4641
+
 ## [14.7] - 2026-03-20

 ### Fixed
@@ -2,7 +2,7 @@
 # The x86-64 is a single-static-binary image built via Nix, see:
 # nix/tools/docker/README.md

-FROM ubuntu:noble@sha256:186072bba1b2f436cbb91ef2567abca677337cfc786c86e107d25b7072feef0c AS postgrest
+FROM ubuntu:resolute@sha256:5e275723f82c67e387ba9e3c24baa0abdcb268917f276a0561c97bef9450d0b4 AS postgrest

 RUN apt-get update -y \
    && apt install -y --no-install-recommends libpq-dev zlib1g-dev jq gcc libnuma-dev \
@@ -6,7 +6,7 @@ Community Tutorials
 * `Building a Contacts List with PostgREST and Vue.js <https://www.youtube.com/watch?v=iHtsALtD5-U>`_ -
  In this video series, DigitalOcean shows how to build and deploy an Nginx + PostgREST(using a managed PostgreSQL database) + Vue.js webapp in an Ubuntu server droplet.

-* `PostgREST + Auth0: Create REST API in mintutes, 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.
+* `PostgREST + Auth0: Create REST API in minutes, and add social login using Auth0 <https://samkhawase.com/blog/postgrest-1-introduction/>`_ - A step-by-step tutorial to show how to dockerize and integrate Auth0 to PostgREST service.

 * `"CodeLess" backend using postgres, postgrest and oauth2 authentication with keycloak <https://www.mathieupassenaud.fr/codeless_backend/>`_ -
  A step-by-step tutorial for using PostgREST with KeyCloak(hosted on a managed service).
@@ -194,3 +194,5 @@ Websockets
 webuser
 wfts
 www
+debouncing
+deduplicates
@@ -14,7 +14,7 @@ Custom Queries

 The PostgREST URL grammar limits the kinds of queries clients can perform. It prevents arbitrary, potentially poorly constructed and slow client queries. It's good for quality of service, but means database administrators must create custom views and functions to provide richer endpoints. The most common causes for custom endpoints are

-* Table unions
+* SET operators like `UNION, INTERSECT and EXCEPT <https://www.postgresql.org/docs/current/queries-union.html>`_.
 * More complicated joins than those provided by :ref:`resource_embedding`.
 * Geo-spatial queries that require an argument, like "points near (lat,lon)"

@@ -46,7 +46,9 @@ This will cause the :ref:`connection_pool` to connect to the read replica host a

 .. 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.
+  - 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.
+    So if you specify ``target_session_attrs=read-only`` as mentioned above, PostgREST will override it for the ``LISTEN``.
+  - ``read-only`` is only available on libpq >= 14, if you use a lower version you will get an error like ``invalid target_session_attrs value: \"read-only\"``.

 .. _listener_automatic_recovery:

@@ -39,7 +39,7 @@ For diagnostic information about the server itself, PostgREST logs to ``stderr``
   06/May/2024:08:16:11 -0500: Listening for database 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:08:16:11 -0500: Schema cache loaded 15 Relations, 8 Relationships, 8 RPCs, 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

@@ -53,6 +53,19 @@ To reload the schema cache from within the database, you can use the ``NOTIFY``

  NOTIFY pgrst, 'reload schema'

+Debouncing
+~~~~~~~~~~
+
+PostgREST does not reload the schema cache for each notification when several ``NOTIFY pgrst`` events are generated quickly after one another.
+
+There are two cases to consider: when notifications are sent within a single transaction and when they are sent across multiple transactions.
+
+In the first case, PostgreSQL deduplicates identical ``NOTIFY`` events within the same transaction. This means that even if multiple ``NOTIFY pgrst`` statements are executed before a ``COMMIT``, only a single notification is delivered to PostgREST.
+
+In the second case, when notifications are sent from separate transactions in a short time span, PostgREST applies a debouncing mechanism to avoid excessive schema cache reloads.
+
+Instead of reloading the schema cache for each notification, events are grouped within a small time window of 100 milliseconds. The reload function is executed once immediately when the first notification is received and once more after the burst of events settles, resulting in at most two executions within that time window.
+
 .. _auto_schema_reloading:

 Automatic Schema Cache Reloading
@@ -25,7 +25,7 @@ let
            "ARG_OPTIONAL_SINGLE([fixtures], [f], [SQL file to load fixtures from])"
            "ARG_POSITIONAL_SINGLE([command], [Command to run])"
            "ARG_LEFTOVERS([command arguments])"
-            "ARG_USE_ENV([PGUSER], [postgrest_test_authenticator], [Authenticator PG role])"
+            "ARG_USE_ENV([PGUSER], [Postgrest_Test_Authenticator], [Authenticator PG role])" # user is written in mixed case to implicitly test that it is being properly quoted in schema cache queries
            "ARG_USE_ENV([PGDATABASE], [postgres], [PG database name])"
            "ARG_USE_ENV([PGRST_DB_SCHEMAS], [test], [Schema to expose])"
            "ARG_USE_ENV([PGTZ], [utc], [Timezone to use])"
@@ -1,5 +1,5 @@
 name:               postgrest
-version:            14.7
+version:            14.11
 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
@@ -303,6 +303,8 @@ test-suite observability
  main-is:            Main.hs
  other-modules:      ObsHelper
                      Observation.JwtCache
+                      Observation.MetricsSpec
+                      Observation.SchemaCacheSpec
  build-depends:      base              >= 4.9 && < 4.20
                    , base64-bytestring >= 1 && < 1.3
                    , bytestring        >= 0.10.8 && < 0.13
@@ -317,6 +319,7 @@ test-suite observability
                    , postgrest
                    , prometheus-client >= 1.1.1 && < 1.2.0
                    , protolude         >= 0.3.1 && < 0.4
+                    , text              >= 1.2.2 && < 2.2
                    , wai               >= 3.2.1 && < 3.3
  ghc-options:        -threaded -O0 -Werror -Wall -fwarn-identities
                      -fno-spec-constr -optP-Wno-nonportable-include-path
@@ -19,22 +19,23 @@ import PostgREST.Observation (Observation (..))

 import qualified PostgREST.AppState as AppState

-import Protolude
+import qualified Network.Socket as NS
+import           Protolude

-runAdmin :: AppState -> Warp.Settings -> IO ()
-runAdmin appState settings = do
-  whenJust (AppState.getSocketAdmin appState) $ \adminSocket -> do
+runAdmin :: AppState -> Maybe NS.Socket -> NS.Socket -> Warp.Settings -> IO ()
+runAdmin appState maybeAdminSocket socketREST settings = do
+  whenJust maybeAdminSocket $ \adminSocket -> do
    address <- resolveSocketToAddress adminSocket
    observer $ AdminStartObs address
    void . forkIO $ Warp.runSettingsSocket settings adminSocket adminApp
  where
-    adminApp = admin appState
+    adminApp = admin appState socketREST
    observer = AppState.getObserver appState

 -- | PostgREST admin application
-admin :: AppState.AppState -> Wai.Application
-admin appState req respond  = do
-  isMainAppReachable  <- isRight <$> reachMainApp (AppState.getSocketREST appState)
+admin :: AppState.AppState -> NS.Socket -> Wai.Application
+admin appState socketREST req respond  = do
+  isMainAppReachable  <- isRight <$> reachMainApp socketREST
  isLoaded <- AppState.isLoaded appState
  isPending <- AppState.isPending appState

@@ -60,10 +60,15 @@ import PostgREST.SchemaCache          (SchemaCache (..))
 import PostgREST.TimeIt               (timeItT)
 import PostgREST.Version              (docsVersion, prettyVersion)

-import qualified Data.ByteString.Char8 as BS
-import qualified Data.List             as L
-import qualified Network.HTTP.Types    as HTTP
-import           Protolude             hiding (Handler)
+import qualified Data.ByteString.Char8  as BS
+import qualified Data.List              as L
+import           Data.Streaming.Network (bindPortTCP,
+                                         bindRandomPortTCP)
+import qualified Data.Text              as T
+import qualified Network.HTTP.Types     as HTTP
+import qualified Network.Socket         as NS
+import           PostgREST.Unix         (createAndBindDomainSocket)
+import           Protolude              hiding (Handler)

 type Handler = ExceptT Error

@@ -72,26 +77,28 @@ run appState = do
  conf@AppConfig{..} <- AppState.getConfig appState

  AppState.schemaCacheLoader appState -- Loads the initial SchemaCache
+  (mainSocket, adminSocket) <- initSockets conf
+
  Unix.installSignalHandlers observer (AppState.getMainThreadId appState) (AppState.schemaCacheLoader appState) (AppState.readInDbConfig False appState)

  Listener.runListener appState

-  Admin.runAdmin appState (serverSettings conf)
+  Admin.runAdmin appState adminSocket mainSocket (serverSettings conf)

  let app = postgrest configLogLevel appState (AppState.schemaCacheLoader appState)

  do
-    address <- resolveSocketToAddress (AppState.getSocketREST appState)
+    address <- resolveSocketToAddress mainSocket
    observer $ AppServerAddressObs address

-  Warp.runSettingsSocket (serverSettings conf & setOnException onWarpException) (AppState.getSocketREST appState) app
+  Warp.runSettingsSocket (serverSettings conf & setOnException onWarpException) mainSocket app
  where
    observer = AppState.getObserver appState

    onWarpException :: Maybe Wai.Request -> SomeException -> IO ()
    onWarpException _ ex =
      when (shouldDisplayException ex) $
-        observer $ WarpErrorObs $ show ex
+        observer $ WarpServerObs $ show ex

    -- Similar to wai defaultShouldDisplayException in
    -- https://github.com/yesodweb/wai//blob/8c3882c60f6abe043889fc20c7efd3fa9747fa4a/warp/Network/Wai/Handler/Warp/Settings.hs#L251-L258
@@ -228,3 +235,40 @@ addRetryHint delay response = do

 isServiceUnavailable :: Wai.Response -> Bool
 isServiceUnavailable response = Wai.responseStatus response == HTTP.status503
+
+type AppSockets = (NS.Socket, Maybe NS.Socket)
+
+initSockets :: AppConfig -> IO AppSockets
+initSockets AppConfig{..} = do
+  let
+    cfg'usp = configServerUnixSocket
+    cfg'uspm = configServerUnixSocketMode
+    cfg'host = configServerHost
+    cfg'port = configServerPort
+    cfg'adminHost = configAdminServerHost
+    cfg'adminPort = configAdminServerPort
+
+  sock <- case cfg'usp of
+    -- I'm not using `streaming-commons`' bindPath function here because it's not defined for Windows,
+    -- but we need to have runtime error if we try to use it in Windows, not compile time error
+    Just path -> createAndBindDomainSocket path cfg'uspm
+    Nothing -> do
+      (_, sock) <-
+        if cfg'port /= 0
+          then do
+            sock <- bindPortTCP cfg'port (fromString $ T.unpack cfg'host)
+            pure (cfg'port, sock)
+          else do
+            -- explicitly bind to a random port, returning bound port number
+            (num, sock) <- bindRandomPortTCP (fromString $ T.unpack cfg'host)
+            pure (num, sock)
+      pure sock
+
+  adminSock <- case cfg'adminPort of
+    Just adminPort -> do
+      adminSock <- bindPortTCP adminPort (fromString $ T.unpack cfg'adminHost)
+      pure $ Just adminSock
+    Nothing -> pure Nothing
+
+  pure (sock, adminSock)
+
@@ -13,11 +13,9 @@ module PostgREST.AppState
  , getNextListenerDelay
  , getTime
  , getJwtCacheState
-  , getSocketREST
-  , getSocketAdmin
  , init
-  , initSockets
  , initWithPool
+  , putConfig -- For tests TODO refactoring
  , putNextListenerDelay
  , putSchemaCache
  , putPgVersion
@@ -32,13 +30,11 @@ module PostgREST.AppState

 import qualified Data.ByteString.Char8      as BS
 import           Data.Either.Combinators    (whenLeft)
-import qualified Data.Text                  as T (unpack)
 import qualified Hasql.Pool                 as SQL
 import qualified Hasql.Pool.Config          as SQL
 import qualified Hasql.Session              as SQL
 import qualified Hasql.Transaction.Sessions as SQL
 import qualified Network.HTTP.Types.Status  as HTTP
-import qualified Network.Socket             as NS
 import qualified PostgREST.Auth.JwtCache    as JwtCache
 import qualified PostgREST.Error            as Error
 import qualified PostgREST.Logger           as Logger
@@ -70,10 +66,7 @@ import PostgREST.SchemaCache             (SchemaCache (..),
                                          querySchemaCache,
                                          showSummary)
 import PostgREST.SchemaCache.Identifiers (quoteQi)
-import PostgREST.Unix                    (createAndBindDomainSocket)

-import Data.Streaming.Network (bindPortTCP, bindRandomPortTCP)
-import Data.String            (IsString (..))
 import Protolude

 data AppState = AppState
@@ -99,10 +92,6 @@ data AppState = AppState
  , stateNextDelay         :: IORef Int
  -- | Keeps track of the next delay for the listener
  , stateNextListenerDelay :: IORef Int
-  -- | Network socket for REST API
-  , stateSocketREST        :: NS.Socket
-  -- | Network socket for the admin UI
-  , stateSocketAdmin       :: Maybe NS.Socket
  -- | Observation handler
  , stateObserver          :: ObservationHandler
  -- | JWT Cache
@@ -117,8 +106,6 @@ data SchemaCacheStatus
  | SCPending
  deriving Eq

-type AppSockets = (NS.Socket, Maybe NS.Socket)
-
 init :: AppConfig -> IO AppState
 init conf@AppConfig{configLogLevel, configDbPoolSize} = do
  loggerState  <- Logger.init
@@ -128,12 +115,10 @@ init conf@AppConfig{configLogLevel, configDbPoolSize} = do
  observer $ AppStartObs prettyVersion

  pool <- initPool conf observer
-  (sock, adminSock) <- initSockets conf
-  state' <- initWithPool (sock, adminSock) pool conf loggerState metricsState observer
-  pure state' { stateSocketREST = sock, stateSocketAdmin = adminSock}
+  initWithPool pool conf loggerState metricsState observer --{ stateSocketREST = sock, stateSocketAdmin = adminSock}

-initWithPool :: AppSockets -> SQL.Pool -> AppConfig -> Logger.LoggerState -> Metrics.MetricsState -> ObservationHandler -> IO AppState
-initWithPool (sock, adminSock) pool conf loggerState metricsState observer = do
+initWithPool :: SQL.Pool -> AppConfig -> Logger.LoggerState -> Metrics.MetricsState -> ObservationHandler -> IO AppState
+initWithPool pool conf loggerState metricsState observer = do

  appState <- AppState pool
    <$> newIORef minimumPgVersion -- assume we're in a supported version when starting, this will be corrected on a later step
@@ -146,8 +131,6 @@ initWithPool (sock, adminSock) pool conf loggerState metricsState observer = do
    <*> myThreadId
    <*> newIORef 0
    <*> newIORef 1
-    <*> pure sock
-    <*> pure adminSock
    <*> pure observer
    <*> JwtCache.init conf observer
    <*> pure loggerState
@@ -166,40 +149,6 @@ initWithPool (sock, adminSock) pool conf loggerState metricsState observer = do
 destroy :: AppState -> IO ()
 destroy = destroyPool

-initSockets :: AppConfig -> IO AppSockets
-initSockets AppConfig{..} = do
-  let
-    cfg'usp = configServerUnixSocket
-    cfg'uspm = configServerUnixSocketMode
-    cfg'host = configServerHost
-    cfg'port = configServerPort
-    cfg'adminHost = configAdminServerHost
-    cfg'adminPort = configAdminServerPort
-
-  sock <- case cfg'usp of
-    -- I'm not using `streaming-commons`' bindPath function here because it's not defined for Windows,
-    -- but we need to have runtime error if we try to use it in Windows, not compile time error
-    Just path -> createAndBindDomainSocket path cfg'uspm
-    Nothing -> do
-      (_, sock) <-
-        if cfg'port /= 0
-          then do
-            sock <- bindPortTCP cfg'port (fromString $ T.unpack cfg'host)
-            pure (cfg'port, sock)
-          else do
-            -- explicitly bind to a random port, returning bound port number
-            (num, sock) <- bindRandomPortTCP (fromString $ T.unpack cfg'host)
-            pure (num, sock)
-      pure sock
-
-  adminSock <- case cfg'adminPort of
-    Just adminPort -> do
-      adminSock <- bindPortTCP adminPort (fromString $ T.unpack cfg'adminHost)
-      pure $ Just adminSock
-    Nothing -> pure Nothing
-
-  pure (sock, adminSock)
-
 initPool :: AppConfig -> ObservationHandler -> IO SQL.Pool
 initPool AppConfig{..} observer = do
  SQL.acquire $ SQL.settings
@@ -270,10 +219,14 @@ usePool AppState{stateObserver=observer, stateMainThreadId=mainThreadId, ..} ses

 -- | Flush the connection pool so that any future use of the pool will
 -- use connections freshly established after this call.
+-- | Emits PoolFlushed observation
 flushPool :: AppState -> IO ()
-flushPool AppState{..} = SQL.release statePool
+flushPool AppState{..} = do
+  SQL.release statePool
+  stateObserver PoolFlushed

 -- | Destroy the pool on shutdown.
+-- | Differs from flushPool in not emiting PoolFlushed observation.
 destroyPool :: AppState -> IO ()
 destroyPool AppState{..} = SQL.release statePool

@@ -313,12 +266,6 @@ getTime = stateGetTime
 getJwtCacheState :: AppState -> JwtCacheState
 getJwtCacheState = stateJwtCache

-getSocketREST :: AppState -> NS.Socket
-getSocketREST = stateSocketREST
-
-getSocketAdmin :: AppState -> Maybe NS.Socket
-getSocketAdmin = stateSocketAdmin
-
 getMainThreadId :: AppState -> ThreadId
 getMainThreadId = stateMainThreadId

@@ -366,8 +313,6 @@ retryingSchemaCacheLoad appState@AppState{stateObserver=observer, stateMainThrea
      observer $ ConnectionRetryObs delay
      putNextListenerDelay appState delay

-    flushPool appState
-
    (,) <$> qPgVersion <*> (qInDbConfig *> qSchemaCache)
  )
  where
@@ -416,6 +361,10 @@ retryingSchemaCacheLoad appState@AppState{stateObserver=observer, stateMainThrea
          -- IORef on putSchemaCache. This is why SCacheStatus is put at SCPending here to signal the Admin server (using isPending) that we're on a recovery state.
          putSCacheStatus appState SCPending
          putSchemaCache appState $ Just sCache
+          -- Flush the pool after loading the schema cache to reset any stale session cache entries
+          -- We do it after successfully querying the schema cache (because this can fail and during retries we would flush the pool repeatedly unnecessarily)
+          -- and after marking sCacheStatus as pending,
+          flushPool appState
          observer $ SchemaCacheQueriedObs resultTime
          (t, _) <- timeItT $ observer $ SchemaCacheSummaryObs $ showSummary sCache
          observer $ SchemaCacheLoadedObs t
@@ -101,7 +101,7 @@ queryDbSettings preConfFunc prepared =
        SELECT setdatabase as database,
               unnest(setconfig) as setting
        FROM pg_catalog.pg_db_role_setting
-        WHERE setrole = CURRENT_USER::regrole::oid
+        WHERE setrole = quote_ident(CURRENT_USER)::regrole::oid
          AND setdatabase IN (0, (SELECT oid FROM pg_catalog.pg_database WHERE datname = CURRENT_CATALOG))
      ),
      kv_settings AS (
@@ -142,7 +142,7 @@ queryRoleSettings pgVer prepared =
        select r.rolname, unnest(r.rolconfig) as setting
        from pg_auth_members m
        join pg_roles r on r.oid = m.roleid
-        where member = current_user::regrole::oid
+        where member = quote_ident(current_user)::regrole::oid
      ),
      kv_settings AS (
        SELECT
@@ -167,7 +167,7 @@ queryRoleSettings pgVer prepared =
    |]

    hasParameterPrivilege
-      | pgVer >= pgVersion150 = "or has_parameter_privilege(current_user::regrole::oid, ps.name, 'set')"
+      | pgVer >= pgVersion150 = "or has_parameter_privilege(quote_ident(current_user)::regrole::oid, ps.name, 'set')"
      | otherwise             = ""

    processRows :: [(Text, Maybe Text, [(Text, Text)])] -> (RoleSettings, RoleIsolationLvl)
@@ -16,26 +16,35 @@ import           PostgREST.Version     (prettyVersion)
 import qualified PostgREST.AppState as AppState
 import qualified PostgREST.Config   as Config

-import Data.Either.Combinators (whenRight)
-import Protolude
+import           Control.Arrow              ((&&&))
+import           Data.Bitraversable         (bisequence)
+import           Data.Either.Combinators    (whenRight)
+import qualified Data.Text                  as T
+import qualified Database.PostgreSQL.LibPQ  as LibPQ
+import qualified Hasql.Session              as SQL
+import           PostgREST.Config.Database  (queryPgVersion)
+import           PostgREST.Config.PgVersion (pgvFullName)
+import           Protolude

 -- | Starts the Listener in a thread
 runListener :: AppState -> IO ()
 runListener appState = do
  AppConfig{..} <- getConfig appState
  when configDbChannelEnabled $
-    void . forkIO . void $ retryingListen appState
+    void . forkIO . void $ retryingListen appState False

 -- | Starts a LISTEN connection and handles notifications. It recovers with exponential backoff with a cap of 32 seconds, if the LISTEN connection is lost.
 -- | This function never returns (but can throw) and return type enforces that.
-retryingListen :: AppState -> IO Void
-retryingListen appState = do
+retryingListen :: AppState -> Bool -> IO Void
+retryingListen appState hasDbListenerBug = do
  AppConfig{..} <- AppState.getConfig appState
  let
    dbChannel = toS configDbChannel
    onError err = do
      AppState.putIsListenerOn appState False
      observer $ DBListenFail dbChannel (Right err)
+      when (isDbListenerBug err) $
+        observer DBListenBugCallQueryFix
      unless configDbPoolAutomaticRecovery $
        killThread mainThreadId

@@ -46,7 +55,7 @@ retryingListen appState = do
      unless (delay == maxDelay) $
        AppState.putNextListenerDelay appState (delay * 2)
      -- loop running the listener
-      retryingListen appState
+      retryingListen appState (isDbListenerBug err)

  -- Execute the listener with with error handling
  handle onError $ do
@@ -59,7 +68,11 @@ retryingListen appState = do
      -- use connection
      \case
        Right db -> do
+          (pqHost, pqPort) <- SQL.withLibPQConnection db $ bisequence . (LibPQ.host &&& LibPQ.port)
+          pgFullName <- SQL.run (queryPgVersion False) db >>= either throwIO (pure . pgvFullName)
+          when hasDbListenerBug $ SQL.run callNotifQueryUsage db >>= either throwIO pure
          SQL.listen db $ SQL.toPgIdentifier dbChannel
+
          AppState.putIsListenerOn appState True

          delay <- AppState.getNextListenerDelay appState
@@ -69,7 +82,7 @@ retryingListen appState = do
            -- reset the delay
            AppState.putNextListenerDelay appState 1

-          observer $ DBListenStart dbChannel
+          observer $ DBListenStart pqHost pqPort pgFullName dbChannel

          -- wait for notifications
          -- this will never return, in case of an error it will throw and be caught by onError
@@ -94,3 +107,10 @@ retryingListen appState = do
      AppState.schemaCacheLoader appState

    releaseConnection = void . forkIO . handle (observer . DBListenerConnectionCleanupFail) . SQL.release
+
+    isDbListenerBug e = "could not access status of transaction" `T.isInfixOf` show e
+
+    -- Used to fix a Postgres bug in the listener, see: https://github.com/PostgREST/postgrest/issues/3147#issuecomment-3494591361
+    -- This query advances the async notification query tail, which solves this issue.
+    callNotifQueryUsage :: SQL.Session ()
+    callNotifQueryUsage = SQL.sql "SELECT pg_notification_queue_usage();"
@@ -110,12 +110,18 @@ observationLogger loggerState logLevel obs = case obs of
  o@PoolRequestFullfilled ->
    when (logLevel >= LogDebug) $ do
      logWithZTime loggerState $ observationMessage o
+  o@PoolFlushed ->
+    when (logLevel >= LogDebug) $ do
+      logWithZTime loggerState $ observationMessage o
  o@JwtCacheEviction ->
    when (logLevel >= LogDebug) $ do
      logWithZTime loggerState $ observationMessage o
  o@(JwtCacheLookup _) ->
    when (logLevel >= LogDebug) $ do
      logWithZTime loggerState $ observationMessage o
+  o@(WarpServerObs _) ->
+    when (logLevel >= LogDebug) $ do
+      logWithZTime loggerState $ observationMessage o
  o ->
    logWithZTime loggerState $ observationMessage o

@@ -1,4 +1,5 @@
-{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE LambdaCase    #-}
 {-|
 Module      : PostgREST.Observation
 Description : This module holds an Observation type which is the core of Observability for PostgREST.
@@ -43,9 +44,10 @@ data Observation
  | SchemaCacheSummaryObs Text
  | SchemaCacheLoadedObs Double
  | ConnectionRetryObs Int
-  | DBListenStart Text
+  | DBListenStart (Maybe ByteString) (Maybe ByteString) Text Text -- host, port, version string, channel
  | DBListenFail Text (Either SQL.ConnectionError SomeException)
  | DBListenRetry Int
+  | DBListenBugCallQueryFix
  | DBListenerGotSCacheMsg ByteString
  | DBListenerGotConfigMsg ByteString
  | DBListenerConnectionCleanupFail SomeException
@@ -61,10 +63,12 @@ data Observation
  | HasqlPoolObs SQL.Observation
  | PoolRequest
  | PoolRequestFullfilled
+  | PoolFlushed
  | JwtCacheLookup Bool
  | JwtCacheEviction
  | TerminationUnixSignalObs Text
-  | WarpErrorObs Text
+  | WarpServerObs Text
+  deriving (Generic)

 data ObsFatalError = ServerAuthError | ServerPgrstBug | ServerError42P05 | ServerError08P01

@@ -110,13 +114,15 @@ observationMessage = \case
    "Attempting to reconnect to the database in " <> (show delay::Text) <> " seconds..."
  QueryPgVersionError usageErr ->
    "Failed to query the PostgreSQL version. " <> jsonMessage usageErr
-  DBListenStart channel -> do
-    "Listening for database notifications on the " <> show channel <> " channel"
+  DBListenStart host port fullName channel -> do
+    "Listener connected to " <> fullName <> " on " <> show (fold $ host <> fmap (":" <>) port) <> " and listening for database notifications on the " <> show channel <> " channel"
  DBListenFail channel listenErr ->
    "Failed listening for database notifications on the " <> show channel <> " channel. " <>
      either showListenerConnError showListenerException listenErr
  DBListenRetry delay ->
    "Retrying listening for database notifications in " <> (show delay::Text) <> " seconds..."
+  DBListenBugCallQueryFix ->
+    "This is likely a PostgreSQL bug in the notification queue, executing the following to try to solve it: SELECT pg_notification_queue_usage();"
  DBListenerGotSCacheMsg channel ->
    "Received a schema cache reload message on the " <> show channel <> " channel"
  DBListenerGotConfigMsg channel ->
@@ -155,14 +161,16 @@ observationMessage = \case
    "Trying to borrow a connection from pool"
  PoolRequestFullfilled ->
    "Borrowed a connection from the pool"
+  PoolFlushed ->
+    "Database connection pool flushed"
  JwtCacheLookup _ ->
    "Looked up a JWT in JWT cache"
  JwtCacheEviction ->
    "Evicted entry from JWT cache"
  TerminationUnixSignalObs signal ->
    "Received termination unix signal " <> signal
-  WarpErrorObs txt ->
-    "Warp server error: " <> txt
+  WarpServerObs txt ->
+    "Warp server: " <> txt
  where
    showMillis :: Double -> Text
    showMillis x = toS $ showFFloat (Just 1) x ""
@@ -73,6 +73,12 @@ toSwaggerType colType             = case T.takeEnd 2 colType of
  "[]" -> Just SwaggerArray
  _    -> Just SwaggerString

+toSwaggerFormat :: Text -> Maybe Text
+toSwaggerFormat "smallint" = Just "int32"
+toSwaggerFormat "integer"  = Just "int32"
+toSwaggerFormat "bigint"   = Just "int64"
+toSwaggerFormat colType    = Just colType
+
 typeFromArray :: Text -> Text
 typeFromArray = T.dropEnd 2

@@ -141,7 +147,7 @@ makeProperty tbl rels col = (colName col, Inline s)
        & default_ .~ (JSON.decode . toUtf8Lazy . parseDefault (colType col) =<< colDefault col)
        & description .~ d
        & enum_ .~ e
-        & format ?~ colType col
+        & format .~ toSwaggerFormat (colType col)
        & maxLength .~ (fromIntegral <$> colMaxLen col)
        & type_ .~ toSwaggerType (colType col)
        & items .~ (SwaggerItemsObject <$> makePropertyItems (colType col))
@@ -160,7 +166,7 @@ makeProcProperty (RoutineParam n t _ _ _) = (n, Inline s)
    s = (mempty :: Schema)
          & type_ .~ toSwaggerType t
          & items .~ (SwaggerItemsObject <$> makePropertyItems t)
-          & format ?~ t
+          & format .~ toSwaggerFormat t

 makePreferParam :: [Text] -> Param
 makePreferParam ts =
@@ -192,14 +198,14 @@ makeProcGetParam (RoutineParam n t _ r v) =
    baseSchema = (mempty :: ParamOtherSchema)
      & in_ .~ ParamQuery
    schemaNotMulti = baseSchema
-      & format ?~ t
+      & format .~ toSwaggerFormat t
      & type_ ?~ toParamType (toSwaggerType t)
    schemaMulti = baseSchema
      & type_ ?~ fromMaybe SwaggerString (toSwaggerType t)
      & items ?~ SwaggerItemsPrimitive (Just CollectionMulti)
        ((mempty :: ParamSchema x)
          & type_ .~ toSwaggerTypeFromArray t
-          & format ?~ typeFromArray t)
+          & format .~ toSwaggerFormat (typeFromArray t))
    toParamType paramType = case paramType of
      -- Array uses {} in query params
      Just SwaggerArray -> SwaggerString
@@ -102,7 +102,7 @@ showSummary (SchemaCache tbls rels routs reps mediaHdlrs tzs _) =
  T.intercalate ", "
  [ show (HM.size tbls)       <> " Relations"
  , show (HM.size rels)       <> " Relationships"
-  , show (HM.size routs)      <> " Functions"
+  , show (HM.size routs)      <> " RPCs"
  , show (HM.size reps)       <> " Domain Representations"
  , show (HM.size mediaHdlrs) <> " Media Type Handlers"
  , show (S.size tzs)         <> " Timezones"
@@ -11399,7 +11399,7 @@ $$;
 DROP ROLE IF EXISTS postgrest_test_anonymous;
 CREATE ROLE postgrest_test_anonymous;

-GRANT postgrest_test_anonymous TO :PGUSER;
+GRANT postgrest_test_anonymous TO :"PGUSER";

 GRANT USAGE ON SCHEMA apflora TO postgrest_test_anonymous;
 GRANT USAGE ON SCHEMA fuzzysearch TO postgrest_test_anonymous;
@@ -4,7 +4,7 @@ set check_function_bodies = false; -- to allow conditionals based on the pg vers
 set search_path to public;

 CREATE ROLE postgrest_test_anonymous;
-ALTER ROLE :PGUSER SET pgrst.db_anon_role = 'postgrest_test_anonymous';
+ALTER ROLE :"PGUSER" SET pgrst.db_anon_role = 'postgrest_test_anonymous';

 CREATE ROLE postgrest_test_author;

@@ -21,14 +21,14 @@ alter role postgrest_test_w_superuser_settings set log_min_messages = 'fatal';
 DO $do$BEGIN
  IF (SELECT current_setting('server_version_num')::INT >= 150000) THEN
    ALTER ROLE postgrest_test_w_superuser_settings SET log_min_duration_sample = 12345;
-    GRANT SET ON PARAMETER log_min_duration_sample to postgrest_test_authenticator;
+    GRANT SET ON PARAMETER log_min_duration_sample to "Postgrest_Test_Authenticator";
  END IF;
 END$do$;

 GRANT
  postgrest_test_anonymous, postgrest_test_author,
  postgrest_test_serializable, postgrest_test_repeatable_read,
-  postgrest_test_w_superuser_settings TO :PGUSER;
+  postgrest_test_w_superuser_settings TO :"PGUSER";

 CREATE SCHEMA v1;
 GRANT USAGE ON SCHEMA v1 TO postgrest_test_anonymous;
@@ -57,7 +57,7 @@ $$ language sql;
 create function change_max_rows_config(val int, notify bool default false) returns void as $_$
 begin
  execute format($$
-    alter role postgrest_test_authenticator set pgrst.db_max_rows = %L;
+    alter role "Postgrest_Test_Authenticator" set pgrst.db_max_rows = %L;
  $$, val);
  if notify then
    perform pg_notify('pgrst', 'reload config');
@@ -66,13 +66,13 @@ end $_$ volatile security definer language plpgsql ;

 create function reset_max_rows_config() returns void as $_$
 begin
-  alter role postgrest_test_authenticator reset pgrst.db_max_rows;
+  alter role "Postgrest_Test_Authenticator" reset pgrst.db_max_rows;
 end $_$ volatile security definer language plpgsql ;

 create function change_db_schema_and_full_reload(schemas text) returns void as $_$
 begin
  execute format($$
-    alter role postgrest_test_authenticator set pgrst.db_schemas = %L;
+    alter role "Postgrest_Test_Authenticator" set pgrst.db_schemas = %L;
  $$, schemas);
  perform pg_notify('pgrst', 'reload config');
  perform pg_notify('pgrst', 'reload schema');
@@ -80,14 +80,14 @@ end $_$ volatile security definer language plpgsql ;

 create function v1.reset_db_schema_config() returns void as $_$
 begin
-  alter role postgrest_test_authenticator reset pgrst.db_schemas;
+  alter role "Postgrest_Test_Authenticator" reset pgrst.db_schemas;
  perform pg_notify('pgrst', 'reload config');
  perform pg_notify('pgrst', 'reload schema');
 end $_$ volatile security definer language plpgsql ;

 create function invalid_role_claim_key_reload() returns void as $_$
 begin
-  alter role postgrest_test_authenticator set pgrst.jwt_role_claim_key = 'test';
+  alter role "Postgrest_Test_Authenticator" set pgrst.jwt_role_claim_key = 'test';
  perform pg_notify('pgrst', 'reload config');
 end $_$ volatile security definer language plpgsql ;

@@ -100,7 +100,7 @@ $_$ language sql;

 create function reset_invalid_role_claim_key() returns void as $_$
 begin
-  alter role postgrest_test_authenticator reset pgrst.jwt_role_claim_key;
+  alter role "Postgrest_Test_Authenticator" reset pgrst.jwt_role_claim_key;
  perform pg_notify('pgrst', 'reload config');
 end $_$ volatile security definer language plpgsql ;

@@ -235,12 +235,12 @@ $$ language sql;

 create function change_db_schemas_config() returns void as $_$
 begin
-  alter role postgrest_test_authenticator set pgrst.db_schemas = 'test';
+  alter role "Postgrest_Test_Authenticator" set pgrst.db_schemas = 'test';
 end $_$ volatile security definer language plpgsql;

 create function reset_db_schemas_config() returns void as $_$
 begin
-  alter role postgrest_test_authenticator reset pgrst.db_schemas;
+  alter role "Postgrest_Test_Authenticator" reset pgrst.db_schemas;
 end $_$ volatile security definer language plpgsql ;

 create function test.get_current_schema() returns text as $$
@@ -13,7 +13,7 @@ create table replica.items as select x as id from generate_series(1, 10) x;
 DROP ROLE IF EXISTS postgrest_test_anonymous;
 CREATE ROLE postgrest_test_anonymous;

-GRANT postgrest_test_anonymous TO :PGUSER;
+GRANT postgrest_test_anonymous TO :"PGUSER";

 GRANT USAGE ON SCHEMA replica TO postgrest_test_anonymous;

@@ -55,13 +55,15 @@ def test_openapi_in_big_schema(defaultenv):
        assert response.status_code == 200


-def test_stackoverflow_is_logged(defaultenv):
-    "Stack overflow errors should be logged with the Warp error message"
+@pytest.mark.parametrize("level", ["crit", "error", "warn", "info", "debug"])
+def test_stackoverflow_is_logged(level, defaultenv):
+    "Stack overflow should be logged with the Warp message only on log-level=debug"

    env = {
        **defaultenv,
        "PGRST_DB_SCHEMAS": "apflora",
        "PGRST_DB_ANON_ROLE": "postgrest_test_anonymous",
+        "PGRST_LOG_LEVEL": level,
    }

    with run(env=env, wait_max_seconds=30, no_startup_stdout=False) as postgrest:
@@ -69,9 +71,15 @@ def test_stackoverflow_is_logged(defaultenv):
            postgrest.session.get("/")

        output = postgrest.read_stdout(nlines=10)
-        output.extend(postgrest.read_stdout(nlines=10))
+        for _ in range(3):
+            output.extend(postgrest.read_stdout(nlines=10))

-        assert any("Warp server error: stack overflow" in line for line in output)
+        found = any("Warp server: stack overflow" in line for line in output)
+
+        if level == "debug":
+            assert found
+        else:
+            assert not found


 # See: https://github.com/PostgREST/postgrest/issues/3329
@@ -109,4 +117,4 @@ def test_second_request_for_non_existent_table_should_be_quick(defaultenv):
        assert data["code"] == "PGRST205"
        first_duration = response.elapsed.total_seconds()
        response = postgrest.session.get("/unknown-table")
-        assert response.elapsed.total_seconds() < first_duration / 10
+        assert response.elapsed.total_seconds() < first_duration / 2
@@ -3,6 +3,7 @@
 import os
 import re
 import signal
+import subprocess
 import time
 import pytest

@@ -21,6 +22,19 @@ from postgrest import (
 )


+def match_log(output, matchers):
+    ito = iter(output)
+    itm = iter(matchers)
+    nextMatcher = next(itm, None)
+    while nextMatcher is not None and (line := next(ito, None)) is not None:
+        if re.match(nextMatcher, line) is not None:
+            nextMatcher = next(itm, None)
+    if nextMatcher is not None:
+        raise AssertionError(
+            f"Expected log line matching {nextMatcher} not found in output"
+        )
+
+
 def test_connect_with_dburi(dburi, defaultenv):
    "Connecting with db-uri instead of LIPQ* environment variables should work."
    defaultenv_without_libpq = {
@@ -529,6 +543,39 @@ def test_admin_ready_w_channel(defaultenv):
        assert response.status_code == 200


+def test_listener_query_is_visible_in_pg_stat_activity(defaultenv):
+    "The listener connection should show the LISTEN pgrst statement in pg_stat_activity"
+
+    env = {
+        **defaultenv,
+        "PGRST_DB_CHANNEL_ENABLED": "true",
+        "PGAPPNAME": "listener-query-test",
+    }
+
+    with run(env=env):
+        query = """
+select query
+from pg_stat_activity
+where application_name = 'listener-query-test'
+  and query = 'LISTEN "pgrst"'
+limit 1;
+"""
+        output = subprocess.check_output(
+            [
+                "psql",
+                "--set",
+                "ON_ERROR_STOP=1",
+                "--tuples-only",
+                "--no-align",
+                "-c",
+                query,
+            ],
+            text=True,
+        ).strip()
+
+        assert output == 'LISTEN "pgrst"'
+
+
 def test_admin_ready_wo_channel(defaultenv):
    "Should get a success response from the admin server ready endpoint when the LISTEN channel is disabled"

@@ -679,55 +726,45 @@ def test_log_level(level, defaultenv):
        response = postgrest.session.get("/")
        assert response.status_code == 200

-        output = sorted(postgrest.read_stdout(nlines=7))
+        output = postgrest.read_stdout(nlines=9)

        if level == "crit":
            assert len(output) == 0
        elif level == "error":
-            assert re.match(
-                r'- - - \[.+\] "GET / HTTP/1.1" 500 \d+ "" "python-requests/.+"',
-                output[0],
+            match_log(
+                output,
+                [r'- - - \[.+\] "GET / HTTP/1.1" 500 \d+ "" "python-requests/.+"'],
            )
            assert len(output) == 1
        elif level == "warn":
-            assert re.match(
-                r'- - - \[.+\] "GET / HTTP/1.1" 500 \d+ "" "python-requests/.+"',
-                output[0],
-            )
-            assert re.match(
-                r'- - postgrest_test_anonymous \[.+\] "GET /unknown HTTP/1.1" 404 \d+ "" "python-requests/.+"',
-                output[1],
+            match_log(
+                output,
+                [
+                    r'- - - \[.+\] "GET / HTTP/1.1" 500 \d+ "" "python-requests/.+"',
+                    r'- - postgrest_test_anonymous \[.+\] "GET /unknown HTTP/1.1" 404 \d+ "" "python-requests/.+"',
+                ],
            )
            assert len(output) == 2
        elif level == "info":
-            assert re.match(
-                r'- - - \[.+\] "GET / HTTP/1.1" 500 \d+ "" "python-requests/.+"',
-                output[0],
-            )
-            assert re.match(
-                r'- - postgrest_test_anonymous \[.+\] "GET / HTTP/1.1" 200 \d+ "" "python-requests/.+"',
-                output[1],
-            )
-            assert re.match(
-                r'- - postgrest_test_anonymous \[.+\] "GET /unknown HTTP/1.1" 404 \d+ "" "python-requests/.+"',
-                output[2],
+            match_log(
+                output,
+                [
+                    r'- - - \[.+\] "GET / HTTP/1.1" 500 \d+ "" "python-requests/.+"',
+                    r'- - postgrest_test_anonymous \[.+\] "GET /unknown HTTP/1.1" 404 \d+ "" "python-requests/.+"',
+                    r'- - postgrest_test_anonymous \[.+\] "GET / HTTP/1.1" 200 \d+ "" "python-requests/.+"',
+                ],
            )
            assert len(output) == 3
        elif level == "debug":
-            assert re.match(
-                r'- - - \[.+\] "GET / HTTP/1.1" 500 \d+ "" "python-requests/.+"',
-                output[0],
+            match_log(
+                output,
+                [
+                    r'- - - \[.+\] "GET / HTTP/1.1" 500 \d+ "" "python-requests/.+"',
+                    r'- - postgrest_test_anonymous \[.+\] "GET /unknown HTTP/1.1" 404 \d+ "" "python-requests/.+"',
+                    r'- - postgrest_test_anonymous \[.+\] "GET / HTTP/1.1" 200 \d+ "" "python-requests/.+"',
+                ],
            )
-            assert re.match(
-                r'- - postgrest_test_anonymous \[.+\] "GET / HTTP/1.1" 200 \d+ "" "python-requests/.+"',
-                output[1],
-            )
-            assert re.match(
-                r'- - postgrest_test_anonymous \[.+\] "GET /unknown HTTP/1.1" 404 \d+ "" "python-requests/.+"',
-                output[2],
-            )
-
-            assert len(output) == 7
+            assert len(output) == 9
            assert any("Connection" and "is available" in line for line in output)
            assert any("Connection" and "is used" in line for line in output)

@@ -1364,16 +1401,21 @@ def test_db_error_logging_to_stderr(level, defaultenv, metapostgrest):
        assert response.status_code == 500

        # ensure the message appears on the logs
-        output = sorted(postgrest.read_stdout(nlines=6))
+        output = postgrest.read_stdout(nlines=8)

        if level == "crit":
            assert len(output) == 0
        elif level == "debug":
-            assert " 500 " in output[0]
-            assert "canceling statement due to statement timeout" in output[5]
+            match_log(
+                output,
+                [
+                    r".*canceling statement due to statement timeout.*",
+                    r".*500.*",
+                ],
+            )
        else:
-            assert " 500 " in output[0]
-            assert "canceling statement due to statement timeout" in output[1]
+            assert " 500 " in output[1]
+            assert "canceling statement due to statement timeout" in output[0]

    reset_statement_timeout(metapostgrest, role)

@@ -1567,18 +1609,17 @@ def test_log_pool_req_observation(level, defaultenv):

    headers = jwtauthheader({"role": "postgrest_test_author"}, SECRET)

-    pool_req = "Trying to borrow a connection from pool"
-    pool_req_fullfill = "Borrowed a connection from the pool"
+    pool_req = r".*Trying to borrow a connection from pool.*"
+    pool_req_fullfill = r".*Borrowed a connection from the pool.*"

    with run(env=env) as postgrest:

        postgrest.session.get("/authors_only", headers=headers)

        if level == "debug":
-            output = postgrest.read_stdout(nlines=5)
-            assert pool_req in output[1]
-            assert pool_req_fullfill in output[4]
-            assert len(output) == 5
+            output = postgrest.read_stdout(nlines=7)
+            assert len(output) == 7
+            match_log(output, [pool_req, pool_req_fullfill])
        elif level == "info":
            output = postgrest.read_stdout(nlines=4)
            assert len(output) == 1
@@ -1658,6 +1699,25 @@ def test_log_listener_connection_errors(defaultenv):
        )


+def test_log_listener_connection_start(defaultenv):
+    "The logs should show the listener connection start message in a single line"
+
+    env = {
+        **defaultenv,
+        "PGRST_DB_CHANNEL_ENABLED": "true",
+    }
+
+    with run(env=env, no_startup_stdout=False, wait_for_readiness=True) as postgrest:
+        output = postgrest.read_stdout(nlines=10)
+        # Check for the listener start message containing host and port
+        # Do not check if pg version is displayed properly as it is tricky to test it
+        assert any(
+            f'"{defaultenv["PGHOST"]}:5432" and listening for database notifications on the "pgrst" channel'
+            in line
+            for line in output
+        )
+
+
 def test_db_pre_config_with_pg_reserved_words(defaultenv):
    "The db-pre-config should not fail unexpectedly when function name is a postgres reserved word"

@@ -1,7 +1,7 @@
 CREATE ROLE postgrest_test_anonymous;
 CREATE ROLE postgrest_test_author;
-GRANT postgrest_test_anonymous TO :PGUSER;
-GRANT postgrest_test_author TO :PGUSER;
+GRANT postgrest_test_anonymous TO :"PGUSER";
+GRANT postgrest_test_author TO :"PGUSER";
 CREATE SCHEMA test;

 -- PUT+PATCH target needs one record and column to modify
@@ -15,40 +15,58 @@ import qualified PostgREST.Metrics         as Metrics
 import           PostgREST.SchemaCache     (querySchemaCache)

 import qualified Observation.JwtCache
+import qualified Observation.MetricsSpec

-import ObsHelper
-import Protolude  hiding (toList, toS)
-import Test.Hspec
+import qualified Observation.SchemaCacheSpec
+import           ObsHelper
+import           PostgREST.Observation       (Observation (HasqlPoolObs))
+import           Protolude                   hiding (toList, toS)
+import           Test.Hspec

 main :: IO ()
 main = do
+  poolChan <- newChan
+  -- make sure poolChan is not growing indefinitely
+  -- start a thread that drains the channel
+  -- this is necessary because test cases operate on
+  -- copies so poolChan is never read from
+  -- this means we have another thread running for the entire duration of the spec but this shouldn't be a problem since Haskell green threads are lightweight
+  void $ forkIO $ forever $ readChan poolChan
+  metricsState <- Metrics.init (configDbPoolSize testCfg)
  pool <- P.acquire $ P.settings
    [ P.size 3
    , P.acquisitionTimeout 10
    , P.agingTimeout 60
    , P.idlenessTimeout 60
    , P.staticConnectionSettings (toUtf8 $ configDbUri testCfg)
+    -- make sure metrics are updated and pool observations published to poolChan
+    , P.observationHandler $ (writeChan poolChan <> Metrics.observationMetrics metricsState) . HasqlPoolObs
    ]

  actualPgVersion <- either (panic . show) id <$> P.use pool (queryPgVersion False)

  -- cached schema cache so most tests run fast
  baseSchemaCache <- loadSCache pool testCfg
-  sockets <- AppState.initSockets testCfg
  loggerState <- Logger.init
-  metricsState <- Metrics.init (configDbPoolSize testCfg)

  let
-    initApp sCache st config = do
-      appState <- AppState.initWithPool sockets pool config loggerState metricsState (Metrics.observationMetrics metricsState)
+    initApp sCache config = do
+      -- duplicate poolChan as a starting point
+      obsChan <- dupChan poolChan
+      stateObsChan <- newObsChan obsChan
+      appState <- AppState.initWithPool pool config loggerState metricsState (Metrics.observationMetrics metricsState <> writeChan obsChan)
      AppState.putPgVersion appState actualPgVersion
      AppState.putSchemaCache appState (Just sCache)
-      return (st, postgrest (configLogLevel config) appState (pure ()))
+      return (SpecState appState metricsState stateObsChan, postgrest (configLogLevel config) appState (pure ()))

  -- Run all test modules
  hspec $ do
-    before (initApp baseSchemaCache metricsState testCfgJwtCache) $
+    before (initApp baseSchemaCache testCfgJwtCache) $
      describe "Observation.JwtCacheObs" Observation.JwtCache.spec
+    before (initApp baseSchemaCache testCfg) $
+      describe "Feature.MetricsSpec" Observation.MetricsSpec.spec
+    before (initApp baseSchemaCache testCfg) $
+      describe "Feature.SchemaCacheSpec" Observation.SchemaCacheSpec.spec

  where
    loadSCache pool conf =
@@ -1,31 +1,69 @@
 {-# LANGUAGE AllowAmbiguousTypes       #-}
+{-# LANGUAGE DeriveAnyClass            #-}
 {-# LANGUAGE ExistentialQuantification #-}
 {-# LANGUAGE FlexibleContexts          #-}
+{-# LANGUAGE FlexibleInstances         #-}
+{-# LANGUAGE LambdaCase                #-}
+{-# LANGUAGE RankNTypes                #-}
 {-# LANGUAGE ScopedTypeVariables       #-}
 {-# LANGUAGE TupleSections             #-}
 {-# LANGUAGE TypeApplications          #-}
+{-# LANGUAGE TypeOperators             #-}
 module ObsHelper where

-import qualified Data.ByteString.Base64 as B64 (decodeLenient)
-import qualified Data.ByteString.Char8  as BS
-import qualified Data.ByteString.Lazy   as BL
-import qualified Jose.Jwa               as JWT
-import qualified Jose.Jws               as JWT
-import qualified Jose.Jwt               as JWT
+import qualified Data.ByteString                 as BS
+import qualified Data.ByteString.Base64          as B64
+import qualified Data.ByteString.Lazy            as BL
+import qualified Data.List                       as DL
+import           Data.List.NonEmpty              (fromList)
+import           Data.String                     (String)
+import qualified Data.Text                       as T
+import qualified Jose.Jwa                        as JWT
+import qualified Jose.Jws                        as JWT
+import qualified Jose.Jwt                        as JWT
+import           Network.HTTP.Types
+import qualified PostgREST.AppState              as AppState
+import           PostgREST.Config                (AppConfig (..),
+                                                  JSPathExp (..),
+                                                  LogLevel (..),
+                                                  OpenAPIMode (..),
+                                                  parseSecret)
+import qualified PostgREST.Metrics               as Metrics
+import           PostgREST.Observation           (Observation (..))
+import           Prometheus                      (Counter, getCounter)
+import           Protolude                       hiding (get, toS)
+import           System.Timeout                  (timeout)
+import           Test.Hspec
+import           Test.Hspec.Expectations.Contrib (annotate)
+-- helpers used to produce observation diagnostics in waitForObs
+-- Implementing the Show instance for Observation is hard due to having many different parameters so instead we use generic programming (`conName`) to obtain the constructor name as `Text`
+class HasConstructor f where
+  genericConstrName :: f x -> Text

-import PostgREST.Config (AppConfig (..), JSPathExp (..),
-                         LogLevel (..), OpenAPIMode (..), parseSecret)
+instance HasConstructor f => HasConstructor (D1 c f) where
+  genericConstrName (M1 x) = genericConstrName x

-import Data.List.NonEmpty              (fromList)
-import Data.String                     (String)
-import Prometheus                      (Counter, getCounter)
-import Test.Hspec.Expectations.Contrib (annotate)
+instance (HasConstructor x, HasConstructor y) => HasConstructor (x :+: y) where
+  genericConstrName (L1 l) = genericConstrName l
+  genericConstrName (R1 r) = genericConstrName r

-import Network.HTTP.Types
-import Protolude
-import Test.Hspec
-import Test.Hspec.Wai
+instance Constructor c => HasConstructor (C1 c f) where
+  genericConstrName = T.pack . conName

+data SpecState = SpecState {
+  specAppState :: AppState.AppState,
+  specMetrics  :: Metrics.MetricsState,
+  specObsChan  :: ObsChan
+}
+
+data StateCheck st m = forall a. StateCheck (st -> (String, m a)) (a -> a -> Expectation)
+
+data TimeoutException = TimeoutException deriving (Show, Exception)
+
+data ObsChan = ObsChan (Chan Observation) (Chan Observation)
+
+constrName :: (HasConstructor (Rep a), Generic a)=> a -> Text
+constrName = genericConstrName . from

 baseCfg :: AppConfig
 baseCfg = let secret = encodeUtf8 "reallyreallyreallyreallyverysafe" in
@@ -107,18 +145,12 @@ generateJWT claims =
  either mempty JWT.unJwt $ JWT.hmacEncode JWT.HS256 generateSecret (BL.toStrict claims)

 -- state check helpers
-
-data StateCheck st m = forall a. StateCheck (st -> (String, m a)) (a -> a -> Expectation)
-
 stateCheck :: (Show a, Eq a) => (c -> m a) -> (st -> (String, c)) -> (a -> a) -> StateCheck st m
 stateCheck extractValue extractComponent expect = StateCheck (second extractValue . extractComponent) (flip shouldBe . expect)

 expectField :: forall s st a c m. (KnownSymbol s, Show a, Eq a, HasField s st c) => (c -> m a) -> (a -> a) -> StateCheck st m
 expectField extractValue = stateCheck extractValue ((symbolVal (Proxy @s),) . getField @s)

-checkState :: (Traversable t) => t (StateCheck st (WaiSession st)) -> WaiSession st b -> WaiSession st ()
-checkState checks act = getState >>= flip (`checkState'` checks) act
-
 checkState' :: (Traversable t, MonadIO m) => st -> t (StateCheck st m) -> m b -> m ()
 checkState' initialState checks act = do
  expectations <- traverse (\(StateCheck g expect) -> let (msg, m) = g initialState in m >>= createExpectation msg m . expect) checks
@@ -131,3 +163,48 @@ expectCounter :: forall s st m. (KnownSymbol s, HasField s st Counter, MonadIO m
 expectCounter = expectField @s intCounter
  where
    intCounter = ((round @Double @Int) <$>) . getCounter
+
+accumulateUntilTimeout :: Int -> (s -> a -> s) -> s -> IO a -> IO s
+accumulateUntilTimeout t f start act = do
+  tid <- myThreadId
+  -- mask to make sure TimeoutException is not thrown before starting the loop
+  mask $ \unmask -> do
+    -- start timeout thread unmasking exceptions
+    ttid <- forkIOWithUnmask ($ (threadDelay t *> throwTo tid TimeoutException))
+    -- unmask effect
+    unmask (fix (\loop accum -> (act >>= loop . f accum) `onTimeout` pure accum) start)
+      -- make sure we catch timeout if happens before entering the loop
+      `onTimeout` pure start
+      -- make sure timer thread is killed on other exceptions
+      -- so that it won't throw TimeoutException later
+      `onException` killThread ttid
+  where
+    onTimeout m a = m `catch` \TimeoutException -> a
+
+newObsChan :: Chan Observation -> IO ObsChan
+newObsChan = fmap <$> ObsChan <*> dupChan
+
+-- read messages from copy chan and once condition is met drain original to the same point
+-- upon timeout report error and messages remaining in the original chan
+-- that way we report messages since last successful read
+waitForObs :: HasCallStack => ObsChan -> Int -> Text -> (Observation -> Maybe a) -> IO ()
+waitForObs (ObsChan orig copy) t msg f =
+  timeout t (readUntil copy *> readUntil orig) >>= maybe failTimeout mempty
+  where
+    failTimeout = takeUntilTimeout decisecond (readChan orig)
+        >>= expectationFailure . DL.unlines . fmap show . (failureMessageHeader :) . fmap obsDiagMessage
+    failureMessageHeader = "Timeout waiting for " <> msg <> " at " <> loc <> ". Remaining observations:"
+    readUntil = void . untilM (pure . not . null . f) . readChan
+    loc = fromMaybe "(unknown)" . head $ (T.pack . prettySrcLoc . snd <$> getCallStack callStack)
+    -- execute effectful computation until result meets provided condition
+    untilM cond m = fix $ \loop -> m >>= \a -> ifM (cond a) (pure a) loop
+    -- duplicate the provided channel and construct wairFor function binding both channels
+    -- accumulate effecful computation results into a list for specified time
+    takeUntilTimeout t' = fmap reverse . accumulateUntilTimeout t' (flip (:)) []
+    decisecond = 100000
+
+obsDiagMessage :: Observation -> Text
+obsDiagMessage = \case
+  (HasqlPoolObs o) -> show o
+  o@(DBListenStart host port name channel) -> constrName o <> show (host, port, name, channel)
+  o -> constrName o
@@ -1,4 +1,5 @@
 {-# LANGUAGE DataKinds        #-}
+{-# LANGUAGE NamedFieldPuns   #-}
 {-# LANGUAGE TypeApplications #-}
 module Observation.JwtCache where

@@ -13,9 +14,11 @@ import PostgREST.Metrics   (MetricsState (..))
 import Protolude
 import Test.Hspec.Wai.JSON (json)

-spec :: SpecWith (MetricsState, Application)
+spec :: SpecWith (SpecState, Application)
 spec = describe "Server started with JWT and metrics enabled" $ do
  it "Should not have JWT in cache" $ do
+    expectCounters <- checkState' . specMetrics <$> getState
+
    let auth = genToken [json|{"exp": 9999999999, "role": "postgrest_test_author", "id": "jdoe1"}|]

    expectCounters
@@ -27,6 +30,8 @@ spec = describe "Server started with JWT and metrics enabled" $ do
         request methodGet "/authors_only" [auth] "" `shouldRespondWith` 200

  it "Should have JWT in cache" $ do
+    expectCounters <- checkState' . specMetrics <$> getState
+
    let auth = genToken [json|{"exp": 9999999999, "role": "postgrest_test_author", "id": "jdoe2"}|]

    expectCounters
@@ -39,6 +44,8 @@ spec = describe "Server started with JWT and metrics enabled" $ do
      *> request methodGet "/authors_only" [auth] "" `shouldRespondWith` 200

  it "Should not cache invalid JWTs" $ do
+    expectCounters <- checkState' . specMetrics <$> getState
+
    let auth = authHeaderJWT "some random bytes"

    expectCounters
@@ -51,6 +58,8 @@ spec = describe "Server started with JWT and metrics enabled" $ do
      *> request methodGet "/authors_only" [auth] "" `shouldRespondWith` 401

  it "Should cache expired JWTs" $ do
+    expectCounters <- checkState' . specMetrics <$> getState
+
    let auth = genToken [json|{"exp": 1, "role": "postgrest_test_author", "id": "jdoe2"}|]

    expectCounters
@@ -63,6 +72,8 @@ spec = describe "Server started with JWT and metrics enabled" $ do
      *> request methodGet "/authors_only" [auth] "" `shouldRespondWith` 401

  it "Should evict entries from the JWT cache (jwt cache max is 2)" $ do
+    expectCounters <- checkState' . specMetrics <$> getState
+
    let jwt1 = genToken [json|{"exp": 9999999999, "role": "postgrest_test_author", "id": "jdoe3"}|]
        jwt2 = genToken [json|{"exp": 9999999999, "role": "postgrest_test_author", "id": "jdoe4"}|]
        jwt3 = genToken [json|{"exp": 9999999999, "role": "postgrest_test_author", "id": "jdoe5"}|]
@@ -82,6 +93,8 @@ spec = describe "Server started with JWT and metrics enabled" $ do
      *> request methodGet "/authors_only" [jwt3] ""

  it "Should not evict entries from the JWT cache in FIFO order" $ do
+    expectCounters <- checkState' . specMetrics <$> getState
+
    let jwt1 = genToken [json|{"exp": 9999999999, "role": "postgrest_test_author", "id": "jdoe6"}|]
        jwt2 = genToken [json|{"exp": 9999999999, "role": "postgrest_test_author", "id": "jdoe7"}|]
        jwt3 = genToken [json|{"exp": 9999999999, "role": "postgrest_test_author", "id": "jdoe8"}|]
@@ -108,6 +121,8 @@ spec = describe "Server started with JWT and metrics enabled" $ do
  -- The test case was added based on coverage report
  -- showing this scenario was not covered by previous tests
  it "Should evict entries even though all were hit" $ do
+    expectCounters <- checkState' . specMetrics <$> getState
+
    let jwt1 = genToken [json|{"exp": 9999999999, "role": "postgrest_test_author", "id": "jdoe9"}|]
        jwt2 = genToken [json|{"exp": 9999999999, "role": "postgrest_test_author", "id": "jdoe10"}|]
        jwt3 = genToken [json|{"exp": 9999999999, "role": "postgrest_test_author", "id": "jdoe11"}|]
@@ -135,4 +150,3 @@ spec = describe "Server started with JWT and metrics enabled" $ do
      requests = expectCounter @"jwtCacheRequests"
      hits = expectCounter @"jwtCacheHits"
      evictions = expectCounter @"jwtCacheEvictions"
-      expectCounters = checkState
@@ -0,0 +1,79 @@
+{-# LANGUAGE DataKinds           #-}
+{-# LANGUAGE FlexibleContexts    #-}
+{-# LANGUAGE MonadComprehensions #-}
+{-# LANGUAGE NamedFieldPuns      #-}
+{-# LANGUAGE TypeApplications    #-}
+
+module Observation.MetricsSpec where
+
+import           Data.List             (lookup)
+import           Network.Wai           (Application)
+import           ObsHelper
+import qualified PostgREST.AppState    as AppState
+import           PostgREST.Config      (AppConfig (configDbSchemas))
+import qualified PostgREST.Metrics     as Metrics
+import           PostgREST.Observation
+import           Prometheus            (getCounter, getVectorWith)
+import           Protolude
+import           Test.Hspec            (SpecWith, describe, it)
+import           Test.Hspec.Wai        (getState)
+
+spec :: SpecWith (SpecState, Application)
+spec = describe "Server started with metrics enabled" $ do
+  it "Should update pgrst_schema_cache_loads_total[SUCCESS]" $ do
+    SpecState{specAppState = appState, specMetrics = metrics, specObsChan} <- getState
+    let waitFor = waitForObs specObsChan
+
+    liftIO $ checkState' metrics [
+        schemaCacheLoads "SUCCESS" (+1)
+      ] $ do
+        AppState.schemaCacheLoader appState
+        waitFor (1 * sec) "SchemaCacheLoadedObs" $ \x -> [ o | o@(SchemaCacheLoadedObs{}) <- pure x]
+
+  it "Should update pgrst_schema_cache_loads_total[ERROR]" $ do
+    SpecState{specAppState = appState, specMetrics = metrics, specObsChan} <- getState
+    let waitFor = waitForObs specObsChan
+
+    liftIO $ checkState' metrics [
+        schemaCacheLoads "FAIL" (+1),
+        schemaCacheLoads "SUCCESS" (+1)
+      ] $ do
+        AppState.getConfig appState >>= \prev -> do
+          AppState.putConfig appState $ prev { configDbSchemas = pure "bad_schema" }
+          AppState.schemaCacheLoader appState
+          waitFor (1 * sec) "SchemaCacheErrorObs" $ \x -> [ o | o@(SchemaCacheErrorObs{}) <- pure x]
+          AppState.putConfig appState prev
+
+        -- wait up to 2 secs so that retry can happen
+        waitFor (2 * sec) "SchemaCacheLoadedObs" $ \x -> [ o | o@(SchemaCacheLoadedObs{}) <- pure x]
+
+  it "Should debounce schema cache loads" $ do
+    SpecState{specAppState = appState, specMetrics = metrics, specObsChan} <- getState
+    let waitFor = waitForObs specObsChan
+
+    liftIO $ checkState' metrics [
+        -- we expect exactly 2 successful schema cache loads
+        schemaCacheLoads "FAIL" (+0),
+        schemaCacheLoads "SUCCESS" (+2)
+      ] $ do
+        AppState.schemaCacheLoader appState
+        -- at this moment there is no dedicated observation emited
+        -- when schema cache load starts
+        -- so we wait for DBConnectedObs which is emited right after successful
+        -- PostgreSQL version query during schema cache loading
+        waitFor (1 * sec) "DBConnectedObs" $ \x -> [ o | o@(DBConnectedObs{}) <- pure x]
+        -- request schema cache load multiple times
+        -- all of them should be handled by a single schema cache load
+        replicateM_ 100 (AppState.schemaCacheLoader appState)
+        -- wait for two expected SchemaCacheLoadedObs events
+        replicateM_ 2 $ waitFor (1 * sec) "SchemaCacheLoadedObs" $ \x -> [ o | o@(SchemaCacheLoadedObs{}) <- pure x]
+        -- wait 1 sec to make sure we capture all potential schema cache loads
+        -- (there should be none but we need to verify that)
+        threadDelay $ 1 * sec
+
+
+  where
+    -- prometheus-client api to handle vectors is convoluted
+    schemaCacheLoads label = expectField @"schemaCacheLoads" $
+      fmap (maybe (0::Int) round . lookup label) . (`getVectorWith` getCounter)
+    sec = 1000000
@@ -0,0 +1,49 @@
+{-# LANGUAGE DataKinds           #-}
+{-# LANGUAGE MonadComprehensions #-}
+{-# LANGUAGE NamedFieldPuns      #-}
+module Observation.SchemaCacheSpec where
+
+import           Network.Wai           (Application)
+import           ObsHelper
+import qualified PostgREST.AppState    as AppState
+import           PostgREST.Config      (configDbSchemas)
+import           PostgREST.Observation
+import           Protolude
+import           Test.Hspec            (SpecWith, describe, it)
+import           Test.Hspec.Wai        (getState)
+
+spec :: SpecWith (SpecState, Application)
+spec = describe "Server started with metrics enabled" $ do
+
+  it "Should emit PoolFlushed, SchemaCacheQueriedObs and SchemaCacheLoadedObs when schema cache is reloaded" $ do
+    SpecState{specAppState = appState, specObsChan} <- getState
+    let waitFor = waitForObs specObsChan
+
+    liftIO $ do
+      AppState.schemaCacheLoader appState
+
+      waitFor (1 * sec) "PoolFlushed" $ \x -> [ o | o@PoolFlushed <- pure x ]
+      waitFor (1 * sec) "SchemaCacheQueriedObs" $ \x -> [ o | o@SchemaCacheQueriedObs{} <- pure x ]
+      waitFor (1 * sec) "SchemaCacheLoadedObs" $ \x -> [ o | o@SchemaCacheLoadedObs{} <- pure x ]
+
+
+  it "Should flush pool once when schema reloading retries" $ do
+    SpecState{specAppState = appState, specObsChan} <- getState
+    let waitFor = waitForObs specObsChan
+
+    liftIO $ do
+        AppState.getConfig appState >>= \cfg -> do
+          AppState.putConfig appState $ cfg { configDbSchemas = pure "bad_schema" }
+          AppState.schemaCacheLoader appState
+
+          waitFor (1 * sec) "SchemaCacheErrorObs" $ \x -> [ o | o@SchemaCacheErrorObs{} <- pure x ]
+
+          -- Restore configuration
+          AppState.putConfig appState cfg
+
+        -- Wait for 2 seconds so that retry can happen
+        waitFor (2 * sec) "PoolFlushed" $ \x -> [ o | o@PoolFlushed <- pure x ]
+        waitFor (1 * sec) "SchemaCacheQueriedObs" $ \x -> [ o | o@SchemaCacheQueriedObs{} <- pure x ]
+        waitFor (1 * sec) "SchemaCacheLoadedObs" $ \x -> [ o | o@SchemaCacheLoadedObs{} <- pure x ]
+  where
+    sec = 1000000
@@ -2,4 +2,4 @@ DROP ROLE IF EXISTS postgrest_test_anonymous, postgrest_test_author;
 CREATE ROLE postgrest_test_anonymous;
 CREATE ROLE postgrest_test_author;

-GRANT postgrest_test_anonymous, postgrest_test_author TO :PGUSER;
+GRANT postgrest_test_anonymous, postgrest_test_author TO :"PGUSER";
@@ -157,7 +157,7 @@ spec = describe "OpenAPI" $ do
              "properties": {
                "id": {
                  "description": "child_entities id comment\n\nNote:\nThis is a Primary Key.<pk/>",
-                  "format": "integer",
+                  "format": "int32",
                  "type": "integer"
                },
                "name": {
@@ -167,7 +167,7 @@ spec = describe "OpenAPI" $ do
                },
                "parent_id": {
                  "description": "Note:\nThis is a Foreign Key to `entities.id`.<fk table='entities' column='id'/>",
-                  "format": "integer",
+                  "format": "int32",
                  "type": "integer"
                }
              },
@@ -192,7 +192,7 @@ spec = describe "OpenAPI" $ do
              "properties": {
                "id": {
                  "description": "child_entities_view id comment\n\nNote:\nThis is a Primary Key.<pk/>",
-                  "format": "integer",
+                  "format": "int32",
                  "type": "integer"
                },
                "name": {
@@ -202,7 +202,7 @@ spec = describe "OpenAPI" $ do
                },
                "parent_id": {
                  "description": "Note:\nThis is a Foreign Key to `entities.id`.<fk table='entities' column='id'/>",
-                  "format": "integer",
+                  "format": "int32",
                  "type": "integer"
                }
              }
@@ -232,7 +232,7 @@ spec = describe "OpenAPI" $ do
        referralLink `shouldBe` Just
          [aesonQQ|
            {
-              "format": "integer",
+              "format": "int32",
              "type": "integer",
              "description": "Note:\nThis is a Foreign Key to `second.id`.<fk table='second' column='id'/>"
            }
@@ -337,7 +337,7 @@ spec = describe "OpenAPI" $ do
        referralLink `shouldBe` Just
          [aesonQQ|
            {
-              "format": "integer",
+              "format": "int32",
              "type": "integer",
              "description": "Note:\nThis is a Foreign Key to `pages.link`.<fk table='pages' column='link'/>"
            }
@@ -354,7 +354,7 @@ spec = describe "OpenAPI" $ do
        referralLink `shouldBe` Just
          [aesonQQ|
            {
-              "format": "integer",
+              "format": "int32",
              "type": "integer",
              "description": "Note:\nThis is a Foreign Key to `clients.id`.<fk table='clients' column='id'/>"
            }
@@ -432,7 +432,7 @@ spec = describe "OpenAPI" $ do
        types `shouldBe` Just
          [aesonQQ|
            {
-              "format": "smallint",
+              "format": "int32",
              "type": "integer"
            }
          |]
@@ -447,7 +447,7 @@ spec = describe "OpenAPI" $ do
        types `shouldBe` Just
          [aesonQQ|
            {
-              "format": "integer",
+              "format": "int32",
              "type": "integer"
            }
          |]
@@ -462,7 +462,7 @@ spec = describe "OpenAPI" $ do
        types `shouldBe` Just
          [aesonQQ|
            {
-              "format": "bigint",
+              "format": "int64",
              "type": "integer"
            }
          |]
@@ -850,7 +850,7 @@ spec = describe "OpenAPI" $ do
                "type": "string"
              },
              {
-                "format": "integer",
+                "format": "int32",
                "in": "query",
                "name": "integer",
                "required": false,
@@ -992,7 +992,7 @@ spec = describe "OpenAPI" $ do
                  "items": {}
                },
                "integer": {
-                  "format": "integer",
+                  "format": "int32",
                  "type": "integer"
                },
                "json": {
@@ -281,7 +281,7 @@ spec =
                    "properties" : {
                      "id" : {
                        "description" : "Note:\nThis is a Primary Key.<pk/>",
-                        "format" : "integer",
+                        "format" : "int32",
                        "type" : "integer"
                      },
                      "name" : {
@@ -310,7 +310,7 @@ spec =
                    "properties" : {
                      "id" : {
                        "description" : "Note:\nThis is a Primary Key.<pk/>",
-                        "format" : "integer",
+                        "format" : "int32",
                        "type" : "integer"
                      },
                      "name" : {
@@ -339,7 +339,7 @@ spec =
                    "properties" : {
                      "id" : {
                        "description" : "Note:\nThis is a Primary Key.<pk/>",
-                        "format" : "integer",
+                        "format" : "int32",
                        "type" : "integer"
                      },
                      "name" : {
@@ -368,7 +368,7 @@ spec =
                    "properties" : {
                      "id" : {
                        "description" : "Note:\nThis is a Primary Key.<pk/>",
-                        "format" : "integer",
+                        "format" : "int32",
                        "type" : "integer"
                      },
                      "another_value" : {
@@ -83,13 +83,12 @@ main = do

  -- cached schema cache so most tests run fast
  baseSchemaCache <- loadSCache pool testCfg
-  sockets <- AppState.initSockets testCfg
  loggerState <- Logger.init
  metricsState <- Metrics.init (configDbPoolSize testCfg)

  let
    initApp sCache st config = do
-      appState <- AppState.initWithPool sockets pool config loggerState metricsState (Metrics.observationMetrics metricsState)
+      appState <- AppState.initWithPool pool config loggerState metricsState (Metrics.observationMetrics metricsState)
      AppState.putPgVersion appState actualPgVersion
      AppState.putSchemaCache appState (Just sCache)
      return (st, postgrest (configLogLevel config) appState (pure ()))
@@ -4,4 +4,4 @@ CREATE ROLE postgrest_test_default_role;
 CREATE ROLE postgrest_test_author;
 CREATE ROLE postgrest_test_superuser WITH SUPERUSER;

-GRANT postgrest_test_anonymous, postgrest_test_default_role, postgrest_test_author, postgrest_test_superuser TO :PGUSER;
+GRANT postgrest_test_anonymous, postgrest_test_default_role, postgrest_test_author, postgrest_test_superuser TO :"PGUSER";
Author	SHA1	Message	Date
Taimoor Zaeem	1f69247cc2	bump version to 14.11	2026-05-04 22:59:24 +05:00
Taimoor Zaeem	e25a87bd84	fix: functions count in startup logs not counting overloaded functions Renames the "Functions" in the logs to "RPCs". This clarifies that we log number of callable functions and not the number of SQL objects. Signed-off-by: Taimoor Zaeem <taimoorzaeem@gmail.com>	2026-05-04 22:08:06 +05:00
Laurence IslaandTaimoor Zaeem	0502488b70	fix: call `pg_notification_queue_usage()` automatically when the LISTEN channel bug is detected (#4858 ) There's a PostgreSQL bug that doesn't let any listener to register in the DB: https://www.postgresql.org/message-id/flat/CAK98qZ3wZLE-RZJN_Y%2BTFjiTRPPFPBwNBpBi5K5CU8hUHkzDpw%40mail.gmail.com The only workaround is to advance the async notification queue tail, which can be done by executing: "SELECT pg_notification_queue_usage();". Before we just logged a HINT with this suggestion, but now we call that function directly and then let the listener to automatically recover. No automated tests were added here as it would be too complex and this is a PostgreSQL bug. But this was manually tested following the steps on https://github.com/PostgREST/postgrest/pull/4581#issuecomment-3690610592	2026-05-04 22:08:06 +05:00
Michal KleczekandTaimoor Zaeem	a62b6de1d0	fix: Restore showing LISTEN pgrst in pg_stat_activity	2026-05-04 22:08:06 +05:00
Taimoor ZaeemandWolfgang Walther	9baf17aed0	fix: login with uppercase and mixed case role names PostgREST failed when querying role settings where current role name contained uppercase letters. This commit resolves it by quoting the CURRENT_USER. Signed-off-by: Taimoor Zaeem <taimoorzaeem@gmail.com>	2026-04-27 19:53:52 +00:00
renovate[bot]andWolfgang Walther	d9eabb2742	chore(deps): update korthout/backport-action action to v4.5	2026-04-27 19:51:56 +00:00
renovate[bot]andWolfgang Walther	7711a86c0c	chore(deps): update ubuntu docker tag to v26	2026-04-24 06:29:44 +00:00
renovate[bot]andWolfgang Walther	d75a2bdce9	chore(deps): update korthout/backport-action action to v4.4.0	2026-04-21 09:05:15 +00:00
steve-chavezandWolfgang Walther	dd1956557d	ci: reinstate macos x86 releases Closes https://github.com/PostgREST/postgrest/issues/4755 (cherry picked from commit `b6c6bb27a8`)	2026-04-19 12:19:17 +00:00
steve-chavez	83e1bebcdc	bump version to 14.10	2026-04-16 13:54:44 -05:00
renovate[bot]andWolfgang Walther	89132e886a	chore(deps): update ubuntu:noble docker digest to c4a8d55	2026-04-16 10:44:03 +00:00
Michal KleczekandTaimoor Zaeem	abd76ca8ac	fix: Flush pool as late as possible during schema cache reloading (#4645 ) retryingSchemaCacheLoad flushes the pool upon every retry before it starts reloading the schema. This is too early as schema reloading might take some time during which new connections might be acquired. The consequence is that: * upon successful schema cache reload we might have some connections created with the old schema cache * we close connections upon each retry and under load we will keep closing and re-opening connections until schema cache load succeeds This change is to make sure we flush the pool only after successful schema cache querying but before loading (so that connections acquired during loading wait for it and do not interfere with timing the loading process).	2026-04-16 11:55:43 +05:00
Michał KłeczekandTaimoor Zaeem	df87ce46ed	add: log pool flushes Emit a dedicated PoolFlushed observation when the DB pool is released during schema cache reload.	2026-04-16 11:18:44 +05:00
renovate[bot]andWolfgang Walther	d369d2c41e	chore(deps): update haskell-actions/setup action to v2.11.0	2026-04-15 18:05:21 +00:00
Wolfgang Walther	9ee366a903	docs: fix broken link	2026-04-15 09:30:05 +02:00
Michał KłeczekandTaimoor Zaeem	01f7f13389	test(refactor): make debug output testing more robust This change introduces a match_log function, that implements lenient matching of log output lines. Tests of log output are retrofited to use the function.	2026-04-15 07:40:16 +05:00
steve-chavez	4922a9feaf	docs: target_session_attrs=read-only in libpq>=14	2026-04-14 11:11:22 -05:00
renovate[bot]andWolfgang Walther	679b957355	chore(deps): update actions/cache action to v5.0.5	2026-04-13 21:04:21 +00:00
renovate[bot]andWolfgang Walther	05df2c5692	chore(deps): update all dependencies	2026-04-12 15:25:03 +00:00
steve-chavez	16e2c73a95	bump version to 14.9	2026-04-10 18:25:04 -05:00
steve-chavez	fb31654277	fix: remove red herring warp logs on default log-level The logs added on `e95e815483` are red herrings under normal operation. This moves them to `log-level=debug` and removes "error" from the message prefix. Fixes https://github.com/PostgREST/postgrest/issues/4799	2026-04-10 18:16:19 -05:00
steve-chavez	9230f3f49a	Revert "refactor: Simplify schema cache loading triggering logic" This reverts commit `810023a47c`.	2026-04-10 18:16:19 -05:00
steve-chavez	96bbc86756	Revert "refactor: clarify debouncer function" This reverts commit `577ed4dd4c`.	2026-04-10 18:16:19 -05:00
renovate[bot]andWolfgang Walther	dd394d6f81	chore(deps): update haskell-actions/setup action to v2.10.4	2026-04-09 08:48:45 +00:00
Steve ChavezandTaimoor Zaeem	577ed4dd4c	refactor: clarify debouncer function (cherry picked from commit `3d98f8d65b`)	2026-04-08 10:46:38 +05:00
Michał KłeczekandTaimoor Zaeem	810023a47c	refactor: Simplify schema cache loading triggering logic DISCLAIMER: This commit was authored entirely by a human without the assistance of LLMs. Using debouncer to trigger schema cache loading makes it difficult to understand when exactly it is triggered. (cherry picked from commit `a4c1d945ee`)	2026-04-08 10:46:38 +05:00
renovate[bot]andWolfgang Walther	687ebf0850	chore(deps): update ubuntu:noble docker digest to 84e77de	2026-04-07 08:10:14 +00:00
Michał KłeczekandSteve Chavez	b9c8562641	add: Log pg version details of listener connection Follow-up to #4617 adding more information to log entry produced upon successful listener connection establishement.	2026-04-06 11:11:16 -05:00
Michał KłeczekandSteve Chavez	34a767a5cc	add: Log actual host and port of listener connection Diagnosing problems with listener channel notifications not being handled properly by PostgREST connected to read replicas is difficult. Issues might be related to lost connections and listener not being connected to the right host after failover or database server restarts. This patch adds logging of actual host:port used by libpq connection opened by the listener. It should make it easier to find out if PostgREST is connected to the right host.	2026-04-06 11:11:16 -05:00
steve-chavezandTaimoor Zaeem	5eac8bd203	docs: clarify set operators need views/functions Closes https://github.com/PostgREST/postgrest/issues/4780.	2026-04-06 11:18:42 +05:00
steve-chavez	9f722e0799	bump version to 14.8	2026-04-03 16:51:55 -05:00
Artur Bento de CarvalhoandSteve Chavez	0d4d1dca51	fix: use int32/int64 formats for integer types Fixed integer type mapping in OpenAPI 2.0: replaced the invalid integer format with int32/int64 and added the toSwaggerFormat function to map PostgreSQL types to valid OpenAPI 2.0 formats: smallint -> int32 integer -> int32 bigint -> int64	2026-04-03 16:36:55 -05:00
Laurence IslaandSteve Chavez	250747aadc	add(logs): Include a HINT when the LISTEN channel breaks due to a Postgres bug The HINT shows a SQL command that solves the issue.	2026-04-03 16:36:55 -05:00
Michał KłeczekandTaimoor Zaeem	aae929a718	test: Schema cache load debouncing test: adjust replicateM to 100 (cherry picked from commit `328598eaed`)	2026-04-03 08:00:57 +05:00
renovate[bot]andWolfgang Walther	77dde73057	chore(deps): update docker/login-action action to v4.1.0	2026-04-02 20:06:52 +00:00
Michal KleczekandSteve Chavez	afb95a5268	refactor(test): provide means to validate metrics and observations Some helpers are provided for introspecting metrics already (used in JWT cache tests). This change provides facilities to additionally validate emited Observation events. A new Spec module is also implemented, adding basic tests of schema cache reloading - their main goal is to excercise the new infrastructure.	2026-04-02 13:34:38 -05:00
Michał KłeczekandTaimoor Zaeem	8262faa235	refactor: move socket creation and management to App module Right now listening sockets initialization, management and usage is split between App, AppState and Admin modules: they are created in AppState.init and remembered in AppState but used only in App and Admin. It has several negative consequences: - sockets are initialized even if not needed (eg. command line invocations like dump-config or dump-schema) - it is impossible to start listening on a socket after initial schema cache load because it requires AppState This change decouples listen socket management from AppState. Sockets are created only when needed (ie. not in command line tools invocation) and passed to admin application and to Warp by the App module.	2026-04-02 12:27:31 +05:00
Michał KłeczekandTaimoor Zaeem	1d40fe5d93	test: Fix flakiness of test_second_request_for_non_existent_table_should_be_quick Changed divider in assertion (response.elapsed.total_seconds() < first_duration / divider) to 2 (from 10). (cherry picked from commit `886df84e87`)	2026-04-01 15:14:45 +05:00
renovate[bot]andWolfgang Walther	3a4dc5eff3	chore(deps): update codecov/codecov-action action to v6	2026-03-27 11:02:38 +00:00
renovate[bot]andWolfgang Walther	55912515c0	chore(deps): update all dependencies	2026-03-27 08:45:13 +00:00
postgrest-ci[bot]andGitHub	863d1c9e9b	docs: explain schema cache reload behavior with NOTIFY debouncing	2026-03-26 11:00:40 +05:00