0.3

.circleci/config.yml

@@ -2,7 +2,7 @@ version: 2
 jobs:
   build:
     docker:
-      - image: haskell:latest
+      - image: haskell:8.2.2
       - image: circleci/postgres:latest
         environment:
           POSTGRES_DB: exampledb

README.md

@@ -44,6 +44,8 @@ composable and cover a large portion of SQL.
 * linear, invertible migrations
 * connection pools
 * transactions
+* views
+* composite and enumerated types
 
 ## installation
 
@@ -62,125 +64,133 @@ Let's see an example!
 First, we need some language extensions because Squeal uses modern GHC
 features.
 
-```haskell
+```Haskell
 >>> :set -XDataKinds -XDeriveGeneric -XOverloadedLabels
 >>> :set -XOverloadedStrings -XTypeApplications -XTypeOperators
 ```
 
 We'll need some imports.
 
-```haskell
+```Haskell
 >>> import Control.Monad (void)
 >>> import Control.Monad.Base (liftBase)
 >>> import Data.Int (Int32)
 >>> import Data.Text (Text)
 >>> import Squeal.PostgreSQL
+>>> import Squeal.PostgreSQL.Render
 ```
 
 We'll use generics to easily convert between Haskell and PostgreSQL values.
 
-```haskell
+```Haskell
 >>> import qualified Generics.SOP as SOP
 >>> import qualified GHC.Generics as GHC
 ```
 
 The first step is to define the schema of our database. This is where
 we use `DataKinds` and `TypeOperators`.
 
-```haskell
+```Haskell
 >>> :{
 type Schema =
-  '[ "users" :::
-       '[ "pk_users" ::: 'PrimaryKey '["id"] ] :=>
-       '[ "id"   :::   'Def :=> 'NotNull 'PGint4
-        , "name" ::: 'NoDef :=> 'NotNull 'PGtext
-        ]
-   , "emails" :::
-       '[ "pk_emails"  ::: 'PrimaryKey '["id"]
-        , "fk_user_id" ::: 'ForeignKey '["user_id"] "users" '["id"]
-        ] :=>
-       '[ "id"      :::   'Def :=> 'NotNull 'PGint4
-        , "user_id" ::: 'NoDef :=> 'NotNull 'PGint4
-        , "email"   ::: 'NoDef :=>    'Null 'PGtext
-        ]
-   ]
+  '[ "users" ::: 'Table (
+      '[ "pk_users" ::: 'PrimaryKey '["id"] ] :=>
+      '[ "id"   :::   'Def :=> 'NotNull 'PGint4
+       , "name" ::: 'NoDef :=> 'NotNull 'PGtext
+       ])
+  , "emails" ::: 'Table (
+      '[ "pk_emails"  ::: 'PrimaryKey '["id"]
+       , "fk_user_id" ::: 'ForeignKey '["user_id"] "users" '["id"]
+       ] :=>
+      '[ "id"      :::   'Def :=> 'NotNull 'PGint4
+       , "user_id" ::: 'NoDef :=> 'NotNull 'PGint4
+       , "email"   ::: 'NoDef :=>    'Null 'PGtext
+       ])
+  ]
 :}
 ```
 
-Notice the use of type operators. `:::` is used
-to pair an alias `Symbol` with either a `TableType` or a `ColumnType`.
-`:=>` is used to pair a `TableConstraint`s with a `ColumnsType`,
+Notice the use of type operators.
+
+`:::` is used to pair an alias `GHC.TypeLits.Symbol` with a `SchemumType`,
+a `TableConstraint` or a `ColumnType`. It is intended to connote Haskell's `::`
+operator.
+
+`:=>` is used to pair `TableConstraints` with a `ColumnsType`,
 yielding a `TableType`, or to pair a `ColumnConstraint` with a `NullityType`,
-yielding a `ColumnType`.
+yielding a `ColumnType`. It is intended to connote Haskell's `=>` operator
 
 Next, we'll write `Definition`s to set up and tear down the schema. In
-Squeal, a `Definition` is a `createTable`, `alterTable` or `dropTable`
-command and has two type parameters, corresponding to the schema
-before being run and the schema after. We can compose definitions using
-`>>>`. Here and in the rest of our commands we make use of overloaded
+Squeal, a `Definition` like `createTable`, `alterTable` or `dropTable` 
+has two type parameters, corresponding to the schema
+before being run and the schema after. We can compose definitions using `>>>`.
+Here and in the rest of our commands we make use of overloaded
 labels to refer to named tables and columns in our schema.
 
-```haskell
+```Haskell
 >>> :{
 let
   setup :: Definition '[] Schema
   setup = 
-   createTable #users
-     ( serial `As` #id :*
-       (text & notNull) `As` #name :* Nil )
-     ( primaryKey (Column #id :* Nil) `As` #pk_users :* Nil ) >>>
-   createTable #emails
-     ( serial `As` #id :*
-       (int & notNull) `As` #user_id :*
-       text `As` #email :* Nil )
-     ( primaryKey (Column #id :* Nil) `As` #pk_emails :*
-       foreignKey (Column #user_id :* Nil) #users (Column #id :* Nil)
-         OnDeleteCascade OnUpdateCascade `As` #fk_user_id :* Nil )
+    createTable #users
+      ( serial `As` #id :*
+        (text & notNullable) `As` #name :* Nil )
+      ( primaryKey #id `As` #pk_users :* Nil ) >>>
+    createTable #emails
+      ( serial `As` #id :*
+        (int & notNullable) `As` #user_id :*
+        (text & nullable) `As` #email :* Nil )
+      ( primaryKey #id `As` #pk_emails :*
+        foreignKey #user_id #users #id
+          OnDeleteCascade OnUpdateCascade `As` #fk_user_id :* Nil )
 :}
 ```
 
-We can easily see the generated SQL is unsuprising looking.
+We can easily see the generated SQL is unsurprising looking.
 
-```haskell
->>> renderDefinition setup
-"CREATE TABLE users (id serial, name text NOT NULL, CONSTRAINT pk_users PRIMARY KEY (id)); CREATE TABLE emails (id serial, user_id int NOT NULL, email text, CONSTRAINT pk_emails PRIMARY KEY (id), CONSTRAINT fk_user_id FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE ON UPDATE CASCADE);"
+```Haskell
+>>> printSQL setup
+CREATE TABLE "users" ("id" serial, "name" text NOT NULL, CONSTRAINT "pk_users" PRIMARY KEY ("id"));
+CREATE TABLE "emails" ("id" serial, "user_id" int NOT NULL, "email" text NULL, CONSTRAINT "pk_emails" PRIMARY KEY ("id"), CONSTRAINT "fk_user_id" FOREIGN KEY ("user_id") REFERENCES "users" ("id") ON DELETE CASCADE ON UPDATE CASCADE);
 ```
 
 Notice that `setup` starts with an empty schema `'[]` and produces `Schema`.
 In our `createTable` commands we included `TableConstraint`s to define
-primary and foreign keys, making them somewhat complex. Our tear down
+primary and foreign keys, making them somewhat complex. Our `teardown`
 `Definition` is simpler.
 
-```haskell
+```Haskell
 >>> :{
 let
   teardown :: Definition Schema '[]
   teardown = dropTable #emails >>> dropTable #users
 :}
->>> renderDefinition teardown
-"DROP TABLE emails; DROP TABLE users;"
+
+>>> printSQL teardown
+DROP TABLE "emails";
+DROP TABLE "users";
 ```
 
 Next, we'll write `Manipulation`s to insert data into our two tables.
-A `Manipulation` is an `insertRow` (or other inserts), `update`
-or `deleteFrom` command and
+A `Manipulation` like `insertRow`, `update` or `deleteFrom`
 has three type parameters, the schema it refers to, a list of parameters
 it can take as input, and a list of columns it produces as output. When
 we insert into the users table, we will need a parameter for the `name`
-field but not for the `id` field. Since it's optional, we can use a default
+field but not for the `id` field. Since it's serial, we can use a default
 value. However, since the emails table refers to the users table, we will
 need to retrieve the user id that the insert generates and insert it into
 the emails table. Take a careful look at the type and definition of both
 of our inserts.
 
-```haskell
+```Haskell
 >>> :{
 let
   insertUser :: Manipulation Schema '[ 'NotNull 'PGtext ] '[ "fromOnly" ::: 'NotNull 'PGint4 ]
   insertUser = insertRow #users
     (Default `As` #id :* Set (param @1) `As` #name :* Nil)
     OnConflictDoNothing (Returning (#id `As` #fromOnly :* Nil))
 :}
+
 >>> :{
 let
   insertEmail :: Manipulation Schema '[ 'NotNull 'PGint4, 'Null 'PGtext] '[]
@@ -190,18 +200,19 @@ let
       Set (param @2) `As` #email :* Nil )
     OnConflictDoNothing (Returning Nil)
 :}
->>> renderManipulation insertUser
-"INSERT INTO users (id, name) VALUES (DEFAULT, ($1 :: text)) ON CONFLICT DO NOTHING RETURNING id AS fromOnly;"
->>> renderManipulation insertEmail
-"INSERT INTO emails (id, user_id, email) VALUES (DEFAULT, ($1 :: int4), ($2 :: text)) ON CONFLICT DO NOTHING;"
+
+>>> printSQL insertUser
+INSERT INTO "users" ("id", "name") VALUES (DEFAULT, ($1 :: text)) ON CONFLICT DO NOTHING RETURNING "id" AS "fromOnly"
+>>> printSQL insertEmail
+INSERT INTO "emails" ("id", "user_id", "email") VALUES (DEFAULT, ($1 :: int4), ($2 :: text)) ON CONFLICT DO NOTHING
 ```
 
 Next we write a `Query` to retrieve users from the database. We're not
 interested in the ids here, just the usernames and email addresses. We
 need to use an inner join to get the right result. A `Query` is like a
 `Manipulation` with the same kind of type parameters.
 
-```haskell
+```Haskell
 >>> :{
 let
   getUsers :: Query Schema '[]
@@ -213,8 +224,9 @@ let
       & innerJoin (table (#emails `As` #e))
         (#u ! #id .== #e ! #user_id)) )
 :}
->>> renderQuery getUsers
-"SELECT u.name AS userName, e.email AS userEmail FROM users AS u INNER JOIN emails AS e ON (u.id = e.user_id)"
+
+>>> printSQL getUsers
+SELECT "u"."name" AS "userName", "e"."email" AS "userEmail" FROM "users" AS "u" INNER JOIN "emails" AS "e" ON ("u"."id" = "e"."user_id")
 ```
 
 Now that we've defined the SQL side of things, we'll need a Haskell type
@@ -223,15 +235,15 @@ for users. We give the type `Generics.SOP.Generic` and
 we receive when we run `getUsers`. Notice that the record fields of the
 `User` type match the column names of `getUsers`.
 
-```haskell
+```Haskell
 >>> data User = User { userName :: Text, userEmail :: Maybe Text } deriving (Show, GHC.Generic)
 >>> instance SOP.Generic User
 >>> instance SOP.HasDatatypeInfo User
 ```
 
 Let's also create some users to add to the database.
 
-```haskell
+```Haskell
 >>> :{
 let
   users :: [User]
@@ -251,7 +263,7 @@ the changing schema information through by using the indexed `PQ` monad
 transformer and when the schema doesn't change we can use `Monad` and
 `MonadPQ` functionality.
 
-```haskell
+```Haskell
 >>> :{
 let
   session :: PQ Schema Schema IO ()
@@ -262,12 +274,11 @@ let
     usersResult <- runQuery getUsers
     usersRows <- getRows usersResult
     liftBase $ print (usersRows :: [User])
-:}
->>> :{
-void . withConnection "host=localhost port=5432 dbname=exampledb" $
-  define setup
-  & pqThen session
-  & pqThen (define teardown)
+in
+  void . withConnection "host=localhost port=5432 dbname=exampledb" $
+    define setup
+    & pqThen session
+    & pqThen (define teardown)
 :}
 [User {userName = "Alice", userEmail = Just "alice@gmail.com"},User {userName = "Bob", userEmail = Nothing},User {userName = "Carole", userEmail = Just "carole@hotmail.com"}]
 ```