Welcome to Rel8! Rel8 is a Haskell library for interacting with PostgreSQL databases, built on top of the fantastic Opaleye library.
The main objectives of Rel8 are:
Conciseness: Users using Rel8 should not need to write boiler-plate code. By using expressive types, we can provide sufficient information for the compiler to infer code whenever possible.
Inferrable: Despite using a lot of type level magic, Rel8 aims to have excellent and predictable type inference.
Familiar: writing Rel8 queries should feel like normal Haskell programming.
Rel8 was presented at ZuriHac 2021. If you want to have a brief overview of what Rel8 is, and a tour of the API - check out the video below:
Rel8 is now less dependant on the internal Opaleye API. (#204)
1.4.0.0 (2022-08-17)
Breaking changes
The behavior of greatest/least has been corrected, and was previously flipped. (#183)
New features
NullTable/HNull have been added. This is an alternative to MaybeTable that doesn’t use a tag columns. It’s less flexible (no Functor or Applicative instance) and is meaningless when used with a table that has no non-nullable columns (so nesting NullTable is redundant). But in situations where the underlying Table does have non-nullable columns, it can losslessly converted to and from MaybeTable. It is useful for embedding into a base table when you don’t want to store the extra tag column in your schema. (#173)
div and mod have been changed to match Haskell semantics. If you need the PostgreSQL div() and mod() functions, use quot and rem. While this is not an API change, we feel this is a breaking change in semantics and have bumped the major version number. (#155)
New features
divMod and quotRem functions have been added, matching Haskell’s Prelude functions. (#155)
avg and mode aggregation functions to find the mean value of an expression, or the most common row in a query, respectively. (#152)
The full EqTable and OrdTable classes have been exported, allowing for instances to be manually created. (#157)
Added like and ilike (for the LIKE and ILIKE operators). (#146)
castTable has been added, which casts all columns selected from in Query according to the types of columns. This can occasionally be useful when using many/some on older PostgreSQL versions. (#137)
Added <:, <=:, >:, >=:, greatest and least, which sort all columns in a table lexicographically. These operators are like the <. operators which operate on Exprs, but the <: operate on entire tables. (#139)
New $* and $+ operators for projecting out of ListTable and NonEmptyTable respectively (analogous to the existing $? for MaybeTable). (#125)
Bug fixes
Fix UPSERT support (and add tests), which was broken due to a typo inside Rel8 that made it impossible to construct Projections which are needed by UPSERT. (#134)
Remove DBMin and DBMax instances for Bool, which are invalid as far as Postgres is concerned. and and or can be used to achieve the same thing. (#126)
Fix aggregateMaybeTable, aggregateEitherTable and aggregateTheseTable, which generated invalid SQL previously. (#127)
Breaking changes
rebind now takes an additional argument for the “name” of the binding. (#128)
1.1.0.0 (2021-07-16)
New features
You can derive Rel8able for “vanilla” higher-kinded data types - data types that don’t use the Column type family. For example, the following is now possible:
data MyTable f = MyTable
{ myTableX :: f Int32
, myTableY :: f Text
} deriving (Generic, Rel8able)
The Projectable and Biprojectable type classes have been introduced. These classes model a type of functors and bifunctors (respectively) on tables, where the mapping function is only able to rearrange columns. For example, the following is now possible:
x <- project myTableX <$> many ...
Insert‘s onConflict field now has a new option - DoUpdate. This maps to PostgreSQL’s ON CONFLICT DO UPDATE syntax, which provides upsert support. (#85)
Insert, Update and Delete has all been expanded to work with Querys. In particular:
Delete now supports a USING sub-query
Update now supports a FROM sub-query
Insert can delete the result of any arbitrary Query (providing the types match)
The new Rel8.Tabulate module has been added, which gives a Map-esque interface to writing and composing queries. (#70)
The new indexedQuery -> Query function was added. This function augments each row in a query with it’s 0-based index. (#117)
Breaking changes
Insert, Delete and Update have all changed. In particular, for Insert users should now replace rows = xs with rows = values xs. (#85)
Rename whereExists and whereNotExists to present and absent respectively. (#57)
Simplify evaluate to run directly inside the Query monad, rendering the Evaluate monad unnecessary. (#56)
The Labelable type class has been removed as it’s no longer necessary. This class was mostly internal, though was visible in some public API functions. (#76)
EitherTable, ListTable, MaybeTable, NonEmptyTable and TheseTable now all have an extra parameter which tracks the context of the table. If you manually specified any types before, you need to provide this parameter - usually Expr will be the correct choice. (#101)
We’ve done a lot of work to simplify the internals of Rel8, but some of these are breaking changes. However, most of these API changes shouldn’t affect users as they are mostly types used in type inference, or affect classes where users don’t need to define their own instances.
The kind of a Rel8able is now (Type -> Type) -> Type. Previously it was (X -> Type) -> Type.
Table has a new associated type - FromExprs. This was previously an open type family.
Table has a new associated type - Transpose - and Recontextualise has been renamed to Transposes. This Transposes class now operates in terms of Transpose.
select, insert, update and delete now produce Hasql Statements, rather than actually running the statement as IO. This allows Rel8 to be used with transaction/connection-managing monads like hasql-transaction. (#94)
Bug fixes
Fixes a bug where cartesian products of queries using catListTable, catNonEmptyTable, catList and catNonEmpty would incorrectly be zipped instead. (#61)
Require Opaleye 0.7.3.0. This version has better support for lateral queries, which can improve query plans, especially in optional/LEFT JOIN (#72)
