Add on_conflict query parameter

api.rst

@@ -1218,7 +1218,7 @@ In this case, only **source**, **publication_date** and **figure** will be inser
 Using this also has the side-effect of being more efficient for :ref:`bulk_insert` since PostgREST will not process the JSON and
 it'll send it directly to PostgreSQL.
 
-Upsert
+UPSERT
 ------
 
 You can make an UPSERT with :code:`POST` and the :code:`Prefer: resolution=merge-duplicates` header:
@@ -1234,11 +1234,31 @@ You can make an UPSERT with :code:`POST` and the :code:`Prefer: resolution=merge
     { "id": 3, "name": "New employee 3", "salary": 50000 }
   ]
 
-UPSERT operates based on the primary key columns, you must specify all of them. You can also choose to ignore the duplicates with :code:`Prefer: resolution=ignore-duplicates`. UPSERT works best when the primary key is natural, but it's also possible to use it if the primary key is surrogate (example: "id serial primary key"). For more details read `this issue <https://github.com/PostgREST/postgrest/issues/1118>`_.
+By default, UPSERT operates based on the primary key columns, you must specify all of them. You can also choose to ignore the duplicates with :code:`Prefer: resolution=ignore-duplicates`. This works best when the primary key is natural, but it's also possible to use it if the primary key is surrogate (example: "id serial primary key"). For more details read `this issue <https://github.com/PostgREST/postgrest/issues/1118>`_.
 
 .. important::
   After creating a table or changing its primary key, you must refresh PostgREST schema cache for UPSERT to work properly. To learn how to refresh the cache see :ref:`schema_reloading`.
 
+.. _on_conflict:
+
+On Conflict
+~~~~~~~~~~~
+
+By specifying the ``on_conflict`` query parameter, you can make UPSERT work on a column(s) that has a UNIQUE constraint.
+
+.. code-block:: http
+
+  POST /employees?on_conflict=name HTTP/1.1
+  Prefer: resolution=merge-duplicates
+
+  [
+    { "name": "Old employee 1", "salary": 40000 },
+    { "name": "Old employee 2", "salary": 52000 },
+    { "name": "New employee 3", "salary": 60000 }
+  ]
+
+PUT
+~~~
 
 A single row UPSERT can be done by using :code:`PUT` and filtering the primary key columns with :code:`eq`:
 
@@ -1252,7 +1272,7 @@ All the columns must be specified in the request body, including the primary key
 
 .. note::
 
-  This feature is only available starting from PostgreSQL 9.5 since it uses the `ON CONFLICT clause <https://www.postgresql.org/docs/9.5/static/sql-insert.html#SQL-ON-CONFLICT>`_.
+  Upsert features are only available starting from PostgreSQL 9.5 since it uses the `ON CONFLICT clause <https://www.postgresql.org/docs/9.5/static/sql-insert.html#SQL-ON-CONFLICT>`_.
 
 .. _delete:
 

releases/upcoming.rst

@@ -10,6 +10,9 @@ These are changes yet unreleased. If you'd like to try them out before a new off
 Added
 -----
 
+* Support for the :ref:`on_conflict <on_conflict>` query parameter to UPSERT based on a unique constraint.
+  |br| -- `@ykst <https://github.com/ykst>`_
+
 * Support for :ref:`planned_count` and :ref:`estimated_count`.
   |br| -- `@steve-chavez <https://github.com/steve-chavez>`_