Upgrading Yesod 1.2 -> 1.4

I’ve recently had to quickly upgrade Yesod 1.2 web application from version 1.2 to 1.4. I was looking for resources on how to do this and couldn’t find anything beyond Announcing Yesod 1.4 and Persistent 2.1 Released. This post should be useful if you’re in a similar situation and your app is backed by PostgreSQL, even though it should work just about the same for any other SQL backend.The transition was actually pretty simple, you have to take care of the following steps:

Update the libraries

Installing Yesod 1.4 through hackage is even more of a pain that before. It’s doable, and I have done that before, but I strongly recommend using Stackage Server. Go with an exclusive snapshot to avoid headaches and having to set constraints. It completely takes care of cabal hell as long as your dependencies aren’t highly exotic. Even then there are ways to work around it, but that’s for another post.

Once yoru cabal is wired against Stackage, remove version constraints from all of the packages in your .cabal file, as those will be decided for you by the Stackage snapshot.

Update Foundation.hs

-- replace this
import Database.Persist.Sql (SqlPersistT)
-- with this
import Database.Persist.Sql (SqlBackend)

Then:

-- replace this
giveUrlRenderer $(hamletFile "templates/default-layout-wrapper.hamlet")
-- with this
withUrlRenderer $(hamletFile "templates/default-layout-wrapper.hamlet")

Add the following after all of the implementations of instance YesodAuth:

instance YesodAuthPersist App

Model.hs

-- replace this
share [mkPersist sqlOnlySettings, mkMigrate "migrateAll"]
-- with this
share [mkPersist sqlSettings, mkMigrate "migrateAll"]

Update SQL entities

Love timestamptz in Postgres? ZonedTime SQL type is gone in Persistent 2.1: it’s now officially replaced with UTCTime which was already available before. If you actually need to know the TZ of a certain timestamp, you’re going to need a custom solution, Persistent isn’t going to do this out of the box, but if you don’t, just swap one for the other.

Update Entity Key creation logic

If like me you were manually generating Entity keys in your tests, then you will no longer be able to do so with Persistent 2.1. Replace your old code doing:

Entity (Key $ PersistInt64 1) { foo = "bar" }

with the new:

import Database.Persist.Sql
Entity (toSqlKey 1) { foo = "bar" }

The steps above should take of the most common conflicts that you will encounter when upgrading PostgreSQL-backed Yesod 1.2 to 1.4. Let me know if it’s missing anything.

As always don’t forget to drop by #yesod and #haskell-beginners on Freenode if you have any questions.