{"id":14068883,"url":"https://github.com/rstudio/connections","last_synced_at":"2025-04-25T19:31:19.489Z","repository":{"id":46563673,"uuid":"206792838","full_name":"rstudio/connections","owner":"rstudio","description":"https://rstudio.github.io/connections/","archived":false,"fork":false,"pushed_at":"2023-12-18T23:44:45.000Z","size":6085,"stargazers_count":56,"open_issues_count":9,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-13T12:42:49.826Z","etag":null,"topics":["connection-pane","database-connection","pins","r","rstudio"],"latest_commit_sha":null,"homepage":"https://rstudio.github.io/connections/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rstudio.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-06T12:49:39.000Z","updated_at":"2024-07-10T05:14:17.000Z","dependencies_parsed_at":"2024-08-13T07:14:47.121Z","dependency_job_id":"fb94a501-df32-44b0-bf2d-4c90a3ede1af","html_url":"https://github.com/rstudio/connections","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstudio%2Fconnections","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstudio%2Fconnections/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstudio%2Fconnections/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rstudio%2Fconnections/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rstudio","download_url":"https://codeload.github.com/rstudio/connections/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224014256,"owners_count":17241281,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["connection-pane","database-connection","pins","r","rstudio"],"created_at":"2024-08-13T07:06:27.779Z","updated_at":"2024-11-10T21:12:00.642Z","avatar_url":"https://github.com/rstudio.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nif (dir.exists(\"~/pins\")) unlink(\"~/pins\", recursive = TRUE)\n\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\",\n  eval = TRUE\n)\n\nadd_figure \u003c- function(path, width = 400) {\n  char_html \u003c- paste0(\"\u003cimg src='\", path, \"' width ='\", width, \"px'/\u003e\u003cbr/\u003e\")\n  htmltools::HTML(char_html)\n}\n\ntoc \u003c- function() {\n  re \u003c- readLines(\"README.Rmd\")\n  has_title \u003c- as.logical(lapply(re, function(x) substr(x, 1, 2) == \"##\"))\n  only_titles \u003c- re[has_title]\n  titles \u003c- trimws(gsub(\"#\", \"\", only_titles))\n  links \u003c- trimws(gsub(\"`\", \"\", titles))\n  links \u003c- tolower(links)\n  links \u003c- trimws(gsub(\" \", \"-\", links))\n  links \u003c- trimws(gsub(\",\", \"\", links))\n  toc_list \u003c- lapply(\n    seq_along(titles),\n    function(x) {\n      pad \u003c- ifelse(substr(only_titles[x], 1, 3) == \"###\", \"    - \", \"  - \")\n      paste0(pad, \"[\", titles[x], \"](#\", links[x], \")\")\n    }\n  )\n  toc_full \u003c- paste(toc_list, collapse = \"\\n\")\n  cat(toc_full)\n}\n```\n\n# connections\n\n\u003c!-- badges: start --\u003e\n[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)\n[![R-CMD-check](https://github.com/rstudio/connections/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/rstudio/connections/actions/workflows/R-CMD-check.yaml)\n[![Codecov test coverage](https://codecov.io/gh/rstudio/connections/branch/main/graph/badge.svg)](https://app.codecov.io/gh/rstudio/connections?branch=main)\n[![CRAN status](https://www.r-pkg.org/badges/version/connections)](https://CRAN.R-project.org/package=connections)\n\u003c!-- badges: end --\u003e\n\n  - [Installation](#installation)\n  - [Functions](#functions)\n  - [Uploading and referencing tables with `dplyr`](#uploading-and-referencing-tables-with-dplyr)\n  - [`pins`](#pins)\n    - [Pin a database connection](#pin-a-database-connection)\n    - [Pin a `dplyr` database query](#pin-a-dplyr-database-query)\n    - [Full `pins` example](#full-pins-example)\n  - [Back-end examples](#back-end-examples)\n    - [BigQuery, via `bigrquery`](#bigquery-via-bigrquery)\n    - [PostgreSQL, via `RPostgres`](#postgresql-via-rpostgres)\n  - [`DBI` connections](#dbi-connections)\n\nThe main goal of `connections` is to integrate `DBI`-compliant packages with the\nRStudio IDE's [Connection\nPane](https://solutions.posit.co/connections/db/tooling/connections/).  Packages such as \n[RPostgres](https://github.com/r-dbi/RPostgres), [RSQLite](https://github.com/r-dbi/RSQLite), \n[RMariaDB](https://github.com/r-dbi/RMariaDB) and\n[bigrquery](https://github.com/r-dbi/bigrquery) connect R to those databases, but \ndo not provide a direct integration with the Connections Pane. `connections` \nreads the configuration of the connection and creates the integration with RStudio.\n\nA second goal is to provide integration with the [pins](https://pins.rstudio.com/)\npackage.  The `connections` package allows you to pin database connections and \n[dplyr](https://dplyr.tidyverse.org/) table objects. \n\n## Installation\n\nInstall the development version from [GitHub](https://github.com/) with:\n\n``` r\n# install.packages(\"remotes\")\nremotes::install_github(\"rstudio/connections\")\n```\n```{r setup, include = FALSE}\nlibrary(connections)\nlibrary(RSQLite)\nlibrary(dplyr)\nlibrary(pins)\n\nif (file.exists(\"local.sqlite\")) unlink(\"local.sqlite\")\n```\n\n## Functions\n\nThe two main functions added by `connections` are: \n\n- `connection_open()` - Opens the database connection. Use instead of \n`dbConnect()`, but use the exact same arguments. It also automatically starts \nthe Connections pane. \n- `connection_close()` - Closes the database connection.\n\n```{r}\nlibrary(connections)\nlibrary(RSQLite)\n\ncon \u003c- connection_open(SQLite(), \"local.sqlite\")\n```\n\n\n`r add_figure(\"man/figures/connection-1.png\")`\n\nThe connection can now be closed by using the appropriate button in the \nConnections pane, or by using `connection_close()`\n\n```{r}\nconnection_close(con)\n```\n\n`r add_figure(\"man/figures/connection-2.png\")`\n\nThe connection code is parsed when connecting to the database, and it is \nvisible once the connection is closed.\n\n## Uploading and referencing tables with `dplyr`\n\n`connections` integrates with `dplyr` by supporting the following two functions: \n\n- `tbl()` - To create a pointer to a table or view within the database.\n- `copy_to()` - To copy data from the R session to the database.\n\nThe version of `copy_to()` inside `connections` automatically updates the \nConnections pane, so the new table automatically shows up.\n\n```{r}\ncon \u003c- connection_open(SQLite(), \"local.sqlite\")\n\ncopy_to(con, mtcars, temporary = FALSE, overwrite = TRUE)\n```\n\nTo use an existing table inside the database use `tbl()`.\n\n```{r}\ndb_mtcars \u003c- tbl(con, \"mtcars\")\n```\n\n`r add_figure(\"man/figures/pane-1.png\")`\n\nThe `tbl()` function opens the rest of the already available `dplyr` \ndatabase integration.\n\n```{r}\ndb_mtcars %\u003e%\n  group_by(am) %\u003e%\n  summarise(avg_mpg = mean(mpg, na.rm = TRUE))\n```\n\n## `pins`\n\nThe `connections` package integrates with `pins`.  It adds the ability to \"pin\"\ndatabase connections and queries. It follows the same approach as the\n[vetiver](https://rstudio.github.io/vetiver-r/reference/vetiver_pin_write.html) \npackage. `connections` now has two new functions:\n\n- `connection_pin_write()`\n- `connection_pin_read()`\n\n### Pin a database connection\n\nThe `connection_pin_write()` function does **not** save the R object. It records\nthe code necessary to recreate the connection.\n\n```{r}\nlibrary(pins)\nboard \u003c- board_folder(\"~/pins\")\n\nconnection_pin_write(board, con, name = \"my_conn\")\n```\n\n`r add_figure(\"man/figures/pins-1.png\")`\n\nIf you wish to see the code that `connections` will use when recreating the\nconneciton from the pin, you can use `connection_code()`:\n\n```{r}\nconnection_code(con)\n```\n\n`connection_pin_read()` will replay the exact same code used to initially \nconnect to the database.  Assign the output to a variable, such as\n`con1`.  The variable will work just like any connection variable.\n\n```{r}\ncon1 \u003c- connection_pin_read(board, \"my_conn\")\n```\n\nThe `con1` variable is now a regular database connection variable.\n\n```{r}\ndb_mtcars \u003c- tbl(con1, \"mtcars\") %\u003e%\n  group_by(am) %\u003e%\n  summarise(avg_mpg = mean(mpg, na.rm = TRUE))\n\ndb_mtcars\n```\n\n### Pin a `dplyr` database query\n\nWhen `dplyr` works with database data, the resulting query is not executed until \nthe data is explicitly collected into R, or when printing the top results to the \nR Console.  The `pin` records two things:\n\n- The `dplyr` R object that contains all of the transformations.  **It does not\nsave the actual results**.\n\n- The necessary information to recreate the database connection. This is to make\nsure that the data is being retrieved from the original database connection.\n\n```{r}\nconnection_pin_write(board, db_mtcars, name = \"avg_mpg\")\n```\n\n`r add_figure(\"man/figures/pins-2.png\")`\n\n`connection_pin_read()` will connect to the database, and return the `dplyr` object. \nWithout assigning it to a variable, the pin will immediately print the results of the \ndatabase.  Those results are being processed at the time `connection_pin_read()` runs. \n\n```{r}\nconnection_pin_read(board, \"avg_mpg\")\n```\n\n### Full `pins` example\n\nThe way `pins` integrates with databases, via the `connections` package, allows \nto open the connection from a pin, and pipe all of the subsequent code into a\nnew pin.  Afterwards, that pin can be used to collect or to continue using the \n`dplyr` object.\n\n```{r}\nboard \u003c- board_folder(\"~/pins\")\n\ncon \u003c- connection_pin_read(board, \"my_conn\")\n\ntbl_summary \u003c- con %\u003e%\n  tbl(\"mtcars\") %\u003e%\n  group_by(cyl) %\u003e%\n  summarise(avg_mpg = mean(mpg, na.rm = TRUE))\n\n\nconnection_pin_write(board, tbl_summary, name = \"cyl_mpg\")\n\nconnection_close(con)\n\nconnection_pin_read(board, \"cyl_mpg\")\n```\n\n`r add_figure(\"man/figures/pins-3.png\")`\n\n## Back-end examples\n\nThere are a couple of examples of how the Connections pane will look when \nopening the connection via `connections`.\n\n### BigQuery, via `bigrquery`\n\n```{r, eval = FALSE}\nlibrary(connections)\nlibrary(bigrquery)\n\ncon \u003c- connection_open(\n  bigquery(),\n  project = \"bigquery-public-data\",\n  dataset = \"austin_311\",\n  billing = \"my_project_billing\",\n  use_legacy_sql = FALSE\n)\n```\n\n`r add_figure(\"man/figures/bigquery-1.png\")`\n\n```{r, eval = FALSE}\nconnection_close(con)\n```\n\n`r add_figure(\"man/figures/bigquery-2.png\")`\n\n\n###  PostgreSQL, via `RPostgres`\n\n```{r, eval = FALSE}\nlibrary(connections)\nlibrary(RPostgres)\ncon \u003c- connection_open(\n  Postgres(),\n  host = \"localhost\",\n  dbname = \"datawarehouse\",\n  user = \"[user id]\",\n  password = \"[password]\",\n  bigint = \"integer\",\n  port = \"5432\"\n)\n```\n\n`r add_figure(\"man/figures/postgres-1.png\")`\n\n\n## `DBI` connections\n\nIt is possible to integrate `DBI` connections not opened via `connection_open()`.\nTo do that, use `connection_view()` and pass it the variable containing the \nexisting database connection.  \n\n```{r, eval = FALSE}\nlibrary(DBI)\n\ncon \u003c- dbConnect(RSQLite::SQLite(), \":memory:\")\n\nconnection_view(con)\n```\n\n`r add_figure(\"man/figures/dbi-1.png\", 200)`\n\n\nChanges to the database will not automatically load in the Connections pane. \nThe `connection_update()` function will refresh the pane with the latest.\n\n```{r, eval = FALSE}\ndbWriteTable(con, \"mtcars\", mtcars)\n\nconnection_update(con)\n```\n\n`r add_figure(\"man/figures/dbi-2.png\", 300)`\n\n```{r, eval = FALSE}\nconnection_close(con)\n```\n\n`r add_figure(\"man/figures/dbi-3.png\", 300)`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstudio%2Fconnections","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frstudio%2Fconnections","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frstudio%2Fconnections/lists"}