boringSQL | Supercharge your SQL & PostgreSQL powers - postgrest

Deep Dive into PostgREST - Time Off Manager (Part 3)

2024-06-06T00:00:00+00:00

This is the third and final instalment of "Deep Dive into PostgREST". In the first part</a>, we explored basic CRUD functionalities. In the second part</a>, we moved forward with abstraction and used the acquired knowledge to create a simple request/approval workflow.

In Part 3, we will explore authentication and authorisation options to finish something that might resemble a real-world application.

Authentication with pgcrypto </a> </h2>

There's no authorisation without knowing user identity. So let's start there. Our users table from the first part had an email</code> to establish the identity, but no way to verify it. We will address this by adding a password column. Of course, nobody in their right mind would store passwords in plain text.

To securely store users' passwords, we are going to utilise PostgreSQL pgcrypto</code> extension (documentation</a>). This built-in extension provides a suite of cryptographic functions for hashing, encryption, and more. In our case, we will leverage crypt</code> with the gen_salt</code> function to generate password hash using bcrypt algorithm.

Let's start with loading the extension and adding password column:

CREATE</span> EXTENSION </span>IF NOT EXISTS</span> pgcrypto;</span></span>
ALTER TABLE</span> users </span>ADD</span> COLUMN password_hash </span>TEXT NOT NULL DEFAULT</span> gen_salt(</span>'bf'</span>); </span></span></code></pre>
The new column password_hash</code> will accommodate the variable-length bcrypt hash, while default function gen_salt('bf')</code> creates a unique bcrypt salt for every user.</p>
Now that our table structure is set, let's see how we can securely set and verify passwords using pgcrypto.</p>
When a user sets or changes their password, we'll hash it using crypt before storing it in the password_hash column.Here's how:</p>
UPDATE users SET password_hash = crypt('new_password', gen_salt('bf')) WHERE email = 'user@example.com';</span></span></code></pre>
and during login, we will verify the hash of the password the user enters with the stored password_hash:</p>
SELECT</span> user_id </span>FROM</span> users </span>WHERE</span> email </span>=</span> 'user@example.com'</span> AND</span> password_hash </span>=</span> crypt(</span>'entered_password'</span>, password_hash);</span></span></code></pre>JWT Authentication</a>
</h2>
With the ability to securely verify users' identity, let's move to the next step and build stateless authentication. The de-facto standard is JSON Web Tokens (JWTs). Represented by digitally signed information, they contain claims about user identity. The digital signature ensures the token's integrity and verifies that it hasn't been tampered with. You can find more in official Introduction to JSON Web Tokens</a>.</p>
While PostgreSQL doesn't have built-in JWT support, we will have to either rely on pgjwt</code> extension (GitHub repo</a>)</p>
CREATE EXTENSION IF NOT EXISTS pgjwt;</span></span></code></pre>
or you can re-create the logic by including PL/pgSQL that comes with it</a> (please, make sure you replace/remove the @extschema@</code> to match the schema you are using). In this article we will use schema jwt</code>.</p>
To make the token signature, we need to re-configure PostgREST to decode JWT tokens and configure the secret inside the database (to be able to use it in our code). For security reasons, the key must be at least 32 characters long. You can either use your own method to generate (for example, your password manager) or add it using the following CLI commands</p>
export</span> LC_CTYPE</span>=</span>C</span></span>
echo</span> "jwt-secret = </span>\"</span>$(</span>LC_ALL</span>=</span>C</span> tr</span> -dc</span> 'A-Za-z0-9'</span> <</span>/dev/urandom</span> |</span> head</span> -c32</span>)</span>\"</span>"</span> >></span> postgrest.conf</span></span></code></pre>
And use the generated secret for the database level configuration parameter, using</p>
ALTER DATABASE</span> time_off_manager </span>SET</span> "pgrst.jwt_secret"</span> to</span> "your-jwt-secret-generated-above1"</span>;</span></span></code></pre>
Please, make sure the database name is updated accordingly to set it correctly. And, I cannot stress it enough, make sure the secret is really 32 characters</strong>.</p>
The web user role</a>
</h2>
In previous parts of this guide, we have worked with two user roles. The first, in PostgREST terminology, called authenticator, is the role used in the db-uri</code> parameter. It's the role used to access the database and its job is to impersonate other users based on the authentication (or lack thereof) of the HTTP requests. In a real production application, this role should be configured to have limited access.</p>
The second role, called anonymous, is used in db-anon-role</code> parameter. This is the role impersonated for all unauthenticated HTTP requests.</p>
The third role, or roles, representing authenticated web users. In our JWT tokens, we will use one specifically designed for PostgREST.</p>
{</span></span>
	"role": "time_off_user"</span></span>
}</span></span></code></pre>
When JWT is successfully validated, with a role claim, PostgREST will switch to the database role with the provided name for the duration of the HTTP request. While PostgREST is quite flexible, we will limit the impersonated role for authenticated requests to a single hard-coded role. For our application, it's going to be called time_off_user</code>.</p>
Let's generate some JWTs</a>
</h2>
The first step is to implement logic to create a JWT token asserting all claims</strong> we need for our application - in the case of Time Off Manager, we will rely on user_id and role. As discussed in the previous section, we will use the hard-coded role time_off_user</code>. Let's create the role and grant our authenticator the permissions.</p>
CREATE ROLE</span> time_off_user NOLOGIN;</span></span>
GRANT</span> time_off_user </span>TO</span> time_off_manager;</span></span></code></pre>
Now create a function, users can call directly to verify the identity and generate the JWT token.</p>
CREATE OR REPLACE</span> FUNCTION api.login(email text, password text)</span></span>
  RETURNS text</span></span>
  LANGUAGE</span> plpgsql</span></span>
  SECURITY DEFINER</span></span>
AS</span> $function$</span></span>
DECLARE</span></span>
  user_record public.users;</span></span>
BEGIN</span></span>
  SELECT * INTO</span> user_record</span></span>
  FROM</span> public.users</span></span>
  WHERE</span> users.email </span>=</span> login.email;</span></span>
</span>
  IF</span> user_record.password_hash </span>=</span> crypt(password, user_record.password_hash) </span>THEN</span></span>
	RETURN</span> create_jwt(user_record.user_id, </span>'user_id'</span>);</span></span>
  ELSE</span></span>
	RAISE</span> EXCEPTION</span> 'Invalid email or password'</span>;</span></span>
  END IF</span>;</span></span>
END</span>;</span></span>
$function$;</span></span></code></pre>
Missing there is helper create_jwt</code></p>
CREATE OR REPLACE</span> FUNCTION public.create_jwt(user_id </span>integer</span>, role text)</span></span>
 RETURNS text</span></span>
 LANGUAGE</span> plpgsql</span></span>
AS</span> $function$</span></span>
DECLARE</span></span>
  payload JSON;</span></span>
BEGIN</span></span>
  payload </span>:=</span> json_build_object(</span></span>
    'user_id'</span>, user_id,</span></span>
    'role'</span>, </span>'time_off_user'</span>,</span></span>
    'exp'</span>, </span>extract</span>(epoch </span>from</span> now()) </span>+</span> 3600</span> -- 1-hour expiration</span></span>
  );</span></span>
  RETURN</span> jwt.</span>sign</span>(payload, current_setting(</span>'pgrst.jwt_secret'</span>));  </span>-- Use configuration value</span></span>
END</span>;</span></span>
$function$;</span></span></code></pre>
Restart the PostgREST instance to apply the changes, and you can try to generate a token using cURL (assuming you have changed the password as demonstrated in the first section ):</p>
curl</span> -X</span> POST "http://localhost:3000/rpc/login"</span> \</span></span>
	-d</span> '{"email":"manager2@example.com", "password": "new_password"}'</span> \</span></span>
	-H</span> "Content-Type: application/json"</span></span></code></pre>
If you set everything as expected you will get a base64 encoded token. To verify/debug it, you can try to use JWT.io</a>.</p>
Prepare the permissions</a>
</h2>
The next step is where things get really interesting. First, we need to clean up excessive permissions. Some obvious, some less so.</p>
First let's start with the revoking all the permissions for time_off_anonymous</code> we provided in previous part.</p>
REVOKE</span> ALL PRIVILEGES </span>ON</span> ALL TABLES </span>IN SCHEMA</span> api </span>FROM</span> time_off_anonymous;</span></span>
REVOKE EXECUTE ON</span> ALL FUNCTIONS </span>IN SCHEMA</span> api </span>FROM</span> time_off_anonymous;</span></span></code></pre>
and same we need to adjust the default privileges</p>
ALTER DEFAULT</span> PRIVILEGES </span>IN SCHEMA</span> api </span>REVOKE SELECT ON</span> TABLES </span>FROM</span> time_off_anonymous;</span></span>
ALTER DEFAULT</span> PRIVILEGES </span>IN SCHEMA</span> api </span>REVOKE EXECUTE ON</span> FUNCTIONS </span>FROM</span> time_off_anonymous;</span></span>
</span></code></pre>
Which is the obvious part. The most likely surprising part is the need to remove EXECUTE</code> permissions for PUBLIC</code>. In PostgreSQL, granting usage on a schema also grants the ability to execute functions to PUBLIC</code>. Unless you revoke these privileges, all users will be able to execute the functions.</p>
For our purposes we want to REVOKE the access for PUBLIC</code> and only grant EXECUTE</code> on function api.login()</code></p>
GRANT</span> USAGE </span>ON SCHEMA</span> api </span>TO</span> time_off_user;</span></span>
</span>
-- REVOKE EXECUTE</span></span>
ALTER DEFAULT</span> PRIVILEGES </span>IN SCHEMA</span> api </span>REVOKE EXECUTE ON</span> FUNCTIONS </span>FROM</span> PUBLIC;</span></span>
REVOKE EXECUTE ON</span> ALL FUNCTIONS </span>IN SCHEMA</span> api </span>FROM</span> PUBLIC;</span></span>
</span>
-- GRANT EXECUTE </span></span>
GRANT EXECUTE ON FUNCTION</span> api</span>.</span>login</span> to</span> time_off_anonymous;</span></span></code></pre>
And finally, we need to establish the necessary permissions for time_off_user</code>, the role which will be used for authenticated requests.</p>
GRANT SELECT ON</span> ALL TABLES </span>IN SCHEMA</span> public </span>TO</span> time_off_user;</span></span>
GRANT SELECT ON</span> ALL TABLES </span>IN SCHEMA</span> api </span>TO</span> time_off_user;</span></span>
GRANT EXECUTE ON</span> ALL FUNCTIONS </span>IN SCHEMA</span> api </span>TO</span> time_off_user;</span></span>
</span>
ALTER DEFAULT</span> PRIVILEGES </span>IN SCHEMA</span> public </span>GRANT SELECT ON</span> TABLES </span>TO</span> time_off_user;</span></span>
ALTER DEFAULT</span> PRIVILEGES </span>IN SCHEMA</span> api </span>GRANT SELECT ON</span> TABLES </span>TO</span> time_off_user;</span></span>
ALTER DEFAULT</span> PRIVILEGES </span>IN SCHEMA</span> api </span>GRANT EXECUTE ON</span> FUNCTIONS </span>TO</span> time_off_user;</span></span></code></pre>
We will now use this to get an overview of only relevant vacation balances for the authenticated user.</p>
Authorization with PostgREST</a>
</h2>
With authentication working, let's start with the implementation of fine-grained authorization in PostgREST. As a first step, the goal is to ensure that users only see the vacation balances they are supposed to. I.e. either their own (for the regular employees) or their own and the people the user manages (for the managers).</p>
For this we will need to access JWT token claims, specifically user_id</code>. To avoid relatively complex notation, let's setup a helper</p>
CREATE OR REPLACE FUNCTION</span> public</span>.current_user_id()</span></span>
 RETURNS integer</span></span>
 LANGUAGE</span> plpgsql</span></span>
 SECURITY</span> DEFINER</span></span>
AS</span> $</span>function</span>$</span></span>
DECLARE</span></span>
    user_id </span>INTEGER</span>;</span></span>
BEGIN</span></span>
    user_id :</span>=</span> current_setting(</span>'request.jwt.claims'</span>, true)::</span>json->></span>'user_id'</span>;</span></span>
</span>
    IF</span> user_id </span>IS NULL THEN</span></span>
        RAISE EXCEPTION </span>'User ID not found in JWT claims'</span>;</span></span>
    END IF</span>;</span></span>
</span>
    RETURN</span> user_id::</span>integer</span>;</span></span>
END</span>;</span></span>
$</span>function</span>$;</span></span></code></pre>
PostgREST seamlessly integrates with PostgreSQL's Row Level Security (RLS) to filter data based on user permissions. RLS policies are rules applied at the row level to determine if a user can access a particular row in a table.</p>
ALTER TABLE</span> public</span>.</span>time_off_transactions</span> ENABLE ROW LEVEL SECURITY</span>;</span></span>
</span>
CREATE POLICY</span> select_own_balance </span>ON</span> public</span>.</span>time_off_transactions</span> </span></span>
FOR SELECT USING</span> (</span>public</span>.</span>current_user_id</span>()</span> =</span> user_id);</span></span>
</span>
CREATE POLICY</span> select_supervised_balance </span>ON</span> public</span>.</span>time_off_transactions</span></span>
FOR SELECT USING</span> (</span>EXISTS</span> (</span>SELECT</span> 1</span> FROM</span> api</span>.</span>users</span> WHERE</span> users</span>.</span>user_id</span> =</span> time_off_transactions</span>.</span>user_id</span> AND</span> users</span>.</span>manager_user_id</span> =</span> public</span>.</span>current_user_id</span>()));</span></span></code></pre>
If you are (and I do hope so) using PostgreSQL 15 and higher, you need to switch the view from the default security definer to invoker.</p>
ALTER VIEW</span> api</span>.</span>vacation_balances</span> SET</span> (security_invoker </span>=</span> true);</span></span></code></pre>
This way the view, and the underlying tables will be evaluated using the permissions of the user querying the view, not the view owner. This is the behaviour we want. For versions beyond PostgreSQL 15 and more complex use cases, you might need to implement function-based security instead.</p>
But without further delay, let's test "the magic" and (assuming you have authenticated as a manager) you might try to retrieve the vacation balances using cURL</p>
curl</span> "http://localhost:3000/vacation_balances"</span> \</span></span>
	-H</span> "Authorization: Bearer ${</span>JWT_TOKEN</span>}"</span></span></code></pre>
to get a result similar to</p>
[{</span>"year"</span>:</span>2024</span>,</span>"user_id"</span>:</span>8</span>,</span>"total_amount"</span>:</span>25</span>},</span></span>
 {</span>"year"</span>:</span>2024</span>,</span>"user_id"</span>:</span>9</span>,</span>"total_amount"</span>:</span>25</span>},</span></span>
 {</span>"year"</span>:</span>2024</span>,</span>"user_id"</span>:</span>10</span>,</span>"total_amount"</span>:</span>25</span>},</span></span>
 {</span>"year"</span>:</span>2024</span>,</span>"user_id"</span>:</span>11</span>,</span>"total_amount"</span>:</span>25</span>},</span></span>
 {</span>"year"</span>:</span>2024</span>,</span>"user_id"</span>:</span>12</span>,</span>"total_amount"</span>:</span>25</span>},</span></span>
 {</span>"year"</span>:</span>2024</span>,</span>"user_id"</span>:</span>13</span>,</span>"total_amount"</span>:</span>25</span>}]</span></span></code></pre>
Guess, it's important to mention the Row Security Policies which are used are much more complex, and the whole topic would deserve another article. For now, I do recommend you to consult the documentation</a></del>, to get more understanding. With the multi-role access you can implement with PostgREST, it might be interesting for you to focus on BYPASSRLS</code> which might be applied to certain role(s).</p>
As mentioned before, Row Level Security is just one way to solve this. The traditional approach would be to use functions to hide the separation logic.</p>
Wrapping up the Time Off Manager</a>
</h2>
Before we wrap up our tutorial, let's finish the core functionality of the Time Off Manager - the approval workflow. Given the basic concepts covered above, this is going to be a good exercise to use all of it.</p>
Similar how we updated time_off_transactions</code>, we will apply Row Level Security to time_off_requests</code>.</p>
ALTER TABLE</span> public</span>.</span>time_off_requests</span> ENABLE ROW LEVEL SECURITY</span>; </span></span>
</span>
CREATE POLICY</span> select_own_requests </span>ON</span> public</span>.</span>time_off_requests</span> </span></span>
FOR SELECT USING</span> (</span>public</span>.</span>current_user_id</span>()</span> =</span> user_id); </span></span>
</span>
CREATE POLICY</span> select_subordinate_requests </span>ON</span> public</span>.</span>time_off_requests</span></span>
FOR SELECT USING</span> (</span>EXISTS</span> (</span>SELECT</span> 1</span> FROM</span> public</span>.</span>users</span> WHERE</span> users</span>.</span>user_id</span> =</span> time_off_requests</span>.</span>user_id</span> AND</span> users</span>.</span>manager_user_id</span> =</span> public</span>.</span>current_user_id</span>()));</span></span></code></pre>
Don't forget to switch the view to security_invoker</code> model.</p>
ALTER VIEW</span> api</span>.</span>pending_requests</span> SET</span> (security_invoker </span>=</span> true);</span></span></code></pre>
And we wouldn't be done with requests creation, if we wouldn't update function api.request_time_off</code> to take the advantage of the newly propagated user_id</code> from authentication.</p>
CREATE OR REPLACE FUNCTION</span> api</span>.request_time_off(leave_type </span>text</span>, </span>period</span> daterange)</span></span>
RETURNS integer</span></span>
LANGUAGE</span> plpgsql</span></span>
SECURITY</span> DEFINER</span></span>
AS</span> $</span>function</span>$</span></span>
DECLARE</span></span>
    v_leave_type_id </span>INT</span>;</span></span>
    v_request_id </span>INT</span>;</span></span>
BEGIN</span></span>
    -- original validation logic </span></span>
</span>
    -- Ensure the user is requesting for themselves</span></span>
    IF</span> public</span>.</span>current_user_id</span>()</span> !=</span> request_time_off</span>.</span>user_id</span> THEN</span></span>
        RAISE EXCEPTION </span>'User can only request time off for themselves'</span>;</span></span>
    END IF</span>;</span></span>
</span>
    -- the rest of the function</span></span>
END</span>;</span></span>
$</span>function</span>$;</span></span></code></pre>
The similar update then applies to the api.update_request</code> function to ensure only managers can approve/reject time off requests.</p>
CREATE OR REPLACE FUNCTION</span> api</span>.update_request(request_id </span>integer</span>, new_status </span>text</span>)</span></span>
RETURNS</span> void</span></span>
LANGUAGE</span> plpgsql</span></span>
SECURITY</span> DEFINER</span></span>
AS</span> $</span>function</span>$</span></span>
DECLARE</span></span>
    v_requested_user_id </span>INT</span>;</span></span>
    v_request_manager_id </span>INT</span>;</span></span>
BEGIN</span></span>
    -- the original code up to the retrival of the requests</span></span>
 </span></span>
    IF</span> public</span>.</span>current_user_id</span>()</span> !=</span> v_request_manager_id </span>THEN</span></span>
        RAISE EXCEPTION </span>'Only the manager can approve or reject this request'</span>;</span></span>
    END IF</span>;</span></span>
</span>
    -- update the request status</span></span>
END</span>;</span></span>
$</span>function</span>$;</span></span></code></pre>
And that's about it! Obviously, we can't pretend Time Off Manager is anywhere complete, and the real-life application would require much more than what we have covered. But it should provide a good training platform to allow you to write a real API-based backends using just PostgREST.</p>

Correction 2024-06-11</em>: during the final edits the function public.current_user_id</code> somehow got missing from the Markdown [FIXED].</p>



Deep Dive into PostgREST - Time Off Manager (Part 2)
2024-05-18T00:00:00+00:00
Let's recap the first part</a> of "Deep Dive into PostgREST," where we explored the basic functionality to expose and query any table using an API, demonstrated using cURL</code>. All it took was to set up a db-schema</code> and give the db-anon-role</code> some permissions. But unless you are creating the simplest of CRUD applications, this only scratches the surface.</p>
In Part 2, we will expand APIs, provide better abstraction, and implement the foundation of what can be considered business logic, all while extending the sample "Time Off Manager" application. While the previous instalment being introductiory only, make sure you don't miss the important details in this one.</p>
Before we move on, let's do a bit of housekeeping and clean up the permissions setup from the first part. This way, we can start with a clean slate (when it comes to the permissions) and avoid any lingering rights that could confuse us later.</p>
REVOKE</span> ALL PRIVILEGES </span>ON</span> ALL TABLES </span>IN SCHEMA</span> public </span>FROM</span> time_off_anonymous;</span></span></code></pre>Dedicated schema for the API</a>
</h2>
Using the public</code> schema (or any schema(s) where your core data model resides) is a fast way to get started. However, using a dedicated schema for the API is beneficial for several reasons:</p>

It provides options for better abstraction, which you might appreciate later when refactoring the original data model.</li>
Data customisation is also a requirement unless you prefer building a "fat" client and thus transferring the majority of the business logic there. Combining data from multiple tables helps shield the consumer from complex queries and relations.</li>
While we won't explore it as a security feature, it can also provide relevant boundaries.</li>
</ul>
Let's get started with the creation of the schema itself, and expose the users using a view and setting basic permissions. We will do this by setting default permissions, so we don't have to repeat the same for all objects as we create them. Please note that default privileges are applied only to new objects created.</p>
CREATE SCHEMA</span> api</span>;</span></span>
</span>
GRANT</span> USAGE </span>ON SCHEMA</span> api </span>TO</span> time_off_anonymous;</span></span>
ALTER DEFAULT</span> PRIVILEGES </span>IN SCHEMA</span> api </span>GRANT SELECT ON</span> TABLES </span>TO</span> time_off_anonymous;</span></span>
ALTER DEFAULT</span> PRIVILEGES </span>IN SCHEMA</span> api </span>GRANT EXECUTE ON</span> FUNCTIONS </span>TO</span> time_off_anonymous;</span></span></code></pre>
Ok, let's create our first view:</p>
CREATE VIEW</span> api</span>.users </span>AS</span></span>
SELECT</span> </span></span>
    u</span>.</span>user_id</span>,</span></span>
    u</span>.</span>email</span>,</span></span>
    m</span>.</span>user_id</span> as</span> manager_user_id,</span></span>
    m</span>.</span>email</span> AS</span> manager_email,</span></span>
    u</span>.</span>created_at</span></span>
FROM</span> </span></span>
    public</span>.</span>users</span> AS</span> u</span></span>
    LEFT JOIN</span> public</span>.</span>users</span> AS</span> m </span>ON</span> u</span>.</span>manager_id</span> =</span> m</span>.</span>user_id</span></span>
WHERE</span></span>
    u</span>.</span>deleted_at</span> is null</span>;</span></span></code></pre>
This way, we established the foundation for listing users while providing much richer information about a person's manager and preventing potential additional roundtrips between client and API. We also included simple business logic—by omitting the soft-deleted employees.</p>
After creating the views, it's important to update the postgrest.conf</code> file to use the new api</code> schema:</p>
db-uri = "postgres://username:password@localhost/time_off_manager"</span></span>
db-schema = "api"</span></span>
db-anon-role = "time_off_anonymous"</span></span></code></pre>
This change tells PostgREST to treat the api</code> schema as the primary interface for API requests, rather than the public schema. Once done, feel free to restart the PostgREST server and test the new setup.</p>
$</span> curl "http://localhost:3000/users"</span></span></code></pre>
We can further extend the example by provisioning a view with a summary of the vacation days available per calendar year (of course, for simplicity we won't consider transfers between years, etc.).</p>
CREATE VIEW</span> api</span>.vacation_balances </span>AS</span></span>
SELECT</span> </span></span>
    EXTRACT(</span>YEAR FROM</span> transaction_date) </span>AS year</span>,</span></span>
    user_id,</span></span>
    SUM</span>(amount) </span>AS</span> total_amount</span></span>
FROM</span> public</span>.</span>time_off_transactions</span></span>
JOIN</span> api</span>.</span>users</span> USING</span> (user_id)</span></span>
WHERE</span> </span></span>
    leave_type_id </span>=</span> (</span>SELECT</span> leave_type_id </span>FROM</span> public</span>.</span>leave_types</span> WHERE</span> label </span>=</span> 'vacation'</span>)</span></span>
GROUP BY</span> </span></span>
    EXTRACT(</span>YEAR FROM</span> transaction_date), user_id;</span></span></code></pre>
While this is nothing groundbreaking, we could (and should) have certainly used views in the first part. So what makes this important now? As mentioned above, the main use cases are abstraction, data access, and security. Additional benefits might include other concerns like derived columns (e.g., full name if we were using first and last name columns), enriching data (e.g., building full URLs from fragments), and other logic specific to the presentation layer.</p>
For practice, we can expose possible time off types via a simple view:</p>
CREATE VIEW</span> api</span>.leave_types </span>AS</span> </span></span>
SELECT</span></span>
    label</span></span>
FROM</span> public</span>.</span>leave_types</span></span>
WHERE</span> deleted_at </span>is null</span>;</span></span></code></pre>Let's modify the data</a>
</h2>
While the simplicity of performing CRUD operations on tables in the public schema was straightforward in the first part of the tutorial, using VIEWs introduces certain complexities. One key limitation of VIEWs is their restricted capability for data modification. Let's look at how to encapsulate the logic.</p>
You might have guessed it—the most obvious way forward is to introduce a database stored procedure for any business logic we want to expose.</p>
CREATE OR REPLACE FUNCTION</span> api</span>.add_user(</span></span>
    email </span>text</span>,</span></span>
    manager_id </span>integer</span></span>
) </span>RETURNS integer AS</span> $$</span></span>
DECLARE</span></span>
    v_new_user_id </span>integer</span>;</span></span>
BEGIN</span></span>
    -- check if email already exists</span></span>
    PERFORM </span>1</span> FROM</span> api</span>.</span>users</span> WHERE</span> users</span>.</span>email</span> =</span> add_user</span>.</span>email</span>;</span></span>
    IF</span> FOUND </span>THEN</span></span>
        RAISE EXCEPTION </span>'The email address % is already in use'</span>, </span>add_user</span>.</span>email</span></span>
            USING</span> ERRCODE </span>=</span> 'unique_violation'</span>;</span></span>
    END IF</span>;</span></span>
    </span></span>
    -- sample business logic: all employees must have manager</span></span>
    IF</span> manager_id </span>IS NULL THEN</span></span>
        RAISE EXCEPTION </span>'manager_id must be provided and cannot be null'</span>;</span></span>
    END IF</span>;</span></span>
    </span></span>
    INSERT INTO</span> public</span>.</span>users</span> (email, manager_id)</span></span>
    VALUES</span> (</span>add_user</span>.</span>email</span>, </span>add_user</span>.</span>manager_id</span>)</span></span>
    RETURNING user_id </span>INTO</span> v_new_user_id;</span></span>
    </span></span>
    RETURN</span> v_new_user_id;</span></span>
END</span>;</span></span>
$$ </span>LANGUAGE</span> plpgsql </span>SECURITY</span> DEFINER;</span></span></code></pre>
Ok, we have introduced a rather complex piece of logic there. While it might look simple (if you've ever seen a PL/pgSQL function), it comes with a couple of important details.</p>
First and foremost, the function api.add_user</code> presents an example of how to implement business logic. In this case, it's providing a custom error message should the employee's email already exist and enforcing the logic that manager_id</code> must be provided. You can probably think of more cases to enrich data.</p>
Now for the more difficult part—you might not be familiar with the SECURITY</code> attribute. Every function created can have two modes, INVOKER</code> (which is the default) and DEFINER</code>. If you look above, when we removed all the permissions for our db-anon-role</code> from schema public</code>, the user lost privileges to perform any operations there. Without modifying the security attribute, the function would result in an error message permission denied for table users</code>. Using SECURITY DEFINER</code> guarantees your application user's (the one used for the creating the view) permissions will be used when calling the function.</p>
This is the opposite of how VIEWs work in this example, as they come with the default option security_invoker</code> disabled by default. You can refer to the documentation</a> to learn more.</p>
If you are not familiar with PL/pgSQL, I recommend you check the basic statements</a>.</p>
With the function in place, let's call it using cURL:</p>
$</span> curl "http://localhost:3000/rpc/add_user"</span> -X</span> POST</span> \</span></span>
	-d</span> '{ "email": "admin2@example.com", "manager_id": 2 }'</span> \</span></span>
	-H</span> "Content-Type: application/json"</span></span></code></pre>
This is the second time we need to deconstruct the seemingly simple logic. Let's start with the URL. The /rpc/</code> prefix is important. Every stored procedure in the schema defined using db-schema</code> is accessible under this prefix. The prefix helps to differentiate object types, as in PostgreSQL you are allowed to have the same name for a table/view and a function.</p>
The second part is the request method, in this case POST</code>. While you can use both GET</code> and POST</code>, it's important to understand the implications. Using the GET</code> method sets the PostgREST transaction to read-only mode and is a powerful security measure—explicitly preventing the operation from performing any modification of the data (even indirectly via functions or triggers). Should you perform the function using GET</code>, you would get a cannot execute INSERT in a read-only transaction</code> error message to confirm it.</p>
The third part of the call is the way the data is presented. In this example, it's using JSON (declared as Content-Type: application/json</code> header) and passed within the request body. If required, you can choose other formats—like application/x-www-form-urlencoded</code>, text/xml</code>, application/octet-stream</code> for bytea</code>, and more using custom media type handlers</a>.</p>
Therefore, the same can be achieved using:</p>
$</span> curl "http://localhost:3000/rpc/add_user"</span> -X</span> POST</span> \</span></span>
 	-d</span> "email=admin2%40example.com&manager_id=2"</span> \</span></span>
	-H</span> "Content-Type: application/x-www-form-urlencoded"</span></span></code></pre>
Let's omit the XML example completely [sic].</p>
As we have introduced the function that modifies the data, we should explore the option to do the same with read-only functions.</p>
CREATE OR REPLACE FUNCTION</span> api</span>.get_max_vacation_days()</span></span>
RETURNS INTEGER</span> STABLE </span>AS</span> $$</span></span>
    SELECT</span> max_days</span></span>
    FROM</span> public</span>.</span>leave_types</span></span>
    WHERE</span> label </span>=</span> 'vacation'</span>;</span></span>
$$ </span>LANGUAGE sql SECURITY</span> DEFINER;</span></span></code></pre>
Here, we defined the function get_max_vacation_days</code>, which enables retrieving the current number of vacation days for all employees. To call the function, we can simply run:</p>
$</span> curl "http://localhost:3000/rpc/get_max_vacation_days"</span></span></code></pre>
This summarises the basics of using a dedicated schema and VIEWs. While using stored procedures is the most obvious way, you can also use updatable views and INSTEAD OF TRIGGERS. This approach allows you to hide the possible transition from table to views and implement the insert logic using the trigger function. While this is a powerful technique, I recommend using direct function calls for clarity (at least when you are getting started).</p>
Simple workflow management</a>
</h2>
As we have introduced quite a lot of (potentially new) concepts, let's practice more and get our hands dirty with the implementation of a simple workflow management system. In our case, it's functionality for employees to request time off and manage approval flow. The premise is simple:</p>

Employee can request a time off of a certain type</li>
Employee can approve/reject the time off request for their reports</li>
The boss can do whatever they want</li>
</ul>
Let's start with defining the table for time off requests. Please notice we are going to create it again in schema public</code> and not directly expose it via the API.</p>
CREATE TABLE</span> public</span>.time_off_requests (</span></span>
    request_id </span>SERIAL PRIMARY KEY</span>,</span></span>
    user_id </span>INT REFERENCES</span> public</span>.</span>users</span>(user_id),</span></span>
    leave_type_id </span>INT REFERENCES</span> public</span>.</span>leave_types</span>(leave_type_id),</span></span>
    requested_date </span>DATE</span>,</span></span>
    period</span> DATERANGE,</span></span>
    status TEXT CHECK</span> (</span>status IN</span> (</span>'pending'</span>, </span>'approved'</span>, </span>'rejected'</span>)),</span></span>
    created_at </span>TIMESTAMP WITH TIME ZONE DEFAULT</span> current_timestamp</span></span>
);</span></span></code></pre>
We will add functionality to request time off via a function:</p>
CREATE OR REPLACE FUNCTION</span> api</span>.request_time_off(</span></span>
    user_id </span>INT</span>,</span></span>
    leave_type </span>TEXT</span>,</span></span>
    period</span> DATERANGE</span></span>
) </span>RETURNS INTEGER AS</span> $$</span></span>
DECLARE</span></span>
    v_leave_type_id </span>INT</span>;</span></span>
    v_request_id </span>INT</span>;</span></span>
BEGIN</span></span>
    -- validate the leave type</span></span>
    SELECT</span> leave_type_id </span>INTO</span> v_leave_type_id </span></span>
    FROM</span> public</span>.</span>leave_types</span> </span></span>
    WHERE</span> label </span>=</span> request_time_off</span>.</span>leave_type</span>;</span></span>
    </span></span>
    IF</span> v_leave_type_id </span>IS NULL THEN</span></span>
        RAISE EXCEPTION </span>'Invalid leave type: %'</span>, </span>request_time_off</span>.</span>leave_type</span>;</span></span>
    END IF</span>;</span></span>
</span>
    -- check if the user ID is valid</span></span>
    PERFORM </span>1</span> FROM</span> public</span>.</span>users</span> WHERE</span> users</span>.</span>user_id</span> =</span> request_time_off</span>.</span>user_id</span>;</span></span>
    IF NOT</span> FOUND </span>THEN</span></span>
        RAISE EXCEPTION </span>'Invalid user ID: %'</span>, </span>request_time_off</span>.</span>user_id</span>;</span></span>
    END IF</span>;</span></span>
    </span></span>
    -- insert the new time off request</span></span>
    INSERT INTO</span> public</span>.</span>time_off_requests</span> (</span></span>
        user_id, leave_type_id, requested_date, </span>period</span>, </span>status</span></span>
    ) </span>VALUES</span> (</span></span>
        request_time_off</span>.</span>user_id</span>, </span></span>
		v_leave_type_id,</span></span>
		CURRENT_DATE,</span></span>
		request_time_off</span>.</span>period</span>,</span></span>
		'pending'</span></span>
    ) RETURNING request_id </span>INTO</span> v_request_id;</span></span>
    </span></span>
    RETURN</span> v_request_id;</span></span>
END</span>;</span></span>
$$ </span>LANGUAGE</span> plpgsql </span>SECURITY</span> DEFINER;</span></span></code></pre>
For the purposes of this guide, let's leave details out, and we would expect the period</code> to be the applicable working days. To reiterate, the function above:</p>

Provides basic application logic, setting the status to 'pending'</li>
Explicitly declares SECURITY DEFINER</code> to facilitate permissions to access the newly created table.</li>
</ul>
We can call it using:</p>
$</span> curl</span> -X</span> POST "http://localhost:3000/rpc/request_time_off"</span> \</span></span>
	-d</span> '{"user_id": 6, "leave_type": "vacation", "period": "[2024-05-20,2024-05-21]"} '</span> \</span></span>
	-H</span> "Content-Type: application/json"</span></span></code></pre>
For the client to be able to display the pending requests, let's introduce the view using the request fields and adding the manager ID of the employee, which we will utilise in the next step:</p>
CREATE VIEW</span> api</span>.pending_requests </span>AS</span></span>
SELECT</span></span>
    r</span>.</span>request_id</span>,</span></span>
    r</span>.</span>user_id</span>,</span></span>
    r</span>.</span>leave_type_id</span>,</span></span>
    r</span>.</span>requested_date</span>,</span></span>
    r</span>.</span>period</span>,</span></span>
    r</span>.</span>status</span>,</span></span>
    r</span>.</span>created_at</span>,</span></span>
    u</span>.</span>manager_id</span></span>
FROM</span> public</span>.</span>time_off_requests</span> r</span></span>
JOIN</span> public</span>.</span>users</span> u </span>ON</span> r</span>.</span>user_id</span> =</span> u</span>.</span>user_id</span></span>
WHERE</span> r</span>.</span>status</span> =</span> 'pending'</span></span>
ORDER BY</span> r</span>.</span>created_at</span>;</span></span></code></pre>
With this in place, we can move forward with implementing the function api.update_request</code> to provide the necessary business logic to approve/reject the requests.</p>
CREATE OR REPLACE FUNCTION</span> api</span>.update_request(</span></span>
    request_id </span>INT</span>,</span></span>
    user_id </span>INT</span>,</span></span>
    new_status </span>TEXT</span></span>
) </span>RETURNS</span> VOID </span>AS</span> $$</span></span>
DECLARE</span></span>
    v_requested_user_id </span>INT</span>;</span></span>
    v_request_manager_id </span>INT</span>;</span></span>
BEGIN</span></span>
    -- validate the new status</span></span>
    IF</span> new_status </span>NOT IN</span> (</span>'approved'</span>, </span>'rejected'</span>) </span>THEN</span></span>
        RAISE EXCEPTION </span>'Invalid status: %. Only "approved" or "rejected" are allowed'</span>, new_status;</span></span>
    END IF</span>;</span></span>
</span>
    -- retrieve the request together with the users associated with it</span></span>
    SELECT</span> pr</span>.</span>user_id</span>, </span>pr</span>.</span>manager_id</span> INTO</span> v_requested_user_id, v_request_manager_id</span></span>
    FROM</span> api</span>.</span>pending_requests</span> pr</span></span>
    WHERE</span> pr</span>.</span>request_id</span> =</span> update_request</span>.</span>request_id</span>;</span></span>
</span>
    IF NOT</span> FOUND </span>THEN</span></span>
        RAISE EXCEPTION </span>'There''s no pending Time off request ID %'</span>, request_id;</span></span>
    END IF</span>;</span></span>
</span>
    -- prevent users from self-approving their requests</span></span>
    IF</span> user_id </span>=</span> v_requested_user_id </span>THEN</span></span>
        RAISE EXCEPTION </span>'User cannot approve or reject their own request'</span>;</span></span>
    END IF</span>;</span></span>
</span>
    -- check if the user is either the requester’s manager or the boss</span></span>
    IF</span> (v_request_manager_id </span>IS NOT NULL AND</span> user_id </span><></span> v_request_manager_id) </span>THEN</span></span>
        RAISE EXCEPTION </span>'Only the manager or The Boss can approve or reject the request'</span>;</span></span>
    END IF</span>;</span></span>
</span>
    -- update the request status</span></span>
    UPDATE</span> public</span>.</span>time_off_requests</span></span>
    SET status =</span> new_status</span></span>
    WHERE</span> time_off_requests</span>.</span>request_id</span> =</span> update_request</span>.</span>request_id</span>;</span></span>
END</span>;</span></span>
$$ </span>LANGUAGE</span> plpgsql </span>SECURITY</span> DEFINER;</span></span></code></pre>
This time, the function shouldn't have any surprises—just ensure you follow all the points addressed previously. With the functionality to approve/reject the requests, we are missing the last crucial step: deducting the balance upon approval. There are two ways to go about this: either add the logic to the function above or implement triggers. While a full discussion goes beyond this guide, let's provide a brief summary of when to choose which solution.</p>
Choose a function if you have complex logic reusable by many functions (which does not prevent re-use in triggers), and use triggers if you prefer the automatic business rule enforcement and consistency on the database level. For this tutorial let's do triggers to expand further the use of different SQL techniques (plus I would personally choose this solution anyway).</p>
Before jumping in, let's create a helper function that will calculate the number of days to deduct from the balance.</p>
CREATE OR REPLACE FUNCTION</span> public</span>.days_in_daterange(</span>period</span> daterange) </span>RETURNS INT AS</span> $$</span></span>
    SELECT</span> upper</span>(</span>period</span>) </span>-</span> lower</span>(</span>period</span>)</span></span>
$$ </span>LANGUAGE sql</span>;</span></span></code></pre>
With it in place, we can create the function:</p>
CREATE OR REPLACE FUNCTION</span> public</span>.create_transaction_on_approval()</span> RETURNS</span> TRIGGER </span>AS</span> $$</span></span>
BEGIN</span></span>
    IF</span> NEW</span>.</span>status</span> =</span> 'approved'</span> THEN</span></span>
        INSERT INTO</span> time_off_transactions (</span></span>
            user_id, </span></span>
            leave_type_id, </span></span>
            transaction_date, </span></span>
            time_off_period, </span></span>
            amount</span></span>
        ) </span>VALUES</span> (</span></span>
            NEW</span>.</span>user_id</span>,</span></span>
            NEW</span>.</span>leave_type_id</span>,</span></span>
            CURRENT_DATE,</span></span>
            NEW</span>.</span>period</span>,</span></span>
            -</span>public</span>.</span>days_in_daterange</span>(</span>NEW</span>.</span>period</span>)</span></span>
        );</span></span>
    END IF</span>;</span></span>
  </span></span>
    RETURN</span> NEW;</span></span>
END</span>;</span></span>
$$ </span>LANGUAGE</span> plpgsql;</span></span></code></pre>
And set up the trigger itself:</p>
CREATE TRIGGER</span> create_transaction_on_approval</span></span>
AFTER UPDATE ON</span> time_off_requests</span></span>
FOR</span> EACH </span>ROW</span></span>
WHEN</span> (</span>NEW</span>.</span>status</span> =</span> 'approved'</span> AND</span> OLD</span>.</span>status</span> =</span> 'pending'</span>)</span></span>
EXECUTE FUNCTION</span> create_transaction_on_approval();</span></span></code></pre>
With the approval logic in place, we can try the original function via API:</p>
$</span> curl</span> -X</span> POST "http://localhost:3000/rpc/update_request"</span> \</span></span>
	-d</span> '{"request_id": 1, "user_id": 2, "new_status": "approved"}'</span> \</span></span>
	-H</span> "Content-Type: application/json"</span></span></code></pre>
If you have used the correct IDs (both for request ID and user ID), you can now verify the balances using the pre-defined view vacation_balances</code>.</p>
$</span> curl "http://localhost:3000/vacation_balances"</span></span></code></pre>
This demonstrates the basic workflow and how it can be exposed using PostgREST as an API. If you want to continue practising more database logic, you can add the following logic:</p>

Prevent negative vacation balances (intermediate)</li>
Prevent employees of a single manager from requesting overlapping vacations (advanced)</li>
</ul>
End of Part 2</a>
</h2>
By introducing a dedicated API schema, we have added an abstraction layer that provides an effective boundary between the model/logic itself and the API specifics. While this is a good practice, it's up to you how to expose functionality. The main benefit of a dedicated schema is simplicity, allowing you to grant privileges on the schema in bulk rather than maintaining granular permissions. It also provides an easy way to expose existing databases with PostgREST.</p>
While the current state of the sample API for Time Off Manager would work for small teams, in the next part, we will move towards authentication for added security and privacy.</p>
And don't forget you can find the source code in the GitHub repository</a>.</p>


Deep Dive into PostgREST - Time Off Manager (Part 1)
2024-05-11T00:00:00+00:00
The primary motivation behind boringSQL</strong> is to explore the robust world of SQL and the PostgreSQL ecosystem, demonstrating how these "boring" tools can cut through the ever-increasing noise and complexity of modern software development. In this series, I'll guide you through building a simple yet fully functional application—a Time Off Manager. The goal of this project is not only to demonstrate practical database/SQL approaches but also to provide a complete, extendable solution that you can immediately build upon. Each part of this series will deliver a self-contained application, setting the stage for introducing more complex functionalities and practices.</p>
The first part of this guide focuses mainly on the application logic and exposing raw data using postgREST</strong>, allowing you to grasp the concept.</p>
Requirements</a>
</h2>
This tutorial assumes you can install PostgreSQL, connect to it using your preferred DB client, have permissions to create a new database, and understand the basics of schema operations and SQL. Similarly, you should be able to follow the installation instructions for postgREST</a>.</p>
The complete source code for the guide is available at GitHub</a>.</p>
The Time Off Manager</a>
</h2>
When choosing a sample application for this tutorial, I was torn between the popular but simple TodoMVC and a slightly more complex application. In the end, a sample like Time Off Manager provides a much richer database scheme, going beyond the basics and offering a solution closer to real-life systems.</p>
Time Off Manager is also an excellent example that combines simple business logic, workflows, and practicality. The main requirements are:</p>

Maintaining the list of users (employees) with their respective managers</li>
Allowing the maintenance of the time off balance, with an audit history</li>
Introducing an approval workflow and automation</li>
</ul>
While the application is intended for learning purposes, the database and API can be easily exposed and built upon.</p>
The Database</a>
</h2>
To get started, you will need to create a database. You can do this in two ways, either using the CREATE DATABASE statement:</p>
CREATE DATABASE time_off_manager;</span></span></code></pre>Users model</a>
</h2>
The foundation and first sample functionality exposed by postgREST is the users themselves. The table schema behind it represents the employees and manages hierarchical relations, which will become important in the second part when we set up the approval workflow.</p>
CREATE TABLE</span> users</span> (</span></span>
    user_id </span>int GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY</span>,</span></span>
    email </span>text NOT NULL UNIQUE</span>,</span></span>
    manager_id </span>int REFERENCES</span> users(user_id),</span></span>
    created_at </span>timestamp with time zone DEFAULT</span> current_timestamp,</span></span>
    deleted_at </span>timestamp with time zone</span></span>
);</span></span></code></pre>
For testing purposes, let's populate the data using a seed of 3 managers (one being "the boss" and hence not having a manager) and 10 employees.</p>
DO $$</span></span>
DECLARE</span></span>
    v_boss_id </span>int</span>;</span></span>
    v_manager_id </span>int</span>;</span></span>
    i </span>int</span>;</span></span>
BEGIN</span></span>
    -- create "the boss"</span></span>
    INSERT INTO</span> users (email, manager_id)</span></span>
    VALUES</span> (</span>'owner@example.com'</span>, </span>NULL</span>)</span></span>
    RETURNING user_id </span>INTO</span> v_boss_id;</span></span>
 </span></span>
    -- setup 2 managers </span></span>
    FOR</span> i </span>IN</span> 1</span>..</span>2</span> LOOP</span></span>
        INSERT INTO</span> users (email, manager_id)</span></span>
        VALUES</span> (</span>'manager'</span> ||</span> i </span>||</span> '@example.com'</span>, v_boss_id)</span></span>
        RETURNING user_id </span>INTO</span> v_manager_id;</span></span>
</span>
        -- and 5 employees for each one of them</span></span>
        FOR</span> j </span>IN</span> 1</span>..</span>5</span> LOOP</span></span>
            INSERT INTO</span> users (email, manager_id)</span></span>
            VALUES</span> (</span>'employee'</span> ||</span> (</span>5</span> *</span> (i </span>-</span> 1</span>) </span>+</span> j) </span>||</span> '@example.com'</span>, v_manager_id);</span></span>
        END LOOP</span>;</span></span>
    END LOOP</span>;</span></span>
END</span> $$;</span></span></code></pre>
In case you are not aware, the seed data is produced by an anonymous block</a>. This way, we executed the logic to create the relationship required without the need to create (and later drop) the PL/pgSQL</em> function.</p>
Expose users using postgREST</a>
</h2>
Having the users table in place, together with sample data, we are ready to expose the data using the REST API. To start, you only need to create a very simple configuration for postgREST</strong> using the file postgrest.conf (you can place the file in the folder created for this sample project).</p>
Sample postgrest.conf</code>:</p>
db-uri = "postgres://username:password@localhost/time_off_manager"</span></span>
db-schema = "public"</span></span>
db-anon-role = "time_off_anonymous"</span></span></code></pre>
The most important part is the db-uri, which follows the standard PostgreSQL connection string format:</p>
postgres://username:password@host/database_name</span></span></code></pre>
You need to replace:</p>

username</code> - with your actual database username. Ideally, you will use a separate user (for example, time_off_manager) for each application, rather than your personal account.</li>
password</code> - the password for the user</li>
host</code> - either localhost (if running locally) or a remote server name or IP address</li>
database_name</code> - in this case, time_off_manager we created earlier.</li>
</ul>
NOTE: We are using hardcoded data (which can potentially get stored in your source code repository), and this is mainly for learning purposes. Any deployment resembling a production environment should follow best practices to reduce security risks.</em></p>
The other configuration options are db-schema</code>, which we will leave pointing to the public schema for this part, and db-anon-role</code>, configuring the role postgREST should use when executing requests on behalf of unauthenticated clients (effectively all requests in Part 1).</p>
For PostgreSQL 15 and higher, please make sure your username</code> is the owner of the database created (should you create it alternatively) in order to be able to create objects in public</code> schema.</p>
To set up the database role, you need to run the following commands:</p>
CREATE ROLE</span> time_off_anonymous NOLOGIN;</span></span>
GRANT SELECT</span>, </span>INSERT</span>, </span>UPDATE ON</span> users </span>TO</span> time_off_anonymous;</span></span>
GRANT</span> time_off_anonymous </span>TO</span> CURRENT_USER;</span></span></code></pre>
Please note you this example assumes CURRENT_USER</code> is same as the username used in the db-uri</code> configured above. The latter GRANT statement assigns the role time_off_anonymous to the configured user to execute the anonymous commands.</p>
Once you have the configuration file ready (assuming it's in the current directory), you can start the postgREST server and expose it locally on port 3000 (by default):</p>
$ postgrest postgrest.con</span></span>
10/May/2024:22:06:12 +0200: Starting PostgREST 12.0.3...</span></span>
10/May/2024:22:06:12 +0200: Attempting to connect to the database...</span></span>
10/May/2024:22:06:12 +0200: Connection successful</span></span>
10/May/2024:22:06:12 +0200: Listening on port 3000</span></span>
10/May/2024:22:06:12 +0200: Listening for notifications on the pgrst channel</span></span>
10/May/2024:22:06:12 +0200: Config reloaded</span></span>
10/May/2024:22:06:12 +0200: Schema cache loaded</span></span></code></pre>Exploring the Users Model Using cURL</a>
</h2>
When you have the server successfully running, you can try to access the data using:</p>
$</span> curl "http://localhost:3000/users"</span></span></code></pre>
and get the list of all the sample data we created above. The API for reading data is described in detail</a> in the documentation, but you can try different alternatives.</p>
# get one specific user</span></span>
$</span> curl http://localhost:3000/users?user_id=eq.10</span></span>
# query only active (i.e. non-deleted users)</span></span>
curl</span> "http://localhost:3000/users?deleted_at=is.null"</span></span>
# or display users without any manager (i.e. boss)</span></span>
curl</span> "http://localhost:3000/users?manager_id=is.null"</span></span></code></pre>
Similarly, you can create, update, and delete users as required—giving you full CRUD functionality with rich filtering options.</p>
Create user:</p>
$ curl -X POST "http://localhost:3000/users" \</span></span>
       -H "Content-Type: application/json" \</span></span>
       -d '{"email": "admin1@example.com", "manager_id": 1}'</span></span></code></pre>
Update user:</p>
$ curl -X PATCH "http://localhost:3000/users?user_id=eq.10" \</span></span>
       -H "Content-Type: application/json" \</span></span>
       -d '{"email": "updateduser@example.com"}'</span></span></code></pre>
or, delete one:</p>
$ curl -X DELETE "http://localhost:3000/users?user_id=eq.10"</span></span></code></pre>
I haven't mentioned CRUD by accident; that's the primary use-case of postgREST—exposing CRUD operations on the tables within the configured schema (public</code> in this part). You can delegate authorisation at the database level.</p>
Please note, the IDs are hardcoded, and you might need to check the output of the commands to get the correct ones (should you have truncated the table before or otherwise manipulated the data).</p>
Basic models for managing time off</a>
</h2>
With the User model set up and tested via the API, it's time to return to the core of the Time Off Manager functionality: absence tracking itself. For these purposes, we will define two tables—leave types (identifying the reason or type of the leave) and the time off transactions (or updates) themselves.</p>
CREATE TABLE</span> leave_types</span> (</span></span>
    leave_type_id </span>int GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY</span>,</span></span>
    label </span>text NOT NULL</span>,</span></span>
    description text</span>,</span></span>
    max_days </span>int</span>,</span></span>
    created_at </span>timestamp with time zone DEFAULT</span> current_timestamp,</span></span>
    deleted_at </span>timestamp with time zone</span></span>
);</span></span>
</span>
CREATE TABLE</span> time_off_transactions</span> (</span></span>
    transaction_id </span>int GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY</span>,</span></span>
    created_at </span>timestamp with time zone DEFAULT</span> current_timestamp,</span></span>
    user_id </span>int NOT NULL REFERENCES</span> users(user_id),</span></span>
    leave_type_id </span>int NOT NULL REFERENCES</span> leave_types(leave_type_id),</span></span>
    transaction_date </span>date</span>,</span></span>
    time_off_period daterange,</span></span>
    amount </span>int NOT NULL</span>,</span></span>
    description text</span></span>
);</span></span>
</span>
CREATE INDEX</span> transaction_for_user</span> ON</span> time_off_transactions(user_id);</span></span></code></pre>
The tables should be self-explanatory, but for clarity, let's delve into the detail of the transaction tracking. Time off is tracked for individual users, the time off transaction type to identify the reason for the change, the period during which the absence is recorded, and the amount of effective days (simplified logic to account for weekends, public holidays, and similar).</p>
To get started we also need to seed the data:</p>
INSERT INTO</span> leave_types (label, </span>description</span>, max_days) </span>VALUES</span> </span></span>
(</span>'vacation'</span>, </span>'Annual vacation leave'</span>, </span>25</span>),</span></span>
(</span>'sick-leave'</span>, </span>'Leave for health reasons'</span>, </span>10</span>),</span></span>
(</span>'unpaid-leave'</span>, </span>'Leave without pay'</span>, </span>NULL</span>),</span></span>
(</span>'sabbatical'</span>, </span>'Extended leave for study or travel'</span>, </span>NULL</span>);</span></span></code></pre>
and create the initial time off balances (this is a simplified version, assuming the employee always has the full balance, ignoring possible mid-year joiners, etc.):</p>
DO $$</span></span>
DECLARE</span></span>
    v_leave_type record;</span></span>
BEGIN</span></span>
    FOR</span> v_leave_type </span>IN SELECT * FROM</span> leave_types </span>WHERE</span> label </span>=</span> 'vacation'</span> LOOP</span></span>
        INSERT INTO</span> time_off_transactions (user_id, leave_type_id, transaction_date, amount, </span>description</span>)</span></span>
        SELECT</span> user_id, </span>v_leave_type</span>.</span>leave_type_id</span>, </span>'2024-01-01'</span>, </span>v_leave_type</span>.</span>max_days</span>, </span>'Initial balance for year 2024'</span></span>
        FROM</span> users;</span></span>
    END LOOP</span>;</span></span>
END</span> $$;</span></span>
</span></code></pre>
This now gives us the ability to start tracking the leave of absence for users and keep a full audit log of it.</p>
Before we can start using the table via the API, we need to complete the last important step: giving access to the configured db-anon-role for the tables. We can do this by assigning the grant to individual tables using:</p>
GRANT SELECT</span>, </span>INSERT</span>, </span>UPDATE ON</span> leave_types </span>TO</span> time_off_anonymous;</span></span>
GRANT SELECT</span>, </span>INSERT</span>, </span>UPDATE ON</span> time_off_transactions </span>TO</span> time_off_anonymous;</span></span></code></pre>
or modify the default privileges. Spoiler alert—we will move away from using the public schema in Part 2, so let's not do more than we need at the moment :)</p>
Working with absence</a>
</h2>
Similar to the users example, we can now track absence directly using the API. Before firing off cURL commands, there's one last thing to remember. postgREST</strong> requires metadata about the database schema itself, and it might be expensive to perform on the fly, hence to avoid this, the server caches the schema.</p>
To reload the schema (after making schema changes), it is required to reload the cache. This can be done via several basic options:</p>

restarting the server</li>
issuing a (SIGUSR1) signal to the server process</li>
</ul>
and more advanced ways</a> (outside Part 1 of this tutorial).</p>
Once reloaded, you can start exploring more:</p>
# getting a time off transaction for particular user</span></span>
$ curl "http://localhost:3000/time_off_transactions?user_id=eq.1"</span></span>
# submitting new leave of absence</span></span>
$ curl -X POST http://localhost:3000/time_off_transactions \</span></span>
       -H "Content-Type: application/json" \</span></span>
       -d '{"user_id": 5, "leave_type_id": 1, "transaction_date": "2024-02-26", "time_off_period": "[2024-02-28,2024-03-04]", "amount": -4, "description": "Vacation to avoid panic over leap year"}'</span></span></code></pre>
All these commands work as expected. Should you forget to reload the schema, you might face an HTTP Status 404 (Not Found) on the newly created objects.</p>
End of Part 1</a>
</h2>
While not being very sophisticated, I hope this first part has demonstrated the CRUD capabilities postgREST</strong> can offer with minimal effort. In the next part, we will move away from accessing the database tables directly and provide more functionality via a new schema api, providing a per-user time off balance view and introducing workflow management.</p>