docs: Simplify auth examples with OUT parameter

The jwt_token type was not created consistently in all examples, which can
be confusing when following those. To return an object with a single key
named token, it's enough to have an OUT parameter to the function.

Resolves https://github.com/PostgREST/postgrest-docs/issues/280

docs/explanations/db_authz.rst

@@ -166,7 +166,7 @@ Another option is to define the function with the :code:`SECURITY DEFINER` optio
   -- 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 $$
+  create or replace function login(email text, pass text, out token text) as $$
   begin
     -- access to a private schema called 'auth'
     select auth.user_role(email, pass) into _role;

docs/how-tos/sql-user-management-using-postgres-users-and-passwords.rst

@@ -162,20 +162,15 @@ As described in :ref:`client_auth`, we'll create a JWT token inside our login fu
 
 .. code-block:: postgres
 
-  CREATE TYPE basic_auth.jwt_token AS (
-    token text
-  );
-
   -- if you are not using psql, you need to replace :DBNAME with the current database's name.
   ALTER DATABASE :DBNAME SET "app.jwt_secret" to 'reallyreallyreallyreallyverysafe';
 
 
-  CREATE FUNCTION public.login(username text, password text) RETURNS basic_auth.jwt_token
+  CREATE FUNCTION public.login(username text, password text, OUT token text)
       LANGUAGE plpgsql security definer
       AS $$
   DECLARE
     _role name;
-    result basic_auth.jwt_token;
   BEGIN
     -- check email and password
     SELECT basic_auth.check_user_pass(username, password) INTO _role;
@@ -190,8 +185,7 @@ As described in :ref:`client_auth`, we'll create a JWT token inside our login fu
         SELECT login.username as role,
           extract(epoch FROM now())::integer + 60*60 AS exp
       ) r
-      INTO result;
+      INTO token;
-    RETURN result;
   END;
   $$;
 

docs/how-tos/sql-user-management.rst

@@ -122,11 +122,7 @@ Next write a stored procedure that returns the token. The one below returns a to
 
 .. code-block:: postgres
 
-  CREATE TYPE jwt_token AS (
+  CREATE FUNCTION jwt_test(OUT token text) AS $$
-    token text
-  );
-
-  CREATE FUNCTION jwt_test() RETURNS public.jwt_token AS $$
     SELECT public.sign(
       row_to_json(r), 'reallyreallyreallyreallyverysafe'
     ) AS token
@@ -161,17 +157,11 @@ As described in `JWT from SQL`_, we'll create a JWT inside our login function. N
 
 .. code-block:: postgres
 
-  -- add type
-  CREATE TYPE basic_auth.jwt_token AS (
-    token text
-  );
-
   -- login should be on your exposed schema
   create or replace function
-  login(email text, pass text) returns basic_auth.jwt_token as $$
+  login(email text, pass text, out token text) as $$
   declare
     _role name;
-    result basic_auth.jwt_token;
   begin
     -- check email and password
     select basic_auth.user_role(email, pass) into _role;
@@ -186,8 +176,7 @@ As described in `JWT from SQL`_, we'll create a JWT inside our login function. N
         select _role as role, login.email as email,
            extract(epoch from now())::integer + 60*60 as exp
       ) r
-      into result;
+      into token;
-    return result;
   end;
   $$ language plpgsql security definer;