Skip to content

Commit

Permalink
#118: forgotten docs update
Browse files Browse the repository at this point in the history
  • Loading branch information
lsulak committed Apr 3, 2024
1 parent 3455339 commit 4d727e8
Showing 1 changed file with 28 additions and 10 deletions.
38 changes: 28 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,14 +47,16 @@ within the application.**

---

Currently, the library is developed with Postgres as the target DB. But the approach is applicable to any DB supporting stored procedure/functions – Oracle, MS-SQL, ...
Currently, the library is developed with Postgres as the target DB. But the approach is applicable to any DB
supporting stored procedure/functions – Oracle, MS-SQL, ...


## Usage

#### Sbt

Import one of the two available module at the moment. Slick module works with Scala Futures. Doobie module works with any effect type (typically IO or ZIO) provided cats effect's Async instance is available.
Import one of the two available module at the moment. Slick module works with Scala Futures. Doobie module works with
any effect type (typically IO or ZIO) provided cats effect's Async instance is available.

```scala
libraryDependencies *= "za.co.absa.fa-db" %% "slick" % "X.Y.Z"
Expand Down Expand Up @@ -111,16 +113,24 @@ Text about status codes returned from the database function can be found [here](

## Slick module

As the name suggests it runs on [Slick library](https://github.com/slick/slick) and also brings in the [Slickpg library](https://github.com/tminglei/slick-pg/) for extended Postgres type support.
As the name suggests it runs on [Slick library](https://github.com/slick/slick) and also brings in the [Slickpg library](https://github.com/tminglei/slick-pg/) for extended
Postgres type support.

It brings:

* `class SlickPgEngine` - implementation of _Core_'s `DBEngine` executing the queries via Slick
* `class SlickSingleResultFunction` - abstract class for DB functions returning single result
* `class SlickMultipleResultFunction` - abstract class for DB functions returning sequence of results
* `class SlickOptionalResultFunction` - abstract class for DB functions returning optional result
* `class SlickSingleResultFunctionWithStatus` - abstract class for DB functions with status handling; it requires an implementation of `StatusHandling` to be mixed-in (`StandardStatusHandling` available out-of-the-box)
* `trait FaDbPostgresProfile` - to bring support for Postgres and its extended data types in one class (except JSON, as there are multiple implementations for this data type in _Slick-Pg_)
* `class SlickSingleResultFunctionWithStatus` - abstract class for DB functions with status handling; it requires an
implementation of `StatusHandling` to be mixed-in (`StandardStatusHandling` available out-of-the-box)
* `class SlickMultipleResultFunctionWithStatus` - as `SlickSingleResultFunctionWithStatus` but for multiple record
retrieval, it requires an implementation of `StatusAggregation` to be mixed-in
(`AggregateByFirstError`, `AggregateByFirstRow`, and `AggregateByMajorityErrors` available out of the box)
* `class SlickOptionalResultFunctionWithStatus` - as `SlickSingleResultFunctionWithStatus` but the returning record
is optional
* `trait FaDbPostgresProfile` - to bring support for Postgres and its extended data types in one class
(except JSON, as there are multiple implementations for this data type in _Slick-Pg_)
* `object FaDbPostgresProfile` - instance of the above trait for direct use

#### Known issues
Expand All @@ -143,18 +153,26 @@ val macAddr: Option[MacAddrString] = pr.nextMacAddrOption

## Doobie module

As the name suggests it runs on [Doobie library](https://tpolecat.github.io/doobie/). The main benefit of the module is that it allows to use any effect type (typically IO or ZIO) therefore is more suitable for functional programming. It also brings in the [Doobie-Postgres library](https://tpolecat.github.io/doobie/docs/14-PostgreSQL.html) for extended Postgres type support.
As the name suggests it runs on [Doobie library](https://tpolecat.github.io/doobie/). The main benefit of the module is that it allows to use any
effect type (typically IO or ZIO) therefore is more suitable for functional programming.
It also brings in the [Doobie-Postgres library](https://tpolecat.github.io/doobie/docs/14-PostgreSQL.html) for extended Postgres type support.

It brings:

* `class DoobieEngine` - implementation of _Core_'s `DBEngine` executing the queries via Doobie. The class is type parameterized with the effect type.
* `class DoobieSingleResultFunction` - abstract class for DB functions returning single result
* `class DoobieMultipleResultFunction` - abstract class for DB functions returning sequence of results
* `class DoobieOptionalResultFunction` - abstract class for DB functions returning optional result
* `class DoobieSingleResultFunctionWithStatus` - abstract class for DB functions with status handling; it requires an implementation of `StatusHandling` to be mixed-in (`StandardStatusHandling` available out-of-the-box)
* `class DoobieMultipleResultFunctionWithStatus` - as `DoobieSingleResultFunctionWithStatus` but for multiple record retrieval

Since Doobie also interoperates with ZIO, there is an example of how a database connection can be properly established within a ZIO application. Please see [this file](doobie/zio-setup.md) for more details.
* `class DoobieSingleResultFunctionWithStatus` - abstract class for DB functions with status handling; it requires
an implementation of `StatusHandling` to be mixed-in (`StandardStatusHandling` available out-of-the-box)
* `class DoobieMultipleResultFunctionWithStatus` - as `DoobieSingleResultFunctionWithStatus` but for multiple record
retrieval, it requires an implementation of `StatusAggregation` to be mixed-in
(`AggregateByFirstError`, `AggregateByFirstRow`, and `AggregateByMajorityErrors` available out of the box)
* `class DoobieOptionalResultFunctionWithStatus` - as `DoobieSingleResultFunctionWithStatus` but the returning record
is optional

Since Doobie also interoperates with ZIO, there is an example of how a database connection can be properly established
within a ZIO application. Please see [this file](doobie/zio-setup.md) for more details.

## Testing

Expand Down

0 comments on commit 4d727e8

Please sign in to comment.