Connection Snippets

RStudio connections can be extended through two methods:

• Snippet Files on a server-based version of RStudio that provide support for new connections using R templates that enable users and system administrators to list and create new connections.

• Packages that do one or more of the following:

  • Implement the Connections Contract to manage and explore data in the Connections Pane and/or

  • Supply Snippet Files or a Shiny Application to extend the New Connection dialog.

Snippet files

A Connection snippet file is an R code snippet with additional metadata which is intended to initialize a connection. This file can be as simple as:

library(readr)
data <- read_csv(readr_example("mtcars.csv"))

This snippet can be saved on a server-based version of RStudio under /etc/rstudio/connections/. For desktop versions of RStudio, Connection Snippets are distributed through R packages as detailed in the R packages section below.

For the above example on a server, it would be saved as:

# Linux server only
/etc/rstudio/connections/Motor Trend Cars.R

Once that file is created and RStudio is restarted, RStudio will make this connection available as Motor Trend Cars underneath Connect to Existing Data Sources:

Snippet test

The snippet can also be tested by pressing the Test button in the New Connection wizard. Testing will return either a success or failure based on the available code snippet.

Snippet customization

The path is configurable through the connections-path environment variable and multiple connection files can be specified.

In order to parameterize this connection, one can create fields using using the ${Position:Label=Default} syntax:

• Position: The row position starting at zero.

• Label: The label assigned to this field.

• Default: An optional default value.

For example, a filter interface for this dataframe can be added with the following connection snippet:

library(readr)
data <- read_csv(readr_example("mtcars.csv"))
data[data$mpg == ${0:Miles per Gallon=21.4} | data$cyl == ${1:Cylinders=6}, ]

In order to create a ; separated list of values, use the syntax ${Position:Label=Default:Key}. Semicolon-separated list are common in database connections and therefore, natively supported in snippet files, for instance:

"${2:Letters=ABC:LettersKey}${3:Numbers=123:NumbersKey}"

There are several escape characters supported: $colon$ to escape : and $equal to escape =.

R packages

R packages provide the New Connection integration to both server and desktop based versions of RStudio.

Package structure

A package supporting connections defines the following components:

• Connections File: A DCF file must be created under inst/rstudio/connections.dcf to enumerate each connection supported in the package.

• Snippet Files: Snippet files are stored under inst/rstudio/connections/.

As a quick start, the RStudio Connections Example GitHub repo contains a working example of this structure.

Connections contract

You can integrate with RStudio’s Connections pane to allow users to explore connections created with your R package by using the Connections Contract.

Snippet files

Snippet Files are specified under the /inst/rstudio/connections and follow the same syntax mentioned in the “Snippet Files” section.

Shiny application

For advanced connection interfaces, a shiny application can be specified. See sparklyr for a working application.