git.iko.soy/project-m36
on 62_python_dbapi help sign in
project-m36/docs/transaction_graph_operators.markdown
111 lines 6.7 kB history raw
1## Transaction Graph Operators
3Relational operators generate new relations and database context operators alter the relations referenced by relation variables. Finally, transaction operators alter the state of the database's transaction graph. This includes adding new transactions, branching, and changing the current database context to point at an arbitrary transaction in the past (time-travel).
5#### The Database Context
7Every database operation occurs within a database context. The database context is the state of the relation variables, constraints, and user-definable functions. While past transactions committed to the transaction graph are immutable, new transactions can be created from database contexts based on any transaction in the transaction graph.
9When a new database is created, a new transaction graph is created for it with one base transaction. The base transaction is special because it is the only transaction in the graph without a parent. At this point, the editable database context necessarily references the singular transaction. It can be considered a mutable copy of the database context stored by the first transaction.
11As the user interactively alters the database context such as by adding a new relation variable, the database context is no longer equal to that of the first transactions. This is called "database context divergence" because many of the same components exist in both the updated context and the context of the first transaction.
13![Initial database starting state](http://g.gravizo.com/g?
14digraph G {
15 base[label="base transaction",shape=rectangle];
16 new[label="mutable database context"];
17 new -> base;
18})
20Once the user decides that the changes in the updated database context are worth adding to the transaction graph, the user issues a "commit" request. The commit operation converts the current database context into a new transaction which is then added to the graph with the parent transaction set to the same parent transaction as the database context. The user's mutable database context is shifted to be a copy of the context of the newly-committed transaction.
22![Freshly committed transaction](http://g.gravizo.com/g?
23digraph G {
24 base[label="base transaction",shape=rectangle];
25 discon[label="mutable database context"];
26 fresh[label="newly committed transaction",shape=rectangle];
27 fresh -> base;
28 discon -> fresh;
29})
31It can be handy to attempt to modify the database without altering the data that others may wish to continue to use and modify. If a set of transactions may diverge from another use-case for the data, the user may choose to "branch" the transaction graph. Branching allows the user to assign an arbitrary name to a series of transactions and then potentially merge the set of transactions back to the originating branch. Project:M36 creates a "master" branch when the transaction graph is first created.
33Note that this transaction graph approach is different from that of most SQL DBMSs which have a strictly linear transaction graph where all the contention is at the head of the graph and neither time-travel nor branching are supported.
35#### Commit
37To convert a mutable database context into a transaction, it must be "committed" to the transaction graph. The equivalent in SQL is COMMIT.
39```
40TutorialD (master/main): :commit
41```
43Once committed, the transaction's database context becomes immutable. Internally, Project:M36 uniquely identifies each transaction with a UUID.
45#### Rollback
47Sometimes, 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.
49```
50TutorialD (master/main): :rollback
51```
53#### Show Transaction Graph
55In 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.
57```
58TutorialD (master/main): :showgraph
59┌───────┬──────┬────────────────────────────────────┬───────┐
60│current│head │id │parents│
61├───────┼──────┼────────────────────────────────────┼───────┤
62<big result elided>
63```
64The "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.
66The "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.
68The "id" attribute is the UUID needed in order to navigate the graph.
70The "parents" attribute is a subrelation holding all parent transaction UUIDs for the given transaction.
73#### Branch
75A 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.
77```
78TutorialD (master/main): :branch testing_data_2005
79TutorialD (testing_data_2005):
80```
82Note 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.
84#### Jump to Head
86To 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.
88Note that jumping to another head implies losing any changes in the current database context.
90```
91TutorialD (testing_data_2005): :jumphead master
92TutorialD (master/main):
93```
95Further commits will be added to the target branch.
97#### Jump to Transaction
99Instead 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:
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
104If one jumps to a non-head transaction, committing new transactions are no longer possible because the past transactions cannot be overwritten.
106```
107TutorialD (master/main): :jump 11b601c9-f46b-42b0-a2ce-cf18ced31b7f
108TutorialD (11b601c9-f46b-42b0-a2ce-cf18ced31b7f):
109```
111Note that the ```tutd``` prompt now indicates that the mutable database context now refers to a specific transaction by UUID.