The persistent-mysql-haskell package

[ Tags: database, library, mit, program, yesod ] [ Propose Tags ]

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. See README.md for more.

This package supports only MySQL 5.1 and above. However, it has been tested only on MySQL 5.5. Only the InnoDB storage engine is officially supported.

Known problems:


[Skip to Readme]

Properties

Versions 0.1.0.0, 0.1.1.0, 0.2.0.0, 0.2.1.0, 0.3.0.0, 0.3.3, 0.3.4, 0.3.4.1, 0.3.5
Change log ChangeLog.md
Dependencies aeson (>=0.6.2), base (>=4.6 && <5), bytestring (>=0.9), conduit (>=0.5.3), containers (>=0.2), io-streams (>=1.2 && <2.0), monad-control (>=0.2), monad-logger, mysql-haskell (>=0.8.0.0 && <1.0), network (>=2.3 && <3.0), persistent (>=2.6.1 && <3), persistent-mysql-haskell, persistent-template, resource-pool, resourcet (>=0.4.10), text (>=0.11.0.6), time (>=1.5.0), tls (>=1.3.5 && <1.5), transformers (>=0.2.1) [details]
License MIT
Author Naushadh <naushadh@protonmail.com>, Felipe Lessa <felipe.lessa@gmail.com>, Michael Snoyman
Maintainer Naushadh <naushadh@protonmail.com>
Category Database, Yesod
Home page http://www.yesodweb.com/book/persistent
Bug tracker https://github.com/naushadh/persistent/issues
Source repository head: git clone git://github.com/naushadh/persistent.git -b persistent-mysql-haskell(persistent-mysql-haskell)
Uploaded Fri Oct 13 00:37:05 UTC 2017 by naushadh
Distributions LTSHaskell:0.3.0.0, NixOS:0.3.5, Stackage:0.3.5
Executables persistent-mysql-haskell-example
Downloads 468 total (53 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
Last success reported on 2017-10-13 [all 3 reports]
Hackage Matrix CI

Modules

  • Database
    • Persist
      • Database.Persist.MySQL

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for persistent-mysql-haskell-0.3.4

[back to package description]

persistent-mysql-haskell

hackage version Build Status

A pure haskell backend for persistent using the MySQL database server. Internally it uses the mysql-haskell driver in order to access the database.

See example/Main.hs for how this MySQL backend can be used with Persistent.

Motivation

persistent-mysql uses mysql (via 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 as noted by @feuerbach.

  • mysql-haskell, a pure haskell driver by @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, 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. Therefore neither can this package.

  • Given the inevitable incompatibility with persistent-mysql, and in the interest of providing a forward-compatible API, ConnectInfo internals and defaultConnectInfo have been deprecated. However the similar utility can be achieved like so:

    import Database.Persist.MySQL
    
    connectInfo :: MySQLConnectInfo
    - connectInfo = defaultConnectInfo
    -             { connectHost     = "localhost"
    -             , connectUser     = "test"
    -             , connectPassword = "test"
    -             , connectDatabase = "test"
    -             }
    + connectInfo = mkMySQLConnectInfo "localhost" "test" "test" "test"
    
    connectInfoNewPort :: MySQLConnectInfo
    - connectInfoNewPort = connectInfo { connectPort = 3307 }
    + connectInfoNewPort = setMySQLConnectInfoPort 3307 connectInfo
    
    connectInfoNewCharSet :: MySQLConnectInfo
    - connectInfoNewCharSet = connectInfo { connectOptions = [CharsetName "utf8"] }
    + connectInfoNewCharSet = setMySQLConnectInfoCharset 33 connectInfo
    
    
  • mysql-haskell and mysql have different APIs/mechanisms for securing the connection to MySQL. persistent-mysql-haskell exposes an API to utilize TLS client params that ships with mysql-haskell.

    connectInfoCustomCaStore :: MySQLConnectInfo
    - connectInfoCustomCaStore = connectInfo { connectSSL = Just customCaParams }
    + connectInfoCustomCaStore = setMySQLConnectInfoTLS customCaParams connectInfo
        where
    -         customCaParams = defaultSSLInfo { sslCAPath = "foobar.pem" }
    +         customCaParams = makeClientParams $ CustomCAStore "foobar.pem"
    

Aside from connection configuration, persistent-mysql-haskell is functionally on par with persistent-mysql (as of writing this). This can be seen by comparing persistent-test between this fork and upstream.

FAQs

Why isn't this part of the main/upstream persistent repo?

persistent-mysql supports X but persistent-mysql-haskell API doesn't. Why?

  • Internals (getters/setters) of MySQLConnectInfo and defaultConnectInfo are intentionally masked for forward compatibility.

  • For all others, 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.

    stack test persistent-test --flag persistent-test:mysql_haskell --exec persistent-test