connector (version 1.0.0)

connect: Connect to datasources specified in a config file

Description

Based on a configuration file or list this functions creates a connectors() object with a Connector for each of the specified datasources.

The configuration file can be in any format that can be read through read_file(), and contains a list. If a yaml file is provided, expressions are evaluated when parsing it using yaml::read_yaml() with eval.expr = TRUE.

See also vignette("connector") on how to use configuration files in your project, details below for the required structure of the configuration.

Usage

connect(
  config = "_connector.yml",
  metadata = NULL,
  datasource = NULL,
  set_env = TRUE,
  logging = zephyr::get_option("logging", "connector")
)

Value

connectors

Arguments

config

character path to a connector config file or a list of specifications

metadata

list Replace, add or create elements to the metadata field found in config

datasource

character Name(s) of the datasource(s) to connect to. If NULL (the default) all datasources are connected.

set_env

logical Should environment variables from the yaml file be set? Default is TRUE.

logging

Add logging capability to connectors using add_logs(). When TRUE, all connector operations will be logged to the console and to whirl log HTML files. See log-functions for available logging functions.. Default: FALSE.

Details

The input list can be specified in two ways:

1. A named list containing the specifications of a single connectors object.

2. An unnamed list, where each element is of the same structure as in 1., which returns a nested connectors object. See example below.

Each specification of a single connectors have to have the following structure:

• Only name, metadata, env and datasources are allowed.

• All elements must be named.

• name is only required when using nested connectors.

• datasources is mandatory.

• metadata and env must each be a list of named character vectors of length 1 if specified.

• datasources must each be a list of unnamed lists.

• Each datasource must have the named character element name and the named list element backend

• For each connection backend.type must be provided

Examples

withr::local_dir(withr::local_tempdir("test", .local_envir = .GlobalEnv))
# Create dir for the example in tmpdir
dir.create("example/demo_trial/adam", recursive = TRUE)

# Create a config file in the example folder
config <- system.file("config", "_connector.yml", package = "connector")

# Show the raw configuration file
readLines(config) |>
  cat(sep = "\n")

# Connect to the datasources specified in it
cnts <- connect(config)
cnts

# Content of each connector

cnts$adam
cnts$sdtm

# Overwrite metadata informations

connect(config, metadata = list(extra_class = "my_class"))

# Connect only to the adam datasource

connect(config, datasource = "adam")

# Connect to several projects in a nested structure

config_nested <- system.file("config", "_nested_connector.yml", package = "connector")

readLines(config_nested) |>
  cat(sep = "\n")

cnts_nested <- connect(config_nested)

cnts_nested

cnts_nested$study1

withr::deferred_run()