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