generated from tpl/purs
docs: update readme
This commit is contained in:
Orion Kindel
parent
f16a348414
commit
2d1f2e4695
GPG Key ID:
6D4165AE4C928719
136
README.md
136
README.md
@ -8,6 +8,7 @@ Purescript PostgreSQL driver
|
|||||||
- [Ranges](#data---ranges)
|
- [Ranges](#data---ranges)
|
||||||
- [Queries](#queries)
|
- [Queries](#queries)
|
||||||
- [Builder](#queries---builder)
|
- [Builder](#queries---builder)
|
||||||
|
- [Errors](#errors)
|
||||||
- [Monads](#monads)
|
- [Monads](#monads)
|
||||||
- [`PostgresT`](#monads---postgrest)
|
- [`PostgresT`](#monads---postgrest)
|
||||||
- [`SessionT`](#monads---sessiont)
|
- [`SessionT`](#monads---sessiont)
|
||||||
@ -50,11 +51,12 @@ import Effect.Class (liftEffect)
|
|||||||
import Effect.Aff (launchAff_)
|
import Effect.Aff (launchAff_)
|
||||||
import Effect.Console (log)
|
import Effect.Console (log)
|
||||||
import Control.Monad.Postgres (runPostgres, query)
|
import Control.Monad.Postgres (runPostgres, query)
|
||||||
|
import Effect.Postgres.Error.Except as PG.X
|
||||||
|
|
||||||
main :: Effect Unit
|
main :: Effect Unit
|
||||||
main =
|
main =
|
||||||
launchAff_ do
|
launchAff_ do
|
||||||
msg <- runPostgres pgConfig $ query "select 'hello, world!'"
|
msg <- PG.X.run $ runPostgres pgConfig $ query "select 'hello, world!'"
|
||||||
liftEffect $ log msg -- logs 'hello, world!'
|
liftEffect $ log msg -- logs 'hello, world!'
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -191,21 +193,37 @@ that will reference that value in the query.
|
|||||||
|
|
||||||
[`Query.Builder.build`] renders the query to [`Query`]
|
[`Query.Builder.build`] renders the query to [`Query`]
|
||||||
|
|
||||||
|
## Errors
|
||||||
|
Errors are wrapped in [`Error`]:
|
||||||
|
```haskell
|
||||||
|
data Error
|
||||||
|
= Deserializing Query Foreign.MultipleErrors
|
||||||
|
| Serializing Foreign.MultipleErrors
|
||||||
|
| Executing Query Effect.Error
|
||||||
|
| Connecting Effect.Error
|
||||||
|
| Disconnecting Effect.Error
|
||||||
|
| Other Effect.Error
|
||||||
|
```
|
||||||
|
|
||||||
|
Most operations in this library return a [`Except`], which is just
|
||||||
|
`ExceptT` pinned to `NonEmptyArray Error`.
|
||||||
|
|
||||||
|
This can be unlifted to `Aff` with [`Except.run`].
|
||||||
|
|
||||||
## Monads
|
## Monads
|
||||||
### Monads - `PostgresT`
|
### Monads - `PostgresT`
|
||||||
[`PostgresT`] is the database driver's main entry point,
|
[`PostgresT`] is a monadic context with a connection [`Pool`]. It allows running [`transaction`]s, simple [queries][`query`] and more.
|
||||||
and is just an `Aff` with access to a [`Pool`].
|
|
||||||
|
|
||||||
Run in `Aff` with [`runPostgres`]:
|
#### Running in Aff
|
||||||
```purescript
|
```purescript
|
||||||
main :: Effect Unit
|
main :: Effect Unit
|
||||||
main =
|
main =
|
||||||
launchAff_ do
|
launchAff_ do
|
||||||
hi <- runPostgres {} $ query "select 'hi!'"
|
hi <- PG.X.run $ runPostgres {} $ query "select 'hi!'"
|
||||||
liftEffect $ log hi
|
liftEffect $ log hi
|
||||||
```
|
```
|
||||||
|
|
||||||
Execute [`SessionT`] monads with [`session`] or [`transaction`]:
|
#### Executing a transaction
|
||||||
```purescript
|
```purescript
|
||||||
dbMain :: PostgresT Aff Unit
|
dbMain :: PostgresT Aff Unit
|
||||||
dbMain = do
|
dbMain = do
|
||||||
@ -220,7 +238,7 @@ dbMain = do
|
|||||||
pure unit
|
pure unit
|
||||||
```
|
```
|
||||||
|
|
||||||
Implements [`MonadSession`] as a shorthand for single-query [`session`]s:
|
#### Simple queries
|
||||||
```purescript
|
```purescript
|
||||||
dbMain :: PostgresT Aff Int
|
dbMain :: PostgresT Aff Int
|
||||||
dbMain = exec_ $ "insert into persons (name) values ($1);" /\ "Sarah"
|
dbMain = exec_ $ "insert into persons (name) values ($1);" /\ "Sarah"
|
||||||
@ -228,7 +246,7 @@ dbMain = exec_ $ "insert into persons (name) values ($1);" /\ "Sarah"
|
|||||||
-- dbMain = session $ exec_ ...
|
-- dbMain = session $ exec_ ...
|
||||||
```
|
```
|
||||||
|
|
||||||
Execute [`CursorT`] monads with [`cursor`]:
|
#### Executing cursor queries
|
||||||
```purescript
|
```purescript
|
||||||
dbMain :: PostgresT Aff Int
|
dbMain :: PostgresT Aff Int
|
||||||
dbMain =
|
dbMain =
|
||||||
@ -241,12 +259,12 @@ dbMain =
|
|||||||
```
|
```
|
||||||
|
|
||||||
### Monads - `SessionT`
|
### Monads - `SessionT`
|
||||||
[`SessionT`] is an `Aff` with access to a [`Client`]
|
[`SessionT`] is a context that can run queries using a specific [`Client`].
|
||||||
issued by a [`Pool`], connected to the database.
|
|
||||||
|
|
||||||
Run in [`PostgresT`] with [`session`] or [`transaction`]
|
Sessions can be started in [`PostgresT`], which will ask the [`Pool`] for a [`Client`],
|
||||||
|
then release the [`Client`] after the session completes.
|
||||||
|
|
||||||
Perform queries with [`query`], [`exec`] or [`exec_`]
|
Within sessions, queries can be performed with [`query`], [`exec`] and [`exec_`].
|
||||||
|
|
||||||
### Monads - `CursorT`
|
### Monads - `CursorT`
|
||||||
[`CursorT`] is a transaction [`SessionT`] with access to a named server-side cursor.
|
[`CursorT`] is a transaction [`SessionT`] with access to a named server-side cursor.
|
||||||
@ -267,59 +285,63 @@ the api of [`node-postgres`]:
|
|||||||
- release clients with [`Pool.release`] or [`Pool.destroy`]
|
- release clients with [`Pool.release`] or [`Pool.destroy`]
|
||||||
- release with [`Pool.end`]
|
- release with [`Pool.end`]
|
||||||
|
|
||||||
[`Pool`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Pool#t:Pool
|
[`Pool`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Pool#t:Pool
|
||||||
[`Config`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Pool#t:Config
|
[`Config`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Pool#t:Config
|
||||||
[`Pool.make`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Pool#v:make
|
[`Pool.make`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Pool#v:make
|
||||||
[`Pool.end`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Pool#v:end
|
[`Pool.end`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Pool#v:end
|
||||||
[`Pool.connect`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Pool#v:connect
|
[`Pool.connect`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Pool#v:connect
|
||||||
[`Pool.destroy`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Pool#v:destroy
|
[`Pool.destroy`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Pool#v:destroy
|
||||||
[`Pool.release`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Pool#v:release
|
[`Pool.release`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Pool#v:release
|
||||||
|
|
||||||
[`Client`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Client#t:Client
|
[`Client`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Client#t:Client
|
||||||
[`Client.end`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Client#v:end
|
[`Client.end`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Client#v:end
|
||||||
[`Client.make`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Client#v:make
|
[`Client.make`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Client#v:make
|
||||||
[`Client.connected`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Client#v:connected
|
[`Client.connected`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Client#v:connected
|
||||||
[`Client.query`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Client#v:query
|
[`Client.query`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Client#v:query
|
||||||
[`Client.queryRaw`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Client#v:queryRaw
|
[`Client.queryRaw`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Client#v:queryRaw
|
||||||
[`Client.exec`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Effect.Aff.Postgres.Client#v:exec
|
[`Client.exec`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Aff.Postgres.Client#v:exec
|
||||||
|
|
||||||
[`Range`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Range#t:Range
|
[`Range`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Range#t:Range
|
||||||
[`Range.gt`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Range#v:gt
|
[`Range.gt`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Range#v:gt
|
||||||
[`Range.gte`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Range#v:gte
|
[`Range.gte`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Range#v:gte
|
||||||
[`Range.lt`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Range#v:lt
|
[`Range.lt`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Range#v:lt
|
||||||
[`Range.lte`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Range#v:lte
|
[`Range.lte`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Range#v:lte
|
||||||
|
|
||||||
[`Raw`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Raw#t:Raw
|
[`Raw`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Raw#t:Raw
|
||||||
[`Null`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Raw#t:Null
|
[`Null`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Raw#t:Null
|
||||||
|
|
||||||
[`Serialize`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres#t:Serialize
|
[`Serialize`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres#t:Serialize
|
||||||
[`Deserialize`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres#t:Deserialize
|
[`Deserialize`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres#t:Deserialize
|
||||||
[`Rep`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres#t:Rep
|
[`Rep`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres#t:Rep
|
||||||
[`modifyPgTypes`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres#v:modifyPgTypes
|
[`modifyPgTypes`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres#v:modifyPgTypes
|
||||||
|
|
||||||
[`Result`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Result#t:Result
|
[`Result`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Result#t:Result
|
||||||
[`FromRow`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Result#t:FromRow
|
[`FromRow`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Result#t:FromRow
|
||||||
[`FromRows`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Result#t:FromRows
|
[`FromRows`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Result#t:FromRows
|
||||||
|
|
||||||
[`Query`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Query#t:Query
|
[`Query`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Query#t:Query
|
||||||
[`AsQuery`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Query#t:AsQuery
|
[`AsQuery`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Query#t:AsQuery
|
||||||
|
|
||||||
[`Query.Builder`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Query.Builder#t:Builder
|
[`Query.Builder`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Query.Builder#t:Builder
|
||||||
[`Query.Builder.param`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Query.Builder#v:param
|
[`Query.Builder.param`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Query.Builder#v:param
|
||||||
[`Query.Builder.build`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Data.Postgres.Query.Builder#v:build
|
[`Query.Builder.build`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Data.Postgres.Query.Builder#v:build
|
||||||
|
|
||||||
[`MonadCursor`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Control.Monad.Postgres#t:MonadCursor
|
[`Except`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Postgres.Error.Except#t:Except
|
||||||
[`MonadSession`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Control.Monad.Postgres#t:MonadSession
|
[`Error`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Postgres.Error#t:Error
|
||||||
[`CursorT`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Control.Monad.Postgres#t:CursorT
|
[`Except.run`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Effect.Postgres.Error.Except#v:run
|
||||||
[`SessionT`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Control.Monad.Postgres#t:SessionT
|
|
||||||
[`PostgresT`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Control.Monad.Postgres#t:PostgresT
|
[`MonadCursor`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Control.Monad.Postgres#t:MonadCursor
|
||||||
[`cursor`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Control.Monad.Postgres#v:cursor
|
[`MonadSession`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Control.Monad.Postgres#t:MonadSession
|
||||||
[`session`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Control.Monad.Postgres#v:session
|
[`CursorT`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Control.Monad.Postgres#t:CursorT
|
||||||
[`transaction`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Control.Monad.Postgres#v:transaction
|
[`SessionT`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Control.Monad.Postgres#t:SessionT
|
||||||
[`runPostgres`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Control.Monad.Postgres#v:runPostgres
|
[`PostgresT`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Control.Monad.Postgres#t:PostgresT
|
||||||
[`query`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Control.Monad.Postgres#v:query
|
[`cursor`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Control.Monad.Postgres#v:cursor
|
||||||
[`exec`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Control.Monad.Postgres#v:exec
|
[`session`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Control.Monad.Postgres#v:session
|
||||||
[`exec_`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/Control.Monad.Postgres#v:exec_
|
[`transaction`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Control.Monad.Postgres#v:transaction
|
||||||
|
[`runPostgres`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Control.Monad.Postgres#v:runPostgres
|
||||||
|
[`query`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Control.Monad.Postgres#v:query
|
||||||
|
[`exec`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Control.Monad.Postgres#v:exec
|
||||||
|
[`exec_`]: https://pursuit.purescript.org/packages/purescript-postgresql/2.0.19/docs/Control.Monad.Postgres#v:exec_
|
||||||
|
|
||||||
[`node-postgres`]: https://node-postgres.com/
|
[`node-postgres`]: https://node-postgres.com/
|
||||||
[`pg-types`]: https://github.com/brianc/node-pg-types/
|
[`pg-types`]: https://github.com/brianc/node-pg-types/
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user