diff --git a/docs/how-tos/working-with-postgresql-data-types.rst b/docs/how-tos/working-with-postgresql-data-types.rst index 04e6562de..650665078 100644 --- a/docs/how-tos/working-with-postgresql-data-types.rst +++ b/docs/how-tos/working-with-postgresql-data-types.rst @@ -62,7 +62,7 @@ Someone located in Cairo can retrieve the data using their local time, too: } ] -The response has the date in the time zone configured by the server: ``UTC -05:00``. +The response has the date in the time zone configured by the server: ``UTC -05:00`` (see :ref:`prefer_timezone`). You can use other comparative filters and also all the `PostgreSQL special date/time input values `_ as illustrated in this example: diff --git a/docs/references/api/preferences.rst b/docs/references/api/preferences.rst index e151e2b08..140e00119 100644 --- a/docs/references/api/preferences.rst +++ b/docs/references/api/preferences.rst @@ -45,3 +45,63 @@ The server ignores unrecognized or unfulfillable preferences by default. You can HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 + +.. _prefer_timezone: + +Timezone +======== + +The ``timezone`` preference allows you to change the `PostgreSQL timezone `_. It accepts all timezones in `pg_timezone_names `_. + + +.. code-block:: http + + GET /timestamps HTTP/1.1 + Prefer: timezone=America/Los_Angeles + +.. code-block:: http + + HTTP/1.1 200 OK + Content-Type: application/json; charset=utf-8 + Preference-Applied: timezone=America/Los_Angeles + +.. code-block:: json + + [ + {"t":"2023-10-18T05:37:59.611-07:00"}, + {"t":"2023-10-18T07:37:59.611-07:00"}, + {"t":"2023-10-18T09:37:59.611-07:00"} + ] + +For an invalid timezone, PostgREST returns values with the default timezone (configured on ``postgresql.conf`` or as a setting on the :ref:`authenticator `). + +.. code-block:: http + + GET /timestamps HTTP/1.1 + Prefer: timezone=Jupiter/Red_Spot + +.. code-block:: http + + HTTP/1.1 200 OK + Content-Type: application/json; charset=utf-8 + +.. code-block:: json + + [ + {"t":"2023-10-18T12:37:59.611+00:00"}, + {"t":"2023-10-18T14:37:59.611+00:00"}, + {"t":"2023-10-18T16:37:59.611+00:00"} + ] + +Note that there's no ``Preference-Applied`` in the response. + +However, with ``handling=strict``, an invalid timezone preference will throw an :ref:`error `. + +.. code-block:: http + + GET /timestamps HTTP/1.1 + Prefer: handling=strict, timezone=Jupiter/Red_Spot + +.. code-block:: http + + HTTP/1.1 400 Bad Request