README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
pkgload::load_all()
```

# dblog

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
[![CRAN status](https://www.r-pkg.org/badges/version/dblog)](https://cran.r-project.org/package=dblog)
<!-- badges: end -->

The goal of dblog is to implement logging for arbitrary DBI backends, similarly to Perl's [DBI::Log](https://metacpan.org/pod/DBI::Log).
This is useful for troubleshooting and auditing codes that access a database.
The initial use case for this package is to help debugging DBItest tests.

## Installation

You can install the released version of dblog from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("dblog")
```

Install the development version from GitHub using

``` r
# install.packages("devtools")
devtools::install_github("r-dbi/dblog")
```


## Basic example

The `dblog` driver wraps arbitrary drivers:

```{r init}
library(dblog)
drv <- dblog(RSQLite::SQLite())
```


All calls to DBI methods are logged, by default to the console.

```{r console}
conn <- dbConnect(drv, file = ":memory:")
dbWriteTable(conn, "iris", iris[1:3, ])
data <- dbGetQuery(conn, "SELECT * FROM iris")
dbDisconnect(conn)

data
```

The log is runnable R code!
Run it in a fresh session to repeat the operations, step by step or in an otherwise controlled fashion.

dblog is smart about DBI objects created or returned, and will assign a new variable name to each new object.
Cleared results or closed connections are not removed automatically.

## Logging options

Logging can be redirected to a file, optionally all outputs may be logged as well.
For example, use a collecting logger to output all calls and results after the fact.


```{r collect}
collecting_logger <- make_collect_logger()

drv <- dblog(RSQLite::SQLite(), logger = collecting_logger)
conn <- dbConnect(drv, file = ":memory:")
dbWriteTable(conn, "iris", iris[1:3, ])
data <- dbGetQuery(conn, "SELECT * FROM iris")
dbDisconnect(conn)

collecting_logger$retrieve()

ev <- evaluate::evaluate(collecting_logger$retrieve())
cat(unlist(ev, use.names = FALSE), sep = "\n")
```

## Logging complex operations

The full power is demonstrated when running with code where the underlying _DBI_ operations are not obvious:

```{r dplyr}
library(dplyr)

drv <- dblog(RSQLite::SQLite())
conn <- dbConnect(drv, file = ":memory:")
dbWriteTable(conn, "iris", iris[1:3, ])

src <- dbplyr::src_dbi(conn)
iris_tbl <- tbl(src, "iris")
iris_tbl %>%
  summarize_if(is.numeric, mean)
```

## Inheritance hierarchy

Despite the common suggestion to [prefer composition over inheritance](https://en.wikipedia.org/wiki/Composition_over_inheritance), the new logging classes are implemented as subclasses of the actual DBI classes.
Moreover, the class definitions are created on demand: for each different database backend, different subclasses are defined, to make sure dispatch is routed to the right methods.

The reason for this is that other methods, unknown to this package, might dispatch on the DBI class.
One such example is _dbplyr_ that introduces specialized behaviors for many classes.
The `explain()` method calls the internal `db_explain()` method which uses `EXPLAIN QUERY PLAN` for SQLite connections but `EXPLAIN` for unspecified database connections.
Without inheritance, _dbplyr_ would use the default method.
This might lead to errors for other databases that do not understand `EXPLAIN`.

```{r dplyr-explain}
iris_tbl %>%
  summarize_if(is.numeric, mean) %>% 
  explain()
```

---

Please note that the 'dblog' project is released with a
[Contributor Code of Conduct](CODE_OF_CONDUCT.md).
By contributing to this project, you agree to abide by its terms.