add: per request statement timeout using prefer header

Adds a feature to set `statement_timeout` using `Prefer: timeout`
header. This also introduces a `PGRST129` error which is returned
when the timeout preferred exceeds the per-role timeout, which
prevents misuse of this feature.

Signed-off-by: Taimoor Zaeem <taimoorzaeem@gmail.com>

Author: taimoorzaeem

CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to this project will be documented in this file. From versio
 
 - Log error when `db-schemas` config contains schema `pg_catalog` or `information_schema` by @taimoorzaeem in #4359
 - Add a `HINT` when the LISTEN channel stops working due to a PostgreSQL bug by @laurenceisla in #4581
+- Add `Prefer: timeout` header for per-request `statement_timeout` by @taimoorzaeem in #4381
 
 ## [14.3] - 2026-01-03
 

docs/references/api/preferences.rst

@@ -15,6 +15,7 @@ The following preferences are supported.
 - ``Prefer: missing``. See :ref:`prefer_missing`.
 - ``Prefer: max-affected``, See :ref:`prefer_max_affected`.
 - ``Prefer: tx``. See :ref:`prefer_tx`.
+- ``Prefer: timeout``. See :ref:`prefer_timeout`.
 
 .. _prefer_handling:
 
@@ -296,3 +297,62 @@ With :ref:`RPC <functions>`, the preference is honored completely on the basis o
 .. note::
 
   It is important for functions to return ``SETOF`` or ``TABLE`` when called with ``max-affected`` preference. A violation of this would cause a :ref:`PGRST128 <pgrst128>` error.
+
+.. _prefer_timeout:
+
+Timeout
+=======
+
+You can set `statement_timeout <https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-STATEMENT-TIMEOUT>`_ for the request using this preference. This works in combination with ``handling=strict`` preference in the same header.
+
+The header only accepts integer value indicating the ``seconds`` that are set as timeout value. To demonstrate, see the following example:
+
+.. code-block:: postgres
+
+  CREATE FUNCTION test.sleep(seconds)
+  RETURNS VOID AS $$
+    SELECT pg_sleep(seconds);
+  $$ LANGUAGE SQL;
+
+.. code-block:: bash
+
+  curl -i "http://localhost:3000/rpc/sleep?seconds=5" \
+    -H "Prefer: handling=strict, timeout=2"
+
+.. code-block:: http
+
+  HTTP/1.1 500 Internal Server Error
+
+.. code-block:: json
+
+  {
+      "code": "57014",
+      "details": null,
+      "hint": null,
+      "message": "canceling statement due to statement timeout"
+  }
+
+It is important to note the timeout value cannot exceed the ``statement_timeout`` set :ref:`per-role <impersonated_settings>`. This restriction prevents misuse of this feature. PostgREST returns a :ref:`PGRST129 <pgrst129>` error in this case.
+
+.. code-block:: postgres
+
+  ALTER ROLE postgrest_test_anonymous SET statement_timeout = '3s';
+
+.. code-block:: bash
+
+  curl -i "http://localhost:3000/rpc/sleep?seconds=4" \
+    -H "Prefer: handling=strict, timeout=5"
+
+.. code-block:: http
+
+  HTTP/1.1 400 Bad Request
+  Content-Type: application/json; charset=utf-8
+
+.. code-block:: json
+
+  {
+      "code": "PGRST129",
+      "message": "Timeout preference value cannot exceed statement_timeout of role",
+      "details": "Timeout preferred: 5s, statement_timeout of role 'postgrest_test_anonymous': 3s",
+      "hint": null
+  }

docs/references/errors.rst

@@ -271,6 +271,10 @@ Related to the HTTP request elements.
 |               |             | See :ref:`prefer_max_affected`.                             |
 | PGRST128      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
+| .. _pgrst129: | 400         | ``timeout`` preference exceeds ``statement_timeout`` value  |
+|               |             | of role. See :ref:`prefer_timeout`.                         |
+| PGRST129      |             |                                                             |
++---------------+-------------+-------------------------------------------------------------+
 
 
 .. _pgrst2**:

postgrest.cabal

@@ -258,36 +258,37 @@ test-suite spec
                       Feature.RollbackSpec
                       Feature.RpcPreRequestGucsSpec
                       SpecHelper
-  build-depends:      base              >= 4.9 && < 4.20
-                    , aeson             >= 2.0.3 && < 2.3
-                    , aeson-qq          >= 0.8.1 && < 0.9
-                    , async             >= 2.1.1 && < 2.3
-                    , base64-bytestring >= 1 && < 1.3
-                    , bytestring        >= 0.10.8 && < 0.13
-                    , case-insensitive  >= 1.2 && < 1.3
-                    , containers        >= 0.5.7 && < 0.7
-                    , hasql-pool        >= 1.0.1 && < 1.1
-                    , hasql-transaction >= 1.0.1 && < 1.2
-                    , heredoc           >= 0.2 && < 0.3
-                    , hspec             >= 2.3 && < 2.12
-                    , hspec-expectations >= 0.8.4 && < 0.9
-                    , hspec-wai         >= 0.10 && < 0.12
-                    , hspec-wai-json    >= 0.10 && < 0.12
-                    , http-types        >= 0.12.3 && < 0.13
-                    , jose-jwt          >= 0.9.6 && < 0.11
-                    , lens              >= 4.14 && < 5.4
-                    , lens-aeson        >= 1.0.1 && < 1.3
-                    , monad-control     >= 1.0.1 && < 1.1
+  build-depends:      base                 >= 4.9 && < 4.20
+                    , aeson                >= 2.0.3 && < 2.3
+                    , aeson-qq             >= 0.8.1 && < 0.9
+                    , async                >= 2.1.1 && < 2.3
+                    , base64-bytestring    >= 1 && < 1.3
+                    , bytestring           >= 0.10.8 && < 0.13
+                    , case-insensitive     >= 1.2 && < 1.3
+                    , containers           >= 0.5.7 && < 0.7
+                    , hasql-pool           >= 1.0.1 && < 1.1
+                    , hasql-transaction    >= 1.0.1 && < 1.2
+                    , heredoc              >= 0.2 && < 0.3
+                    , hspec                >= 2.3 && < 2.12
+                    , hspec-expectations   >= 0.8.4 && < 0.9
+                    , hspec-wai            >= 0.10 && < 0.12
+                    , hspec-wai-json       >= 0.10 && < 0.12
+                    , http-types           >= 0.12.3 && < 0.13
+                    , jose-jwt             >= 0.9.6 && < 0.11
+                    , lens                 >= 4.14 && < 5.4
+                    , lens-aeson           >= 1.0.1 && < 1.3
+                    , monad-control        >= 1.0.1 && < 1.1
                     , postgrest
-                    , process           >= 1.4.2 && < 1.7
-                    , prometheus-client >= 1.1.1 && < 1.2.0
-                    , protolude         >= 0.3.1 && < 0.4
-                    , regex-tdfa        >= 1.2.2 && < 1.4
-                    , scientific        >= 0.3.4 && < 0.4
-                    , text              >= 1.2.2 && < 2.2
-                    , transformers-base >= 0.4.4 && < 0.5
-                    , wai               >= 3.2.1 && < 3.3
-                    , wai-extra         >= 3.0.19 && < 3.2
+                    , process              >= 1.4.2 && < 1.7
+                    , prometheus-client    >= 1.1.1 && < 1.2.0
+                    , protolude            >= 0.3.1 && < 0.4
+                    , regex-tdfa           >= 1.2.2 && < 1.4
+                    , scientific           >= 0.3.4 && < 0.4
+                    , text                 >= 1.2.2 && < 2.2
+                    , transformers-base    >= 0.4.4 && < 0.5
+                    , unordered-containers >= 0.2.8 && < 0.3
+                    , wai                  >= 3.2.1 && < 3.3
+                    , wai-extra            >= 3.0.19 && < 3.2
   ghc-options:        -threaded -O0 -Werror -Wall -fwarn-identities
                       -fno-spec-constr -optP-Wno-nonportable-include-path
                       -fno-warn-missing-signatures

src/PostgREST/ApiRequest/Preferences.hs

@@ -6,7 +6,7 @@
 --
 -- [1] https://datatracker.ietf.org/doc/html/rfc7240
 --
-{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE RecordWildCards #-}
 module PostgREST.ApiRequest.Preferences
   ( Preferences(..)
   , PreferCount(..)
@@ -17,6 +17,7 @@ module PostgREST.ApiRequest.Preferences
   , PreferTransaction(..)
   , PreferTimezone(..)
   , PreferMaxAffected(..)
+  , PreferTimeout(..)
   , fromHeaders
   , shouldCount
   , shouldExplainCount
@@ -43,6 +44,7 @@ import Protolude
 -- >>> deriving instance Show PreferHandling
 -- >>> deriving instance Show PreferTimezone
 -- >>> deriving instance Show PreferMaxAffected
+-- >>> deriving instance Show PreferTimeout
 -- >>> deriving instance Show Preferences
 
 -- | Preferences recognized by the application.
@@ -56,6 +58,7 @@ data Preferences
     , preferHandling       :: Maybe PreferHandling
     , preferTimezone       :: Maybe PreferTimezone
     , preferMaxAffected    :: Maybe PreferMaxAffected
+    , preferTimeout        :: Maybe PreferTimeout
     , invalidPrefs         :: [ByteString]
     }
 
@@ -77,12 +80,13 @@ data Preferences
 --         ( PreferTimezone "America/Los_Angeles" )
 --     , preferMaxAffected = Just
 --         ( PreferMaxAffected 100 )
+--     , preferTimeout = Nothing
 --     , invalidPrefs = []
 --     }
 --
 -- Multiple headers can also be used:
 --
--- >>> pPrint $ fromHeaders True sc [("Prefer", "resolution=ignore-duplicates"), ("Prefer", "count=exact"), ("Prefer", "missing=null"), ("Prefer", "handling=lenient"), ("Prefer", "invalid"), ("Prefer", "max-affected=5999")]
+-- >>> pPrint $ fromHeaders True sc [("Prefer", "resolution=ignore-duplicates"), ("Prefer", "count=exact"), ("Prefer", "missing=null"), ("Prefer", "handling=lenient"), ("Prefer", "invalid"), ("Prefer", "max-affected=5999"), ("Prefer", "timeout=10")]
 -- Preferences
 --     { preferResolution = Just IgnoreDuplicates
 --     , preferRepresentation = Nothing
@@ -93,6 +97,8 @@ data Preferences
 --     , preferTimezone = Nothing
 --     , preferMaxAffected = Just
 --         ( PreferMaxAffected 5999 )
+--     , preferTimeout = Just
+--         ( PreferTimeout 10 )
 --     , invalidPrefs = [ "invalid" ]
 --     }
 --
@@ -124,6 +130,7 @@ data Preferences
 --     , preferHandling = Just Strict
 --     , preferTimezone = Nothing
 --     , preferMaxAffected = Nothing
+--     , preferTimeout = Nothing
 --     , invalidPrefs = [ "anything" ]
 --     }
 --
@@ -138,7 +145,8 @@ fromHeaders allowTxDbOverride acceptedTzNames headers =
     , preferHandling       = parsePrefs [Strict, Lenient]
     , preferTimezone       = if isTimezonePrefAccepted then PreferTimezone <$> timezonePref else Nothing
     , preferMaxAffected    = PreferMaxAffected <$> maxAffectedPref
-    , invalidPrefs         = filter isUnacceptable prefs
+    , preferTimeout        = PreferTimeout <$> timeoutPref
+    , invalidPrefs         = filter (not . isPrefValid) prefs
     }
   where
     mapToHeadVal :: ToHeaderValue a => [a] -> [ByteString]
@@ -159,10 +167,13 @@ fromHeaders allowTxDbOverride acceptedTzNames headers =
     isTimezonePrefAccepted = ((S.member . decodeUtf8 <$> timezonePref) <*> pure acceptedTzNames) == Just True
 
     maxAffectedPref = listStripPrefix "max-affected=" prefs >>= readMaybe . BS.unpack
+    timeoutPref     = listStripPrefix "timeout=" prefs >>= readMaybe . BS.unpack
 
-    isUnacceptable p = p `notElem` acceptedPrefs &&
-                       (isNothing (BS.stripPrefix "timezone=" p) ||  not isTimezonePrefAccepted) &&
-                       isNothing (BS.stripPrefix "max-affected=" p)
+    isPrefValid p =
+      p `elem` acceptedPrefs ||
+      (isJust (BS.stripPrefix "timezone=" p) && isTimezonePrefAccepted) ||
+      isJust (BS.stripPrefix "max-affected=" p) ||
+      isJust (BS.stripPrefix "timeout=" p)
 
     parsePrefs :: ToHeaderValue a => [a] -> Maybe a
     parsePrefs vals =
@@ -171,8 +182,9 @@ fromHeaders allowTxDbOverride acceptedTzNames headers =
     prefMap :: ToHeaderValue a => [a] -> Map.Map ByteString a
     prefMap = Map.fromList . fmap (\pref -> (toHeaderValue pref, pref))
 
+
 prefAppliedHeader :: Preferences -> Maybe HTTP.Header
-prefAppliedHeader Preferences {preferResolution, preferRepresentation, preferCount, preferTransaction, preferMissing, preferHandling, preferTimezone, preferMaxAffected } =
+prefAppliedHeader Preferences{..} =
   if null prefsVals
     then Nothing
     else Just (HTTP.hPreferenceApplied, combined)
@@ -187,6 +199,7 @@ prefAppliedHeader Preferences {preferResolution, preferRepresentation, preferCou
       , toHeaderValue <$> preferHandling
       , toHeaderValue <$> preferTimezone
       , if preferHandling == Just Strict then toHeaderValue <$> preferMaxAffected else Nothing
+      , if preferHandling == Just Strict then toHeaderValue <$> preferTimeout else Nothing
       ]
 
 -- |
@@ -289,3 +302,10 @@ newtype PreferMaxAffected = PreferMaxAffected Int64
 
 instance ToHeaderValue PreferMaxAffected where
   toHeaderValue (PreferMaxAffected n) = "max-affected=" <> show n
+
+-- |
+-- Statement Timeout per request
+newtype PreferTimeout = PreferTimeout Int
+
+instance ToHeaderValue PreferTimeout where
+  toHeaderValue (PreferTimeout n) = "timeout=" <> show n

src/PostgREST/App.hs

@@ -147,7 +147,7 @@ postgrestResponse appState conf@AppConfig{..} maybeSchemaCache authResult@AuthRe
       prefs = ApiRequest.userPreferences conf req timezones
 
   (parseTime, apiReq@ApiRequest{..}) <- withTiming $ liftEither . mapLeft Error.ApiRequestError $ ApiRequest.userApiRequest conf prefs req body
-  (planTime, plan)                   <- withTiming $ liftEither $ Plan.actionPlan iAction conf apiReq sCache
+  (planTime, plan)                   <- withTiming $ liftEither $ Plan.actionPlan iAction conf apiReq authResult sCache
 
   let mainQ = Query.mainQuery plan conf apiReq authResult configDbPreRequest
       tx = MainTx.mainTx mainQ conf authResult apiReq plan sCache

src/PostgREST/Error.hs

@@ -99,6 +99,7 @@ data ApiRequestError
   | InvalidResourcePath
   | OpenAPIDisabled
   | MaxAffectedRpcViolation
+  | TimeoutConstraintError Int ByteString ByteString
   deriving Show
 
 data QPError = QPError Text Text
@@ -142,6 +143,7 @@ instance PgrstError ApiRequestError where
   status InvalidResourcePath         = HTTP.status404
   status OpenAPIDisabled             = HTTP.status404
   status MaxAffectedRpcViolation     = HTTP.status400
+  status TimeoutConstraintError{}    = HTTP.status400
 
   headers _ = mempty
 
@@ -189,6 +191,7 @@ instance ErrorBody ApiRequestError where
   code OpenAPIDisabled             = "PGRST126"
   code NotImplemented{}            = "PGRST127"
   code MaxAffectedRpcViolation     = "PGRST128"
+  code TimeoutConstraintError{}    = "PGRST129"
 
   -- MESSAGE: Text
   message (QueryParamError (QPError msg _)) = msg
@@ -215,6 +218,7 @@ instance ErrorBody ApiRequestError where
   message OpenAPIDisabled                = "Root endpoint metadata is disabled"
   message (NotImplemented _)             = "Feature not implemented"
   message MaxAffectedRpcViolation        = "Function must return SETOF or TABLE when max-affected preference is used with handling=strict"
+  message TimeoutConstraintError{}       = "Timeout preference value cannot exceed statement_timeout of role"
 
   -- DETAILS: Maybe JSON.Value
   details (QueryParamError (QPError _ dets)) = Just $ JSON.String dets
@@ -230,6 +234,7 @@ instance ErrorBody ApiRequestError where
   details (InvalidPreferences prefs) = Just $ JSON.String $ T.decodeUtf8 ("Invalid preferences: " <> BS.intercalate ", " prefs)
   details (MaxAffectedViolationError n) = Just $ JSON.String $ T.unwords ["The query affects", show n, "rows"]
   details (NotImplemented details') = Just $ JSON.String details'
+  details (TimeoutConstraintError t rt role) = Just $ JSON.String $ "Timeout preferred: " <> show t <> "s, statement_timeout of role '" <> T.decodeUtf8 role <> "': " <> T.decodeUtf8 rt
 
   details _ = Nothing