git.iko.soy/squeal
on dev help sign in
release notes
5f9026fEitan Chatav
RELEASE NOTES.mdnew file+117
compare with dev
unifiedsplit
@@ -0,0 +1,117 @@
1+## RELEASE NOTES
2+
3+### Version 0.2 - March 24, 2018
4+
5+**Enhancements**
6+- **Constraints** - Type level table constraints like primary and foreign keys and column constraints like having `DEFAULT`.
7+- **Arrays** - Support for fixed- and variable-length arrays
8+- **Aliases** - Generalized `Has` constraint
9+- **Pools** - Support for pooled connections
10+- **Transactions** - Support for transaction control language
11+- **Migrations** - Support for linear migrations tracked in an auxiliary table
12+- **Queries, Manipulations, Definitions** - Small and large changes to Squeal's DSL
13+
14+Well, a lot of things changed!
15+
16+**Constraints**
17+
18+An important request was to bring constraints to the type level.
19+This means that more of the schema is statically known. In 0.1 column constraints - which boil down
20+to having `DEFAULT` or not - were at the type level, but they were confusingly named.
21+
22+```
23+0.1: 'Optional ('NotNull 'PGInt4)
24+0.2: 'Def :=> 'NotNull 'PGInt4
25+0.1: 'Required ('NotNull 'PGInt4)
26+0.2: 'NoDef :=> 'NotNull 'PGInt4
27+```
28+
29+The `:=>` type operator is intended to helpfully connote a constraint relation.
30+It's also used for table constraints which are new in 0.2.
31+
32+```
33+"emails" :::
34+ '[ "pk_emails" ::: 'PrimaryKey '["id"]
35+ , "fk_user_id" ::: 'ForeignKey '["user_id"] "users" '["id"]
36+ ] :=>
37+ '[ "id" ::: 'Def :=> 'NotNull 'PGint4
38+ , "user_id" ::: 'NoDef :=> 'NotNull 'PGint4
39+ , "email" ::: 'NoDef :=> 'Null 'PGtext
40+ ]
41+```
42+
43+Another change in the constraint system was the removal of column constraints from
44+query and manipulation results, as result columns don't support a notion of `DEFAULT`.
45+This necessitates a distinction between `TableType`s which have both column and table
46+constraints and `RelationType`s which have neither.
47+
48+
49+**Aliases**
50+
51+In Squeal 0.1, we had different typeclasses `HasColumn` and `HasTable` to indicate
52+that a table has a column or that a schema has a table. In Squeal 0.2 this has been
53+unified to a single typeclass,
54+
55+```
56+class KnownSymbol alias =>
57+ Has (alias :: Symbol) (fields :: [(Symbol,kind)]) (field :: kind)
58+ | alias fields -> field where
59+```
60+
61+**Arrays**
62+
63+Support for array types has been added to Squeal 0.2 through
64+the `'PGfixarray` and `'PGvararray` `PGType`s. Array values can be
65+constructed using the `array` function and can be encoded from and decoded to
66+Haskell `Vector`s.
67+
68+**Pools**
69+
70+Squeal 0.2 provides a monad transformer `PoolPQ` that's an instance of `MonadPQ`.
71+The `resource-pool` library is leveraged to provide striped pools of `Connection`s.
72+`PoolPQ` should be a drop in replacement for running `Manipulation`s and `Query`s with
73+`PQ`.
74+
75+**Transactions**
76+
77+Squeal 0.2 supports a simple transaction control language. A computation in
78+`MonadPQ` can be called `transactionally` with different levels of isolation.
79+Additionally, a schema changing computation, a data definition, can be run in a
80+transaction. Running a computation in a transaction means that all SQL statements
81+will be rolled back if an exception is encountered.
82+
83+**Migrations**
84+
85+Migrations are a hot topic and many people have requested this feature. Squeal 0.2
86+adds support for linear, invertible migrations. That is, a migration is a named,
87+invertible, schema-tracking computation:
88+
89+```
90+data Migration io schema0 schema1 = Migration
91+ { name :: Text -- ^ The `name` of a `Migration`.
92+ -- Each `name` in a `Migration` should be unique.
93+ , up :: PQ schema0 schema1 io () -- ^ The `up` instruction of a `Migration`.
94+ , down :: PQ schema1 schema0 io () -- ^ The `down` instruction of a `Migration`.
95+ }
96+```
97+
98+And, `Migration`s can be put together in an "aligned" list:
99+
100+```
101+data AlignedList p x0 x1 where
102+ Done :: AlignedList p x x
103+ (:>>) :: p x0 x1 -> AlignedList p x1 x2 -> AlignedList p x0 x2
104+```
105+
106+These aligned lists are free categories and might look familiar from
107+the [reflections without remorse](http://okmij.org/ftp/Haskell/zseq.pdf) technique,
108+which uses their cousins, aligned sequences.
109+
110+In the context of migration, they allow one to chain new migrations as a
111+schema evolves over time. `Migration`s' execution is tracked in an auxiliary
112+migrations table.
113+
114+**Queries, Manipulations and Definitions**
115+
116+The above changes required major and minor changes to Squeal DSL functions.
117+Please consult the documentation.