git.iko.soy/project-m36
on master help sign in
add documentation for transaction operators
06370c3AgentM
docs/index.markdown+1
compare with master
unifiedsplit
@@ -2,5 +2,6 @@
21. [Introduction to the Relational Algebra](introduction_to_the_relational_algebra.markdown)
21. [Introduction to the Relational Algebra](introduction_to_the_relational_algebra.markdown)
31. [Introduction to ProjectM36](introduction_to_projectm36.markdown)
31. [Introduction to ProjectM36](introduction_to_projectm36.markdown)
41. [TutorialD Tutorial](tutd_tutorial.markdown)
41. [TutorialD Tutorial](tutd_tutorial.markdown)
5+1. [Tranaction Graph Operators](transaction_graph_operators.markdown)
51. [Persistent Library Driver](persistent_library_driver.markdown)
61. [Persistent Library Driver](persistent_library_driver.markdown)
61. [ProjectM36.Client Library](projectm36_client_library.markdown)
71. [ProjectM36.Client Library](projectm36_client_library.markdown)
docs/transaction_graph_operators.markdown+70−2
@@ -34,7 +34,7 @@ Note that this transaction graph approach is different from that of most SQL DBM
34
34
35#### Commit
35#### Commit
36
36
37−To convert a mutable database context into a transaction, it must be "committed" to the transaction graph.
37+To convert a mutable database context into a transaction, it must be "committed" to the transaction graph. The equivalent in SQL is COMMIT.
38
38
39```
39```
40TutorialD (master): :commit
40TutorialD (master): :commit
@@ -44,4 +44,72 @@ Once committed, the transaction's database context becomes immutable. Internally
44
44
45#### Rollback
45#### Rollback
46
46
47−Sometimes, the user determines that the changes in the mutable database context can be discarded and the context reset to be a copy of its parent's transaction. This is called a "rollback" because it rolls back to a previous known state.
47+Sometimes, the user determines that the changes in the mutable database context can be discarded and the context reset to be a copy of its parent's transaction. This is called a "rollback" because it rolls back to a previous known state. The equivalent in SQL is ROLLBACK.
48+
49+```
50+TutorialD (master): :rollback
51+```
52+
53+#### Show Transaction Graph
54+
55+In order to navigate the transaction graph, one must specify transaction UUIDs. Viewing the entirety of the transaction graph as a relation is a single command.
56+
57+```
58+TutorialD (master): :showgraph
59+┌───────┬──────┬────────────────────────────────────┬───────┐
60+│current│head │id │parents│
61+├───────┼──────┼────────────────────────────────────┼───────┤
62+<big result elided>
63+```
64+The "current" attribute is a boolean value. If true, the transaction is the parent of the current database context. Commits will be children of this transaction.
65+
66+The "head attribute is a boolean value indicating whether or not the transaction is a "head" node of its graph. Head nodes are nodes which have no children.
67+
68+The "id" attribute is the UUID needed in order to navigate the graph.
69+
70+The "parents" attribute is a subrelation holding all parent transaction UUIDs for the given transaction.
71+
72+
73+#### Branch
74+
75+A new branch can be create from any point in the transaction. A branch associates a human-readable name with a set of transactions diverging from a parent transaction. After a branch, there are two heads to which one could commit.
76+
77+```
78+TutorialD (master): :branch testing_data_2005
79+TutorialD (testing_data_2005):
80+```
81+
82+Note how the prompt refers to the new branch. This indicates that further commits from the mutable database context will now be added to the new branch.
83+
84+#### Jump to Head
85+
86+To switch the current mutable database context to refer to a different branch, jump to a different head. Committing to a head ensure that the branch growth continues linearly.
87+
88+Note that jumping to another head implies losing any changes in the current database context.
89+
90+```
91+TutorialD (testing_data_2005): :jumphead master
92+TutorialD (master):
93+```
94+
95+Further commits will be added to the target branch.
96+
97+#### Jump to Transaction
98+
99+Instead of jumping to the head of a branch for the purpose of adding more commits, it can be also useful to jump to a specific transaction in the past for two possible reasons:
100+
101+* to examine the state of the database in the past; for example, for auditing purposes
102+* to branch the database from a point in the past
103+
104+If one jumps to a non-head transaction, committing new transactions are no longer possible because the past transactions cannot be overwritten.
105+
106+```
107+TutorialD (master): :jump 11b601c9-f46b-42b0-a2ce-cf18ced31b7f
108+TutorialD (11b601c9-f46b-42b0-a2ce-cf18ced31b7f):
109+```
110+
111+Note that the ```tutd``` prompt now indicates that the mutable database context now refers to a specific transaction by UUID.
112+
113+
114+
115+