Consolidate schema structure page

auth.rst

@@ -298,7 +298,7 @@ PostgREST uses JWT mainly for authentication and authorization purposes and enco
 Schema Isolation
 ================
 
-You can isolate your api schema from internal implementation details, as explained in :ref:`schema_structure`. For an example of wrapping a private table with a public view see the :ref:`public_ui` section below.
+You can isolate your api schema from internal implementation details, as explained in :ref:`schema_isolation`. For an example of wrapping a private table with a public view see the :ref:`public_ui` section below.
 
 SQL User Management
 ===================

index.rst

@@ -110,6 +110,40 @@ Technical references for PostgREST's functionality.
 - :doc:`API <api>`
 - :doc:`configuration`
 
+Topic guides
+------------
+
+Explanations of some key concepts in PostgREST.
+
+.. toctree::
+   :caption: Authentication
+   :hidden:
+
+   auth.rst
+
+.. toctree::
+   :caption: Schema Structure
+   :hidden:
+
+   schema_structure.rst
+
+.. toctree::
+   :caption: Administration
+   :hidden:
+
+   admin.rst
+
+.. toctree::
+   :caption: Installation
+   :hidden:
+
+   install.rst
+
+- :doc:`Authentication <auth>`
+- :doc:`Schema Structure <schema_structure>`
+- :doc:`Administration <admin>`
+- :doc:`Installation <install>`
+
 .. _how_tos:
 
 How-to guides
@@ -128,40 +162,6 @@ 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`
 
-Topic guides
-------------
-
-Explanations of some key concepts in PostgREST.
-
-.. toctree::
-   :caption: Authentication
-   :hidden:
-
-   auth.rst
-
-.. toctree::
-   :caption: Installation
-   :hidden:
-
-   install.rst
-
-.. toctree::
-   :caption: Administration
-   :hidden:
-
-   admin.rst
-
-.. toctree::
-   :caption: Best Practices
-   :hidden:
-
-   best_practices.rst
-
-- :doc:`Authentication <auth>`
-- :doc:`Installation <install>`
-- :doc:`Administration <admin>`
-- :doc:`Best Practices <best_practices>`
-
 Ecosystem
 ---------
 

schema_structure.rst

@@ -1,7 +1,7 @@
 
-.. _schema_structure:
+.. _schema_isolation:
 
-Schema Structure
+Schema Isolation
 ================
 
 A PostgREST instance exposes all the tables, views, and stored procedures of a single `PostgreSQL schema <https://www.postgresql.org/docs/12/ddl-schemas.html>`_ (a namespace of database objects). This means private data or implementation details can go inside different private schemas and be invisible to HTTP clients.
@@ -13,19 +13,15 @@ This allows you to change the internals of your schema and maintain backwards co
 
 .. _func_privs:
 
-Function privileges
-===================
+Functions
+=========
 
 By default, when a function is created, the privilege to execute it is not restricted by role. The function access is PUBLIC—executable by all roles(more details at `PostgreSQL Privileges page <https://www.postgresql.org/docs/12/ddl-priv.html>`_). This is not ideal for an API schema. To disable this behavior, you can run the following SQL statement:
 
 .. code-block:: postgres
 
-  -- Assuming your schema is named "api"
   ALTER DEFAULT PRIVILEGES IN SCHEMA api REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;
 
-  -- Or to stop functions from being PUBLICly executable in the whole database
-  ALTER DEFAULT PRIVILEGES REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;
-
 See `PostgreSQL alter default privileges <https://www.postgresql.org/docs/current/static/sql-alterdefaultprivileges.html>`_ for more details.
 
 After that, you'll need to grant EXECUTE privileges on functions explicitly:
@@ -35,32 +31,46 @@ After that, you'll need to grant EXECUTE privileges on functions explicitly:
    GRANT EXECUTE ON FUNCTION login TO anonymous;
    GRANT EXECUTE ON FUNCTION reset_password TO web_user;
 
-   -- you can also GRANT EXECUTE on all functions to a privileged role
-   GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA api TO admin;
-
 Security definer
 ----------------
 
-By default, a function is executed with the privileges of the user who calls it. This means that the user has to have all permissions to do the operations the procedure performs.
+A function is executed with the privileges of the user who calls it. This means that the user has to have all permissions to do the operations the procedure performs.
+If the function accesses private database objects, your `API roles <roles>`_ won't be able to succesfully execute the function.
 
-Another option is to define the function with the :code:`SECURITY DEFINER` option. Then only one permission check will take place, the permission to call the function, and the operations in the function will have the authority of the user who owns the function itself. See `PostgreSQL documentation <https://www.postgresql.org/docs/current/static/sql-createfunction.html#SQL-CREATEFUNCTION-SECURITY>`_ for more details.
-
-Views with RLS
-==============
-
-Views are invoked with the privileges of the view owner, much like stored procedures with the ``SECURITY DEFINER`` option. When created by a SUPERUSER role, all `row-level security <https://www.postgresql.org/docs/current/static/ddl-rowsecurity.html>`_ will be bypassed unless a different, non-SUPERUSER owner is specified.
+Another option is to define the function with the :code:`SECURITY DEFINER` option. Then only one permission check will take place, the permission to call the function, and the operations in the function will have the authority of the user who owns the function itself.
 
 .. code-block:: postgres
 
- -- Workaround:
- -- non-SUPERUSER role to be used as the owner of the views
- CREATE ROLE api_views_owner;
- -- alter the view owner so RLS can work normally
+  -- login as a user wich has privileges on the private schemas
+
+  -- create a sample function
+  create or replace function login(email text, pass text) returns jwt_token as $$
+  begin
+    -- access to a private schema called 'auth'
+    select auth.user_role(email, pass) into _role;
+    -- other operations
+    -- ...
+  end;
+  $$ language plpgsql security definer;
+
+Note the ``SECURITY DEFINER`` keywords at the end of the function. See `PostgreSQL documentation <https://www.postgresql.org/docs/current/static/sql-createfunction.html#SQL-CREATEFUNCTION-SECURITY>`_ for more details.
+
+Views
+=====
+
+Views are invoked with the privileges of the view owner, much like stored procedures with the ``SECURITY DEFINER`` option. When created by a SUPERUSER role, all `row-level security <https://www.postgresql.org/docs/current/static/ddl-rowsecurity.html>`_ will be bypassed unless a different, non-SUPERUSER owner is specified.
+
+For changing this, we can create a non-SUPERUSER role and make this role the view's owner.
+
+.. code-block:: postgres
+
+ CREATE ROLE api_views_owner NOINHERIT;
  ALTER VIEW sample_view OWNER TO api_views_owner;
 
-Views with Rules
-================
+Rules
+-----
 
 Insertion on VIEWs with complex `RULEs <https://www.postgresql.org/docs/11/sql-createrule.html>`_ might not work out of the box with PostgREST.
 It's recommended that you `use triggers instead of RULEs <https://wiki.postgresql.org/wiki/Don%27t_Do_This#Don.27t_use_rules>`_.
 If you want to keep using RULEs, a workaround is to wrap the VIEW insertion in a stored procedure and call it through the :ref:`s_procs` interface.
+For more details, see this `github issue <https://github.com/PostgREST/postgrest/issues/1283>`_.