feat: New duck_exec(), replaces duckplyr_execute()

NAMESPACE

@@ -152,6 +152,7 @@ export(df_from_parquet)
 export(df_to_parquet)
 export(distinct)
 export(duck_csv)
+export(duck_exec)
 export(duck_file)
 export(duck_json)
 export(duck_parquet)

R/duckplyr_execute.R

@@ -1,5 +1,8 @@
 #' Execute a statement for the default connection
 #'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
 #' The \pkg{duckplyr} package relies on a DBI connection
 #' to an in-memory database.
 #' The `duckplyr_execute()` function allows running SQL statements
@@ -10,10 +13,13 @@
 #'
 #' @param sql The statement to run.
 #' @return The return value of the [DBI::dbExecute()] call, invisibly.
+#' @keywords internal
 #' @export
 #' @examples
 #' duckplyr_execute("SET threads TO 2")
 duckplyr_execute <- function(sql) {
+  lifecycle::deprecate_soft("1.0.0", "duckplyr_execute()", "duck_exec()")
+
   con <- get_default_duckdb_connection()
   invisible(DBI::dbExecute(con, sql))
 }

R/exec.R

@@ -0,0 +1,31 @@
+#' Execute a statement for the default connection
+#'
+#' The \pkg{duckplyr} package relies on a DBI connection
+#' to an in-memory database.
+#' The `duck_exec()` function allows running SQL statements
+#' with this connection to, e.g., set up credentials
+#' or attach other databases.
+#' See <https://duckdb.org/docs/configuration/overview.html>
+#' for more information on the configuration options.
+#'
+#' @seealso [duck_sql()]
+#'
+#' @param sql The statement to run.
+#' @inheritParams duck_sql
+#' @return The return value of the [DBI::dbExecute()] call, invisibly.
+#' @export
+#' @examples
+#' duck_exec("SET threads TO 2")
+duck_exec <- function(sql, ..., con = NULL) {
+  check_dots_empty()
+
+  if (!is_string(sql)) {
+    cli::cli_abort("{.arg sql} must be a string.")
+  }
+
+  if (is.null(con)) {
+    con <- get_default_duckdb_connection()
+  }
+
+  invisible(DBI::dbExecute(con, sql))
+}

R/io2.R

@@ -68,8 +68,8 @@ duck_csv <- function(path, ..., lazy = TRUE, options = list()) {
 #' writeLines('[{"a": 1, "b": "x"}, {"a": 2, "b": "y"}]', path)
 #'
 #' # Reading needs the json extension
-#' duckplyr_execute("INSTALL json")
-#' duckplyr_execute("LOAD json")
+#' duck_exec("INSTALL json")
+#' duck_exec("LOAD json")
 #' duck_json(path)
 duck_json <- function(path, ..., lazy = TRUE, options = list()) {
   check_dots_empty()

R/sql.R

@@ -9,6 +9,8 @@
 #' Using data frames from the calling environment is not supported yet,
 #' see <https://github.com/duckdb/duckdb-r/issues/645> for details.
 #'
+#' @seealso [duck_exec()]
+#'
 #' @inheritParams duck_file
 #' @param sql The SQL to run.
 #' @param con The connection, defaults to the default connection.

_pkgdown.yml

@@ -70,7 +70,7 @@ reference:
   - fallback
   - stats_show
   - last_rel
-  - duckplyr_execute
+  - duck_exec
 
 - title: Relational operations and expressions
   contents: