/selda

A type-safe, high-level SQL library for Haskell

Primary LanguageHaskellMIT LicenseMIT

Selda

Join the chat at https://gitter.im/selda-hs/Lobby Hackage IRC channel MIT License Haskell CI Hackage Dependencies

What is Selda?

Selda is a Haskell library for interacting with SQL-based relational databases. It was inspired by LINQ and Opaleye.

Features

  • Monadic interface.
  • Portable: backends for SQLite and PostgreSQL.
  • Generic: easy integration with your existing Haskell types.
  • Creating, dropping and querying tables using type-safe database schemas.
  • Typed query language with products, filtering, joins and aggregation.
  • Inserting, updating and deleting rows from tables.
  • Conditional insert/update.
  • Transactions, uniqueness constraints and foreign keys.
  • Type-safe, backend-specific functionality, such as JSON lookups.
  • Seamless prepared statements.
  • Lightweight and modular: few dependencies, and non-essential features are optional or split into add-on packages.

Getting started

Install the selda package from Hackage, as well as at least one of the backends:

$ cabal update
$ cabal install selda selda-sqlite selda-postgresql

Then, read the tutorial. The API documentation will probably also come in handy.

Requirements

Selda requires GHC 8.0+, as well as SQLite 3.7.11+ or PostgreSQL 9.4+. To build the SQLite backend, you need a C compiler installed. To build the PostgreSQL backend, you need the libpq development libraries installed (libpq-dev on Debian-based Linux distributions).

Hacking

Contributing

All forms of contributions are welcome!

If you have a bug to report, please try to include as much information as possible, preferably including:

  • A brief description (one or two sentences) of the bug.
  • The version of Selda+backend where the bug was found.
  • A step-by-step guide to reproduce the bug.
  • The expected result from following these steps.
  • What actually happens when following the steps.
  • Which component contains the bug (selda, selda-sqlite or selda-postgresql), if you're reasonably sure about where the bug is.

Bonus points for a small code example that illustrates the problem.

If you want to contribute code, please consult the following checklist before sending a pull request:

  • Does the code build with a recent version of GHC?
  • Do all the tests pass?
  • Have you added any tests covering your code?

If you want to contribute code but don't really know where to begin, issues tagged good first issue are a good start.

Setting up the build environment

From the repository root:

  • Install libpq-dev from your package manager. This is required to build the PostgreSQL backend.
  • Make sure you're running a cabal version that supports v2-style commands.
  • Familiarise yourself with the various targets in the makefile. The dependencies between Selda, the backends and the tests are slightly complex, so straight-up cabal is too quirky for day to day hacking.

PostgreSQL backend testing with Docker

To test the PostgreSQL backend, use the provided pgtest-compose.yml docker-compose file:

sudo docker-compose -f pgtest-compose.yml up -d
make pgtest
sudo docker-compose -f pgtest-compose.yml down

TODOs

Features that would be nice to have but are not yet implemented.

  • Monadic if/else
  • Streaming
  • MySQL/MariaDB backend
  • MSSQL backend