Add multiple schemas feature

api.rst

@@ -1371,6 +1371,8 @@ You can get raw output from a ``text`` column by using ``Accept: text/plain``.
 
 This follows the same rules as :ref:`binary_output`.
 
+.. _open-api:
+
 OpenAPI Support
 ===============
 
@@ -1406,6 +1408,38 @@ You can use a tool like `Swagger UI <http://swagger.io/swagger-ui/>`_ to create
 
   The OpenAPI information can go out of date as the schema changes under a running server. To learn how to refresh the cache see :ref:`schema_reloading`.
 
+.. _multiple-schemas:
+
+Switching Schemas
+=================
+
+You can switch schemas at runtime with the ``Accept-Profile`` and ``Content-Profile`` headers. You can only switch to a schema that is included in :ref:`db-schema`.
+This is useful for **api versioning** and **schema-based multitenancy**.
+
+The schema to be used can be selected through the ``Accept-Profile`` header for GET or HEAD:
+
+.. code-block:: http
+
+   GET /items HTTP/1.1
+   Accept-Profile: tenant2
+
+If you don't specify the ``Accept-Profile`` header, the first schema on :ref:`db-schema` will be used.
+
+For POST, PATCH, PUT, DELETE you can use the ``Content-Profile`` header for selecting the schema:
+
+.. code-block:: http
+
+   POST /items HTTP/1.1
+   Content-Profile: tenant2
+
+   {...}
+
+You can also select the schema for :ref:`s_procs` and :ref:`open-api`.
+
+.. note::
+
+   These headers are based on the nascent "Content Negotiation by Profile" spec: https://www.w3.org/TR/dx-prof-conneg
+
 HTTP Logic
 ==========
 

configuration.rst

@@ -75,7 +75,19 @@ db-schema
 
   The database schema to expose to REST clients. Tables, views and stored procedures in this schema will get API endpoints.
 
-  This schema gets added to the `search_path <https://www.postgresql.org/docs/11/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ of every request.
+  The chosen schema gets added to the `search_path <https://www.postgresql.org/docs/11/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ of every request. Example:
+
+  .. code:: bash
+
+     db-schema = "api"
+
+  You can also specify a list of schemas that can be used for **schema-based multitenancy** and **api versioning** by :ref:`multiple-schemas`. Example:
+
+  .. code:: bash
+
+     db-schema = "tenant1, tenant2"
+     ##or
+     ##db-schema = "v1, v2"
 
 .. _db-anon-role:
 

releases/upcoming.rst

@@ -10,11 +10,14 @@ 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.
+* Support for :ref:`multiple-schemas` at runtime.
-  |br| -- `@ykst <https://github.com/ykst>`_
+  |br| -- `@steve-chavez <https://github.com/steve-chavez>`_, `@mahmoudkassem <https://github.com/mahmoudkassem>`_
 
 * Support for :ref:`planned_count` and :ref:`estimated_count`.
-  |br| -- `@steve-chavez <https://github.com/steve-chavez>`_
+  |br| -- `@steve-chavez <https://github.com/steve-chavez>`_, `@LorenzHenk <https://github.com/LorenzHenk>`_
+
+* 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:`Resource Embedding Disambiguation <embed_disamb>`.
   |br| -- `@steve-chavez <https://github.com/steve-chavez>`_