README.Rmd

---
output:
  github_document:
    html_preview: true
---

<!-- 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%"
)
```

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="man/figures/sail-darkmode.png">
  <img align="right" src="man/figures/sail-lightmode.png" alt="SAIL Databank Logo" height="70" title="SAIL Databank">
</picture>

<br/>
<br/>

# SAILDB

An unofficial package to interface and interact with [SAIL Databank](https://saildatabank.com)'s database via R.

<!-- badges: start -->
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://www.tldrlegal.com/license/mit-license)
<!-- badges: end -->

## Getting Started

### Installation

1. Installing `saildb` whilst inside SAIL's TRE Gateway:
    - Running the `installer.R` script found within `R:/R_Packages/SAIL_DBI` directly, or by sourcing it:
    ```{r eval=FALSE}
    # Somewhere in your project
    source('R:/R_Packages/SAIL_DBI/installer.R')
    ```

    - Or; you can install directly using the `install.packages()` function:
    ```{r eval=FALSE}
    # Install from resource (`R:/`) directory somewhere in your project
    install.packages(
      pkgs   = 'R:/R_Packages/SAIL_DBI/saildb_1.0.0.tar.gz',
      repos  = NULL,
      source = 'source'
    )
    ```

2. Installing `saildb` whilst outside the gateway:

> [!IMPORTANT] \
> You won't be able to use this method whilst inside the gateway as \
> Github is blocked for security; use the first method if you are \
> developing inside the gateway \

```{r eval=FALSE}
# Install devtools if not already installed
install.packages('devtools')

# Install from github
devtools::install_github('JackScanlon/SAILDB-R')
```

### Connecting to SAIL's DB

Once installed, you may connect to the database as described below:

```{r eval=FALSE}
# Load the package
library(saildb)

# Connect to the datase
#
#  NOTE:
#   - You will be automatically connected using your gateway credentials if
#     they have already been stored by `saildb::Profile`; otherwise you will
#     be prompted to enter your username/password
#
db = Connection$new()

# Check if we're connected (not required)
if (db$connected) {
  print('We are connected!')
}

# Perform some query
db$run("
  SELECT
      'Hello, world!' AS MESSAGE
    FROM SYSIBM.SYSDUMMY1;
")

```


## Example usage

To view detailed examples and their explanations, see:

- If you're viewing from the documentation website: please see the [Reference](reference/index.html) page(s) and the available article(s), _e.g._ the [Connection](articles/Connection.html) article
- If you're viewing via Github: please see the [documentation](./man) and [vignettes](./vignettes)