purescript-postgresql-client/README.md

163 lines
6.0 KiB
Markdown
Raw Normal View History

2016-12-24 12:34:27 +00:00
# purescript-postgresql-client
2019-11-10 14:27:24 +00:00
purescript-postgresql-client is a PostgreSQL client library for PureScript based on `node-postgres`.
2016-12-25 22:58:29 +00:00
## Install
2018-10-22 01:27:35 +00:00
To use this library, you need to add [`pg`][pg] and [`decimal.js`][decimal.js] as an npm dependency. You can also
find first of them on [https://github.com/brianc/node-postgres](https://github.com/brianc/node-postgres).
## Usage
2018-10-21 01:58:45 +00:00
This guide is a literate Purescript file which is extracted into testing module (using [`literate-purescript`](https://github.com/Thimoteus/literate-purescript)) so it is a little verbose.
2018-10-21 09:39:25 +00:00
Let's start with imports.
```purescript
2018-12-06 19:14:08 +00:00
module Test.README where
import Prelude
import Control.Monad.Except.Trans (ExceptT, runExceptT)
import Database.PostgreSQL.PG (defaultPoolConfiguration, PGError, command, execute, newPool, Pool, Connection, query, Query(Query))
import Database.PostgreSQL.PG as PG
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)
2018-10-21 01:56:11 +00:00
import Effect.Class (liftEffect)
import Test.Assert (assert)
2018-10-21 09:39:25 +00:00
```
2018-12-06 19:30:38 +00:00
The whole API for interaction with PostgreSQL is performed asynchronously in `Aff`
2019-05-07 18:16:59 +00:00
(the only function which runs in plain `Effect` is `newPool`). Core library
functions usually results in somthing like `Aff (Either PGError a)` which can be easily
wrapped by user into `ExceptT` or any other custom monad stack.
To be honest we provide alternatives to functions in the `Database.PostgreSQL.PG` module that work on any stack `m` with `MonadError PGError m` and `MonadAff m`.
The module contains two functions `withConnection` and `withTransaction` that require additional parameter - a transformation from a custom monad stack to `Aff (Either PGError a)`.
2019-05-07 18:16:59 +00:00
We are going to work with `PG` type in this tutorial but please don't consider it as the only option
if you encounter any troubles integrating it into your own app monad stack.
2018-12-06 19:30:38 +00:00
```purescript
type PG a = ExceptT PGError Aff a
withConnection :: forall a. Pool -> (Connection -> PG a) -> PG a
withConnection = PG.withConnection runExceptT
withTransaction :: forall a. Connection -> PG a -> PG a
withTransaction = PG.withTransaction runExceptT
```
2018-12-06 19:30:38 +00:00
2019-05-07 18:16:59 +00:00
We assume here that Postgres is running on a standard local port
2018-10-21 09:39:25 +00:00
with `ident` authentication so configuration can be nearly empty (`defaultPoolConfiguration`).
It requires only database name which we pass to `newPool` function.
2019-05-07 18:16:59 +00:00
Additionally we pass `idleTimeoutMillis` value because this code
2018-12-09 20:50:13 +00:00
is run by our test suite and we want to exit after its execution quickly ;-)
2018-10-21 09:39:25 +00:00
2018-10-21 09:39:25 +00:00
```purescript
2018-12-06 19:14:08 +00:00
run ∷ PG Unit
run = do
2018-12-09 20:50:13 +00:00
pool <- liftEffect $ newPool
((defaultPoolConfiguration "purspg") { idleTimeoutMillis = Just 1000 })
withConnection pool \conn -> do
2018-10-21 09:39:25 +00:00
```
We can now create our temporary table which we are going to query in this example.
`execute` ignores result value which is what we want in this case.
2018-10-21 09:41:25 +00:00
The last `Row0` value indicates that this `Query` doesn't take any additional parameters.
2018-10-21 09:39:25 +00:00
```purescript
execute conn (Query """
2018-10-21 01:56:11 +00:00
CREATE TEMPORARY TABLE fruits (
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
2018-10-21 09:39:25 +00:00
```
There is `withTransaction` helper provided. You can wrap the whole
piece of interaction with database in it. It will rollback if any exception
is thrown during execution of a given `Aff` block. It excecutes `COMMIT`
in the other case.
We start our session with insert of some data. It is done by `execute`
function with `INSERT` statement.
Please notice that we are passing a tuple of the arguments to this query
using dedicated constructor. In this case `Row3`. This library provides types
from `Row0` to `Row19` and they are wrappers which provide instances for
automatic conversions from and to SQL values.
2019-05-07 18:16:59 +00:00
For details please investigate following classes `ToSQLRow`, `ToSQLValue`,
`FromSQLRow` and `FromSQLValue`.
```purescript
withTransaction conn $ do
execute conn (Query """
INSERT INTO fruits (name, delicious, price)
VALUES ($1, $2, $3)
""") (Row3 "coconut" true (Decimal.fromString "8.30"))
2018-10-21 09:39:25 +00:00
```
2018-10-21 09:39:25 +00:00
We can also use nested tuples instead of `Row*` constructors. This can be a bit more
verbose but is not restricted to limited and constant number of arguments.
`/\` is just an alias for the `Tuple` constructor from `Data.Tuple.Nested`.
2018-10-21 09:39:25 +00:00
```purescript
execute conn (Query """
INSERT INTO fruits (name, delicious, price)
VALUES ($1, $2, $3)
""") ("lemon" /\ false /\ Decimal.fromString "3.30")
2018-10-21 09:39:25 +00:00
```
Of course `Row*` types and nested tuples can be also used when we are fetching
data from db.
`query` function processes db response and returns an `Array` of rows.
```purescript
names <- query conn (Query """
SELECT name, delicious
FROM fruits
ORDER BY name ASC
""") Row0
liftEffect <<< assert $ names == ["coconut" /\ true, "lemon" /\ false]
2018-10-21 09:39:25 +00:00
```
There is also a `command` function at our disposal.
Some postgres SQL expressions return a "command tag" which carries
a value with a number of rows which were affected by a given query.
2018-10-21 09:39:25 +00:00
For example we can have: `DELETE rows`, `UPDATE rows`, `INSERT oid rows` etc.
This function should return `rows` value associated with given response.
2018-10-21 09:39:25 +00:00
```purescript
deleted <- command conn (Query """DELETE FROM fruits """) Row0
liftEffect <<< assert $ deleted == 2
```
2018-10-21 01:32:06 +00:00
## Testing
Currently tests are prepared to work with default and local setup for postgresql (ident authentication, standart port etc.).
If you think that we should add configuration layer for our test runner please open an issue.
2018-10-21 02:22:16 +00:00
To run suite please:
2018-10-21 01:32:06 +00:00
* `$ npm install`
2018-10-21 01:32:06 +00:00
* `$ createdb purspg`
2018-10-21 01:32:06 +00:00
* `$ npm run test`
2018-04-22 14:52:32 +00:00
## Generating SQL Queries
2019-05-07 18:16:59 +00:00
The `purspg` preprocessor has been replaced by `sqltopurs`, which is a code
2017-06-03 12:06:09 +00:00
generator instead of a preprocessor, and easier to use.
[sqltopurs]: https://github.com/rightfold/sqltopurs
2018-10-22 01:27:35 +00:00
[pg]: https://www.npmjs.com/package/pg
[decimal.js]: https://www.npmjs.com/package/decimal.js