What changed in PostgREST from 14 to 16

Added

• Make jwt-role-claim-key config backwards compatible by @taimoorzaeem in #5171
• Deprecation policy by @steve-chavez on #5173

Deprecated

• The old (pre-v16) syntax for JSPath in jwt-role-claim-key is deprecated by @taimoorzaeem in #5171
  • You will see a warning in the logs when old syntax is used for the config.
  • See migration to v16 section for migration guide.

Fixed

• JWT validation uses wrong current time due to a bug in auto-update by @mkleczek in #5159

Changes

HTTP Server

• Graceful shutdown by @mkleczek, @Vlix in #4702

• server-reuseport allows starting multiple PostgREST instances using the same port on supported platforms by @mkleczek in #4703, #4694

Performance

• Optimize schema cache domain type resolution by using pg_basetype on PostgreSQL 17+ by @joelonsql in #4567

• Prefer: count=exact no longer does a double count on requests that do not use ranges or db-max-rows by @laurenceisla in #3957

• Prefer: timezone no longer requires the schema cache by @steve-chavez in #5100

  • Previously this required caching pg_timezone_names which was slow in some systems

Integrations

• PostgREST is now tested to work with OrioleDB in #4845 by @wolfgangwalther
  • See our guide for running OrioleDB on NixOS

JWT

• JWT Role Extraction is now more flexible, supporting the standard JSON Path defined in RFC 9535 by @taimoorzaeem in #4984

API

• Prefer: timezone now supports numeric offsets like 05:00 or -4 by @steve-chavez in #5100

• 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 to false.

• 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 and a Warning header on the client response when this happens.
  • You can disable this behavior now by setting url-use-legacy-target-names = false.

• Add Vary header to responses by @develop7 in #4609

• Fix automatic transaction retries on 40001 (serialization_failure) errors to prevent replication lag by @laurenceisla in #3673

Observability

• GHC runtime metrics by @mkleczek in #4862
• client-error-verbosity to customize responses error verbosity by @taimoorzaeem in #4088, #3980, #3824
• log-level config is now reloadable by @taimoorzaeem in #5113
• Log error when db-schemas config contains schema pg_catalog or information_schema by @taimoorzaeem in #4359
• Log schema cache queries timings on log-level=debug by @steve-chavez in #4805

Admin Server

• admin-server-unix-socket/admin-server-unix-socket-mode to run the admin server on a unix socket by @wolfgangwalther in #5003
• Fix responding with Something went wrong on Admin server when under EMFILE by @mkleczek in #5077

Deployment

• Make executable for aarch64-linux static instead of Ubuntu-based by @wolfgangwalther in #4193
• Docker image for aarch64-linux is now built from scratch instead of being Ubuntu-based by @wolfgangwalther in #4193
• Besides Docker Hub, docker images are now published to Github Container Registry by @wolfgangwalther in #2836

Schema Cache

• Fix requests failing when the schema cache fails to reload, when this happens PostgREST will continue serving requests in "best effort" by @mkleczek in #4873 #4869
• Fix reporting 503s errors unnecessarily while the schema cache is loading at startup by @mkleczek in #4880
• Fix schema cache dump missing RPC transaction isolation level by @taimoorzaeem in #5079

Listener

• Fix config db-channel-enabled not reloading by @taimoorzaeem in #4894

Migration to v16

• Drop support for PostgreSQL EOL version 13 by @wolfgangwalther in #4193

  • PostgreSQL 13 end of life was on 2025 (ref)
  • Upgrade your PostgreSQL version to at least 14 to use this new PostgREST version.

• Fail at startup when db-schemas contains schema pg_catalog or information_schema by @taimoorzaeem in #4359

  • Previously it failed at runtime with PGRST205 on requests related to these schemas.
  • Remove pg_catalog and information_schema from db-schemas.

• Prefer: timezone no longer complies with handling=lenient and instead always fails by @steve-chavez in #5128

  • Supporting this required caching pg_timezone_names, which was expensive.
  • Ensure your requests always have a valid timezone.

• jwt-role-claim-key no longer uses the JSPath DSL and instead uses JSON Path by @taimoorzaeem in #4984

  • If you don't explicitly set this config, you don't need to change anything as the default value will do the same thing on this version. If you do set this config, read on.
  • Now all config values must start with $ character. Example: .roles.read -> $.roles.read
  • Keys with special characters, with the exception of _ char must be quoted. Example: .roles.write-role -> $.roles["write-role"]
  • String comparison operators (^==, ==^ and *==) are replaced with regular expression search. Example: .roles[?(@ ^== "postgrest_test_")] -> $.roles[?search(@, "^postgrest_test_")]
  • Update the jwt-role-claim-key value accoring to the above rules. Also see the syntax reference: RFC 9535.