Fix #22 - Added Transaction Control category with rules G-3210 and G-3220

Author: kibeha

docs/4-language-usage/3-dml-and-sql/3-transaction-control/.pages

@@ -0,0 +1 @@
+title: Transaction Control

docs/4-language-usage/3-dml-and-sql/3-transaction-control/g-3210.md

@@ -0,0 +1,66 @@
+# G-3210: Never commit within a cursor loop.
+
+!!! danger "Critical"
+    Efficiency, Reliability
+
+## Reason
+
+Doing frequent commits within a cursor loop (all types of loops over cursors, whether implicit cursor for loop or loop with explicit fetch from cursor or cursor variable) risks not being able to complete due to ORA-01555, gives bad performance, and risks that the work is left in an unknown half-finished state and cannot be restarted.
+
+* If the work belongs together (an atomic transaction) the commit should be moved to after the loop. Or even better if the logic can be rewritten to a single DML statement on all relevant rows instead of a loop, committing after the single statement.
+* If each loop iteration is a self-contained atomic transaction, consider instead to populate a collection of "transactions" to be done (taking restartability into account by collection population), loop over that collection (instead of looping over a cursor) and call a procedure (that contains the transaction logic and the commit) in the loop (see also G-3220).
+
+
+## Example (bad)
+
+``` sql
+declare
+   l_counter   integer := 0;
+   l_discount  discount.percentage%type;
+begin
+   for r_order in (
+      select o.order_id, o.customer_id
+        from orders o
+       where o.order_status = 'New'
+   ) loop
+      l_discount := sales_api.calculate_discount(p_customer_id => r_order.customer_id);
+      
+      update order_lines ol
+         set ol.discount = l_discount
+       where ol.order_id = r_order.order_id;
+      
+      l_counter := l_counter + 1;
+      if l_counter = 100 then
+         commit;
+         l_counter := 0;
+      end if;
+   end loop;
+   if l_counter > 0 then
+      commit;
+   end if;
+end;
+/
+```
+
+## Example (good)
+
+``` sql
+declare
+   l_discount  discount.percentage%type;
+begin
+   for r_order in (
+      select o.order_id, o.customer_id
+        from orders o
+       where o.order_status = 'New'
+   ) loop
+      l_discount := sales_api.calculate_discount(p_customer_id => r_order.customer_id);
+      
+      update order_lines ol
+         set ol.discount = l_discount
+       where ol.order_id = r_order.order_id;
+   end loop;
+
+   commit;
+end;
+/
+```

docs/4-language-usage/3-dml-and-sql/3-transaction-control/g-3220.md

@@ -0,0 +1,51 @@
+# G-3220: Try to move transactions within a non-cursor loop into procedures.
+
+!!! warning "Major"
+    Maintainability, Reusability, Testability
+
+## Reason
+
+Commit inside a non-cursor loop (other loop types than loops over cursors - see also G-3210) is either a self-contained atomic transaction, or it is a chunk (with suitable restartability handling) of very large data manipulations. In either case encapsulating the transaction in a procedure is good modularity, enabling reuse and testing of a single call.
+
+## Example (bad)
+
+``` sql
+begin
+   for l_counter in 1..5 loop
+      insert into headers (id, text) values (l_counter, 'Number '||l_counter);
+      
+      insert into lines (header_id, line_no, text)
+      select l_counter, rownum, 'Line '||rownum
+        from dual
+      connect by level <= 3;
+      
+      commit;
+   end loop;
+end;
+/
+```
+
+## Example (good)
+
+``` sql
+declare
+   procedure create_rows (
+      p_header_id    in    headers.id%type
+   ) is
+   begin
+      insert into headers (id, text) values (p_header_id, 'Number '||p_header_id);
+      
+      insert into lines (header_id, line_no, text)
+      select p_header_id, rownum, 'Line '||rownum
+        from dual
+      connect by level <= 3;
+      
+      commit;
+   end;
+begin
+   for l_counter in 1..5 loop
+      create_rows(l_counter);
+   end loop;
+end;
+/
+```

docs/stylesheets/extra.css

@@ -89,6 +89,7 @@
     [id="large-objects"],
     [id="dml-sql"], 
     [id="bulk-operations"], 
+    [id="transaction-control"], 
     [id="control-structures"], 
     [id="case-if-decode-nvl-nvl2-coalesce"], 
     [id="flow-control"],