@@ -1,148 +1,37 @@
11# Project:M36 Relational Algebra Engine
22
3−##Introduction
4−Project:M36 implements a relational algebra engine as inspired by the writings of Chris Date.
5−
6−## Installation
7−
8−1. Install [Haskell Platform](https://www.haskell.org/platform/)
9−1. ```git clone https://github.com/agentm/project-m36```
10−2. ```cd project-m36```
11−3. ```cabal sandbox init```
12−4. ```cabal configure --enable-tests```
13−5. ```cabal install --enable-tests```
14−6. ```cabal run tutd``` to run the Tutorial D interpreter
15−7. ```cabal test``` to run test suite
16−
17−## Usage
18−
19−Currently, the best-supported frontend is the Tutorial D interpreter. Run `cabal run tutd` to start the command line interpreter linked to an in-memory database. Alternatively, to create a database backed by the filesystem (to be able to save committed transactions in the filesystem), use `cabal run tutd -- -d <db directory>`.
20−
21−You will be greeted with:
22−
23−`TutorialD (master):`
24−
25−To load Chris Date's supplier/product examples, run `:importtutd "scripts/DateExamples.tutd"` from within the tutd interpreter. After this, the `S`, `P`, and `SP` relation variables are available within the current context.
26−
27−This TutorialD interpreter is case-sensitive.
28−
29−At this point, there are three types of command which can be executed:
30−
31−1. relational algebra expressions such as:
32−
33− ```
34−TutorialD (master): :showexpr S join P
35−┌──────┬─────┬──┬─────┬──┬─────┬──────┬──────┐
36−│CITY │COLOR│P#│PNAME│S#│SNAME│STATUS│WEIGHT│
37−├──────┼─────┼──┼─────┼──┼─────┼──────┼──────┤
38−│Paris │Blue │P5│Cam │S3│Blake│30 │12 │
39−│London│Red │P1│Nut │S4│Clark│20 │12 │
40−│London│Red │P1│Nut │S1│Smith│20 │12 │
41−│Paris │Blue │P5│Cam │S2│Jones│10 │12 │
42−│London│Red │P6│Cog │S1│Smith│20 │19 │
43−│London│Red │P6│Cog │S4│Clark│20 │19 │
44−│Paris │Green│P2│Bolt │S3│Blake│30 │17 │
45−│London│Red │P4│Screw│S1│Smith│20 │14 │
46−│London│Red │P4│Screw│S4│Clark│20 │14 │
47−│Paris │Green│P2│Bolt │S2│Jones│10 │17 │
48−└──────┴─────┴──┴─────┴──┴─────┴──────┴──────┘
49−```
50−
51− where ":showexpr" instructs the interpreter to show the resultant relation, "S" and "P" are relation names, and "join" is the join operator.
52−2. interpreter-level queries such as:
3+## Introduction
534
54− ```
55−TutorialD (master): :type S
56−{CITY "char", S# "char", SNAME "char", STATUS "char"}
57−```
58−
59− which shows the Tutorial D type for a relational expression and
60−
61− ```
62−TutorialD (master): :constraints
63−fromList []
64−```
65−which displays database constraints.
66−
67− ```
68−TutorialD (master): :showplan x:=S{CITY,S#,SNAME,STATUS}
69−Right (Assign "x" (RelationVariable "S"))
70−```
71−which displays the optimized execution plan which would have been executed to evaluate the expression.
72−
73− ```
74−TutorialD (master): :commit
75−Done.
76−```
77−which commits the current "disconnected" transaction which is similar to the git staging area/index.
78−
79− ```
80−TutorialD (master): :jumphead master
81−Done.
82−```
83−which changes the current disconnected transaction to reference another head.
84−
85− ```
86−TutorialD (master): :jump 4a4ee715-297d-49db-bfd1-afaefadc902b
87−Done.
88−```
89−which resets the current "disconnected" transaction to refer to the committed transaction specified by the UUID.
90−
91− ```
92−TutorialD (master): :branch devel
93−Done.
94−```
95−
96−which creates a new head named "devel" in the transaction graph and resets the current "disconnected" transaction to refer to the new branch.
97−
98− ```
99−TutorialD (devel): :rollback
100−Done.
101−```
102−
103−which resets the current "disconnected" transaction to discard any collected changes.
5+Project:M36 implements a relational algebra engine as inspired by the writings of Chris Date.
1046
105− ```
106−TutorialD (devel): :showGraph
107−┌───────┬────────────────────────────────────┬──────────────────────────────────────┐
108−│current│id │parents │
109−├───────┼────────────────────────────────────┼──────────────────────────────────────┤
110−│True │1d064d54-cd2a-4a43-822a-cbd18cf7c4e8│┌────────────────────────────────────┐│
111−│ │ ││id ││
112−│ │ │├────────────────────────────────────┤│
113−│ │ ││4a4ee715-297d-49db-bfd1-afaefadc902b││
114−│ │ │└────────────────────────────────────┘│
115−│False │4a4ee715-297d-49db-bfd1-afaefadc902b│┌──┐ │
116−│ │ ││id│ │
117−│ │ │ │
118−│ │ │└──┘ │
119−└───────┴────────────────────────────────────┴──────────────────────────────────────┘
120−```
7+## Description
1218
122−which displays all committed transactions and their parents. The "current" attribute indicates to which transactions the current "disconnected" transaction refers.
9+Unlike most database management systems (DBMS), Project:M36 is opinionated software which adheres strictly to the mathematics of the relational algebra. The purpose of this adherence is to prove that software which implements mathematically-sound design principles reaps benefits in the form of code clarity, consistency, performance, and future-proofing.
12310
124−3. expressions which modify the database context such as:
11+Project:M36 can be used as an in-process or remote DBMS.
12512
126− ```
127−TutorialD (master): x := S JOIN P
128−```
129− which sets the relational variable named "x" to the results of "S join P" if the database constraint checking succeeds.
13+Project:M36 is written entirely in the [Haskell programming language](https://www.haskell.org/).
13014
131− To create a new constraint which are represented as inclusion dependencies:
15+## Documentation
13216
133− ```
134−constraint check_x false in true
135−```
17+1. [Installation and Introduction to Project:M36](docs/introduction_to_projectm36.markdown)
18+1. [Introduction to the Relational Algebra](docs/introduction_to_the_relational_algebra.markdown)
19+1. [TutorialD Tutorial](docs/tutd_tutorial.markdown)
20+1. [Transaction Graph Operators](docs/transaction_graph_operators.markdown)
21+1. [Persistent Library Driver](docs/persistent_library_driver.markdown)
22+1. [ProjectM36.Client Library](docs/projectm36_client_library.markdown)
13623
137− checks that the expression "false" is a subrelation of "true", which, in this case, is always true.
13824
13925## Development
14026
141−Project:M36 is developed in Haskell and compiled with GHC. There are three primary, independent modules:
27+Project:M36 is developed in Haskell and compiled with GHC.
28+
29+Important modules:
14230
143311. Relation - represents a relation in the relational algebra and implements the relational operators
144322. Relational Expressions - represents a composable abstract syntax tree for the relational algebra
145333. Tutorial D Interpreter - one available frontend to evaluate relational expressions
34+4. ProjectM36.Client- user-facing native Haskell library
14635
14736Other modules include:
14837