diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,71 @@ +# persistent-mysql-haskell + +A pure haskell backend for [persistent](https://github.com/yesodweb/persistent) using the MySQL database server. +Internally it uses the [mysql-haskell](https://github.com/winterland1989/mysql-haskell) driver in order to access the database. + +See [example/Main.hs](example/Main.hs) for how this MySQL backend can be used with Persistent. + +### Motivation + +`persistent-mysql` uses [mysql](https://hackage.haskell.org/package/mysql) (via [mysql-simple](https://hackage.haskell.org/package/mysql-simple)) as the database driver. `mysql` is a haskell FFI wrapper for `mysqlclient` written in C. + +Reasons to use a pure haskell driver: + +- `mysql` has [concurrency issues](https://ro-che.info/articles/2015-04-17-safe-concurrent-mysql-haskell) as noted by [@feuerbach](https://github.com/feuerbach). + +- [mysql-haskell](https://hackage.haskell.org/package/mysql-haskell), a pure haskell driver by [@winterland1989](https://github.com/winterland1989), outperforms `mysql-simple` in benchmarks (see hackage or project repo). + +- better portability and possible static compilation of an entire project that uses `persistent-mysql`. + + +Personal experience on replacing `mysql-simple` with `mysql-haskell` in a project: + +- Performance gains consistent with benchmark. + +- Smoother deployment to [Amazon AMI/EC2](https://en.wikipedia.org/wiki/Amazon_Machine_Image), since `mysql` appears to have a hard dependency on the oracle version of `libmysqlclient` that does not work with the open source variant that is available by default on EC2 (and possibly on other cloud providers). + +### Potential issues moving from persistent-mysql to persistent-mysql-haskell + +`ConnectInfo` and `defaultConnectInfo` are not the same between `mysql` and `mysql-haskell`, therefore this package is not a 100% drop in replacement for persistent-mysql from the connection configuration perspective. + +- `mysql-haskell` does not allow provide an API for the entirety of [mysqlclient options](https://hackage.haskell.org/package/mysql-0.1.4/docs/Database-MySQL-Base.html#t:Option). Therefore neither can this package. + +- Given the inevitable incompatibility with `persistent-mysql`, and in the interest of [providing a forward-compatible API](http://www.snoyman.com/blog/2016/11/designing-apis-for-extensibility), `ConnectInfo` internals and `defaultConnectInfo` have been deprecated. However the similar utility can be achieved like so: + + ```diff + import Database.Persist.MySQL + + connectInfo :: MySQLConnectInfo + - connectInfo = defaultConnectInfo + - { connectHost = "localhost" + - , connectUser = "test" + - , connectPassword = "test" + - , connectDatabase = "test" + - } + + connectInfo = mkMySQLConnectInfo "localhost" "test" "test" "test" + ``` + +### FAQs + +#### Why isn't this part of the main/upstream persistent repo? + +- TLDR: Upstream wants to gauge community interest before absorbing this backend into the main repo. +- Long version: See [issue yesodweb/persistent/issues/659](https://github.com/yesodweb/persistent/issues/659). + +#### mysql-haskell supports X but persistent-mysql-haskell API doesn't expose it. Why? + +- Internals (getters/setters) of MySQLConnectInfo and `defaultConnectInfo` are intentionally masked for [forward compatibility](http://www.snoyman.com/blog/2016/11/designing-apis-for-extensibility). + +- Setting `MySQLConnectInfo` charset and port number are in the works. + +- `TLS` support is also in the works. + +- For all others, including what's already in the works, feel free to open an issue and/or submit a PR. + +#### Does persistent-mysql-haskell ship with tests? + +- It does! :) `persistent-test` is fully re-used with an additional flag to specifically test persistent-mysql-haskell. + + ```bash + stack test persistent-test --flag persistent-test:mysql_haskell + ``` diff --git a/example/Main.hs b/example/Main.hs new file mode 100644 --- /dev/null +++ b/example/Main.hs @@ -0,0 +1,53 @@ +{-# LANGUAGE EmptyDataDecls #-} +{-# LANGUAGE FlexibleContexts #-} +{-# LANGUAGE GADTs #-} +{-# LANGUAGE GeneralizedNewtypeDeriving #-} +{-# LANGUAGE MultiParamTypeClasses #-} +{-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} +{-# LANGUAGE TypeFamilies #-} + +-- | Taken from http://www.yesodweb.com/book/persistent. +module Main where + +import Control.Monad.IO.Class (liftIO) +import Control.Monad.Logger (runStderrLoggingT) +import Database.Persist +import Database.Persist.MySQL +import Database.Persist.TH +import Control.Monad (void) + +share [mkPersist sqlSettings, mkMigrate "migrateAll"] [persistLowerCase| +Person + name String + age Int Maybe + deriving Show +BlogPost + title String + authorId PersonId + deriving Show +|] + +connectionInfo :: MySQLConnectInfo +connectionInfo = mkMySQLConnectInfo "localhost" "test" "test" "example" + +main :: IO () +main = runStderrLoggingT $ withMySQLPool connectionInfo 10 $ \pool -> liftIO $ do + flip runSqlPersistMPool pool $ do + runMigration migrateAll + + johnId <- insert $ Person "John Doe" $ Just 35 + janeId <- insert $ Person "Jane Doe" Nothing + + void $ insert $ BlogPost "My fr1st p0st" johnId + void $ insert $ BlogPost "One more for good measure" johnId + + oneJohnPost <- selectList [BlogPostAuthorId ==. johnId] [LimitTo 1] + liftIO $ print (oneJohnPost :: [Entity BlogPost]) + + john <- get johnId + liftIO $ print (john :: Maybe Person) + + delete janeId + deleteWhere [BlogPostAuthorId ==. johnId] diff --git a/persistent-mysql-haskell.cabal b/persistent-mysql-haskell.cabal --- a/persistent-mysql-haskell.cabal +++ b/persistent-mysql-haskell.cabal @@ -1,5 +1,5 @@ name: persistent-mysql-haskell -version: 0.1.0.0 +version: 0.1.1.0 license: MIT license-file: LICENSE author: Naushadh , Felipe Lessa , Michael Snoyman @@ -7,14 +7,14 @@ synopsis: A pure haskell backend for the persistent library using MySQL database server. category: Database, Yesod stability: Stable -cabal-version: >= 1.6 +cabal-version: >= 1.8 build-type: Simple homepage: http://www.yesodweb.com/book/persistent bug-reports: https://github.com/naushadh/persistent/issues description: This package contains a backend for persistent using the MySQL database server. Internally it uses the @mysql-haskell@ - package in order to access the database. + package in order to access the database. See README.md for more. . This package supports only MySQL 5.1 and above. However, it has been tested only on MySQL 5.5. @@ -24,10 +24,10 @@ . * This package does not support statements inside other statements. -extra-source-files: ChangeLog.md +extra-source-files: ChangeLog.md, README.md library - build-depends: base >= 4.6 && < 5 + build-depends: base >= 4.6 && < 5 , transformers >= 0.2.1 , persistent >= 2.6.1 && < 3 , containers >= 0.2 @@ -45,6 +45,17 @@ , tls >= 1.3.5 && <1.4 exposed-modules: Database.Persist.MySQL ghc-options: -Wall + +executable persistent-mysql-haskell-example + hs-source-dirs: example + main-is: Main.hs + ghc-options: -Wall -threaded -rtsopts -with-rtsopts=-N + build-depends: base >= 4.6 && < 5 + , persistent >= 2.6.1 && < 3 + , monad-logger + , persistent-template + , persistent-mysql-haskell + , transformers >= 0.2.1 source-repository head type: git