README.qmd

---
format: gfm
default-image-extension: ""
editor_options: 
  chunk_output_type: console
---


# DIZutils <img src="man/figures/logo.png" align="right" width="120" />

<!-- badges: start -->
```{r}
#| echo: false
#| message: false
#| results: asis

pkg <- desc::desc_get_field("Package")
cat_var <- paste(
  badger::badge_lifecycle(),
  badger::badge_cran_release(pkg = pkg),
  gsub("summary", "worst", badger::badge_cran_checks(pkg = pkg)),
  badger::badge_cran_download(pkg = pkg, type = "grand-total", color = "blue"),
  badger::badge_cran_download(pkg = pkg, type = "last-month", color = "blue"),
  gsub("netlify\\.com", "netlify.app", badger::badge_dependencies(pkg = pkg)),
  badger::badge_github_actions(action = utils::URLencode("R CMD Check via {tic}")),
  badger::badge_github_actions(action = "lint"),
  badger::badge_github_actions(action = "test-coverage"),
  badger::badge_codecov(ref = desc::desc_get_urls()),
  sep = "\n"
)
cat_var |> cat()
```
<!-- badges: end -->

The R package `DIZutils` provides utility functions used for the R package development infrastructure inside the data integration centers ('DIZ') to standardize and facilitate repetitive tasks such as setting up a database connection or issuing notification messages and to avoid redundancy.

## Installation

You can install `DIZutils` directly from CRAN:

```{r}
#| eval: false
install.packages("DIZutils")
```

The development version can be installed using

```{r}
#| eval: false
install.packages("remotes")
remotes::install_github("miracum/misc-dizutils", ref = "development")
```

## Basic functions

### db_connection

The function `DIZutils::db_connection` provides one simple interface for connecting to various types of databases. It reads necessary connection settings from the active environment (see below how to use the function `set_env_vars` to set environment variables).

The following database types are currently supported:

* postgres (via the R package [`RPostgres`](https://CRAN.R-project.org/package=RPostgres))
* oracle (via the R packages [`RJDBC`](https://CRAN.R-project.org/package=RJDBC) and [`DBI`](https://CRAN.R-project.org/package=DBI/))

#### postgres

The following environment variables need to be set to the active environment in order to connect with a postgres database with "i2b2" as name of the database to connect with:

| Variable          | Description                                                               |
| ----------------- | ------------------------------------------------------------------------- |
| I2B2_HOST         | The hostname/ IP address of your pg instance.                             |
| I2B2_DBNAME       | The name of the pg-database.                                              |
| I2B2_PORT         | The port, your pg postgres instance is running on.                        |
| I2B2_USER         | The name of the 'I2B2_USER'.                                              |
| I2B2_PASSWORD     | The password of the 'I2B2_USER' of your pg instance.                      |
| I2B2_SCHEMA       | (optional) The database schema on which queries should be performed.      |

To establish the connection, please set those environment variables accordingly and execute the following command. The argument `db_name` is used to detect the corresponding environment variables and thus must match with the environment variables' prefix.

```{r}
#| eval: false
db_con <- DIZutils::db_connection(
    system_name = "i2b2",
    db_type = "postgres"
  )
```

#### oracle

The following environment variables need to be set to the active environment in order to connect with an oracle database:

| Variable          | Description                                                               |
| ----------------- | ------------------------------------------------------------------------- |
| MYORACLEDB_HOST         | The hostname/ IP address of your oracle instance.                   |
| MYORACLEDB_DBNAME       | The name of the oracle-database.                                    |
| MYORACLEDB_DRIVER       | The path to the oracle jdbc driver.                                 |
| MYORACLEDB_SID          | The SID of the oracle-database.                                     |
| MYORACLEDB_PORT         | The port, your oracle postgres instance is running on.              |
| MYORACLEDB_USER         | The name of the 'MYORACLEDB_USER'.                                  |
| MYORACLEDB_PASSWORD     | The password of the 'MYORACLEDB_USER' of your oracle instance.      |

To establish the connection, please set those environment variables accordingly and execute the following command. The argument `db_name` is used to detect the corresponding environment variables and thus must match with the environment variables' prefix. Furthermore, an ojdbc*.jar-file needs to be provided via the function's `lib_path` argument.

```{r}
#| eval: false
db_con <- DIZutils::db_connection(
  system_name = "myoracledb",
  db_type = "oracle",
  lib_path = "path/to/ojdbc*.jar"
)
```

For further details on how to set the specific environment variables using a configuration file, please refer to the documentation in the [`DIZtools`](https://github.com/miracum/misc-diztools#setenv_file) R package.

## More Infos

* about MIRACUM: <https://www.miracum.org/>
* about the Medical Informatics Initiative: <https://www.medizininformatik-initiative.de/en/start>