merge master

.github/workflows/haskell.yml

@@ -32,13 +32,23 @@ jobs:
           --health-retries=3
     strategy:
       matrix:
-        cabal: ["3.4"]
-        ghc: ["8.6.5", "8.8.4", "8.10.4", "9.0.1"]
+        cabal: ["3.10.2.1"]
+        ghc: 
+          - "8.6"
+          - "8.8"
+          - "8.10"
+          - "9.0"
+          - "9.2"
+          - "9.4"
+          - "9.6"
+          - "9.8"
+          - "9.10"
+            # - "9.12"
     env:
       CONFIG: "--enable-tests --enable-benchmarks "
     steps:
-      - uses: actions/checkout@v2
-      - uses: haskell/actions/setup@v1
+      - uses: actions/checkout@v4
+      - uses: haskell-actions/setup@v2
         id: setup-haskell-cabal
         with:
           ghc-version: ${{ matrix.ghc }}
@@ -61,7 +71,7 @@ jobs:
             #     mysql password: 'esqutest' # Required if "mysql user" exists. The password for the "mysql user"
       - run: cabal v2-update
       - run: cabal v2-freeze $CONFIG
-      - uses: actions/cache@v2
+      - uses: actions/cache@v4
         with:
           path: |
             ${{ steps.setup-haskell-cabal.outputs.cabal-store }}
@@ -72,5 +82,6 @@ jobs:
             ${{ runner.os }}-${{ matrix.ghc }}-
       - run: cabal v2-build --disable-optimization -j $CONFIG
       - run: cabal v2-test --disable-optimization -j $CONFIG --test-options "--fail-on-focus"
-      - run: cabal v2-haddock -j $CONFIG
+      - if: ${{ matrix.ghc != '8.6' }}
+        run: cabal v2-haddock -j $CONFIG
       - run: cabal v2-sdist

Makefile

@@ -1,45 +1,70 @@
+STACK := stack --jobs $(shell nproc)
+
+match ?=
+
+STACK_TEST_ARGS := $(if $(match),--test-arguments "--match $(match)",)
+
+.PHONY: build
 build:
-	stack build
+	$(STACK) build
 
+.PHONY: build-tests
 build-tests:
-	stack build --test --no-run-tests
+	$(STACK) build --test --no-run-tests
 
+.PHONY: ghci
 ghci:
-	stack ghci
+	$(STACK) ghci
 
+.PHONY: test
 test:
-	stack test
+	$(STACK) test $(STACK_TEST_ARGS)
 
 # Intended for use in local dev
+.PHONY: test-postgresql
 test-postgresql: reset-pgsql
-	stack test esqueleto:postgresql
+	$(STACK) test esqueleto:postgresql $(STACK_TEST_ARGS)
 
+.PHONY: test-mysql
 test-mysql:
-	stack test esqueleto:mysql
+	$(STACK) test esqueleto:mysql $(STACK_TEST_ARGS)
 
+.PHONY: test-ghci
 test-ghci:
-	stack ghci esqueleto:test:sqlite
+	$(STACK) ghci esqueleto:test:sqlite $(STACK_TEST_ARGS)
 
+.PHONY: test-ghcid
 test-ghcid:
-	ghcid -c "stack ghci --ghci-options -fobject-code esqueleto --test" \
+	ghcid -c "$(STACK) ghci --ghci-options -fobject-code esqueleto --test" \
 		--warnings \
 		--restart "stack.yaml" \
 		--restart "esqueleto.cabal" \
 		--test main
 
+.PHONY: test-ghcid-build
 test-ghcid-build:
-	ghcid -c "stack ghci --ghci-options -fobject-code esqueleto --test" \
+	ghcid -c "$(STACK) ghci --ghci-options -fobject-code esqueleto --test" \
 		--warnings \
 		--restart "stack.yaml" \
 		--restart "esqueleto.cabal"
 
+.PHONY: haddock doc
+haddock: doc
+doc:
+	$(STACK) haddock
+
+.PHONY: clean
+clean:
+	$(STACK) clean
+
+.PHONY: init-pgsql
+
 init-pgsql:
 	sudo -u postgres -- createuser -s esqutest
 
+.PHONY: reset-pgsql
 reset-pgsql:
 	-sudo -u postgres dropdb esqutest
 	-sudo -u postgres dropuser esqutest
 	echo "CREATE USER esqutest WITH PASSWORD 'esqutest';" | sudo -u postgres psql
 	sudo -u postgres createdb -O esqutest esqutest
-
-.PHONY: build build-7.10 build-8.0 ghci test test-ghci

README.md

@@ -127,7 +127,61 @@ FROM Person
 WHERE Person.age >= 18
 ```
 
-Since `age` is an optional `Person` field, we use `just` to lift`val 18 :: SqlExpr (Value Int)` into `just (val 18) ::SqlExpr (Value (Maybe Int))`.
+Since `age` is an optional `Person` field, we use `just` to lift `val 18 :: SqlExpr (Value Int)` into `just (val 18) ::SqlExpr (Value (Maybe Int))`.
+
+### Alternative Field Projections
+
+The `(^.)` operator works on an `EntityField` value, which are generated by
+`persistent` as the table name + the field name. This can get a little bit
+verbose. As of `persistent-2.11`, you can use `OverloadedLabels` to make this a
+bit more concise:
+
+```haskell
+{-# LANGUAGE OverloadedLabels #-}
+
+select $ do
+    p <- from $ table @Person
+    pure
+        ( p ^. PersonName
+        , p ^. #name
+        )
+```
+
+The `OverloadedLabels` support uses the `fieldName` as given by the Persistent
+entity definition syntax - no type name prefix necessary. Additionally, these
+field accesses are *polymorphic* - the following query filters any table that
+has a `name` column:
+
+```haskell
+rowsByName
+    :: forall rec.
+    ( PersistEntity rec
+    , PersistEntityBackend rec ~ SqlBackend
+    , SymbolToField "name" rec Text
+    )
+    => SqlExpr (Value Text)
+    -> SqlQuery (SqlExpr (Entity rec))
+rowsByName name = do
+    rec <- from $ table @rec
+    where_ $ rec ^. #name ==. name
+    pure rec
+```
+
+GHC 9.2 introduces the `OverloadedRecordDot` language extension, and `esqueleto`
+supports this on `SqlExpr (Entity rec)` and `SqlExpr (Maybe (Entity rec))`. It
+looks like this:
+
+```haskell
+select $ do
+    (person, blogPost) <-
+        from $
+            table @Person
+            `leftJoin` table @BlogPost
+            `on` do
+                \(person :& blogPost) ->
+                    just person.id ==. blogPost.authorId
+    pure (person.name, blogPost.title)
+```
 
 ## Experimental/New Joins
 
@@ -165,7 +219,7 @@ Advantages:
 - `ON` clause is attached directly to the relevant join, so you never need to
   worry about how they're ordered, nor will you ever run into bugs where the
   `on` clause is on the wrong `JOIN`
-- The `ON` clause lambda will all the available tables in it. This forbids
+- The `ON` clause lambda will exclusively have all the available tables in it. This forbids
   runtime errors where an `ON` clause refers to a table that isn't in scope yet.
 - You can join on a table twice, and the aliases work out fine with the `ON`
   clause.
@@ -488,5 +542,5 @@ user which can access it:
 mysql> CREATE DATABASE esqutest;
 mysql> CREATE USER 'travis'@'localhost';
 mysql> ALTER USER 'travis'@'localhost' IDENTIFIED BY 'esqutest';
-mysql> GRANT ALL ON esqutest.* TO 'travis';
+mysql> GRANT ALL ON esqutest.* TO 'travis'@'localhost';
 ```