persistent-mysql-haskell 0.1.0.0 → 0.1.1.0
raw patch · 3 files changed
+140/−5 lines, 3 filesdep +persistent-mysql-haskelldep +persistent-templatenew-component:exe:persistent-mysql-haskell-examplePVP ok
version bump matches the API change (PVP)
Dependencies added: persistent-mysql-haskell, persistent-template
API changes (from Hackage documentation)
Files
- README.md +71/−0
- example/Main.hs +53/−0
- persistent-mysql-haskell.cabal +16/−5
+ README.md view
@@ -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+ ```
+ example/Main.hs view
@@ -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]
persistent-mysql-haskell.cabal view
@@ -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 <naushadh@protonmail.com>, Felipe Lessa <felipe.lessa@gmail.com>, 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