https://github.com/absaoss/fa-db
Functional Access to Database
https://github.com/absaoss/fa-db
Last synced: 6 months ago
JSON representation
Functional Access to Database
- Host: GitHub
- URL: https://github.com/absaoss/fa-db
- Owner: AbsaOSS
- License: apache-2.0
- Created: 2022-01-14T01:14:58.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2024-04-10T11:58:48.000Z (almost 2 years ago)
- Last Synced: 2024-04-12T07:05:51.155Z (almost 2 years ago)
- Language: Scala
- Size: 705 KB
- Stars: 2
- Watchers: 11
- Forks: 0
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/codeowners
Awesome Lists containing this project
README
# fa-db
## _Functional Access to Database_
### Build Status
[](https://github.com/AbsaOSS/fa-db/actions)
[](https://search.maven.org/search?q=g:za.co.absa.db.fa-db)
___
- [What is fa-db](#what-is-fa-db)
- [Usage](#usage)
- [Concepts](#concepts)
- [Slick module](#slick-module)
- [Testing](#testing)
- [How to Release](#how-to-release)
## What is fa-db
This library is a less traditional way to facilitate data between an application and an SQL Database.
Traditionally application directly applies SQL queries or use some ORM framework. While the first approach mixes two
rather different domain languages within one source, the second too often fails in case of more complicated queries and
table relations.
---
This library offers a different approach.
The idea is that the application transfers data to and from using database stored procedures/functions (from here on
referenced in this library as _DB functions_). This establishes a stable contract between the DB and the application. To
emphasize – the data are both **read** and **written** to/from DB using _DB functions_.
**The purpose of the library then is to facilitate an easy and natural – meaning Scala style – call of the _DB functions_
within the application.**
Benefits:
* Stable contract between the application and the DB
* Early locking of the data model
* Separation of the domains while keeping each part doing what they are good for:
* the application parsing and utilizing the data
* the DB storing and retrieving the data effectively
* Better data security and consistency protection
---
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.
```scala
libraryDependencies *= "za.co.absa.db.fa-db" %% "slick" % "X.Y.Z"
libraryDependencies *= "za.co.absa.db.fa-db" %% "doobie" % "X.Y.Z"
```
#### Maven
##### Scala 2.12
Modules:
* Core [](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/core_2.12)
* Slick [](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/slick_2.12)
* Doobie [](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/doobie_2.12)
```xml
za.co.absa.db.fa-db
slick_2.12
${latest_version}
za.co.absa.db.fa-db
doobie_2.12
${latest_version}
```
### Scala 2.13
Modules:
* Core [](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/core_2.13)
* Slick [](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/slick_2.13)
* Doobie [](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/doobie_2.13)
```xml
za.co.absa.db.fa-db
slick_2.13
${latest_version}
za.co.absa.db.fa-db
doobie_2.13
${latest_version}
```
## Concepts
### Status codes
Text about status codes returned from the database function can be found [here](core/src/main/scala/za/co/absa/db/fadb/status/README.md).
## 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.
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)
* `class SlickMultipleResultFunctionWithStatus` - as `SlickSingleResultFunctionWithStatus` but for multiple record
retrieval
* `class SlickMultipleResultFunctionWithAggStatus` - as `SlickMultipleResultFunctionWithStatus` but it aggregates
the statuses into a single record. It requires an implementation of `StatusAggregator` to be mixed-in
(`ByFirstErrorStatusAggregator`, `ByFirstRowStatusAggregator`, and `ByMajorityErrorsStatusAggregator` 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
When getting result from `PositionedResult` for these types `HStore` -> `Option[Map[String, String]]` and
`macaddr` -> `MacAddrString` type inference doesn't work well.
So instead of:
```scala
val pr: PositionedResult = ???
val hStore: Option[Map[String, String]] = pr.<<
val macAddr: Option[MacAddrString] = pr.<<
```
explicit extraction needs to be used:
```scala
val pr: PositionedResult = ???
val hStore: Option[Map[String, String]] = pr.nextHStoreOption
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.
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
* `class DoobieMultipleResultFunctionWithAggStatus` - as `DoobieMultipleResultFunctionWithStatus` but it aggregates
the statuses into a single record. It requires an implementation of `StatusAggregator` to be mixed-in
(`ByFirstErrorStatusAggregator`, `ByFirstRowStatusAggregator`, and `ByMajorityErrorsStatusAggregator` 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
### How to generate unit tests code coverage report
```sbt
sbt jacoco
```
Note: this command will start all tests in the project.
Code coverage will be generated on path:
```
{project-root}/fa-db/{module}/target/scala-{scala_version}/jacoco/report/html
```
### Integration tests
There are now integration tests as part of the project (at the time of writing they are in
the _Slick_ and _Doobie_ modules).
For the tests to work properly a running Postgres instance is needed as well as all DB objects must be placed on the DB.
We automated this process, see [demo_database/README.md](https://github.com/AbsaOSS/fa-db/tree/master/demo_database#readme) for more details.
How to execute the `unit` tests only:
```sbt
sbt test
```
How to execute the `integration` tests only:
```sbt
sbt testIT
```
## How to Release
Please see [this file](RELEASE.md) for more details.