Merge pull request #68 from Metropolitan-Council/67-functions-returni…

…ng-database-connection-not-table

Implement functions returning database connection, not table

DESCRIPTION

@@ -1,8 +1,8 @@
 Type: Package
 Package: councilR
 Title: Functions and Templates for the Metropolitan Council
-Version: 0.2.3
-Date: 2023-09-15
+Version: 0.2.4
+Date: 2023-10-05
 Authors@R: c(
     person("Metropolitan Council", role = "cph"),
     person("Liz", "Roten", , "[email protected]", role = c("cre", "aut"),
@@ -25,20 +25,20 @@ Imports:
     cli (>= 3.6.1),
     data.table (>= 1.14.8),
     DBI (>= 1.1.3),
-    dplyr (>= 1.1.2),
+    dplyr (>= 1.1.3),
     fs (>= 1.6.3),
-    ggplot2 (>= 3.4.2),
-    ggspatial (>= 1.1.8),
+    ggplot2 (>= 3.4.3),
+    ggspatial (>= 1.1.9),
     glue (>= 1.6.2),
     magrittr (>= 2.0.3),
     odbc (>= 1.3.5),
     plotly (>= 4.10.2),
-    purrr (>= 1.0.1),
+    purrr (>= 1.0.2),
     rlang (>= 1.1.1),
     rstudioapi (>= 0.15.0),
     sf (>= 1.0-14),
     tictoc (>= 1.2),
-    tigris (>= 2.0.3),
+    tigris (>= 2.0.4),
     utils
 Suggests: 
     citr (>= 0.3.2),

NAMESPACE

@@ -1,17 +1,21 @@
 # Generated by roxygen2: do not edit by hand
 
 export("%>%")
+export(FRED_connection)
 export(council.pal)
 export(council_layout)
 export(council_pal2)
 export(council_theme)
+export(emissions_connection)
 export(fetch_county_geo)
 export(fetch_ctu_geo)
+export(fred_connection)
 export(import_from_FRED)
 export(import_from_emissions)
 export(import_from_fred)
 export(import_from_gis)
 export(import_from_gpkg)
+export(import_gpkg)
 export(look)
 export(map_council_continuous)
 export(plotly_layout)

R/import_from_FRED.R → R/db_FRED.R

@@ -1,7 +1,35 @@
-#' @title Import data table from FRED (main CD Research database) data stored
+#' @title FRED
+#'
+#' @description
+#' Functions for interacting with FRED, the main CD Research database, stored
 #'  Azure SQL Server
 #'
-#' @param table_name character, which table to pull.
+#' @details
+#' Both "FRED" and "fred" capitalization are supported.
+#'
+#'  - `fred_connection()` creates an S4 Microsoft SQL Server object for FRED.
+#'     This function will *not* automatically close the connection, so take
+#'     care to use [DBI::dbDisconnect()] once you are done.
+#'  - `import_from_fred()` imports a given table from FRED. The connection will
+#'     be automatically closed after the table is imported.
+#'
+#' @note See `vignette("Options")` to review package options.
+#'
+#'  You must be set up with the appropriate database drivers to use these functions.
+#'
+#'  **Windows** users need ODBC with Microsoft SQL. Contact IS support for ODBC installation.
+#'
+#'  **Mac** users need `unixodbc`, `freetds`, and properly configured `odbc.ini`.
+#'
+#'  See instructions in the
+#'  [onboarding guide](https://furry-adventure-596f3adb.pages.github.io/database-connections.html)
+#'  and contact package maintainer for assistance.
+#'  These functions rely on `{rlang}` internal functions.
+#'  Further examples can be found in `vignette("Databases")`.
+#'
+#' @rdname fred
+#' @family database functions
+#'
 #' @param uid character, your network ID.
 #'     Default is `getOption("councilR.uid")`.
 #' @param pwd character, your network password.
@@ -10,44 +38,45 @@
 #' @param prod logical, whether to pull from the test or production db.
 #'     Default is `TRUE`.
 #'
-#'
-#' @note See `vignette("Options")` to review package options.
-#'     You must be set up with the appropriate database drivers to use this function.
-#'     **Windows** users need ODBC with Microsoft SQL. Contact IS support for ODBC installation.
-#'     **Mac** users need `unixodbc`, `freetds`, and properly configured `odbc.ini`.
-#'     See instructions in the
-#'     [onboarding guide](https://furry-adventure-596f3adb.pages.github.io/database-connections.html)
-#'     and contact package maintainer for assistance.
-#'
-#'     This function relies on `[{rlang}]` internal functions.
-#'
-#' @return Requested table
+#' @return `fred_connection()` - A S4 Microsoft SQL Server object
 #' @export
 #'
 #' @examples
 #' \dontrun{
 #' library(councilR)
+#' library(DBI)
 #'
 #' # set options if you haven't already
 #' options(
 #'   councilR.uid = "mc\\you",
 #'   councilR.pwd = "mypwd"
 #' )
+#' # create connection
+#' conn <- FRED_connection(prod = FALSE)
+#'
+#' # pull table using SQL
+#' DBI::dbGetQuery(conn, "SELECT * FROM GQ_UNIT WHERE UNIT_ZIP = 55104")
+#'
+#' # disconnect
+#' DBI::dbDisconnect(conn)
 #'
+#' # import a specific table, with no additional SQL logic
 #' import_from_FRED(table_name = "GQ_UNIT", prod = FALSE)
 #' }
+#'
 #' @importFrom DBI dbCanConnect dbGetQuery dbConnect dbDisconnect
 #' @importFrom odbc odbc
 #' @importFrom utils osVersion
 #' @importFrom purrr map
-import_from_FRED <- function(table_name,
-                             uid = getOption("councilR.uid"),
-                             pwd = getOption("councilR.pwd"),
-                             db = "CD_RESEARCH_WEB",
-                             prod = TRUE) {
+#' @importFrom cli cli_abort
+FRED_connection <- function(
+    uid = getOption("councilR.uid"),
+    pwd = getOption("councilR.pwd"),
+    db = "CD_RESEARCH_WEB",
+    prod = TRUE) {
   # check input types
   purrr::map(
-    c(table_name, uid, pwd, db),
+    c(uid, pwd, db),
     rlang:::check_string
   )
   purrr::map(
@@ -87,7 +116,7 @@ import_from_FRED <- function(table_name,
         Pwd = pwd
       )
       == FALSE) {
-      stop("Database failed to connect")
+      cli::cli_abort("Database failed to connect")
     }
   } else if (drv == "SQL Server") {
     if (
@@ -100,7 +129,7 @@ import_from_FRED <- function(table_name,
         Server = serv,
         Trusted_Connection = "yes"
       ) == FALSE) {
-      stop("Database failed to connect")
+      cli::cli_abort("Database failed to connect")
     }
   }
 
@@ -126,6 +155,44 @@ import_from_FRED <- function(table_name,
       )
     }
 
+  # return connection
+  return(conn)
+}
+
+#' @rdname fred
+#' @export
+fred_connection <- FRED_connection
+
+#'
+#' @param table_name character, which table to pull.
+#'
+#' @return `import_from_FRED()` - Requested table
+#' @export
+#'
+#' @importFrom DBI dbGetQuery dbDisconnect
+#' @rdname fred
+import_from_FRED <- function(table_name,
+                             uid = getOption("councilR.uid"),
+                             pwd = getOption("councilR.pwd"),
+                             db = "CD_RESEARCH_WEB",
+                             prod = TRUE) {
+  # check input types
+  purrr::map(
+    c(table_name, uid, pwd, db),
+    rlang:::check_string
+  )
+  purrr::map(
+    c(prod),
+    rlang:::check_bool
+  )
+
+  conn <- fred_connection(
+    uid = uid,
+    pwd = pwd,
+    db = db,
+    prod = prod
+  )
+
   db_sp_table <- DBI::dbGetQuery(
     conn,
     paste0("SELECT * FROM ", table_name)
@@ -138,7 +205,6 @@ import_from_FRED <- function(table_name,
 
 
 
-#' @rdname import_from_FRED
+#' @rdname fred
 #' @export
 import_from_fred <- import_from_FRED
-

R/import_from_emissions.R → R/db_emissions.R

@@ -14,49 +14,65 @@
 #'  To access Azure, your IP address must be approved. Contact Sean Molloy.
 #'
 #' @note See `vignette("Options")` to review package options.
-#'     You must be set up with the appropriate database drivers to use this function.
+#'     You must be set up with the appropriate database drivers to use these functions.
 #'     **Windows** users need ODBC with Microsoft SQL. Contact IS support for ODBC installation.
 #'     **Mac** users need `unixodbc` and `freetds`. See instructions in the
 #'     [onboarding guide](https://furry-adventure-596f3adb.pages.github.io/database-connections.html)
 #'
-#'     This function relies on `[{rlang}]` internal functions.
+#'     These functions rely on `{rlang}` internal functions.
 #'
 #' @return Requested table
 #' @export
+#' @family database functions
+#' @rdname emissions
+#'
+#' @examples \dontrun{
 #'
-#' @examples
-#' \dontrun{
 #' library(councilR)
+#' library(DBI)
 #'
 #' # set options if you haven't already
 #' options(
 #'   councilR.uid = "mc\\you",
 #'   councilR.pwd = "mypwd"
 #' )
 #'
+#' # create connection
+#' conn <- emissions_connect()
+#'
+#' # pull table using SQL
+#' DBI::dbGetQuery(conn, "SELECT * FROM metro_energy.vw_electricity_residential_ctu")
+#'
+#' # disconnect
+#' DBI::dbDisconnect(conn)
+#'
+#' # get specific tables
 #' t_electricity_residential_ctu <- import_from_emissions(
 #'   table_name = "metro_energy.vw_electricity_residential_ctu"
-#' )
+#'   )
+#'
 #' t_eia_energy_consumption_state <- import_from_emissions(
 #'   table_name = "state_energy.eia_energy_consumption_state"
-#' )
+#'   )
+#'
 # t_utility_natural_gas_by_ctu <- import_from_emissions(
 #'   table_name = "metro_energy.vw_utility_natural_gas_by_ctu"
 #'   )
 #' }
-#' @importFrom DBI dbCanConnect dbGetQuery dbConnect dbDisconnect
+#'
+#' @importFrom DBI dbCanConnect dbConnect
 #' @importFrom odbc odbc
 #' @importFrom utils osVersion
 #' @importFrom purrr map
-import_from_emissions <- function(table_name,
-                                  uid = getOption("councilR.uid"),
-                                  pwd = getOption("councilR.pwd"),
-                                  local = TRUE,
-                                  db = "CD_Emissions") {
-  requireNamespace("rlang", quietly = TRUE)
+#' @importFrom cli cli_abort
+emissions_connection <- function(
+    uid = getOption("councilR.uid"),
+    pwd = getOption("councilR.pwd"),
+    local = TRUE,
+    db = "CD_Emissions") {
   # check input types
   purrr::map(
-    c(table_name, uid, pwd, db),
+    c(uid, pwd, db),
     rlang:::check_string
   )
   purrr::map(
@@ -90,7 +106,7 @@ import_from_emissions <- function(table_name,
         Pwd = pwd,
         Server = serv
       ) == FALSE) {
-      stop("Database failed to connect")
+      cli::cli_abort("Database failed to connect")
     }
   } else if (drv == "SQL Server") {
     if (
@@ -103,12 +119,10 @@ import_from_emissions <- function(table_name,
         Server = serv,
         Trusted_Connection = "yes"
       ) == FALSE) {
-      stop("Database failed to connect")
+      cli::cli_abort("Database failed to connect")
     }
   }
 
-
-
   conn <-
     if (drv == "FreeTDS") {
       DBI::dbConnect(
@@ -131,6 +145,41 @@ import_from_emissions <- function(table_name,
       )
     }
 
+  return(conn)
+}
+
+
+#' @param table_name character, which table to pull.
+#'
+#' @return `import_from_emissions()` - Requested table
+#' @export
+#'
+#' @importFrom DBI dbGetQuery dbDisconnect
+#' @importFrom purrr map
+#' @rdname emissions
+import_from_emissions <- function(table_name,
+                                  uid = getOption("councilR.uid"),
+                                  pwd = getOption("councilR.pwd"),
+                                  local = TRUE,
+                                  db = "CD_Emissions") {
+  # check input types
+  purrr::map(
+    c(table_name, uid, pwd, db),
+    rlang:::check_string
+  )
+  purrr::map(
+    c(local),
+    rlang:::check_bool
+  )
+
+
+  conn <- emissions_connection(
+    uid = uid,
+    pwd = pwd,
+    local = local,
+    db = db
+  )
+
   db_sp_table <- DBI::dbGetQuery(
     conn,
     paste0("SELECT * FROM ", table_name)