Fix #120 - Added new rule G-7910: Never use DML within a SQL macro.

Author: kibeha

docs/4-language-usage/7-stored-objects/9-sql-macros/.pages

@@ -0,0 +1 @@
+title: SQL Macros

docs/4-language-usage/7-stored-objects/9-sql-macros/g-7910.md

@@ -0,0 +1,44 @@
+# G-7910: Never use DML within a SQL macro.
+
+!!! danger "Critical"
+    Reliability, Testability
+
+## Restriction
+
+Oracle Database 21c (19c from version 19.7 for table macros alone)
+
+## Reason
+
+Doing DML (except for `select`) within a SQL macro can lead to disastrous side effects from calling the macro in a SQL query.
+
+Logging macro calls via a call to a procedure that does DML in an autonomous transaction can be an exception to the rule.
+
+## Example (bad)
+
+``` sql
+create or replace function row_generator (
+   num_rows_in in number(32,0)
+)
+   return varchar2 sql_macro as
+begin
+   insert into function_calls(name, called_at, parameter_value)
+      values ($$PLSQL_UNIT, current_timestamp, num_rows_in);
+   commit;
+   
+   return 'select level as row_sequence from dual connect by level <= num_rows_in';
+end row_generator;
+/
+```
+
+## Example (good)
+
+``` sql
+create or replace function row_generator (
+   num_rows_in in number(32,0)
+)
+   return varchar2 sql_macro as
+begin
+   return 'select level as row_sequence from dual connect by level <= num_rows_in';
+end row_generator;
+/
+```

docs/9-appendix/appendix.md

@@ -124,6 +124,7 @@ n/a | 7720 | Never use multiple UPDATE OF in trigger event clause. | Blocker |
 n/a | 7730 | Avoid multiple DML events per trigger. | Minor |  |  | ✘ |  |  |  |  | ✘
 n/a | 7740 | Never handle multiple DML events per trigger if primary key is assigned in trigger. | Major |  | ✘ |  |  | ✘ |  |  | 
 n/a | 7810 | Never use SQL inside PL/SQL to read sequence numbers (or SYSDATE). | Major |  | ✘ | ✘ |  |  |  |  | 
+n/a | 7910 | Never use DML within a SQL macro. | Critical |  |  |  |  | ✘ |  |  | ✘
 78 | 8110 | Never use SELECT COUNT(*) if you are only interested in the existence of a row. | Major |  | ✘ |  |  |  |  |  | 
 n/a | 8120 | Never check existence of a row to decide whether to create it or not. | Major |  | ✘ |  |  | ✘ |  |  | 
 79 | 8210 | Always use synonyms when accessing objects of another application schema. | Major | ✘ |  | ✘ |  |  |  |  | 

docs/stylesheets/extra.css

@@ -222,6 +222,7 @@
     [id="object-types"],
     [id="triggers"],
     [id="sequences"],
+    [id="sql-macros"],
     [id="patterns"],
     [id="access-objects-of-foreign-application-schemas"], 
     [id="validating-input-parameter-size"],

tools/run-in-container/genpdf.sh

@@ -156,6 +156,8 @@ write_text "### Triggers"
 write_guidelines "4-language-usage/7-stored-objects/7-triggers" "####"
 write_text "### Sequences"
 write_guidelines "4-language-usage/7-stored-objects/8-sequences" "####"
+write_text "### SQL Macros"
+write_guidelines "4-language-usage/7-stored-objects/9-sql-macros" "####"
 write_text "## Patterns"
 write_text "### Checking the Number of Rows"
 write_guidelines "4-language-usage/8-patterns/1-checking-the-number-of-rows" "####"