Feature</th>	pg_cron</th>	pg_timetable</th></tr></thead>
Distribution</td>	PostgreSQL extension</td>	Standalone executable</td></tr>
Scheduling</td>	Limited (cron-like)</td>	Extensive (intervals, calendar, custom)</td></tr>
Job Types</td>	SQL</td>	SQL, Built-in, Shell</td></tr>
Job Chaining</td>	No</td>	Yes</td></tr>
Error Handling</td>	Basic</td>	Intermediate</td></tr>
Logging</td>	Basic</td>	Intermediate</td></tr>
Dependencies</td>	No</td>	Yes</td></tr>
Ease of Use</td>	Easy</td>	Moderate</td></tr>
Configuration</td>	Easy</td>	Moderate</td></tr>
Orchestration</td>	Single Cluster</td>	Advanced (multiple clusters)</td></tr> </tbody></table> When to Use pg_cron</code></a> </h3> If your requirements are straightforward, such as running maintenance tasks, refreshing materialised views, or generating periodic reports using simple SQL commands, pg_cron</code> is an excellent choice. Its cron-like syntax is familiar and easy to use</strong>.</li> pg_cron</code> is a PostgreSQL extension, making it easier to install</strong> and configure within your existing PostgreSQL environment. This makes it ideal for users who prefer minimal setup effort.</li> When your environment is limited to a single PostgreSQL cluster</strong>, pg_cron</code> is well-suited for the job. It does not support orchestration across multiple clusters, so it’s best used in environments where all operations are confined to one database cluster.</li> If Basic Error Handling and Logging</strong> is sufficient, pg_cron</code> provides the necessary functionalities without additional complexity.</li> </ol> When to Use pg_timetable</code></a> </h3> If you need more advanced scheduling capabilities</strong> and task depedencies and chaining</strong>, such as task chaining, complex intervals, and custom execution times, pg_timetable</code> is the better choice. It supports extensive scheduling options beyond the typical cron syntax.</li> pg_timetable</code> supports a variety of job types</strong>, including SQL commands, built-in tasks (like sending emails or downloading files), and shell commands. This makes it ideal for more complex automation needs that go beyond simple SQL execution.</li> If your environment spans multiple PostgreSQL clusters, pg_timetable</code> can handle advanced orchestration</strong>, allowing tasks to be executed across different clusters seamlessly.</li> Intermediate Error Handling and Logging</strong> provides better insights and control over job executions.</li> Although bit more complex to setup, pg_timetable</code> works as standalone Service</strong>, which makes it suitable for environments where extensions cannot be installed directly.</li> </ol> Choosing between pg_cron</code> and pg_timetable</code> depends on your specific needs. For simpler, single-cluster tasks, pg_cron</code> offers ease of use and straightforward setup. For more complex requirements involving advanced scheduling, task dependencies, and multi-cluster orchestration, pg_timetable</code> provides a more powerful and flexible solution.</p> By understanding the strengths and limitations of each tool, you can make an informed decision that best suits your database automation needs.</p> PS: there's also pgAgent</a>, but it was officially deprecated in June 2026, which leaves the two tools above as the clear options worth knowing.</p> PSS: article updated June 2026.</p> 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.</p> In Part 3, we will explore authentication and authorisation options to finish something that might resemble a real-world application.</p> 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.</p> 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.</p> Let's start with loading the extension and adding password column:</p> 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>

RegreSQL: Regression Testing for PostgreSQL Queries

2025-11-13T22:47:00+00:00

TL;DR - RegreSQL brings PostgreSQL's regression testing methodology to your application queries, catching both correctness bugs and performance regressions before production.

As puzzling as it might seem, the common problem with production changes is the ever-present "AHA" moment when things start slowing down or crashing straight away. Testing isn't easy as it is, but there's a widespread practice gap when it comes to testing SQL queries. Some might pretend to "fix it" by using ORMs to abstract away the problem. Others treat SQL as "just glue code" that doesn't deserve systematic testing. Most settle for integration tests that verify the application layer works, never actually testing whether their queries will survive the next schema change or index modification.

For PostgreSQL development itself, the project has a robust regression test suite that has been preventing disasters in core development for decades. The database itself knows how to test SQL systematically - we just don't use those same techniques for our own queries. Enter RegreSQL</a>, a tool originally created by Dimitri Fontaine for The Art of PostgreSQL</a> book (which is excellent for understanding and mastering PostgreSQL as a database system), designed to bring the same regression testing framework to our application queries.

I've been trying to use it for some time, but due to missing features and limitations gave up several times. Until now. I decided to fork the project and spend the time needed to take it to the next level.

Introduction</a> </h2>
The RegreSQL</a> promise starts with the biggest strength and perceived weakness of SQL queries. They are just strings. And unless you use something like sqlc</a> (for Go), PG'OCaml</a> or Rust's SQLx</a> toolkit giving you compile-time checking, your queries are validated only when they are executed. Which in better case mean either usually slow-ish test suite or integration tests, in worst scenario only when deployed. ORMs are another possibility - completely abstracting away SQL (but more on that later).
But even with compile-time checking, you are only checking for one class of problems: schema mismatches. What about behavior changes after schema migration or performance regressions? What about understanding whether your optimization actually made things faster or just moved the problem elsewhere?
This is where RegreSQL comes in. Rather than trying to turn SQL into something else, RegreSQL embraces "SQL as strings" reality and applies the same testing methodology PostgreSQL itself uses: regression testing. You write (or generate - continue reading) your SQL queries, provide input data, and RegreSQL verifies that future changes don't break those expectations.
The features don't stop there though - it tracks performance baselines, detects common query plan regressions (like sequential scans), and gives you framework for systematic experimentation with the schema changes and query change management.
Basic regression testing </a> </h2>
Enough with theory. Let's jump in straight into the action and see what a sample run of RegreSQL looks like
$ regresql text Connecting to 'postgres://radim:password123@192.168.139.28/cdstore_test'… ✓ Running regression tests... ✓ album-by-artist_list-albums-by-artist.1.json (0.00s) ✓ album-by-artist_list-albums-by-artist.2.json (0.00s) ✓ album-tracks_list-tracks-by-albumid.2.json (0.00s) ✓ album-tracks_list-tracks-by-albumid.1.json (0.00s) ✓ artist_top-artists-by-album.1.json (0.00s) ✓ genre-topn_genre-top-n.top-1.json (0.00s) ✓ genre-topn_genre-top-n.top-3.json (0.00s) ✓ genre-tracks_tracks-by-genre.json (0.00s) Results: 8 passed, 0 failed, 8 skipped (0.00s)</code></pre>
In this example based on Chinook database</a> (as used originally in The Art of PostgreSQL book), RegreSQL scans the current directory (or one provided by -C /path/to/project</code>) for *.sql</code> files and attempts to run all queries against the configured PostgreSQL connection.
The individual files can contain either single or multiple sql queries. Like following example
-- name: top-artists-by-album -- Get the list of the N artists with the most albums SELECT artist.name, count(*) AS albums FROM artist LEFT JOIN album USING (artist_id) GROUP BY artist.name ORDER BY albums DESC LIMIT :n;</code></pre> The syntax for the queries supports both positional arguments (like $1</code> known from libpq library) or (preferred) psql</code> style variable (:varname</code>). The each identified query (not file) is then executed for 0..N times, based on number of predefined plans and verified to the expected results - validating the expected data matches the one returned. The support for SQL files handling is available separately with https://github.com/boringSQL/queries (Go version only for now). This gives you what original RegreSQL tool has introduced - change your schema, refactor a query, run regresql test</code> and see immediately what broke. The test suite now has ability to catch regressions before they are committed / shipped. The current version built on top of it, giving you better console formatter instead of TAP style output, as well as jUnit, JSON and GitHub actions formatters for better integration into your CI/CD pipelines.
Performance regression testing</a> </h2> Basic regression testing catches correctness issues - wrong results, broken queries, schema mismatches. But there's another class of production issues it misses. Performance regressions. No matter how unbelievable it might sound but queries get deployed without appropriate indexes — which might then be ignored</a> entirely — or they change over time. Simple fix - both for handwritten SQL or ORM code - can switch from milliseconds to seconds. You add index that helps one query, but tanks another. You modify conditionals and accidently force a sequential scan of millions of rows</a>. This is where it hurts. RegreSQL addresses this by tracking performance baselines alongside correctness. Once baselines are generated $ regresql baseline Connecting to 'postgres://appuser:password123@192.168.139.28/cdstore_test'… ✓ Creating baselines directory: regresql/baselines Creating directory 'regresql/baselines' Creating baselines for queries: ./ Created baseline: album-by-artist_list-albums-by-artist.1.json Created baseline: album-by-artist_list-albums-by-artist.2.json Created baseline: album-tracks_list-tracks-by-albumid.1.json Created baseline: album-tracks_list-tracks-by-albumid.2.json Created baseline: artist_top-artists-by-album.1.json Created baseline: genre-topn_genre-top-n.top-1.json Created baseline: genre-topn_genre-top-n.top-3.json Created baseline: genre-tracks_tracks-by-genre.json Baselines have been created successfully! Baseline files are stored in: regresql/baselines</code></pre> the test command not only tests the regressions to the captured times, but also detects the common bad patterns in query execution plans</a>. For now it provides warnings for detection of sequential scans - both on their and/or with nested loops and multiple sort operations. I believe this alone might provide a valuable insights and reduce the mishaps in production. It's also a place where further development of RegreSQL will take place. To demonstrate this, let's review the test output with the baselines. Connecting to 'postgres://appuser:password123@192.168.139.28/cdstore_test'… ✓ Running regression tests... ✓ album-by-artist_list-albums-by-artist.1.json (0.00s) ✓ album-by-artist_list-albums-by-artist.2.json (0.00s) ✓ album-by-artist_list-albums-by-artist.1.cost (22.09 <= 22.09 * 110%) (0.00s) ⚠️ Sequential scan detected on table 'artist' Suggestion: Consider adding an index if this table is large or this query is frequently executed ⚠️ Nested loop join with sequential scan detected Suggestion: Add index on join column to avoid repeated sequential scans ✓ album-by-artist_list-albums-by-artist.2.cost (22.09 <= 22.09 * 110%) (0.00s) ⚠️ Sequential scan detected on table 'artist' Suggestion: Consider adding an index if this table is large or this query is frequently executed ⚠️ Nested loop join with sequential scan detected Suggestion: Add index on join column to avoid repeated sequential scans ✓ album-tracks_list-tracks-by-albumid.1.json (0.00s) ✓ album-tracks_list-tracks-by-albumid.2.json (0.00s) ✓ album-tracks_list-tracks-by-albumid.1.cost (8.23 <= 8.23 * 110%) (0.00s) ✓ album-tracks_list-tracks-by-albumid.2.cost (8.23 <= 8.23 * 110%) (0.00s) ✓ artist_top-artists-by-album.1.json (0.00s) ✓ artist_top-artists-by-album.1.cost (35.70 <= 35.70 * 110%) (0.00s) ⚠️ Multiple sequential scans detected on tables: album, artist Suggestion: Review query and consider adding indexes on filtered/joined columns ✓ genre-topn_genre-top-n.top-1.json (0.00s) ✓ genre-topn_genre-top-n.top-3.json (0.00s) ✓ genre-topn_genre-top-n.top-1.cost (6610.59 <= 6610.59 * 110%) (0.00s) ⚠️ Multiple sequential scans detected on tables: genre, artist Suggestion: Review query and consider adding indexes on filtered/joined columns ⚠️ Multiple sort operations detected (2 sorts) Suggestion: Consider composite indexes for ORDER BY clauses to avoid sorting ⚠️ Nested loop join with sequential scan detected Suggestion: Add index on join column to avoid repeated sequential scans ✓ genre-topn_genre-top-n.top-3.cost (6610.59 <= 6610.59 * 110%) (0.00s) ⚠️ Multiple sequential scans detected on tables: artist, genre Suggestion: Review query and consider adding indexes on filtered/joined columns ⚠️ Multiple sort operations detected (2 sorts) Suggestion: Consider composite indexes for ORDER BY clauses to avoid sorting ⚠️ Nested loop join with sequential scan detected Suggestion: Add index on join column to avoid repeated sequential scans ✓ genre-tracks_tracks-by-genre.json (0.00s) ✓ genre-tracks_tracks-by-genre.cost (37.99 <= 37.99 * 110%) (0.00s) ⚠️ Multiple sequential scans detected on tables: genre, track Suggestion: Review query and consider adding indexes on filtered/joined columns Results: 16 passed (0.00s)</code></pre> As you can see, despite from not having baseline, RegreSQL is able to detect the basic bad patterns that should be addressed before queries can be considered "production ready". In some cases, having the detection of sequential scans, or just tracking query costs baselines might be considered undesirable, which would lead to false positives. RegreSQL enables this to be addressed by query metadata as demonstrated below. -- name: query_name -- metadata: key1=value1, key2=value2 SELECT ...;</code></pre> At this point RegreSQL recognizes notest</code> to skip the query testing altogether (not just cost tracking)</li> nobaseline</code> to skip cost tracking</li> noseqscanwarn</code> to keep cost tracking but disable sequential scan warnings</li> and difffloattolerance</code> to cost failure threshold (default 10% at the moment).</li> </ul> -- name: query_name -- regresql: notest, nobaseline -- regresql: noseqscanwarn -- regresql: difffloattolerance:0.25 -- query that can vary in cost by 20% without being considered a failure SELECT ...;</code></pre>ORM enters the room</a> </h2> ORMs abstract away SQL, but they still generate it - much like view inlining</a> where the planner rewrites your SQL behind the scenes - and that generated SQL can have performance problems you won't catch until production. Consider this common scenario: you start with a simple SQLAlchemy query that works fine, then months later add eager loading for related data: orders = ( session.query(Order) .filter(Order.user_id == user_id) .options( joinedload(Order.user), joinedload(Order.shipping_address), selectinload(Order.items) # NEW: Load order items ) .all() )</code></pre> That innocent selectinload(Order.items)</code> generates a separate query - and without an index on order_items.order_id</code>, it performs a sequential scan. RegreSQL can catch this by intercepting ORM-generated SQL using SQLAlchemy's event system: @event.listens_for(engine, "before_cursor_execute") def capture_sql(conn, cursor, statement, *args): captured_queries.append(statement)</code></pre> Run your ORM code, capture the SQL, save it as a .sql file, and test it with RegreSQL. The performance baseline testing will flag the missing index before it hits production. This is currently experimental, but ORM integration is a key area for RegreSQL's future development. Test Data Management</a> </h2> Up until now we have covered how RegreSQL verifies query correctness and tracks performance regressions. But there's a critical prerequisite we've only skimmed through. Every regression test needs consistent, reproducible data. Change the data, change their cardinality, and your expected results become meaningless. Your performance baselines drift. Your tests become flaky. Traditional approach to create test data might involve Database dumps become unmanageable - 500MB files you can't review, can't understand, that break with every schema migration, and whose data becomes stale as production evolves. Which version of the dump are your tests even using?</li> SQL scripts might be better than dumps, but still imperative and hard to maintain. You end up with INSERT statements scattered across multiple files, managing foreign keys manually, and debugging constraint violations.</li> Factories in application code might work great for integration tests, but we're testing SQL directly. Do you really want to maintain parallel data generation in your application language just for SQL tests?</li> Shared test database is the synonym for classic "works on my machine" problem. State leaks between tests. Parallel execution becomes impossible. Debugging is a nightmare.</li> </ul> What we need is something that's declarative (what data, not how to insert it), reproducible (similar data every time), composable (build complex scenarios from simple pieces), and scalable (from 10 rows to 100,000). This is where next improvement in RegreSQL's fixture system comes in. Think of it as infrastructure-as-code for your test data. You describe the data you need in YAML files, and RegreSQL handles the rest - dependencies, cleanup, foreign keys, and even realistic data generation at scale. RegreSQL's fixture system lets you define test data in YAML files stored in regresql/fixtures/</code>. Here's a simple example fixture: basic_users description: a handful of test users cleanup: rollback data: - table: users rows: - id: 1 email: alice@example.com name: Alice Anderson created_at: 2024-01-15 - id: 2 email: bob@example.com name: Bob Builder created_at: 2024-02-20</code></pre> To use this fixture in your tests, reference it in the query's plan file (regresql/plans/get-user.yaml</code>) you can just reference the fixture fixtures: - basic_users "1": email: alice@example.com "2": email: bob@example.com</code></pre> And when you run regresql test</code>, the fixture is automatically loaded before the query executes, and cleaned up afterward. No manual setup scripts, no state leakage between tests. But it does not stop with static fixtures. When you want to test queries against realistic volumes you can use range of data generators including sequences, random integer, decimal, string, uuid, email and name generators</li> date_between for generating random timestamps within a range</li> foreign key references to be able to reuse data from other table's fixtures</li> range to select value from predefined sources</li> Go template support</li> </ul> fixture: realistic_orders generate: - table: customers count: 1000 columns: id: generator: sequence start: 1 email: generator: email domain: shop.example.com name: generator: name type: full created_at: generator: date_between start: "2023-01-01" end: "2024-12-31" - table: orders count: 5000 columns: id: generator: sequence start: 1 customer_id: generator: int min: 1 max: 1000 amount: generator: decimal min: 10.00 max: 999.99 precision: 2 order_date: generator: date_between start: "2023-01-01" end: "2024-12-31"</code></pre> This generates 1,000 customers and 5,000 orders with realistic-looking data - names, emails, dates, and amounts that feel production-like. The fixtures are also stackable and can be build on top of each other. For example if you need to make sure users fixtures are created before orders fixtures, just declare the dependency (the already planned improvement is to include the support automatic foreign-key detection to avoid ID hard-coding). RegreSQL loads fixtures in dependency order and handles cleanup in reverse. fixture: orders_with_shipping depends_on: - basic_users data: - table: orders rows: - id: 101 user_id: 1 # References Alice from basic_users total: 99.99 status: shipped</code></pre> Should the available options for fixtures (manual data or data generators) not be enough, you always have options to use good old SQL based data generation. fixture: mixed_setup description: Combine SQL with YAML and generated data cleanup: rollback # SQL executes first (either as file or inline) sql: - file: sql/setup_schema.sql - inline: "INSERT INTO config (key, value) VALUES ('version', '1.0');" # followed YAML data data: - table: users rows: - id: 1 email: admin@example.com # and finally generated data generate: - table: orders count: 100 columns: id: generator: sequence start: 1 user_id: generator: int min: 1 max: 1</code></pre> RegreSQL provides commands to inspect and validate your fixtures # List all available fixtures regresql fixtures list # Show fixture details and dependencies regresql fixtures show realistic_orders # Validate fixture definitions regresql fixtures validate # Show dependency graph regresql fixtures deps # Apply fixture manually (for debugging) regresql fixtures apply basic_users</code></pre> The fixture system has been design to transforms test data from a maintenance burden into a documented, version-controlled process. Your YAML files become the single source of truth for what data your tests need, making it easy to understand test scenarios and maintain test data as the application evolves. (EDIT 2025-11-20) The dynamically generated fixtures on each tests will break the correctness testing of RegreSQL. You have to use fixtures according to your use Fixed generated fixtures re-used between tests</li> Use RegreSQL to test fixtures before/after migration</li> </ul> I'm working on next release of RegreSQL to address DX of fixtures usage. RegreSQL future</a> </h2> Introducing a new open source project is an ambitious goal, and RegreSQL</a> is just starting up. Despite the fork being in works for almost 2 years. In coming weeks and months I plan further improvements, as well as better documentation and more tutorials. The project is maintained as part of my boringSQL brand, where it's vital component (together with pgTap) for building SQL Labs</a> which (as I sincerely hope) will provide a foundation for its further development. At the same time RegreSQL is an attempt to give back to welcoming PostgreSQL community, make developer user experience slightly better if possible and (just maybe) provide one more argument against the case that SQL queries are not testable. RegreSQL is available at boringsql.com/products/regresql</a> - feel free to open issue, or drop me email about the project at radim@boringsql.com</a> or connect on LinkedIn</a>.

The time keepers: pg_cron and pg_timetable

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

Working with PostgreSQL, and virtually any database system, extends far beyond merely inserting and retrieving data. Many application and business processes, maintenance tasks, reporting, and orchestration tasks require the integration of a job scheduler. While third-party tools can drive automation, you can also automate the execution of predefined tasks directly within the database environment. Although system-level cron might be a starting point, the power of the database system lies in its ability to store all the necessary information alongside your data/schema. In this article, we will explore pg_cron</code> and pg_timetable</code> as two distinct PostgreSQL-specific tools for scheduled task automation.

The Many Roles of Job Scheduling

</a>
</h2>
Usually, the first requirement to automate job execution is the optimisation of the PostgreSQL cluster and databases. Except in very low usage scenarios, routine maintenance</strong> is the foundation of all database deployments. Whether it is VACUUMing, index rebuilding, or updating statistics, these are tasks that you will eventually need to automate to maintain operational efficiency.</p>
Job scheduling is also indispensable for maintaining data quality</strong>, particularly through operations like refreshing materialised views or batch removal of outdated data from the system. From there, it is just a step to reporting</strong>, which can involve the automation of generating operational and business reports.</p>
I also believe that databases are an excellent place to coordinate business processes</strong>. Automating data flows between components, teams, and departments helps create agile systems. As mentioned above, there is no better place to store the description of such automations than alongside your data.</p>
pg_cron: Automation's First Gear</a>
</h2>
Traditionally, the role of automation started with operating system tools like cron or Task Scheduler. That's where pg_cron</code></a> comes in. It's a PostgreSQL extension that provides the simplicity and familiarity of cron's scheduling directly within the database environment.</p>
Due to its dependency on a shared library (because of the use of the background worker), it requires a full cluster restart. Nevertheless, due to its popularity, it is available within most managed cloud environments.</p>
# requires </span>configuration update in</span> postgresql</span>.</span>conf</span> (</span>or</span> conf</span>.</span>d</span>)</span></span>
shared_preload_libraries </span>=</span> 'pg_cron'</span></span>
</span>
#</span> add</span> extension </span>as</span> superuser</span></span>
CREATE</span> EXTENSION pg_cron;</span></span></code></pre>
As long as you are familiar with cron-like syntax, you can get started immediately by using commands like:</p>
SELECT</span> cron</span>.</span>schedule</span>(</span>'30 3 * * 6'</span>, $$</span>DELETE FROM</span> events </span>WHERE</span> event_time </span>< now</span>()</span> -</span> interval </span>'1 week'</span>$$);</span></span></code></pre>
By default, pg_cron</code> exposes its functionality in the postgres</code> database (configurable), where it expects its metadata tables. Personally, I consider this a drawback, as it makes it less obvious to the casual DBA who might not be aware of the scheduling logic present.</p>
In the same database, you can perform basic monitoring, for example, getting details of running and recently completed jobs:</p>
SELECT * FROM</span> cron</span>.</span>job_run_details</span> ORDER BY</span> start_time </span>DESC LIMIT</span> 5</span>;</span></span></code></pre>
There is no direct support to talk to other PostgreSQL clusters (you would have to facilitate this, for example, using Foreign Data Wrappers).</p>
While cron-like syntax is beneficial for adoption, it is where pg_cron</code> falls short, as it does not support advanced cases like task chaining, dependencies, and triggers.</p>
Full Speed with pg_timetable</a>
</h2>
If pg_cron</code> offers automation in first gear, pg_timetable</code> is where you can go full speed ahead. It not only provides cron-like syntax but elevates it to a whole new level with task chaining, parameter support, multiple execution clients, enhanced scheduling, and much more.</p>
The first difference you might notice is in its distribution. Timetable is not a PostgreSQL extension but a standalone binary (or available as a Docker image) that you have to configure and run. This immediately raises the bar in terms of the infrastructure it requires. On the other hand, not being distributed as an extension makes it compatible with all managed services by default (if you can get the process up and running).</p>
While the basic syntax might be similar to pg_cron</code>:</p>
SELECT</span> timetable</span>.</span>add_job</span>(</span>'execute-func'</span>, </span>'5 0 * 8 *'</span>, </span>'SELECT public.my_func()'</span>);</span></span></code></pre>
this is not anywhere near the limits of pg_timetable</code>. add_job</code> is a helper function that creates a simple one-task chain. For task execution, it directly supports more options, including built-in tasks (like sending emails if properly configured, downloading files, sleeping, copying files, etc.), external commands, the ability to choose which client should execute the job, concurrency, and more.</p>
In its full definition, add_job</code> is quite powerful (see documentation</a> for details):</p>
SELECT</span> timetable</span>.</span>add_job</span>(</span></span>
    job_name            </span>=></span> 'notify every minute'</span>,</span></span>
    job_schedule        </span>=></span> '* * * * *'</span>,</span></span>
    job_command         </span>=></span> 'SELECT pg_notify($1, $2)'</span>,</span></span>
    job_parameters      </span>=></span> '["TT_CHANNEL", "Hello World!"]'</span>::jsonb,</span></span>
    job_kind            </span>=></span> 'SQL'</span>::</span>timetable</span>.</span>command_kind</span>,</span></span>
    job_client_name     </span>=> NULL</span>,</span></span>
    job_max_instances   </span>=></span> 1</span>,</span></span>
    job_live            </span>=></span> TRUE,</span></span>
    job_self_destruct   </span>=></span> FALSE,</span></span>
    job_ignore_errors   </span>=></span> TRUE</span></span>
) </span>AS</span> chain_id;</span></span></code></pre>
The components of pg_timetable</code> consist of the command</strong> (SQL/program or built-in), task</strong> controlling the configuration for the command execution (error handling, timeout, or database connection to use), and chain</strong> which can contain a number of tasks chained together.</p>
The big difference comes in the scheduling options. While pg_cron</code> is limited (as its name suggests) to cron-like syntax, pg_timetable</code> uses it for simple use cases but offers much more. It supports schedules @every</code> and @after</code>, allowing repeated execution and breaking away from the limitations of cron notation as it can go down to custom intervals (including second intervals). Another case is @reboot</code> for instances when the pg_timetable</code> controller reconnects to the database.</p>
The timetable setup manages own schema migrations and stores all the configuration in schema timetable</code> (by default), where you can find the definitions of chains/tasks and relevant auditing information (logs).</p>
And yes, if you have been paying attention, pg_timetable</code> architecture allows for running tasks across multiple PostgreSQL clusters, making it an advanced orchestration tool. The database connection, which can be configured in-place or via a drop-in connection service file</a>, can be set on a per-task basis.</p>
With chains, the setup can be much more complex:</p>
DO $$</span></span>
DECLARE</span></span>
  v_chain_id </span>BIGINT</span>;</span></span>
  v_notify_task_id </span>BIGINT</span>;</span></span>
BEGIN</span></span>
    INSERT INTO</span> timetable</span>.</span>chain</span> (</span></span>
        chain_name,</span></span>
        run_at,</span></span>
        max_instances,</span></span>
        live)</span></span>
    VALUES</span> (</span></span>
        'Generate Weekly Report'</span>,</span></span>
        '5 4 * * 1'</span>,</span></span>
        1</span>,</span></span>
        TRUE</span></span>
    )</span></span>
    RETURNING chain_id </span>INTO</span> v_chain_id;</span></span>
</span>
    INSERT INTO</span> timetable</span>.</span>task</span> (</span></span>
        chain_id,</span></span>
        task_order,</span></span>
        task_name,</span></span>
        command,</span></span>
        database_connection</span></span>
    )</span></span>
    VALUES</span> (</span></span>
        v_chain_id,</span></span>
        1</span>,                                    </span>-- task_order</span></span>
        'generate_report'</span>,                    </span>-- task_name</span></span>
        'SELECT generate_weekly_report();'</span>,   </span>-- command</span></span>
        NULL</span>                                  -- database_connection</span></span>
    );</span></span>
</span>
    INSERT INTO</span> timetable</span>.</span>task</span> (</span></span>
        chain_id,</span></span>
        task_order,</span></span>
        task_name,</span></span>
        command,</span></span>
        database_connection</span></span>
    )</span></span>
    VALUES</span> (</span></span>
        v_chain_id,</span></span>
        2</span>,                                   </span>-- task_order (second task in the chain)</span></span>
        'notify_management'</span>,                 </span>-- task_name</span></span>
        'SELECT pg_notify($1, $2)'</span>,          </span>-- command</span></span>
        'service=service_db'</span>                 -- database_connection</span></span>
    )</span></span>
    RETURNING task_id </span>INTO</span> v_notify_task_id;</span></span>
</span>
    INSERT INTO</span> timetable</span>.</span>task_parameter</span> (task_id, order_id, </span>value</span>)</span></span>
    VALUES</span></span>
        (v_notify_task_id, </span>1</span>, </span>'management_notifications'</span>),</span></span>
        (v_notify_task_id, </span>2</span>, </span>'Weekly report'</span>);</span></span>
END</span>;</span></span>
$$ </span>LANGUAGE</span> plpgsql;</span></span></code></pre>
Since v6.0, chains can also be defined in YAML — a cleaner alternative to the SQL inserts above, especially for version-controlled configurations:</p>
chain</span>:</span></span>
  name</span>:</span> Generate Weekly Report</span></span>
  run_at</span>:</span> "5 4 * * 1"</span></span>
  max_instances</span>:</span> 1</span></span>
  live</span>:</span> true</span></span>
  tasks</span>:</span></span>
    -</span> name</span>:</span> generate_report</span></span>
      command</span>:</span> SELECT generate_weekly_report();</span></span>
    -</span> name</span>:</span> notify_management</span></span>
      command</span>:</span> SELECT pg_notify($1, $2)</span></span>
      database_connection</span>:</span> service=service_db</span></span>
      parameters</span>:</span></span>
        -</span> management_notifications</span></span>
        -</span> Weekly report</span></span></code></pre>The Comparison</a>
</h2>
When deciding between pg_cron</code> and pg_timetable</code>, it's essential to consider the specific needs of your use case, as both tools target different scenarios and scales of deployment. Here’s a comparison to help you decide which tool is more suitable for your requirements:</p>
Feature</th> pg_cron</th> pg_timetable</th></tr></thead>

Distribution</td> PostgreSQL extension</td> Standalone executable</td></tr>
Scheduling</td> Limited (cron-like)</td> Extensive (intervals, calendar, custom)</td></tr>
Job Types</td> SQL</td> SQL, Built-in, Shell</td></tr>
Job Chaining</td> No</td> Yes</td></tr>
Error Handling</td> Basic</td> Intermediate</td></tr>
Logging</td> Basic</td> Intermediate</td></tr>
Dependencies</td> No</td> Yes</td></tr>
Ease of Use</td> Easy</td> Moderate</td></tr>
Configuration</td> Easy</td> Moderate</td></tr>
Orchestration</td> Single Cluster</td> Advanced (multiple clusters)</td></tr>
</tbody></table>
When to Use pg_cron</code></a>
</h3>

If your requirements are straightforward, such as running maintenance tasks, refreshing materialised views, or generating periodic reports using simple SQL commands, pg_cron</code> is an excellent choice. Its cron-like syntax is familiar and easy to use</strong>.</li>
pg_cron</code> is a PostgreSQL extension, making it easier to install</strong> and configure within your existing PostgreSQL environment. This makes it ideal for users who prefer minimal setup effort.</li>
When your environment is limited to a single PostgreSQL cluster</strong>, pg_cron</code> is well-suited for the job. It does not support orchestration across multiple clusters, so it’s best used in environments where all operations are confined to one database cluster.</li>
If Basic Error Handling and Logging</strong> is sufficient, pg_cron</code> provides the necessary functionalities without additional complexity.</li>
</ol>
When to Use pg_timetable</code></a>
</h3>

If you need more advanced scheduling capabilities</strong> and task depedencies and chaining</strong>, such as task chaining, complex intervals, and custom execution times, pg_timetable</code> is the better choice. It supports extensive scheduling options beyond the typical cron syntax.</li>
pg_timetable</code> supports a variety of job types</strong>, including SQL commands, built-in tasks (like sending emails or downloading files), and shell commands. This makes it ideal for more complex automation needs that go beyond simple SQL execution.</li>
If your environment spans multiple PostgreSQL clusters, pg_timetable</code> can handle advanced orchestration</strong>, allowing tasks to be executed across different clusters seamlessly.</li>
Intermediate Error Handling and Logging</strong> provides better insights and control over job executions.</li>
Although bit more complex to setup, pg_timetable</code> works as standalone Service</strong>, which makes it suitable for environments where extensions cannot be installed directly.</li>
</ol>
Choosing between pg_cron</code> and pg_timetable</code> depends on your specific needs. For simpler, single-cluster tasks, pg_cron</code> offers ease of use and straightforward setup. For more complex requirements involving advanced scheduling, task dependencies, and multi-cluster orchestration, pg_timetable</code> provides a more powerful and flexible solution.</p>
By understanding the strengths and limitations of each tool, you can make an informed decision that best suits your database automation needs.</p>
PS: there's also pgAgent</a>, but it was officially deprecated in June 2026, which leaves the two tools above as the clear options worth knowing.</p>
PSS: article updated June 2026.</p>


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.</p>
In Part 3, we will explore authentication and authorisation options to finish something that might resemble a real-world application.</p>
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.</p>
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.</p>
Let's start with loading the extension and adding password column:</p>
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>

Getting started </a> </h2>
dryrun is MIT licensed and available on GitHub</a>. The tutorial</a> covers installation, offline and online workflows, multi-node setups, and MCP integration. It's part of the boringSQL</a> suite.</p>

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

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

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

boringSQL | Supercharge your SQL & PostgreSQL powers - tools

The tests passed. The plan didn't.

Don't let AI touch your production database

RegreSQL: Regression Testing for PostgreSQL Queries

The time keepers: pg_cron and pg_timetable