PostgREST Files

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]

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]

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