{"id":14067624,"url":"https://github.com/daroczig/dbr","last_synced_at":"2025-04-11T21:21:19.537Z","repository":{"id":139896795,"uuid":"140653831","full_name":"daroczig/dbr","owner":"daroczig","description":"Secure database connections and convenient queries from R on the top of DBI","archived":false,"fork":false,"pushed_at":"2020-06-12T22:01:06.000Z","size":151,"stargazers_count":32,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-10T06:59:32.701Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://daroczig.github.io/dbr","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daroczig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2018-07-12T03:04:08.000Z","updated_at":"2024-12-06T23:22:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"64504981-403b-4eca-a9f1-7c61ec0d35dc","html_url":"https://github.com/daroczig/dbr","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daroczig%2Fdbr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daroczig%2Fdbr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daroczig%2Fdbr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daroczig%2Fdbr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daroczig","download_url":"https://codeload.github.com/daroczig/dbr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248480421,"owners_count":21110939,"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":[],"created_at":"2024-08-13T07:05:41.769Z","updated_at":"2025-04-11T21:21:19.511Z","avatar_url":"https://github.com/daroczig.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"# dbr: Convenient database connections and queries from R\n\n[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) ![CRAN](https://www.r-pkg.org/badges/version/dbr) [![Build Status](https://travis-ci.org/daroczig/dbr.svg?branch=master)](https://travis-ci.org/daroczig/dbr) [![Code Coverage](https://codecov.io/gh/daroczig/dbr/branch/master/graph/badge.svg)](https://codecov.io/gh/daroczig/dbr)\n\nVignette coming, until then, please check the talk presented at the useR! 2018 conference:\n\n* [slides](http://bit.ly/user2018-dbr)\n* [video](https://www.youtube.com/watch?v=z7x4UOHNguY)\n\n## Setting up a config file for the database connections\n\nTo be able to connect to a database, the connection parameters are to be specified in a YAML file, for example for a SQLite database to be created in a temp file:\n\n```yaml\nsqlite:\n  drv: !expr RSQLite::SQLite()\n  dbname: !expr tempfile()\n```\n\nBy default, `dbr` will look for a file named `db_config.yaml` in the current working directory, that can be override via the `dbr.db_config_path` global option, eg to the example config bundled in this package:\n\n```r\noptions(dbr.db_config_path = system.file('example_db_config.yaml', package = 'dbr'))\n```\n\nA more complex example from the demo YAML file describing a MySQL connection to a database hosted by RStudio (with public username and password):\n\n```yaml\nshinydemo:\n  drv: !expr RMySQL::MySQL()\n  host: shiny-demo.csa7qlmguqrf.us-east-1.rds.amazonaws.com\n  username: guest\n  password: guest\n  dbname: shinydemo\n```\n\nNote, that instead of simple strings, you can also specify KMS-encrypted passwords, other secrets and parameters as well, eg:\n\n```yaml\nredshift:\n  host: !aws_kms |\n    KMSencryptedciphertext...\n  port: 5439\n  dbname: dbname\n  user: username\n  drv: !expr RPostgreSQL::PostgreSQL()\n  password: !aws_kms |\n    KMSencryptedciphertext...\n  s3_copy_bucket: !attr |-\n    's3://openmail-model/temp'\n  s3_copy_iam_role: !attr |-\n    arn:aws:iam::accountid:role/redshift_role\n```\n\n## Querying databases\n\nOnce the connection parameters are loaded from a config file, making SQL queries are as easy as specifying the SQL statement and the name of the connection:\n\n```r\ndb_query('show tables', 'shinydemo')\n#\u003e INFO [2019-01-06 01:06:18] Connecting to shinydemo\n#\u003e INFO [2019-01-06 01:06:19] Executing:**********\n#\u003e INFO [2019-01-06 01:06:19] show tables\n#\u003e INFO [2019-01-06 01:06:19] ********************\n#\u003e INFO [2019-01-06 01:06:19] Finished in 0.1336 secs returning 3 rows\n#\u003e INFO [2019-01-06 01:06:19] Closing connection to shinydemo\n#\u003e   Tables_in_shinydemo\n#\u003e 1                City\n#\u003e 2             Country\n#\u003e 3     CountryLanguage\n```\n\nFor more advanced usage, eg caching database connections, check `?db_connect` and the above mentioned vignette.\n\n## SQL templating\n\nTo reuse SQL chunks, you may list your SQL queries (or parts of it) in a structured YAML file, like in the bundled example config at [`example_sql_chunks.yaml`](https://github.com/daroczig/dbr/blob/master/inst/example_sql_chunks.yaml)\n\nUse `sql_chunk_files` to list or update the currently used SQL template YAML file(s), eg via\n\n```r\nsql_chunk_files(system.file('example_sql_chunks.yaml', package = 'dbr'))\n```\n\nThen you may refer to any key in that definition by a string that consist of the keys in hierarchy separated by a dot, so looking at the below definition (part of [`example_sql_chunks.yaml`](https://github.com/daroczig/dbr/blob/master/inst/example_sql_chunks.yaml)):\n\n```yaml\ndbr:\n  shinydemo:\n    countries:\n      count: SELECT COUNT(*) FROM Country\n```\n\nGetting the `count` key from for the `countries` item in `dbr`'s `shinydemo` section, you could do something like:\n\n```r\nsql_chunk('dbr.shinydemo.countries.count')\n#\u003e SELECT COUNT(*) FROM Country\n```\n\nAnd pass it right away to `db_query`:\n\n```r\ncountries \u003c- db_query(sql_chunk('dbr.shinydemo.countries.count'), 'shinydemo')\n#\u003e INFO [2019-01-06 01:33:33] Connecting to shinydemo\n#\u003e INFO [2019-01-06 01:33:34] Executing:**********\n#\u003e INFO [2019-01-06 01:33:34] SELECT COUNT(*) FROM Country\n#\u003e INFO [2019-01-06 01:33:34] ********************\n#\u003e INFO [2019-01-06 01:33:34] Finished in 0.1291 secs returning 1 rows\n#\u003e INFO [2019-01-06 01:33:34] Closing connection to shinydemo\n```\n\nSQL chunks can be also defined in files outside of the YAML with the `sql` file extensions, and referenced with the `!include` tag in the YAML file, eg:\n\n```yaml\ndbr:\n  shinydemo:\n    countries:\n      europe: !include europe.sql\n```\n\nThis will read the content of [`europe.sql`](https://github.com/daroczig/dbr/blob/master/inst/europe.sql) and make it available as `sql_chunk('dbr.shinydemo.countries.count')`.\n\nBesides files, a folder with `sql` files can be also included -- in that case, the base filename (without the `sql` file extension) will become the key under the given key. For example, consider this YAML definition:\n\n```yaml\ncities: !include cities.sql\n```\n\nWill load all the files from the [`cities.sql`](https://github.com/daroczig/dbr/tree/master/inst/cities.sql) folder and make those available under `europe`, so resulting in an intermediate YAML as:\n\n```\ncities: !include cities.sql\n  europe: |-\n    SELECT Name\n    FROM City\n    WHERE CountryCode IN (\n      {sql_chunk('dbr.shinydemo.countries.europe', indent_after_linebreak = 2)})\n  europe_large: |-\n    SELECT Name\n    FROM City\n    WHERE\n      Population \u003e 1000000 AND\n      Name IN (\n        {sql_chunk('dbr.shinydemo.cities.europe', indent_after_linebreak = 4)}))\n```\n\nIf the key of a directory `!include` is `~!`, then the keys are made available in the parent node, so eg\n\n```\ncities:\n  ~!: !include cities.sql\n```\n\nWould not actually create the `cities` key, but only the `europe` and `europe_large` keys in the root node.\n\nAs you can see from the above, the main power of this templating approach is that you can easily reuse SQL chunks, eg for the list of European countries in:\n\n```r\ncities \u003c- db_query(sql_chunk('dbr.shinydemo.cities.europe'), 'shinydemo')\n#\u003e INFO [2019-01-06 01:32:02] Connecting to shinydemo\n#\u003e INFO [2019-01-06 01:32:02] Executing:**********\n#\u003e INFO [2019-01-06 01:32:02] SELECT Name\n#\u003e FROM City\n#\u003e WHERE CountryCode IN (\n#\u003e   SELECT Code\n#\u003e   FROM Country\n#\u003e   WHERE Continent = 'Europe')\n#\u003e INFO [2019-01-06 01:32:02] ********************\n#\u003e INFO [2019-01-06 01:32:02] Finished in 0.1225 secs returning 643 rows\n#\u003e INFO [2019-01-06 01:32:02] Closing connection to shinydemo\n```\n\nWhere the `Country`-related subquery was specified in the `dbr.shinydemo.countries.europe` key as per:\n\n```sql\nSELECT Name\nFROM City\nWHERE CountryCode IN (\n  {sql_chunk('dbr.shinydemo.countries.europe', indent_after_linebreak = 2)})\n```\n\nThe `indent_after_linebreak` parameter is just for cosmetic updates in the query to align `FROM` and `WHERE` on the same character in the SQL statement.\n\nEven more complex / nested example:\n\n```sql\nsql_chunk('dbr.shinydemo.cities.europe_large')\n#\u003e SELECT Name\n#\u003e FROM City\n#\u003e WHERE\n#\u003e   Population \u003e 1000000 AND\n#\u003e   Name IN (\n#\u003e     SELECT Name\n#\u003e     FROM City\n#\u003e     WHERE CountryCode IN (\n#\u003e       SELECT Code\n#\u003e       FROM Country\n#\u003e       WHERE Continent = 'Europe')))\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaroczig%2Fdbr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaroczig%2Fdbr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaroczig%2Fdbr/lists"}