@@ -2,13 +2,13 @@
22
33### Version 0.2 - March 24, 2018
44
5−**Enhancements**
5+**Changes**
66- **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
78- **Arrays** - Support for fixed- and variable-length arrays
89- **Aliases** - Generalized `Has` constraint
910- **Pools** - Support for pooled connections
1011- **Transactions** - Support for transaction control language
11−- **Migrations** - Support for linear migrations tracked in an auxiliary table
1212- **Queries, Manipulations, Definitions** - Small and large changes to Squeal's DSL
1313
1414Well, a lot of things changed!
@@ -16,10 +16,10 @@ Well, a lot of things changed!
1616**Constraints**
1717
1818An 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
2020to having `DEFAULT` or not - were at the type level, but they were confusingly named.
2121
22−```
22+```haskell
23230.1: 'Optional ('NotNull 'PGInt4)
24240.2: 'Def :=> 'NotNull 'PGInt4
25250.1: 'Required ('NotNull 'PGInt4)
@@ -27,9 +27,9 @@ to having `DEFAULT` or not - were at the type level, but they were confusingly n
2727```
2828
2929The `:=>` 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`.
3131
32−```
32+```haskell
3333"emails" :::
3434 '[ "pk_emails" ::: 'PrimaryKey '["id"]
3535 , "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
4545This necessitates a distinction between `TableType`s which have both column and table
4646constraints and `RelationType`s which have neither.
4747
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+```
4896
4997**Aliases**
5098
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
99+In Squeal `0.1`, we had different typeclasses `HasColumn` and `HasTable` to indicate
100+that a table has a column or that a schema has a table. In Squeal `0.2` this has been
53101unified to a single typeclass,
54102
55−```
103+```haskell
56104class KnownSymbol alias =>
57105 Has (alias :: Symbol) (fields :: [(Symbol,kind)]) (field :: kind)
58106 | alias fields -> field where
@@ -60,57 +108,26 @@ class KnownSymbol alias =>
60108
61109**Arrays**
62110
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
64112the `'PGfixarray` and `'PGvararray` `PGType`s. Array values can be
65113constructed using the `array` function and can be encoded from and decoded to
66114Haskell `Vector`s.
67115
68116**Pools**
69117
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`.
71119The `resource-pool` library is leveraged to provide striped pools of `Connection`s.
72120`PoolPQ` should be a drop in replacement for running `Manipulation`s and `Query`s with
73121`PQ`.
74122
75123**Transactions**
76124
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
78126`MonadPQ` can be called `transactionally` with different levels of isolation.
79127Additionally, a schema changing computation, a data definition, can be run in a
80128transaction. Running a computation in a transaction means that all SQL statements
81129will be rolled back if an exception is encountered.
82130
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−
114131**Queries, Manipulations and Definitions**
115132
116133The above changes required major and minor changes to Squeal DSL functions.