-
Notifications
You must be signed in to change notification settings - Fork 57
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[Documentation:Developer] Add Trigger Function Documentation (#551)
### What does this PR do? There is now documentation on how to create trigger functions and edit existing functions. ### Images ![image](https://github.com/Submitty/submitty.github.io/assets/51209504/509d89f4-6606-42b1-89fd-611fab9100ad)
- Loading branch information
1 parent
68bb819
commit a86c021
Showing
2 changed files
with
91 additions
and
1 deletion.
There are no files selected for viewing
88 changes: 88 additions & 0 deletions
88
_docs/developer/development_instructions/trigger_functions.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,88 @@ | ||
--- | ||
title: Trigger Functions | ||
category: Developer > Development Instructions | ||
--- | ||
|
||
Trigger functions are a useful tool to keep data in sync. When a | ||
database table's column is modified, a trigger function can be | ||
set up to activate and modify the database as appropiate. | ||
|
||
We use PL/pgSQL for our trigger functions, which is a procedural | ||
programming language part of PostgreSQL, the language our database | ||
queries are conducted in. | ||
|
||
### Editing an Existing Trigger Function | ||
To edit an existing trigger function, simply edit the appropiate file inside the | ||
``migrations/migrator/triggers`` directory. When you next run ``submitty_install`` | ||
or the migrator manually, the trigger functions on the database will be updated | ||
with the changes to the code. | ||
|
||
### Creating New Trigger Functions | ||
To create a new trigger function, | ||
|
||
1. First, navigate to the ``migrations/migrator/triggers`` directory. Then choose | ||
between the ``master`` and ``course`` folder. Choose the ``master`` folder if | ||
your trigger function is activated by changes to the master database, and similarly, | ||
choose the ``course`` if your trigger function is activated by changes to the course | ||
database. | ||
|
||
2. Create your file ``trigger_function_name.sql`` with these contents: | ||
|
||
``` | ||
-- | ||
-- Name: trigger_function_name(); Type: FUNCTION; Schema: public; Owner: - | ||
-- | ||
CREATE OR REPLACE FUNCTION public.trigger_function_name() RETURNS trigger | ||
LANGUAGE plpgsql | ||
AS $$ | ||
BEGIN | ||
(Body) | ||
END; | ||
$$; | ||
``` | ||
Replace the body with the trigger function. We recommend | ||
[this tutorial series](https://www.postgresqltutorial.com/postgresql-triggers/introduction-postgresql-trigger/) | ||
on how to write them. Check other trigger functions we have for an idea | ||
on the syntax. One of the most important ideas to note is that OLD.column represents | ||
the column's date before the edit and NEW.column represents the column's data after the | ||
edit. | ||
3. Create a migration (see [here](/developer/development_instructions/migrations) | ||
on how to write a migration). Somewhere in the migration, include the following: | ||
``` | ||
CREATE OR REPLACE FUNCTION public.trigger_function_name() | ||
RETURNS trigger | ||
LANGUAGE plpgsql | ||
AS $$ | ||
BEGIN | ||
RETURN NEW; | ||
END; | ||
$$; | ||
CREATE TRIGGER some_name_about_your_trigger_function | ||
BEFORE/AFTER UPDATE/INSERT/DELETE ON public.the_table_your_function_is_activated_by | ||
FOR EACH ROW EXECUTE PROCEDURE public.trigger_function_name(); | ||
``` | ||
There's a few things to break down here. Your trigger function can be actived before or after | ||
a table has a deletion, an insertion, or a value update on it. Pick either ``BEFORE`` or ``AFTER``. Pick either ``UPDATE``, ``INSERT``, or ``DELETE``. If you want your function to be activated on, say, an update or an insertion, write instead | ||
``UPDATE OR INSERT`` in the spot above. | ||
Declaring the trigger function above is neccessary so that we can then | ||
bind the trigger function to the appropiate action on the table. You do not need | ||
the body to be blank, but we recommend it to be to avoid code duplication. | ||
The blank body will be replaced by the migrator with the completed body in | ||
your other file, so do not worry. | ||
It can be strategic to choose when in your migration you include the code above, | ||
as you may want your trigger function binded only after a table is created. | ||
4. Make sure you include in the down migration section the deletion of the trigger function. | ||
``` | ||
DROP TRIGGER IF EXISTS | ||
the_same_name_about_your_trigger_function | ||
ON public.the_table_your_function_is_activated_by; | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters