108 lines
2.4 KiB
ReStructuredText
108 lines
2.4 KiB
ReStructuredText
.. _schemas:
|
|
|
|
Schemas
|
|
=======
|
|
|
|
PostgREST can expose a single or multiple schema's tables, views and functions. The :ref:`active database role <roles>` must have the usage privilege on the schemas to access them.
|
|
|
|
Single schema
|
|
-------------
|
|
|
|
To expose a single schema, specify a single value in :ref:`db-schemas`.
|
|
|
|
.. code:: bash
|
|
|
|
db-schemas = "api"
|
|
|
|
This schema is added to the `search_path <https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ of every request using :ref:`tx_settings`.
|
|
|
|
.. _multiple-schemas:
|
|
|
|
Multiple schemas
|
|
----------------
|
|
|
|
To expose multiple schemas, specify a comma-separated list on :ref:`db-schemas`:
|
|
|
|
.. code:: bash
|
|
|
|
db-schemas = "tenant1, tenant2"
|
|
|
|
To switch schemas, use the ``Accept-Profile`` and ``Content-Profile`` headers.
|
|
|
|
If you don't specify a Profile header, the first schema in the list(``tenant1`` here) is selected as the default schema.
|
|
|
|
Only the selected schema gets added to the `search_path <https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ of every request.
|
|
|
|
.. note::
|
|
|
|
These headers are based on the "Content Negotiation by Profile" spec: https://www.w3.org/TR/dx-prof-conneg
|
|
|
|
GET/HEAD
|
|
~~~~~~~~
|
|
|
|
For GET or HEAD, select the schema with ``Accept-Profile``.
|
|
|
|
.. tabs::
|
|
|
|
.. code-tab:: http
|
|
|
|
GET /items HTTP/1.1
|
|
Accept-Profile: tenant2
|
|
|
|
.. code-tab:: bash Curl
|
|
|
|
curl "http://localhost:3000/items" \
|
|
-H "Accept-Profile: tenant2"
|
|
|
|
Other methods
|
|
~~~~~~~~~~~~~
|
|
|
|
For POST, PATCH, PUT and DELETE, select the schema with ``Content-Profile``.
|
|
|
|
.. tabs::
|
|
|
|
.. code-tab:: http
|
|
|
|
POST /items HTTP/1.1
|
|
Content-Profile: tenant2
|
|
|
|
{...}
|
|
|
|
.. code-tab:: bash Curl
|
|
|
|
curl "http://localhost:3000/items" \
|
|
-X POST -H "Content-Type: application/json" \
|
|
-H "Content-Profile: tenant2" \
|
|
-d '{...}'
|
|
|
|
You can also select the schema for :ref:`s_procs` and :ref:`open-api`.
|
|
|
|
Restricted schemas
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
You can only switch to a schema included in :ref:`db-schemas`. Using another schema will result in an error:
|
|
|
|
.. tabs::
|
|
|
|
.. code-tab:: http
|
|
|
|
GET /items HTTP/1.1
|
|
Accept-Profile: tenant3
|
|
|
|
{...}
|
|
|
|
.. code-tab:: bash Curl
|
|
|
|
curl "http://localhost:3000/items" \
|
|
-H "Accept-Profile: tenant3"
|
|
|
|
.. code-block::
|
|
|
|
{
|
|
"code":"PGRST106",
|
|
"details":null,
|
|
"hint":null,
|
|
"message":"The schema must be one of the following: tenant1, tenant2"
|
|
}
|
|
|