purescript-postgresql-client/README.md

purescript-postgresql-client

purescript-postgresql-client is a PostgreSQL client library for PureScript.

Install

To use this library, you need to add pg and decimal.js as an npm dependency. You can also find first of them on [https://github.com/brianc/node-postgres][pg].

Usage

This guide is a literate Purescript file which is compiled into testing module (using literate-purescript - check bin/docs.sh) so it is a little verbose.

Let's start with imports and some testing boilerplate.

module Test.Example where

import Prelude

import Database.PostgreSQL (defaultPoolConfiguration, execute, newPool, Query(Query), withConnection)
import Database.PostgreSQL.Row (Row0(Row0), Row3(Row3))
import Data.Decimal as Decimal
import Data.Maybe (Maybe(..))
import Data.Tuple.Nested ((/\))
import Effect.Aff (Aff)

-- Our interaction with db is performed asynchronously in `Aff`
run ∷ Aff Unit
run = do

  -- Now we are able to setup connection. We are assuming here
  -- that postgres is running on a standard local port.
  -- We use `ident` authentication so configuration can be nearly empty.
  -- It requires only database name which we pass to `newPool` function.
  -- We want to close connection after a second (`idleTimeoutMillis` setting) because this code
  -- would be run by our test suite ;-)
  -- Of course you can provide additional configuration settings if you need to.

  pool <- newPool ((defaultPoolConfiguration "purspg") { idleTimeoutMillis = Just 1000 })
  withConnection pool \conn -> do

    -- We can now create our temporary table which we are going to query in this example.
    -- `execute` performs this query. It ignores result value by default.
 
    execute conn (Query """
      CREATE TEMPORARY TABLE foods (
        name text NOT NULL,
        delicious boolean NOT NULL,
        price NUMERIC(4,2) NOT NULL,
        added TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
        PRIMARY KEY (name)
      );
    """) Row0

    -- We can insert some data calling `execute` function with `INSERT` statement.
    -- Please notice that we are passing a tuple of arguments to this query
    -- using dedicated constructor (in this case `Row3`).
    -- This library provides types from `Row0` to `Row19` and they are wrappers which
    -- provides instances for automatic conversions from and to SQL values.

    execute conn (Query """
      INSERT INTO foods (name, delicious, price)
      VALUES ($1, $2, $3)
    """) (Row3 "pork" true (Decimal.fromString "8.30"))


    -- You can also use nested tuples instead of `Row*` types but this can be a bit more
    -- verbose. `/\` is just an alias for `Tuple` constructor.

    execute conn (Query """
      INSERT INTO foods (name, delicious, price)
      VALUES ($1, $2, $3)
    """) ("sauerkraut" /\ false /\ Decimal.fromString "3.30")

Generating SQL Queries

The purspgpp preprocessor has been replaced by sqltopurs, which is a code generator instead of a preprocessor, and easier to use.

Testing

To run tests you have to prepare "purspg" database and use standard command: pulp test.