|
1 | | -#' Connect to a Supabase Database with Automatic Cleanup |
| 1 | +#' Connect to a 'PostgreSQL' Database with Automatic Cleanup |
2 | 2 | #' |
3 | | -#' This function establishes a connection pool to a Supabase database and sets |
4 | | -#' up automatic cleanup when the Shiny session ends. |
| 3 | +#' This function establishes a connection pool to a 'PostgreSQL' database |
| 4 | +#' (e.g. Supabase) and sets up automatic cleanup when the 'shiny' session ends. |
5 | 5 | #' |
6 | 6 | #' @param host Character string. The host address of the Supabase database. |
7 | 7 | #' @param dbname Character string. The name of the Supabase database. |
8 | 8 | #' @param port Integer. The port number for the Supabase database connection. |
9 | 9 | #' @param user Character string. The username for the Supabase database |
10 | | -#' connection. |
| 10 | +#' connection. |
11 | 11 | #' @param table Character string. The name of the table to interact with in |
12 | | -#' the Supabase database. |
| 12 | +#' the Supabase database. |
13 | 13 | #' @param password Character string. The password for the Supabase database |
14 | | -#' connection. NOTE: While you can provide a hard-coded password here, we do |
15 | | -#' NOT recommend doing so for security purposes. Instead, you should establish |
16 | | -#' a password with `surveydown::sd_set_password()`, which will create a local |
17 | | -#' .Renviron file that stores you password as a SURVEYDOWN_PASSWORD environment |
18 | | -#' variable. The `password` argument uses this as the default value, so if you |
19 | | -#' set a password properly with `surveydown::sd_set_password()`, then you can |
20 | | -#' safely ignore using the `password` argument here. |
| 14 | +#' connection. NOTE: While you can provide a hard-coded password here, we do |
| 15 | +#' NOT recommend doing so for security purposes. Instead, you should establish |
| 16 | +#' a password with `surveydown::sd_set_password()`, which will create a local |
| 17 | +#' `.Renviron` file that stores your password as a `SURVEYDOWN_PASSWORD` |
| 18 | +#' environment |
| 19 | +#' variable. The `password` argument uses this as the default value, so if you |
| 20 | +#' set a password properly with `surveydown::sd_set_password()`, then you can |
| 21 | +#' safely ignore using the `password` argument here. |
21 | 22 | #' @param gssencmode Character string. The GSS encryption mode for the database |
22 | | -#' connection. Defaults to `"prefer"`. NOTE: If you have verified all |
23 | | -#' connection details are correct but still cannot access the database, |
24 | | -#' consider setting this to `"disable"`. This can be necessary if you're on a |
25 | | -#' secure connection, such as a VPN. |
26 | | -#' @param ignore Logical. If TRUE, data will be saved to a local CSV file instead of the database. Defaults to FALSE. |
27 | | -#' @param min_size Integer. The minimum number of connections in the pool. Defaults to 1. |
28 | | -#' @param max_size Integer. The maximum number of connections in the pool. Defaults to Inf. |
| 23 | +#' connection. Defaults to `"prefer"`. NOTE: If you have verified all |
| 24 | +#' connection details are correct but still cannot access the database, |
| 25 | +#' consider setting this to `"disable"`. This can be necessary if you're on a |
| 26 | +#' secure connection, such as a VPN. |
| 27 | +#' @param ignore Logical. If `TRUE`, data will be saved to a local CSV file |
| 28 | +#' instead of the database. Defaults to `FALSE`. |
| 29 | +#' @param min_size Integer. The minimum number of connections in the pool. |
| 30 | +#' Defaults to 1. |
| 31 | +#' @param max_size Integer. The maximum number of connections in the pool. |
| 32 | +#' Defaults to `Inf`. |
29 | 33 | #' |
30 | | -#' @return A list containing the database connection pool (`db`) and the table name (`table`), |
31 | | -#' or NULL if in ignore mode or if there's an error. |
| 34 | +#' @return A list containing the database connection pool (`db`) and the table |
| 35 | +#' name (`table`), or `NULL` if in ignore mode or if there's an error. |
32 | 36 | #' |
33 | 37 | #' @examples |
34 | | -#' \dontrun{ |
| 38 | +#' if (interactive()) { |
35 | 39 | #' # Assuming SURVEYDOWN_PASSWORD is set in .Renviron |
36 | | -#' db_connection <- sd_database( |
37 | | -#' host = "aws-0-us-west-1.pooler.supabase.com", |
38 | | -#' dbname = "postgres", |
39 | | -#' port = "6---", |
40 | | -#' user = "postgres.k----------i", |
41 | | -#' table = "your-table-name", |
42 | | -#' ignore = FALSE |
| 40 | +#' db <- sd_database( |
| 41 | +#' host = "aws-0-us-west-1.pooler.supabase.com", |
| 42 | +#' dbname = "postgres", |
| 43 | +#' port = "6---", |
| 44 | +#' user = "postgres.k----------i", |
| 45 | +#' table = "your-table-name", |
| 46 | +#' ignore = FALSE |
43 | 47 | #' ) |
44 | 48 | #' |
45 | | -#' # Explicitly providing the password |
46 | | -#' db_connection <- sd_database( |
47 | | -#' host = "aws-0-us-west-1.pooler.supabase.com", |
48 | | -#' dbname = "postgres", |
49 | | -#' port = "6---", |
50 | | -#' user = "postgres.k----------i", |
51 | | -#' table = "your-table-name", |
52 | | -#' password = "your-password", |
53 | | -#' ignore = FALSE |
54 | | -#' ) |
55 | | -#' } |
| 49 | +#' # Print the structure of the connection |
| 50 | +#' str(db) |
56 | 51 | #' |
| 52 | +#' # Close the connection pool when done |
| 53 | +#' if (!is.null(db)) { |
| 54 | +#' pool::poolClose(db$db) |
| 55 | +#' } |
| 56 | +#' } |
57 | 57 | #' @export |
58 | 58 | sd_database <- function( |
59 | 59 | host = NULL, |
@@ -120,38 +120,47 @@ sd_database <- function( |
120 | 120 | #' |
121 | 121 | #' This function retrieves all data from a specified table in a database. |
122 | 122 | #' It automatically detects whether it's being used in a reactive context |
123 | | -#' (e.g., within a Shiny application) and behaves accordingly. In a reactive |
| 123 | +#' (e.g., within a 'shiny' application) and behaves accordingly. In a reactive |
124 | 124 | #' context, it returns a reactive expression that automatically refreshes |
125 | 125 | #' the data at specified intervals. |
126 | 126 | #' |
127 | | -#' @param db A list containing database connection details. Must have elements: |
| 127 | +#' @param db A list containing database connection details created using |
| 128 | +#' `sd_database()`. Must have elements: |
128 | 129 | #' \itemize{ |
129 | | -#' \item db: A DBI database connection object |
130 | | -#' \item table: A string specifying the name of the table to query |
| 130 | +#' \item `db`: A `DBI` database connection object |
| 131 | +#' \item `table`: A string specifying the name of the table to query |
131 | 132 | #' } |
132 | | -#' @param refresh_interval Numeric. The time interval (in seconds) between data refreshes |
133 | | -#' when in a reactive context. Default is `NULL`, meaning the data will not refresh. |
134 | | -#' |
135 | | -#' @return In a non-reactive context, returns a data frame containing all rows and columns |
136 | | -#' from the specified table. In a reactive context, returns a reactive expression that, |
137 | | -#' when called, returns the most recent data from the specified database table. |
| 133 | +#' @param refresh_interval Numeric. The time interval (in seconds) between data |
| 134 | +#' refreshes when in a reactive context. Default is `NULL`, meaning the data |
| 135 | +#' will not refresh. |
138 | 136 | #' |
139 | | -#' @export |
| 137 | +#' @return In a non-reactive context, returns a data frame containing all rows |
| 138 | +#' and columns from the specified table. In a reactive context, returns a |
| 139 | +#' reactive expression that, when called, returns the most recent data from |
| 140 | +#' the specified database table. |
140 | 141 | #' |
141 | 142 | #' @examples |
| 143 | +#' # Non-reactive context example |
142 | 144 | #' \dontrun{ |
143 | | -#' # Non-reactive context |
144 | | -#' db <- list(db = DBI::dbConnect(...), table = "my_table") |
145 | | -#' data <- sd_get_data(db) |
| 145 | +#' library(surveydown) |
146 | 146 | #' |
147 | | -#' # Reactive context (inside a Shiny server function) |
148 | | -#' server <- function(input, output, session) { |
149 | | -#' data <- sd_get_data(db, refresh_interval = 10) |
150 | | -#' output$table <- renderTable({ |
151 | | -#' data() # Note the parentheses to retrieve the reactive value |
152 | | -#' }) |
153 | | -#' } |
| 147 | +#' # Assuming you have a database connection called db created using |
| 148 | +#' # sd_database(), you can fetch data with: |
| 149 | +#' |
| 150 | +#' data <- sd_get_data(db) |
| 151 | +#' head(data) |
| 152 | +#' |
| 153 | +#' # Reactive context example (inside a surveydown app) |
| 154 | +#' |
| 155 | +#' server <- function(input, output, session) { |
| 156 | +#' data <- sd_get_data(db, refresh_interval = 10) |
| 157 | +#' |
| 158 | +#' output$data_table <- renderTable({ |
| 159 | +#' data() # Note the parentheses to retrieve the reactive value |
| 160 | +#' }) |
| 161 | +#' } |
154 | 162 | #' } |
| 163 | +#' @export |
155 | 164 | sd_get_data <- function(db, refresh_interval = NULL) { |
156 | 165 | if (is.null(db)) { |
157 | 166 | warning("Database is not connected, db is NULL") |
|
0 commit comments