From 9b1ff2235abb22cb3e9ad954204dbf42e20cf4b7 Mon Sep 17 00:00:00 2001
From: Wolfgang Walther <walther@technowledgy.de>
Date: Tue, 20 Feb 2024 20:16:04 +0100
Subject: [PATCH] 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                  |  2 +-
 ...ement-using-postgres-users-and-passwords.rst | 10 ++--------
 docs/how-tos/sql-user-management.rst            | 17 +++--------------
 3 files changed, 6 insertions(+), 23 deletions(-)

diff --git a/docs/explanations/db_authz.rst b/docs/explanations/db_authz.rst
index e81842839..f0b0499f6 100644
--- a/docs/explanations/db_authz.rst
+++ b/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;
diff --git a/docs/how-tos/sql-user-management-using-postgres-users-and-passwords.rst b/docs/how-tos/sql-user-management-using-postgres-users-and-passwords.rst
index b245bb6f7..6a55c3ff4 100644
--- a/docs/how-tos/sql-user-management-using-postgres-users-and-passwords.rst
+++ b/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;
-    RETURN result;
+      INTO token;
   END;
   $$;
 
diff --git a/docs/how-tos/sql-user-management.rst b/docs/how-tos/sql-user-management.rst
index c6981e62b..fd314622c 100644
--- a/docs/how-tos/sql-user-management.rst
+++ b/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 (
-    token text
-  );
-
-  CREATE FUNCTION jwt_test() RETURNS public.jwt_token AS $$
+  CREATE FUNCTION jwt_test(OUT token text) 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;
-    return result;
+      into token;
   end;
   $$ language plpgsql security definer;