@@ -4,7 +4,8 @@
44-- Maintainer: eitan@morphism.tech
55-- Stability: experimental
66--
7−-- Squeal is a deep embedding of PostgreSQL in Haskell. Let's see an example!
7+-- Squeal is a deep embedding of [PostgreSQL](https://www.postgresql.org) in Haskell.
8+-- Let's see an example!
89--
910-- First, we need some language extensions because Squeal uses modern GHC
1011-- features.
@@ -26,32 +27,32 @@
2627-- >>> import qualified GHC.Generics as GHC
2728--
2829-- The first step is to define the schema of our database. This is where
29−-- we use @DataKinds@ and @TypeOperators@. The schema consists of a type-level
30−-- list of tables, a `:::` pairing of a type level string or
31−-- @Symbol@ and a list a columns, itself a `:::` pairing of a
32−-- @Symbol@ and a `ColumnType`. The `ColumnType` describes the
33−-- PostgreSQL type of the column as well as whether or not it may contain
34−-- @NULL@ and whether or not inserts and updates can use a @DEFAULT@. For our
35−-- schema, we'll define two tables, a users table and an emails table.
30+-- we use @DataKinds@ and @TypeOperators@.
3631--
3732-- >>> :{
3833-- type Schema =
3934-- '[ "users" :::
4035-- '[ "pk_users" ::: 'PrimaryKey '["id"] ] :=>
41−-- '[ "id" ::: 'Def :=> 'NotNull 'PGint4
36+-- '[ "id" ::: 'Def :=> 'NotNull 'PGint4
4237-- , "name" ::: 'NoDef :=> 'NotNull 'PGtext
4338-- ]
4439-- , "emails" :::
45−-- '[ "pk_emails" ::: 'PrimaryKey '["id"]
40+-- '[ "pk_emails" ::: 'PrimaryKey '["id"]
4641-- , "fk_user_id" ::: 'ForeignKey '["user_id"] "users" '["id"]
4742-- ] :=>
48−-- '[ "id" ::: 'Def :=> 'NotNull 'PGint4
43+-- '[ "id" ::: 'Def :=> 'NotNull 'PGint4
4944-- , "user_id" ::: 'NoDef :=> 'NotNull 'PGint4
50−-- , "email" ::: 'NoDef :=> 'Null 'PGtext
45+-- , "email" ::: 'NoDef :=> 'Null 'PGtext
5146-- ]
5247-- ]
5348-- :}
5449--
50+-- Notice the use of type operators. `:::` is used
51+-- to pair an alias `Symbol` with either a `TableType` or a `ColumnType`.
52+-- `:=>` is used to pair a `TableConstraint`s with a `ColumnsType`,
53+-- yielding a `TableType`, or to pair a `ColumnConstraint` with a `NullityType`,
54+-- yielding a `ColumnType`.
55+--
5556-- Next, we'll write `Definition`s to set up and tear down the schema. In
5657-- Squeal, a `Definition` is a `createTable`, `alterTable` or `dropTable`
5758-- command and has two type parameters, corresponding to the schema
@@ -96,7 +97,8 @@
9697-- "DROP TABLE emails; DROP TABLE users;"
9798--
9899-- Next, we'll write `Manipulation`s to insert data into our two tables.
99−-- A `Manipulation` is a `insertInto`, `update` or `deleteFrom` command and
100+-- A `Manipulation` is an `insertRow` (or other inserts), `update`
101+-- or `deleteFrom` command and
100102-- has three type parameters, the schema it refers to, a list of parameters
101103-- it can take as input, and a list of columns it produces as output. When
102104-- we insert into the users table, we will need a parameter for the @name@
@@ -108,8 +110,7 @@
108110--
109111-- >>> :{
110112-- let
111−-- insertUser :: Manipulation Schema '[ 'NotNull 'PGtext ]
112−-- '[ "fromOnly" ::: 'NotNull 'PGint4 ]
113+-- insertUser :: Manipulation Schema '[ 'NotNull 'PGtext ] '[ "fromOnly" ::: 'NotNull 'PGint4 ]
113114-- insertUser = insertRow #users
114115-- (Default `As` #id :* Set (param @1) `As` #name :* Nil)
115116-- OnConflictDoNothing (Returning (#id `As` #fromOnly :* Nil))
@@ -138,8 +139,8 @@
138139-- >>> :{
139140-- let
140141-- getUsers :: Query Schema '[]
141−-- '[ "userName" ::: 'NotNull 'PGtext
142−-- , "userEmail" ::: 'Null 'PGtext ]
142+-- '[ "userName" ::: 'NotNull 'PGtext
143+-- , "userEmail" ::: 'Null 'PGtext ]
143144-- getUsers = select
144145-- (#u ! #name `As` #userName :* #e ! #email `As` #userEmail :* Nil)
145146-- ( from (table (#users `As` #u)