Add how-to for working with PostgreSQL data types

docs/how-tos/working-with-postgresql-data-types.rst

@@ -0,0 +1,80 @@
+.. _working_with_types:
+
+Working with PostgreSQL data types
+==================================
+
+PostgREST makes use of PostgreSQL string representations to work with data types. Thanks to this, you can use special values, such as ``now`` for timestamps, ``yes`` for booleans or time values including the time zones. This page describes how you can take advantage of these string representations to perform operations on different PostgreSQL data types.
+
+Timestamps
+----------
+
+You can use the **time zone** to filter or send data if needed. Let's use this table as an example:
+
+.. code-block:: postgres
+
+  create table reports (
+    id int primary key
+    , due_date timestamptz
+  );
+
+Suppose you are located in Sydney and want create a report with the date in the local time zone. Your request should look like this:
+
+.. tabs::
+
+  .. code-tab:: http
+
+    POST /reports HTTP/1.1
+    Content-Type: application/json
+
+    [{ "id": 1, "due_date": "2022-02-24 11:10:15 Australia/Sydney" },
+     { "id": 2, "due_date": "2022-02-27 22:00:00 Australia/Sydney" }]
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/reports" \
+      -X POST -H "Content-Type: application/json" \
+      -d '[{ "id": 1, "due_date": "2022-02-24 11:10:15 Australia/Sydney" },{ "id": 2, "due_date": "2022-02-27 22:00:00 Australia/Sydney" }]'
+
+Someone located in Cairo can retrieve the data using their local time, too:
+
+.. tabs::
+
+  .. code-tab:: http
+
+    GET /reports?due_date=eq.2022-02-24+02:10:15+Africa/Cairo HTTP/1.1
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/reports?due_date=eq.2022-02-24+02:10:15+Africa/Cairo"
+
+.. code-block:: json
+
+  [
+    {
+      "id": 1,
+      "due_date": "2022-02-23T19:10:15-05:00"
+    }
+  ]
+
+The response has the date in the time zone configured by the server: ``UTC -05:00``.
+
+You can use other comparative filters and also `PostgreSQL special date/time input values <https://www.postgresql.org/docs/current/datatype-datetime.html#DATATYPE-DATETIME-SPECIAL-TABLE>`_. For instance, to get the reports that are due after today you would do:
+
+.. tabs::
+
+  .. code-tab:: http
+
+    GET /reports?due_date=gt.today HTTP/1.1
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/reports?due_date=gt.today"
+
+.. code-block:: json
+
+  [
+    {
+      "id": 2,
+      "due_date": "2022-02-27T06:00:00-05:00"
+    }
+  ]

docs/index.rst

@@ -201,6 +201,7 @@ These are recipes that'll help you address specific use-cases.
 - :doc:`how-tos/embedding-table-from-another-schema`
 - :doc:`how-tos/providing-images-for-img`
 - `How PostgreSQL triggers work when called with a PostgREST PATCH HTTP request <https://blog.fgribreau.com/2020/11/how-postgresql-triggers-works-when.html>`_
+- :doc:`how-tos/working-with-postgresql-data-types`
 
 Ecosystem
 ---------

postgrest.dict

@@ -11,6 +11,7 @@ authenticator
 backoff
 balancer
 Beles
+booleans
 Bouscal
 buildpack
 Cardano