In shunsambongi/dbiconf: DBI Configuration

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Database parameters can be configured to dynamically obtain its value at connection-time using "loaders". For example, a database might look like:

[database.loader_example]
_driver = "RSQLite::SQLite"
dbname = { interactive = true }

In this case, the dbname parameter is a loader, and the value will be obtained from the user interactively when creating a connection using dbConnect(). Loaders are usually specified using inline tables:

[database.database_name]
_driver = "RSQLite::SQLite"
param = { loader_name = "loader_value" }

but standard tables are also fine.:

[database.database_name]
_driver = "RSQLite::SQLite"

   [database.database_name.param]
   loader_name = "loader_value"

Included loaders

There are a few types of loaders which are included with dbiconf. See below for their arguments.

Interactive loader

The interactive loader will show an interactive prompt at connection-time for the user to type the parameter value. The value obtained from the prompt can be specified as being a secret or not. If the value is secret, the prompt will mask the value as it is being typed, otherwise the value will be plainly visible. By default the prompt will be secret.

When specifying an interactive loader, it should have a single key interactive. The value of interactive should be one of the following:

1. the value true

toml param = { interactive = true }

1. a table with the following keys:

2. prompt - an optional string indicating the prompt message

3. secret - an optional boolean indicating whether the prompt should be secret or not.

toml param1 = { interactive = { prompt = "Enter your email", secret = false } }

Environment variable loader

The environment variable loader can dynamically obtain parameter values from an environment variable.

An environment variable loader should have a single key envvar. The value of envvar should be one of the following:

1. a non-empty string specifying the environment variable to read from

toml param = { envvar = "MY_SECRET_VALUE" }

1. a table with the following keys:

2. x - a required non-empty string specifying the environment variable to read from

3. unset - an optional non-empty string specifying the default value to use if the environment variable is unset

toml param = { envvar = { x = "MY_SECRET_VALUE", unset = "default value" } }

File loader

A file loader will read a file, and use the content as the parameter value. You can also specify whether any whitespace surrounding the content should be trimmed or not, e.g. a trailing newline.

A file loader should have a single key file. The value of file should be one of the following:

1. a non-empty string specifying the path to the file to read from

toml param = { file = "my-secret.txt" }

1. a table with the following keys:

2. path - a required non-empty string specifying the path to the file to read from

3. trim - an optional boolean specifying whether the content should be trimmed of whitespace (default: true)

toml param = { file = { path = "my-secret.txt", trim = false } }

Keyring loader

A keyring loader uses the keyring package to read values from the OS system credential store.

A keyring loader should have a single key keyring. The value of keyring should be one of the following:

1. a non-empty string specifying the service to obtain the value from (see ?keyring::key_get)

toml param = { keyring = "my-password" }

1. a table with the following keys:

2. service - a required non-empty string specifying the service to obtain the value from

3. username - an optional string specifying the username passed keyring::key_get()
4. keyring - an optional string specifying the keyring passed keyring::key_get()

See ?keyring::key_get for more information about these parameters.

toml param = { keyring = { service = "my-password", username = "my-username", keyring = "my-keyring" } }

Zap loader(?)

A zap loader removes the specified parameter when the configuration file is parsed. It has no effect at connection-time. So in that sense, it is not really a loader... This can be used when merging multiple configuration files, and you would like to override a database by removing a parameter.

A zap loader should have a single key zap. The value of zap must be the constant true.

param = { zap = true }

Custom loaders

Custom loaders can be defined by adding a method for the loader_resolve() generic.

For example, if I wanted to add a hello loader:

loader_resolve.dbiconf_loader_hello <- function(x) {
   paste("hello", x)
}

Then I could write in my configuration file:

[database.custom_hello_db]
_driver = "RSQLite::SQLite"
dbname = { hello = "world" }

When I try to connect to the database custom_hello_db using dbConnect(), the value of dbname will be equal to "hello world"

shunsambongi/dbiconf documentation built on Aug. 29, 2022, 11:15 p.m.