Orville - Getting Started

Orville is a PostgreSQL client library, so it needs a working PostgreSQL server to work. This tutorial assumes that PostgreSQL in running on localhost, listening on port 5432 and that the user postgres exists with password postgres.

Orville itself depends on the native LibPQ library being installed to communicate with the server, so we need to install it before building everything. If you’re on Debian-like distribution that uses apt, this command will do that.

shell

apt update
apt install -y libpq-dev

With that setup out of the way, let’s make a new project for this demo:

shell

mkdir orville-getting-started
cd orville-getting-started
stack new orville-getting-started --bare simple --resolver lts-21.19

Now we need to edit stack.yaml and add orville-postgresql as an extra-dep.

stack.yaml : diff

42c42,43
< # extra-deps: []
---
> extra-deps:
>  - orville-postgresql-1.0.0.0

Next, edit the orville-getting-started.cabal file to make it depend on Orville.

orville-getting-started.cabal : diff

22c22
<   build-depends:       base >= 4.7 && < 5
---
>   build-depends:       base >= 4.7 && < 5, orville-postgresql ^>= 1.0.0.0

Here is a minimal program that simply computes 1+1 on the database. Replace the src/Main.hs with it.

src/Main.hs : haskell

module Main
  ( main
  ) where

import qualified Orville.PostgreSQL as O
import qualified Orville.PostgreSQL.Execution as Execution
import qualified Orville.PostgreSQL.Raw.Connection as Connection
import qualified Orville.PostgreSQL.Raw.RawSql as RawSql
import qualified Orville.PostgreSQL.Raw.SqlValue as SqlValue

main :: IO ()
main = do
  pool <-
    O.createConnectionPool
        O.ConnectionOptions
          { O.connectionString = "host=localhost user=postgres password=postgres"
          , O.connectionNoticeReporting = O.DisableNoticeReporting
          , O.connectionPoolStripes = O.OneStripePerCapability
          , O.connectionPoolLingerTime = 10
          , O.connectionPoolMaxConnections = O.MaxConnectionsPerStripe 1
          }

  Connection.withPoolConnection pool $ \connection -> do
    result <- RawSql.execute connection (RawSql.fromString "SELECT 1+1")
    [[(_, sqlValue)]] <- Execution.readRows result
    print (SqlValue.toInt sqlValue)

All that’s left is to build the executable and run it. When it runs it will connect to the PostgreSQL server, run the SQL to calculate 1 + 1 and then print the result out.

shell

stack build
stack exec orville-getting-started

This is the output you will see in the console if everything went as planned:

output : plaintext

Right 2