Put warning in db-schema and clarify search_path

api.rst

@@ -1421,18 +1421,15 @@ 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:
+For GET or HEAD, the schema to be used can be selected through the ``Accept-Profile`` header:
 
 .. 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:
+For POST, PATCH, PUT and DELETE, you can use the ``Content-Profile`` header for selecting the schema:
 
 .. code-block:: http
 

configuration.rst

@@ -75,12 +75,12 @@ db-schema
 
   The database schema to expose to REST clients. Tables, views and stored procedures in this schema will get API endpoints.
 
-  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"
 
+  This schema gets added to the `search_path <https://www.postgresql.org/docs/11/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ of every request.
+
   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
@@ -89,6 +89,14 @@ db-schema
      ##or
      ##db-schema = "v1, v2"
 
+  .. warning::
+
+     Never expose private schemas in this way. See :ref:`schema_isolation`.
+
+  If you don't :ref:`Switch Schemas <multiple-schemas>`, the first schema in the list(``tenant1`` in this case) is chosen as the default schema.
+
+  Only the chosen schema gets added to the `search_path <https://www.postgresql.org/docs/11/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ of every request.
+
 .. _db-anon-role:
 
 db-anon-role

releases/upcoming.rst

@@ -10,7 +10,7 @@ These are changes yet unreleased. If you'd like to try them out before a new off
 Added
 -----
 
-* Support for :ref:`multiple-schemas` at runtime.
+* Support for :ref:`Switching to a schema <multiple-schemas>` defined in :ref:`db-schema`.
   |br| -- `@steve-chavez <https://github.com/steve-chavez>`_, `@mahmoudkassem <https://github.com/mahmoudkassem>`_
 
 * Support for :ref:`planned_count` and :ref:`estimated_count`.