SQRL (version 0.6.2)

sqrlSource: Define New Data Sources

Description

Defines new data sources and creates the interface functions for communicating with them. Can also redefine and/or delete existing sources.

Usage

sqrlSource(...)

Arguments

A name and definition for the source (refer to the details section, below).

Value

Invisibly returns the interface function name, after defining the new source and creating that interface. In general, this need not match the name of the source itself.

Details

The arguments may be supplied as a single name = definition pair, or as a sequence of unnamed strings. In the latter usage, the leading string is taken for the new source name, while the remainder constitute its definition. In either usage, the definition may be a connection string, a configuration file, a data source name (DSN), or the name of an existing SQRL source. To be precise, if the definition specifies the path of an existing file, then the source is configured from that file. Otherwise, if the definition names an existing source, then the new source is created as a copy of that. Otherwise, if the definition consists of multiple terms, or if it contains an equals character (=), then it is assumed to represent a connection string. When none of these conditions apply, the definition is assumed to specify a DSN.

Alternatively, the arguments may instead be supplied as a single string followed by at least one named parameter = value pair. In this usage, the leading string is taken for the new source name, while the named pairs constitute its definition. The named pairs may represent components of a connection string, and/or SQRL parameter values to be applied (see sqrlParams). If one of the pairs is named “copy”, then the new source is created as a copy of the corresponding preexisting source. If one of the pairs is named “config”, then the new source is configured from the corresponding file (see sqrlConfig). If neither of those applies, and if no pair is named “connection” (i.e., if no explicit value was given for the connection string), and if either the remaining names do not include “dsn”, or they do include some other name not recognised as being a SQRL parameter, then those pairs are concatenated into a connection string.

Whichever form is used, the new interface name (which defaults to the source name) must not conflict with that of any other object on the R search path (or else an error will be thrown).

Redefinition of an existing source is allowed, provided it is closed.

When the source name is ‘remove’, the definition is interpreted as a list of sources to be deregistered. This precludes the use of ‘remove’ as a source name. Alternatively, redefining a source to NULL also deregisters the source.

See Also

sqrlConfig

Examples

Run this code
# NOT RUN {
# Define a new source from a DSN.
sqrlSource("daedalus", dsn = "Knossos")

# Define another source as a copy of the former.
sqrlSource(icarus = "daedalus")

# Redefine an existing source by a connection string.
# (This example is for a Windows-system client.)
sqrlSource("icarus",
            driver = "PostgreSQL ANSI(x64)",
            server = "localhost",
            port = 5432,
            uid = "asterion",
            pwd = "moo")

# Define a new source by a connection string.
# (This example is for a GNU/Linux-system client,
#  and employs the <pwd> password placeholder.)
sqrlSource("knossos",
            "dbcname=Knossos;uid=theseus;pwd=<pwd>",
            "driver=/opt/teradata/client/16.10/lib64/tdata.so")

# }
# NOT RUN {
# Define a new source from a configuration file.
sqrlSource(minos = "path/to/minos.config")

# Define a new source, ariadne, as a copy of the existing
# source, minos, then apply the configuration file conf.txt
# over that, and then set both the connection string and
# interface function name (parameter values) over those.
sqrlSource("ariadne",
            copy = "minos",
            config = "conf.txt",
            connection = "DSN=Knossos",
            interface = "a")
            
# Source names may conflict with those of preexisting
# R objects, provided that the config file defines a 
# conflict-free name for the source's interface function.
sqrlSource("c", "path/to/", "c.config")
# }
# NOT RUN {
# Review defined sources.
sqrlSources()

# Remove two of the sources.
sqrlSource("remove", c("daedalus", "knossos"))

# Remove another.
sqrlSource(icarus = NULL)
# }

Run the code above in your browser using DataCamp Workspace