{"id":18810412,"url":"https://github.com/absaoss/fa-db","last_synced_at":"2025-08-04T19:42:19.543Z","repository":{"id":42064713,"uuid":"447802860","full_name":"AbsaOSS/fa-db","owner":"AbsaOSS","description":"Functional Access to Database","archived":false,"fork":false,"pushed_at":"2024-04-10T11:58:48.000Z","size":722,"stargazers_count":2,"open_issues_count":30,"forks_count":0,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-04-12T07:05:51.155Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AbsaOSS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/codeowners","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-01-14T01:14:58.000Z","updated_at":"2024-04-24T15:58:37.411Z","dependencies_parsed_at":"2024-04-24T16:08:38.488Z","dependency_job_id":null,"html_url":"https://github.com/AbsaOSS/fa-db","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbsaOSS%2Ffa-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbsaOSS%2Ffa-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbsaOSS%2Ffa-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbsaOSS%2Ffa-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AbsaOSS","download_url":"https://codeload.github.com/AbsaOSS/fa-db/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239744096,"owners_count":19689602,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T23:20:08.026Z","updated_at":"2025-02-19T22:27:08.180Z","avatar_url":"https://github.com/AbsaOSS.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fa-db\n## _Functional Access to Database_\n\n### Build Status\n\n[![Build](https://github.com/AbsaOSS/fa-db/workflows/Build/badge.svg)](https://github.com/AbsaOSS/fa-db/actions)\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/core_2.12/badge.svg)](https://search.maven.org/search?q=g:za.co.absa.db.fa-db)\n\n___\n\n\u003c!-- toc --\u003e\n- [What is fa-db](#what-is-fa-db)\n- [Usage](#usage)\n- [Concepts](#concepts)\n- [Slick module](#slick-module)\n- [Testing](#testing)\n- [How to Release](#how-to-release)\n\u003c!-- tocstop --\u003e\n\n## What is fa-db\n\nThis library is a less traditional way to facilitate data between an application and an SQL Database.\n\nTraditionally application directly applies SQL queries or use some ORM framework. While the first approach mixes two\nrather different domain languages within one source, the second too often fails in case of more complicated queries and \ntable relations.\n\n---\n\nThis library offers a different approach.\n\nThe idea is that the application transfers data to and from using database stored procedures/functions (from here on\nreferenced in this library as _DB functions_). This establishes a stable contract between the DB and the application. To \nemphasize – the data are both **read** and **written** to/from DB using _DB functions_.\n\n**The purpose of the library then is to facilitate an easy and natural – meaning Scala style – call of the _DB functions_ \nwithin the application.**\n\n\u003cu\u003eBenefits:\u003c/u\u003e\n* Stable contract between the application and the DB\n* Early locking of the data model\n* Separation of the domains while keeping each part doing what they are good for:\n    * the application parsing and utilizing the data\n    * the DB storing and retrieving the data effectively\n* Better data security and consistency protection\n\n---\n\nCurrently, the library is developed with Postgres as the target DB. But the approach is applicable to any DB \nsupporting stored procedure/functions – Oracle, MS-SQL, ...\n\n\n## Usage\n\n#### Sbt\n\nImport one of the two available module at the moment. Slick module works with Scala Futures. Doobie module works with \nany effect type (typically IO or ZIO) provided cats effect's Async instance is available.\n\n```scala\nlibraryDependencies *= \"za.co.absa.db.fa-db\" %% \"slick\"  % \"X.Y.Z\"\nlibraryDependencies *= \"za.co.absa.db.fa-db\" %% \"doobie\"  % \"X.Y.Z\"\n```\n\n#### Maven\n\n##### Scala 2.12\n\nModules:\n* Core [![Maven Central](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/core_2.12/badge.svg)](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/core_2.12)\n* Slick [![Maven Central](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/slick_2.12/badge.svg)](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/slick_2.12)\n* Doobie [![Maven Central](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/doobie_2.12/badge.svg)](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/doobie_2.12)\n\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eza.co.absa.db.fa-db\u003c/groupId\u003e\n        \u003cartifactId\u003eslick_2.12\u003c/artifactId\u003e\n        \u003cversion\u003e${latest_version}\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eza.co.absa.db.fa-db\u003c/groupId\u003e\n        \u003cartifactId\u003edoobie_2.12\u003c/artifactId\u003e\n        \u003cversion\u003e${latest_version}\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n### Scala 2.13\nModules:\n* Core [![Maven Central](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/core_2.13/badge.svg)](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/core_2.13)\n* Slick [![Maven Central](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/slick_2.13/badge.svg)](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/slick_2.13)\n* Doobie [![Maven Central](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/doobie_2.13/badge.svg)](https://maven-badges.herokuapp.com/maven-central/za.co.absa.db.fa-db/doobie_2.13)\n\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eza.co.absa.db.fa-db\u003c/groupId\u003e\n        \u003cartifactId\u003eslick_2.13\u003c/artifactId\u003e\n        \u003cversion\u003e${latest_version}\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eza.co.absa.db.fa-db\u003c/groupId\u003e\n        \u003cartifactId\u003edoobie_2.13\u003c/artifactId\u003e\n        \u003cversion\u003e${latest_version}\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n## Concepts\n\n### Status codes\n\nText about status codes returned from the database function can be found [here](core/src/main/scala/za/co/absa/db/fadb/status/README.md).\n\n\n## Slick module\n\nAs 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 \nPostgres type support.\n\nIt brings:\n\n* `class SlickPgEngine` - implementation of _Core_'s `DBEngine` executing the queries via Slick\n* `class SlickSingleResultFunction` - abstract class for DB functions returning single result\n* `class SlickMultipleResultFunction` - abstract class for DB functions returning sequence of results\n* `class SlickOptionalResultFunction` - abstract class for DB functions returning optional result\n* `class SlickSingleResultFunctionWithStatus` - abstract class for DB functions with status handling; it requires an \n  implementation of `StatusHandling` to be mixed-in (`StandardStatusHandling` available out-of-the-box)\n* `class SlickMultipleResultFunctionWithStatus` - as `SlickSingleResultFunctionWithStatus` but for multiple record\n  retrieval\n* `class SlickMultipleResultFunctionWithAggStatus` - as `SlickMultipleResultFunctionWithStatus` but it aggregates\n  the statuses into a single record. It requires an implementation of `StatusAggregator` to be mixed-in\n  (`ByFirstErrorStatusAggregator`, `ByFirstRowStatusAggregator`, and `ByMajorityErrorsStatusAggregator` available\n  out of the box)\n* `class SlickOptionalResultFunctionWithStatus` - as `SlickSingleResultFunctionWithStatus` but the returning record \n  is optional\n* `trait FaDbPostgresProfile` - to bring support for Postgres and its extended data types in one class \n  (except JSON, as there are multiple implementations for this data type in _Slick-Pg_)\n* `object FaDbPostgresProfile` - instance of the above trait for direct use\n\n#### Known issues\n\nWhen getting result from `PositionedResult` for these types `HStore` -\u003e `Option[Map[String, String]]` and \n`macaddr` -\u003e `MacAddrString` type inference doesn't work well.\nSo instead of:\n```scala\nval pr: PositionedResult = ???\nval hStore: Option[Map[String, String]] = pr.\u003c\u003c\nval macAddr: Option[MacAddrString] = pr.\u003c\u003c\n```\n\nexplicit extraction needs to be used:\n```scala\nval pr: PositionedResult = ???\nval hStore: Option[Map[String, String]] = pr.nextHStoreOption\nval macAddr: Option[MacAddrString] = pr.nextMacAddrOption\n```\n\n## Doobie module\n\nAs 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 \neffect type (typically IO or ZIO) therefore is more suitable for functional programming. \nIt also brings in the [Doobie-Postgres library](https://tpolecat.github.io/doobie/docs/14-PostgreSQL.html) for extended Postgres type support.\n\nIt brings:\n\n* `class DoobieEngine` - implementation of _Core_'s `DBEngine` executing the queries via Doobie. The class is type parameterized with the effect type.\n* `class DoobieSingleResultFunction` - abstract class for DB functions returning single result\n* `class DoobieMultipleResultFunction` - abstract class for DB functions returning sequence of results\n* `class DoobieOptionalResultFunction` - abstract class for DB functions returning optional result\n* `class DoobieSingleResultFunctionWithStatus` - abstract class for DB functions with status handling; it requires \n  an implementation of `StatusHandling` to be mixed-in (`StandardStatusHandling` available out-of-the-box)\n* `class DoobieMultipleResultFunctionWithStatus` - as `DoobieSingleResultFunctionWithStatus` but for multiple record\n  retrieval\n* `class DoobieMultipleResultFunctionWithAggStatus` - as `DoobieMultipleResultFunctionWithStatus` but it aggregates \n  the statuses into a single record. It requires an implementation of `StatusAggregator` to be mixed-in\n  (`ByFirstErrorStatusAggregator`, `ByFirstRowStatusAggregator`, and `ByMajorityErrorsStatusAggregator` available\n  out of the box)\n* `class DoobieOptionalResultFunctionWithStatus` - as `DoobieSingleResultFunctionWithStatus` but the returning record \n  is optional\n\nSince Doobie also interoperates with ZIO, there is an example of how a database connection can be properly established \nwithin a ZIO application. Please see [this file](doobie/zio-setup.md) for more details.\n\n## Testing\n\n### How to generate unit tests code coverage report\n\n```sbt\nsbt jacoco\n```\nNote: this command will start all tests in the project.\n\nCode coverage will be generated on path:\n\n```\n{project-root}/fa-db/{module}/target/scala-{scala_version}/jacoco/report/html\n```\n\n### Integration tests\n\nThere are now integration tests as part of the project (at the time of writing they are in \nthe _Slick_ and _Doobie_ modules).\n\nFor the tests to work properly a running Postgres instance is needed as well as all DB objects must be placed on the DB.\nWe automated this process, see [demo_database/README.md](https://github.com/AbsaOSS/fa-db/tree/master/demo_database#readme) for more details.\n\nHow to execute the `unit` tests only:\n```sbt\nsbt test\n```\nHow to execute the `integration` tests only:\n```sbt\nsbt testIT\n```\n\n## How to Release\n\nPlease see [this file](RELEASE.md) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabsaoss%2Ffa-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabsaoss%2Ffa-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabsaoss%2Ffa-db/lists"}