pg-entity: A pleasant PostgreSQL layer

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

A PostgreSQL layer to safely expand your SQL queries with a lightweight eDSL. Read the tutorial at https://tchoutri.github.io/pg-entity/Tutorial


[Skip to Readme]

Properties

Versions 0.0.1.0, 0.0.2.0, 0.0.3.0, 0.0.4.0, 0.0.4.1, 0.0.4.1, 0.0.4.2, 0.0.4.3, 0.0.4.4
Change log CHANGELOG.md
Dependencies base (>=4.12 && <4.18.0), bytestring (>=0.11 && <0.12), colourista (>=0.1 && <0.2), containers, directory, exceptions (>=0.10 && <0.11), literatex, monad-control (>=1.0 && <1.1), mtl, parsec (>=3.1 && <3.2), pg-entity, pg-transact (>=0.3 && <0.4), postgresql-simple (>=0.6 && <0.7), resource-pool (>=0.3 && <0.4), safe-exceptions (>=0.1 && <0.2), shake, strict, template-haskell (>=2.15.0.0 && <2.18.0.0.0), text (>=2.0 && <2.1), text-display (>=0.0 && <0.1), text-manipulate (>=0.3 && <0.4), time (>=1.12 && <1.13), uuid (>=1.3 && <1.4), vector (>=0.13 && <0.14) [details]
License MIT
Author Théophile Choutri
Maintainer Théophile Choutri
Category Database
Home page https://tchoutri.github.io/pg-entity
Bug tracker https://github.com/tchoutri/pg-entity/issues
Source repo head: git clone https://github.com/tchoutri/pg-entity
Uploaded by hecate at 2023-01-01T20:20:39Z

Modules

[Index] [Quick Jump]

Flags

Manual Flags

NameDescriptionDefault
prod

This flag enables features for production usage, like disabling logs

Disabled
book

Enable the generation of the book

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for pg-entity-0.0.4.1

[back to package description]

pg-entity

CI badge made with Haskell Hackage

This library is a pleasant layer on top of postgresql-simple to safely expand the fields of a table when writing SQL queries.
It aims to be a convenient middle-ground between rigid ORMs and hand-rolled SQL query strings. Here is its philosophy:

Its dependency footprint is optimised for my own setups, and as such it makes use of text, vector and pg-transact.

Table of Contents

Installation

At present time, pg-entity is published on Hackage but not on Stackage. To use it in your projects, add it in your cabal file like this:

pg-entity ^>= 0.0

or in your stack.yaml file:

extra-deps:
  - pg-entity-0.0.4.0

Documentation

This library aims to be thoroughly tested, by the means of Oleg Grenrus' cabal-docspec and more traditional tests for database roundtrips.

I aim to produce and maintain a decent documentation, therefore do not hesitate to raise an issue if you feel that something is badly explained and should be improved.

You will find the Tutorial here, and you will find below a short showcase of the library.

Escape hatches

Safe SQL generation is a complex subject, and it is far from being the objective of this library. The main topic it addresses is listing the fields of a table, which is definitely something easier. This is why every level of this wrapper is fully exposed, so that you can drop down a level at your convience.

It is my personal belief, firmly rooted in experience, that we should not aim to produce statically-checked SQL and have it "verified" by the compiler. The techniques that would allow that in Haskell are still far from being optimised and ergonomic. As such, this library makes no effort to produce semantically valid SQL queries, because one would have to encode the semantics of SQL in the type system (or in a rule engine of some sort), and this is clearly not the kind of things I want to spend my youth on.

Each function is tested for its output with doctests, and the ones that cannot (due to database connections) are tested in the more traditional test-suite.

The conclusion is : Test your DB queries. Test the encoding/decoding. Make roundtrip tests for your data-structures.

Acknowledgements

I wish to thank