Ability to bind data.frames to table valued parameters (#928)

* nanodbc: tvp: complete parameter_* API

Compare to upstream: nanodbc/nanodbc@1d03657

* Allow users to bind data.frames to TVPs in parametrized queries

* code-review: cli API usage

* Update NEWS

* Apply suggestions from code review

Co-authored-by: Simon P. Couch <[email protected]>

* code-review: more robust to first parameter a df

* nanodbc: fixup some casts/silence warnings

* Add some documentation on binding data frames

* fixup docs

---------

Co-authored-by: Simon P. Couch <[email protected]>

Author: detule

NEWS.md

@@ -1,5 +1,13 @@
 # odbc (development version)
 
+* SQL Server: You can now bind `data.frames` to table
+  valued parameters of stored procedures (#928).
+
+* Snowflake: Add `sf_private_key` and `sf_private_key_password`
+  connection attributes to allow users to pass the contents
+  of the PEM formatted private key to the driver directly from
+  memory (#933).
+
 * Fix retrieving multiple result sets from parametrized queries
   in cases when some parameters yield empty results (#927).
 

R/dbi-result.R

@@ -139,7 +139,23 @@ setMethod("dbBind", "OdbcResult",
       return(invisible(res))
     }
 
-    if (is.na(batch_rows)) {
+    paramDfs <- sapply(params, is.data.frame)
+    if (any(paramDfs)) {
+      # When binding table-valued-parameters verify that:
+      # * The `batch_rows` parameter is either unset or equal to one.
+      # * All non-tvp parameters are of length 1.
+      if (!is.na(batch_rows) && batch_rows > 1) {
+        cli::cli_warn(c("Since some parameters are data frames, {.arg batch_rows} will be overwritten to `1`.", 
+                       "Set {.code batch_rows = 1} to quiet this warning."))
+      }
+      batch_rows <- 1
+      paramLengths <- sapply(params[!paramDfs], length)
+      if (any(paramLengths > 1))
+      {
+        cli::cli_abort("When mixing data.frame(s) with other parameter types,
+                       all non-df parameters must be of length one")
+      }
+    } else if (is.na(batch_rows)) {
       batch_rows <- length(params[[1]])
     }
 

R/driver-sql-server.R

@@ -5,6 +5,18 @@
 #'
 #' Details of SQL Server methods for odbc and DBI generics.
 #'
+#' Note on binding \href{https://learn.microsoft.com/en-us/sql/relational-databases/tables/use-table-valued-parameters-database-engine}{TVPs}:
+#' You can bind `data.frame`s to SQL Server TVPs when executing stored procedures with the following caveats:
+#' * All non-df parameters must be of length 1; and
+#' * The `batch_rows` parameter (to `dbBind`, for example) should be set to 1.
+#' @examples
+#' \dontrun{
+#' # Bind `data.frame` to a TVP when executing a
+#' # stored procedure that takes three parameters:
+#' # a TVP, an INT and a VARCHAR(max).
+#' res <- dbGetQuery(conn, "{ CALL example_sproc(?, ?, ?) }",
+#'   params = list(df.data, 100, "Lorem ipsum dolor sit amet"))
+#' }
 #' @rdname SQLServer
 #' @export
 setClass("Microsoft SQL Server", contains = "OdbcConnection")

man/SQLServer.Rd

@@ -1973,7 +1973,7 @@ class statement::statement_impl
 
         describe_parameters(param_index);
         const SQLSMALLINT& param_scale = param_descr_data_.at(param_index).scale_;
-        NANODBC_ASSERT(param_scale < static_cast<SQLULEN>(std::numeric_limits<short>::max()));
+        NANODBC_ASSERT(param_scale < static_cast<SQLSMALLINT>(std::numeric_limits<short>::max()));
         return static_cast<short>(param_scale);
     }
 
@@ -1986,7 +1986,7 @@ class statement::statement_impl
 
         describe_parameters(param_index);
         const SQLSMALLINT& param_type = param_descr_data_.at(param_index).type_;
-        NANODBC_ASSERT(param_type < static_cast<SQLULEN>(std::numeric_limits<short>::max()));
+        NANODBC_ASSERT(param_type < static_cast<SQLSMALLINT>(std::numeric_limits<short>::max()));
         return static_cast<short>(param_type);
     }
 
@@ -2902,6 +2902,48 @@ class table_valued_parameter::table_valued_parameter_impl
         }
     }
 
+    short parameters() const { return param_descr_data_.size(); }
+
+    unsigned long parameter_size(short param_index)
+    {
+        if (param_descr_data_.count(param_index))
+        {
+            return static_cast<unsigned long>(param_descr_data_.at(param_index).size_);
+        }
+
+        prepare_tvp_param_all();
+        const SQLULEN& param_size = param_descr_data_.at(param_index).size_;
+        NANODBC_ASSERT(
+            param_size < static_cast<SQLULEN>(std::numeric_limits<unsigned long>::max()));
+        return static_cast<unsigned long>(param_size);
+    }
+
+    short parameter_scale(short param_index)
+    {
+        if (param_descr_data_.count(param_index))
+        {
+            return static_cast<short>(param_descr_data_.at(param_index).scale_);
+        }
+
+        prepare_tvp_param_all();
+        const SQLSMALLINT& param_scale = param_descr_data_.at(param_index).scale_;
+        NANODBC_ASSERT(param_scale < static_cast<SQLSMALLINT>(std::numeric_limits<short>::max()));
+        return static_cast<short>(param_scale);
+    }
+
+    short parameter_type(short param_index)
+    {
+        if (param_descr_data_.count(param_index))
+        {
+            return static_cast<short>(param_descr_data_.at(param_index).type_);
+        }
+
+        prepare_tvp_param_all();
+        const SQLSMALLINT& param_type = param_descr_data_.at(param_index).type_;
+        NANODBC_ASSERT(param_type < static_cast<SQLSMALLINT>(std::numeric_limits<short>::max()));
+        return static_cast<short>(param_type);
+    }
+
     // comparator for null sentry values
     template <class T>
     bool equals(T const& lhs, T const& rhs)
@@ -5272,8 +5314,8 @@ NANODBC_INSTANTIATE_TVP_BIND_STRINGS(wide_string_type);
 NANODBC_INSTANTIATE_TVP_BIND_VECTOR_STRINGS(string_type);
 
 #ifdef NANODBC_HAS_STD_STRING_VIEW
-/NANODBC_INSTANTIATE_TVP_BIND_VECTOR_STRINGS(std::string_view);
-/NANODBC_INSTANTIATE_TVP_BIND_VECTOR_STRINGS(wide_string_view);
+NANODBC_INSTANTIATE_TVP_BIND_VECTOR_STRINGS(std::string_view);
+NANODBC_INSTANTIATE_TVP_BIND_VECTOR_STRINGS(wide_string_view);
 #endif
 
 #undef NANODBC_INSTANTIATE_TVP_BINDS
@@ -5397,6 +5439,26 @@ void table_valued_parameter::describe_parameters(
 {
     impl_->describe_parameters(idx, type, size, scale);
 }
+
+short table_valued_parameter::parameters() const
+{
+    return impl_->parameters();
+}
+
+unsigned long table_valued_parameter::parameter_size(short param_index) const
+{
+    return impl_->parameter_size(param_index);
+}
+
+short table_valued_parameter::parameter_scale(short param_index) const
+{
+    return impl_->parameter_scale(param_index);
+}
+
+short table_valued_parameter::parameter_type(short param_index) const
+{
+    return impl_->parameter_type(param_index);
+}
 } // namespace nanodbc
 #endif // NANODBC_DISABLE_MSSQL_TVP
 

src/nanodbc/nanodbc.cpp

@@ -648,6 +648,19 @@ class table_valued_parameter
         const std::vector<unsigned long>& size,
         const std::vector<short>& scale);
 
+    /// \brief Returns the number of columns in the table valued parameter.
+    /// \throws database_error
+    short parameters() const;
+
+    /// \brief Returns parameter size for indicated column in the TVP.
+    unsigned long parameter_size(short param_index) const;
+
+    /// \brief Returns parameter scale for indicated column in the TVP.
+    short parameter_scale(short param_index) const;
+
+    /// \brief Returns parameter type for indicated column in the TVP.
+    short parameter_type(short param_index) const;
+
 private:
     class table_valued_parameter_impl;
     friend class statement;