Hasql

PostgreSQL driver for Haskell, that prioritizes:

• Reliability
• Flexibility
• Performance

Status

Hasql is production-ready, actively maintained and the API is moderately stable. It's used by many companies and most notably by the Postgrest project.

Pluggable Transport

Hasql's transport is pluggable via pqi. Hasql itself carries no C dependency. It programs against the pqi interface, and you pick the adapter that implements it. That means you depend on two packages, not one:

build-depends:
  hasql,
  pqi-ffi,  -- or pqi-native

Hasql.Connection.acquire then takes the adapter explicitly, as its first argument:

import Pqi.Ffi qualified    -- the C-backed libpq transport
import Pqi.Native qualified -- alpha: pure-Haskell, no C dependency, interchangeable with Pqi.Ffi

connection <- Hasql.Connection.acquire Pqi.Ffi.adapter settings
-- or
connection <- Hasql.Connection.acquire Pqi.Native.adapter settings

pqi-ffi is the stable, production-proven default. It binds the C libpq library, so it requires libpq of at least version 14 to be installed to compile - which typically just means having a recent PostgreSQL distro installed. Through it Hasql is tested against a wide range of PostgreSQL servers, starting from version 9.

pqi-native is a from-scratch, pure-Haskell implementation of the Postgres wire protocol, with no C dependency at all. It is thoroughly tested: pqi-conformance runs it side by side with libpq on the same inputs and checks that the results agree, and the test-suites of hasql, hasql-pool and hasql-transaction now run against both adapters, so the whole stack above the transport is exercised on pqi-native too. It's still labelled alpha - not yet proven at production scale. The two adapters are fully interchangeable: swapping between them is a one-line change (a different Adapter value, nothing else), so you can try pqi-native today with no lock-in and no rewrite to fall back if needed.

Ecosystem

Hasql is not just a single library, it is a granular ecosystem of composable libraries, each isolated to perform its own task and stay simple.

• "hasql" - the root of the ecosystem, which provides the essential abstraction over the PostgreSQL client functionality and mapping of values. Everything else revolves around that library.

• "hasql-transaction" - an STM-inspired composable abstraction over database transactions providing automated conflict resolution.

• "hasql-pool" - a Hasql-specialized abstraction over the connection pool.

• "hasql-postgresql-types" - integration with the "postgresql-types" library, which is a collection of Haskell types precisely modeling PostgreSQL types without data loss or compromise.

• "hasql-dynamic-statements" - a toolkit for generating statements based on the parameters.

• "hasql-th" - Template Haskell utilities, providing compile-time syntax checking and easy statement declaration.

• "hasql-cursor-query" - a declarative abstraction over cursors.

• "hasql-cursor-transaction" - a lower-level abstraction over cursors, which however allows to fetch from multiple cursors simultaneously. Generally though "hasql-cursor-query" is the recommended alternative.

• "hasql-migration" - A port of postgresql-simple-migration for use with hasql.

• "hasql-listen-notify" / "hasql-notifications" - Support for PostgreSQL asynchronous notifications.

• "hasql-optparse-applicative" - "optparse-applicative" parsers for Hasql.

• "hasql-implicits" - implicit definitions, such as default codecs for standard types.

• "hasql-interpolate" - a QuasiQuoter that supports interpolating Haskell expressions into Hasql queries.

^{Want to list your package or correct something here? Make a PR.}

Transport adapters

Unlike the extension libraries above, which are optional, a transport adapter is mandatory: Hasql needs one to talk to the server at all. See Pluggable Transport for how to pick one.

• "pqi" - the driver-agnostic interface that Hasql programs against. Pulled in automatically. You don't depend on it directly.

• "pqi-ffi" - the stable adapter, backed by the C libpq library.

• "pqi-native" - an alpha pure-Haskell adapter speaking the PostgreSQL wire protocol directly, with no C dependency.

Why make it an ecosystem?

• Focus. Each library in isolation provides a simple API, which is focused on a specific task or a few related tasks.

• Flexibility. The user picks and chooses the features, thus precisely matching the level of abstraction that he needs for his task.

• Much more stable and descriptive semantic versioning. E.g., a change in the API of the "hasql-transaction" library won't affect any of the other libraries and it gives the user a more precise information about which part of his application he needs to update to conform.

• Interchangeability and competition of the ecosystem components. E.g., not everyone will agree with the restrictive design decisions made in the "hasql-transaction" library. However those decisions are not imposed on the user, and instead of having endless debates about how to abstract over transactions, another extension library can simply be released, which will provide a different interpretation of what the abstraction over transactions should be.

• Horizontal scalability of the ecosystem. Instead of posting feature- or pull-requests, the users are encouraged to release their own small extension-libraries, with themselves becoming the copyright owners and taking on the maintenance responsibilities. Compare this model to the classical one, where some core-team is responsible for everything. One is scalable, the other is not.

Documentation

• Data-Access Architecture — a normative reference for organising database integration code built on Hasql. It specifies how to layer types, statements, transactions and sessions, where the application domain enters the picture, how the three error channels differ, and what to test at each level. Every rule carries its rationale and derives from the capability differences between Hasql's four constructs.

The reference is written to be consumed directly by coding agents as well as by people. Point an agent at the raw file and it has the whole system in context, with the rules numbered so they can be cited back in review.

Short Example

Following is a complete application, which performs some arithmetic in Postgres using Hasql.

{-# LANGUAGE OverloadedStrings, QuasiQuotes #-}

import Data.Functor.Contravariant
import Data.Int
import Hasql.Session (Session)
import Prelude
import qualified Hasql.Connection as Connection
import qualified Hasql.Connection.Settings as Settings
import qualified Hasql.Decoders as Decoders
import qualified Hasql.Encoders as Encoders
import qualified Hasql.Session as Session
import qualified Hasql.Statement as Statement
import qualified Pqi.Ffi -- from "pqi-ffi" (stable). Swap for "Pqi.Native" from "pqi-native" (alpha, fully interchangeable) to try the pure-Haskell backend

main :: IO ()
main = do
  Right connection <- Connection.acquire Pqi.Ffi.adapter connectionSettings
  result <- Connection.use connection (sumAndDivModSession 3 8 3)
  print result
  where
    connectionSettings =
      mconcat
        [ Settings.hostAndPort "localhost" 5432,
          Settings.user "postgres",
          Settings.password "postgres",
          Settings.dbname "postgres"
          -- Prepared statements are enabled by default.
          -- To disable them (e.g., for pgbouncer compatibility):
          -- Settings.noPreparedStatements True
        ]

-- * Sessions

-- Session abstracts over the execution of operations on a database connection.
-- It is composable and has a Monad instance.
-------------------------

sumAndDivModSession :: Int64 -> Int64 -> Int64 -> Session (Int64, Int64)
sumAndDivModSession a b c = do
  -- Get the sum of a and b
  sumOfAAndB <- Session.statement (a, b) sumStatement
  -- Divide the sum by c and get the modulo as well
  Session.statement (sumOfAAndB, c) divModStatement

-- * Statements

-- Statement is a definition of an individual SQL-statement,
-- accompanied by a specification of how to encode its parameters and
-- decode its result.
-------------------------

-- | A statement with two integer parameters and an integer result.
sumStatement :: Statement.Statement (Int64, Int64) Int64
sumStatement = Statement.preparable sql encoder decoder
  where
    -- The SQL of the statement, with $1, $2, ... placeholders for parameters.
    sql =
      "select $1 + $2"
    -- Specification of how to encode the parameters of the statement
    -- where the association with placeholders is achieved by order.
    encoder =
      mconcat
        [ -- Encoder of the first parameter as a non-nullable int8.
          -- It extracts the first element of the tuple using the contravariant functor
          -- instance.
          fst >$< Encoders.param (Encoders.nonNullable Encoders.int8),
          -- Encoder of the second parameter,
          -- which extracts the second element of the tuple.
          snd >$< Encoders.param (Encoders.nonNullable Encoders.int8)
        ]
    -- Specification of how to decode the result of the statement.
    -- States that we expect a single row with a single non-nullable int8 column.
    decoder =
      Decoders.singleRow
        (Decoders.column (Decoders.nonNullable Decoders.int8))

divModStatement :: Statement.Statement (Int64, Int64) (Int64, Int64)
divModStatement = Statement.preparable sql encoder decoder
  where
    sql =
      "select $1 / $2, $1 % $2"
    encoder =
      mconcat
        [ fst >$< Encoders.param (Encoders.nonNullable Encoders.int8),
          snd >$< Encoders.param (Encoders.nonNullable Encoders.int8)
        ]
    -- Decoder that expects a single row with two non-nullable int8 columns,
    -- returning the result as a tuple.
    -- Uses the applicative functor instance to combine two column decoders.
    decoder =
      Decoders.singleRow
        ( (,)
            <$> Decoders.column (Decoders.nonNullable Decoders.int8)
            <*> Decoders.column (Decoders.nonNullable Decoders.int8)
        )

For the general use-case it is advised to prefer declaring statements using the "hasql-th" library, which validates the statements at compile-time and generates codecs automatically. So the above two statements could be implemented the following way:

import qualified Hasql.TH as TH -- from "hasql-th"

sumStatement :: Statement.Statement (Int64, Int64) Int64
sumStatement =
  [TH.singletonStatement|
    select ($1 :: int8 + $2 :: int8) :: int8
  |]

divModStatement :: Statement.Statement (Int64, Int64) (Int64, Int64)
divModStatement =
  [TH.singletonStatement|
    select
      (($1 :: int8) / ($2 :: int8)) :: int8,
      (($1 :: int8) % ($2 :: int8)) :: int8
  |]

Discussions

Join GitHub Discussions to ask questions, provide feedback, suggest and vote on features, and help shape the future of Hasql.

Support Policy

This policy is intended to balance stability for users with the ability to evolve the library.

Each major release of Hasql is supported for at least one year from the date of its first release. During this period, fixes are backported to the latest minor version of that major release.

After the support period ends, the release may continue to work but is no longer guaranteed to receive fixes.

You're welcome to post requests to change the policy or issues if you believe something is not being addressed.