README.Rmd

---
output: github_document
editor_options: 
  chunk_output_type: console
---

<!-- 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%"
)
if (!interactive()) {
  options(width = 99)
}
```

# mdbr <img src='man/figures/logo.png' align="right" height="139" />

<!-- badges: start -->
[![Lifecycle: experimental][life_badge]][life_link]
[![CRAN status][cran_badge]][cran_link]
[![Codecov test coverage][cov_badge]][cov_link]
![Downloads][dl_badge]
[![R build status][ga_badge]][ga_link]
<!-- badges: end -->

The goal of mdbr is to easily access the open source [MDB Tools][mdbt] written
by Brian Bruns. The MDB Tools command line utilities take proprietary Microsoft
Access files and convert them to standard text files. This package is
experimental and has only been tested on simple MDB databases.

## Installation

You can install the release version of mdbr from [CRAN][cran].

```{r cran, eval=FALSE}
install.packages("mdbr")
```

The development version can be installed from [GitHub][gh].

```{r github, eval=FALSE}
# install.packages("remotes")
remotes::install_github("k5cents/mdbr")
```

> [!IMPORTANT]  
> The user must install [MDB Tools][mdbt] separately. For example, users on 
> Debian systems can install the tools from the apt repository.

```bash
sudo apt install mdbtools
```

On MacOS, the tools can be installed using homebrew.

```bash
brew install mdbtools
```

More installation methods can be found on the package's [README][readme].

## Example

```{r libs}
library(mdbr)
library(readr)
```

The package comes with a version of the [nycflights13][nycf] relational database
found with `mdb_examples()`.

The tables in a database can be listed with `mdb_tables()`.

```{r tables}
mdb_tables(ex <- mdb_example())
```

These tables can be exported as a delimited string or file.

```{r export}
string <- export_mdb(ex, "Airlines", path = TRUE, delim = "|", quote = "'")
cat(string, sep = "\n")
```

Tables can be easily converted to a temporary file and read immediately.

```{r read, message=FALSE}
read_mdb(ex, "Airports")
```

When reading a converted table, you might need to know what types of data to
expect from each column. 

The schema of database tables describes the column types.

``` bash
mdb-schema -T Airports nycflights13.mdb
#> -- ----------------------------------------------------------
#> -- MDB Tools - A library for reading MS Access database files
#> -- Copyright (C) 2000-2011 Brian Bruns and others.
#> -- Files in libmdb are licensed under LGPL and the utilities under
#> -- the GPL, see COPYING.LIB and COPYING files respectively.
#> -- Check out http://mdbtools.sourceforge.net
#> -- ----------------------------------------------------------
#> 
#> CREATE TABLE [Airports]
#> (
#>     [faa]            Text (510), 
#>     [name]           Text (510), 
#>     [lat]            Double, 
#>     [lon]            Double, 
#>     [alt]            Long Integer, 
#>     [tz]             Integer, 
#>     [dst]            Text (510), 
#>     [tzone]          Text (510)
#> );
```

This information can be interpreted as a [readr spec object][spec], which is
used to accurately parse columns of a converted text file.

```{r schema}
mdb_schema(ex, "Airports", condense = TRUE)
```


<!-- refs: start -->
[life_badge]: https://img.shields.io/badge/lifecycle-experimental-orange.svg
[life_link]: https://lifecycle.r-lib.org/articles/stages.html#experimental)
[cran_badge]: https://www.r-pkg.org/badges/version/mdbr
[cran_link]: https://CRAN.R-project.org/package=mdbr
[ga_badge]: https://github.com/k5cents/mdbr/workflows/R-CMD-check/badge.svg
[ga_link]: https://github.com/k5cents/mdbr/actions
[cov_badge]: https://img.shields.io/codecov/c/github/k5cents/mdbr/master.svg
[cov_link]: https://app.codecov.io/gh/k5cents/mdbr?branch=master
[dl_badge]: https://cranlogs.r-pkg.org/badges/grand-total/mdbr
[mdbt]: https://github.com/mdbtools/mdbtools
[gh]:  https://github.com/k5cents/mdbr/
[cran]:  https://cran.r-project.org/package=mdbr
[readme]: https://github.com/mdbtools/mdbtools/blob/dev/README.md
[nycf]: https://github.com/tidyverse/nycflights13
[spec]: https://readr.tidyverse.org/reference/spec.html
<!-- refs: end -->