add: config to emit warning for legacy target names

Adds the `url_use_legacy_target_names` config.

Enabled (default):
* It allows using the resource name in filters,
  orders or limits when it has an alias, e.g.
  `table?select=alias:target(*)&target.id=eq.1`
* Logs a WARNING with a hint to use the alias
* Returns a Warning header in the response

Disabled:
* It returns an error, only the alias is allowed
* No warnings returned

This feature is deprecated

Author: steve-chavez

CHANGELOG.md

@@ -15,12 +15,14 @@ All notable changes to this project will be documented in this file. From versio
 - Log schema cache queries timings on `log-level=debug` by @steve-chavez in #4805
 - Add GHC runtime metrics to the metrics endpoint by @mkleczek in #4862
 - Support running the admin server on a unix socket by @wolfgangwalther in #5003
+- Add config `url-use-legacy-target-names` to allow using the embedded table name in filters, orders or limits when it has an alias by @laurenceisla in #4075
 
 ### Fixed
 
 - Shutdown should wait for in flight requests by @mkleczek in #4702
 - Remove automatic transaction retries on `40001 (serialization_failure)` errors to prevent replication lag by @laurenceisla in #3673
 - Fix unexpected results when embedding and filtering the same table more than once by @laurenceisla in #4075
+  + You need to set `url-use-legacy-target-names = false`.
 - If the schema cache fails to reload, PostgREST will no longer stop serving requests and will continue doing so in a "best effort" basis by @mkleczek in #4873 #4869
 - Stop reporting 503s errors unnecessarily while the schema cache is loading at startup by @mkleczek in #4880
 - Fix admin server dying silently by @Vlix, @mkleczek, @steve-chavez in #5012
@@ -33,8 +35,6 @@ All notable changes to this project will be documented in this file. From versio
   + Now fails at startup. Prior to this, it failed with `PGRST205` on requests related to these schemas.
 - Build a static executable for aarch64-linux by @wolfgangwalther in #4193
 - Build the minimal docker image for aarch64-linux by @wolfgangwalther in #4193
-- The name of an embedded table can no longer be used in filters if it has an alias by @laurenceisla in #4075
-  + e.g. `?select=alias:table(*)&table.id=eq.1` is not possible anymore, use `?select=alias:table(*)&alias.id=eq.1` instead.
 - Config `jwt-role-claim-key` now uses RFC 9535 syntax for JSON Path by @taimoorzaeem in #4984
 
 #### Changed Syntax for JWT Role Extraction
@@ -49,6 +49,12 @@ The `jwt-role-claim-key` config should be updated according to the following:
   + Example: `.roles[?(@ ^== "postgrest_test_")]` -> `$.roles[?search(@, "^postgrest_test_")]`
 - Detailed reference for syntax: [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535.html#name-jsonpath-syntax-and-semanti).
 
+### Deprecated
+
+- Deprecate filters, orders and limits with the name of an embedded table when it has an alias by @steve-chavez, @laurenceisla in #4075
+  + e.g. `?select=alias:table(*)&table.id=eq.1` will not be possible anymore, use `?select=alias:table(*)&alias.id=eq.1` instead.
+  + You will see a warning in the logs when this happens.
+
 ## [14.14] - 2026-06-29
 
 ### Fixed

docs/references/configuration.rst

@@ -1013,3 +1013,37 @@ server-unix-socket-mode
   .. code:: bash
 
     server-unix-socket-mode = "660"
+
+.. _url-use-legacy-target-names:
+
+url-use-legacy-target-names
+---------------------------
+
+  =============== =================================
+  **Type**        Boolean
+  **Default**     True
+  **Reloadable**  Y
+  **Environment** PGRST_URL_USE_LEGACY_TARGET_NAMES
+  **In-Database** pgrst.url_use_legacy_target_names
+  =============== =================================
+
+  When active, it allows using the the name of an embedded table in filters, orders or limits even if it has an alias:
+
+  .. code:: bash
+
+    curl "http://localhost:3000/table?select=alias:target(*)&target.order=id" -i
+
+  .. code:: text
+
+    Warning: 299 PostgRESTv16 "Embedded resource was referenced by relation name even though it has an alias. This is deprecated and will stop working in a future release. Update `target` to `alias` in query string filters, orders or limits."
+    [...]
+
+  Note that the response includes a deprecation message in the ``Warning`` header.
+  This will also show in the PostgREST logs:
+
+  .. code::
+
+    28/May/2026:20:33:22 -0500: WARNING: Embedded resource was referenced by relation name even though it has an alias. This is deprecated and will stop working in a future release.
+    28/May/2026:20:33:22 -0500: Update filters, orders or limits that use `target` to `alias` in `GET /table?select=alias:target(*)&target.order=id`
+
+  This feature will be removed in a future release, so you should start using the ``alias`` in these cases.

src/PostgREST/App.hs

@@ -71,7 +71,7 @@ import qualified Data.List                 as L
 import           Data.Streaming.Network    (bindPortTCP)
 import qualified Data.Text                 as T
 import qualified Network.HTTP.Types        as HTTP
-import           Network.HTTP.Types.Header (hVary)
+import           Network.HTTP.Types.Header (hVary, hWarning)
 import qualified Network.Socket            as NS
 import           PostgREST.Unix            (createAndBindDomainSocket)
 import           System.Posix.Types        (FileMode)
@@ -210,6 +210,14 @@ postgrestResponse appState conf@AppConfig{..} maybeSchemaCache jwtTime authResul
   (parseTime, apiReq@ApiRequest{..}) <- withTiming conf $ liftEither . mapLeft Error.ApiRequestErr $ ApiRequest.userApiRequest conf prefs req body
   (planTime, plan)                   <- withTiming conf $ liftEither $ Plan.actionPlan iAction conf apiReq sCache
 
+  let warnings = Plan.legacyWarnings plan
+      legacyWarnMsg = "Embedded resource was referenced by relation name even though it has an alias. This is deprecated and will stop working in a future release."
+      legacyWarnHint = let replacement (relName, alias) = "`" <> relName <> "` to `" <> alias <> "`" in T.intercalate ", " (replacement <$> warnings)
+      shouldShowWarnings = configUrlUseLegacyTargetNames && not (null warnings)
+
+  liftIO $ when shouldShowWarnings $
+    observer $ LegacyTargetNameWarningObs (legacyWarnMsg, legacyWarnHint) iMethod (iPath <> Wai.rawQueryString req) -- TODO maybe store rawQueryString in ApiRequest for consistency
+
   let mainQ = Query.mainQuery plan conf apiReq authResult configDbPreRequest
       tx = MainTx.mainTx mainQ conf authResult apiReq plan sCache
       obsQuery s = when configLogQuery $ observer $ QueryObs mainQ s
@@ -235,12 +243,14 @@ postgrestResponse appState conf@AppConfig{..} maybeSchemaCache jwtTime authResul
     liftIO $ obsQuery status'
     liftEither response
 
-  return $ toWaiResponse (ServerTiming jwtTime parseTime planTime txTime respTime) resp
+  let warnHdrMsgs = if shouldShowWarnings then Just (legacyWarnMsg, legacyWarnHint) else Nothing
+
+  return $ toWaiResponse (ServerTiming jwtTime parseTime planTime txTime respTime) warnHdrMsgs resp
 
   where
-    toWaiResponse :: ServerTiming -> Response.PgrstResponse -> Wai.Response
-    toWaiResponse timing (Response.PgrstResponse st hdrs bod) =
-      Wai.responseLBS st (hdrs ++ serverTimingHeaders timing ++ [varyHeader | not $ varyHeaderPresent hdrs]) bod
+    toWaiResponse :: ServerTiming -> Maybe (Text, Text) -> Response.PgrstResponse -> Wai.Response
+    toWaiResponse timing warnMsgs (Response.PgrstResponse st hdrs bod) =
+      Wai.responseLBS st (hdrs ++ serverTimingHeaders timing ++ warningHeaders warnMsgs ++ [varyHeader | not $ varyHeaderPresent hdrs]) bod
 
     serverTimingHeaders :: ServerTiming -> [HTTP.Header]
     serverTimingHeaders timing = [serverTimingHeader timing | configServerTimingEnabled]
@@ -251,6 +261,14 @@ postgrestResponse appState conf@AppConfig{..} maybeSchemaCache jwtTime authResul
     varyHeaderPresent :: [HTTP.Header] -> Bool
     varyHeaderPresent = any (\(h, _v) -> h == hVary)
 
+    warningHeaders :: Maybe (Text, Text) -> [HTTP.Header]
+    warningHeaders Nothing = []
+    warningHeaders (Just (msg, hint)) =
+      let warnMsg = msg <> " Update " <> hint <> " in query string filters, orders or limits."
+          pgrstVer = "PostgRESTv" <> BS.filter (/= ' ') prettyVersion
+      in
+      [(hWarning, "299 " <> pgrstVer <> " \"" <> encodeUtf8 warnMsg <> "\"")]
+
 withTiming :: (MonadError e m, MonadIO m) => AppConfig -> m a -> m (Maybe Double, a)
 withTiming AppConfig{configServerTimingEnabled} f = if configServerTimingEnabled
     then do

src/PostgREST/Config.hs

@@ -121,6 +121,7 @@ data AppConfig = AppConfig
   , configServerTimingEnabled       :: Bool
   , configServerUnixSocket          :: Maybe FilePath
   , configServerUnixSocketMode      :: FileMode
+  , configUrlUseLegacyTargetNames   :: Bool
   , configAdminServerHost           :: Text
   , configAdminServerPort           :: Maybe Int
   , configAdminServerUnixSocket     :: Maybe FilePath
@@ -207,6 +208,7 @@ toText conf =
       ,("server-timing-enabled",         T.toLower . show . configServerTimingEnabled)
       ,("server-unix-socket",        q . maybe mempty T.pack . configServerUnixSocket)
       ,("server-unix-socket-mode",   q . T.pack . showSocketMode)
+      ,("url-use-legacy-target-names",   T.toLower . show . configUrlUseLegacyTargetNames)
       ,("admin-server-host",         q . configAdminServerHost)
       ,("admin-server-port",             maybe "\"\"" show . configAdminServerPort)
       ,("admin-server-unix-socket",  q . maybe mempty T.pack . configAdminServerUnixSocket)
@@ -325,6 +327,7 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
     <*> (fromMaybe False <$> optBool "server-timing-enabled")
     <*> (fmap T.unpack <$> optString "server-unix-socket")
     <*> parseSocketFileMode "server-unix-socket-mode"
+    <*> (fromMaybe True <$> optBool "url-use-legacy-target-names")
     <*> (defaultServerHost <$> optWithAlias (optString "admin-server-host")
                                             (optString "server-host"))
     <*> parseAdminServerPort "admin-server-port"
@@ -794,4 +797,9 @@ exampleConfigFile = S.unlines
   , "## Unix socket file mode"
   , "## When none is provided, 660 is applied by default"
   , "# server-unix-socket-mode = \"660\""
+  , ""
+  , "## Use legacy target names in relationship filters"
+  , "## If active, allows using the target name of the relationship in filters even if it has an alias."
+  , "## Otherwise it only allows the alias in filters"
+  , "url-use-legacy-target-names = true"
   ]

src/PostgREST/Config/Database.hs

@@ -71,6 +71,7 @@ dbSettingsNames =
   ,"server_cors_allowed_origins"
   ,"server_trace_header"
   ,"server_timing_enabled"
+  ,"url_use_legacy_target_names"
   ]
 
 queryPgVersion :: Session PgVersion

src/PostgREST/Error.hs

@@ -175,7 +175,7 @@ instance ErrorBody ApiRequestError where
   message InvalidFilters               = "Filters must include all and only primary key columns with 'eq' operators"
   message (UnacceptableSchema sch _)   = "Invalid schema: " <> sch
   message (MediaTypeError cts)         = "None of these media types are available: " <> T.intercalate ", " (map T.decodeUtf8 cts)
-  message (NotEmbedded resource)       = "'" <> resource <> "' is not an embedded resource in this request"
+  message (NotEmbedded resource _)     = "'" <> resource <> "' is not an embedded resource in this request"
   message GucHeadersError              = "response.headers guc must be a JSON array composed of objects with a single key and a string value"
   message GucStatusError               = "response.status guc must be a valid status code"
   message PutLimitNotAllowedError      = "limit/offset querystring parameters are not allowed for PUT"
@@ -207,11 +207,13 @@ 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 (NotEmbedded _ (Just _)) = Just $ JSON.String "Target names are not allowed in filters if they have an alias"
 
   details _ = Nothing
 
   -- HINT: Maybe JSON.Value
-  hint (NotEmbedded resource) = Just $ JSON.String $ "Verify that '" <> resource <> "' is included in the 'select' query parameter."
+  hint (NotEmbedded resource Nothing) = Just $ JSON.String $ "Verify that '" <> resource <> "' is included in the 'select' query parameter."
+  hint (NotEmbedded _ (Just (name, alias))) = Just $ JSON.String $ "Change '" <> name <> "' to '" <> alias <> "' in filters, orders or limits."
   hint (PGRSTParseError raiseErr) = Just $ JSON.String $ pgrstParseErrorHint raiseErr
   hint (UnacceptableSchema _ schemas) = Just $ JSON.String $ "Only the following schemas are exposed: "  <> T.intercalate ", " schemas
 

src/PostgREST/Error/Types.hs

@@ -44,7 +44,7 @@ data ApiRequestError
   | InvalidPreferences [ByteString]
   | InvalidRange RangeError
   | InvalidRpcMethod ByteString
-  | NotEmbedded Text
+  | NotEmbedded Text (Maybe (Text, Text))
   | NotImplemented Text
   | PutLimitNotAllowedError
   | QueryParamError QPError

src/PostgREST/Logger.hs

@@ -192,6 +192,10 @@ observationMessages = \case
       let snipts  = renderSnippet <$> [mqTxVars, fromMaybe mempty mqPreReq, mqMain, x, y, z, fromMaybe mempty mqExplain]
       in
         showOnSingleLine '\n' . T.decodeUtf8 <$> filter (/= mempty) snipts
+  LegacyTargetNameWarningObs (warningMsg, warningHints) requestMethod requestTarget ->
+    [ "WARNING: " <> warningMsg
+    , "Update filters, orders or limits that use " <> warningHints <> " in " <> "`" <> T.decodeUtf8 (requestMethod <> " " <> requestTarget) <> "`"
+    ]
   ConfigReadErrorObs usageErr ->
     pure $ "Failed to query database settings for the config parameters." <> jsonMessage usageErr
   QueryRoleSettingsErrorObs usageErr ->

src/PostgREST/Observation.hs

@@ -45,6 +45,7 @@ data Observation
   | DBListenerGotConfigMsg ByteString
   | DBListenerConnectionCleanupFail SomeException
   | QueryObs MainQuery Status
+  | LegacyTargetNameWarningObs (Text, Text) ByteString ByteString
   | ConfigReadErrorObs SQL.UsageError
   | ConfigInvalidObs Text
   | ConfigSucceededObs