From d817b64626bfb1f6c53e41315e7117d7dec44084 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Fri, 17 Dec 2021 07:56:39 +0100 Subject: [PATCH 1/5] Document --- man/dbQuoteLiteral.Rd | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/man/dbQuoteLiteral.Rd b/man/dbQuoteLiteral.Rd index 250323fbb..1077dbacc 100644 --- a/man/dbQuoteLiteral.Rd +++ b/man/dbQuoteLiteral.Rd @@ -17,7 +17,15 @@ dbQuoteLiteral(conn, x, ...) \value{ \code{dbQuoteLiteral()} returns an object that can be coerced to \link{character}, of the same length as the input. -For an empty character vector this function returns a length-0 object. +For an empty +integer, +numeric, +character, +logical, +date, +time, +or blob vector, +this function returns a length-0 object. When passing the returned object again to \code{dbQuoteLiteral()} as \code{x} From 3a20ec872e2a8401051d02c7727fd0e351de89e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Fri, 17 Dec 2021 08:07:05 +0100 Subject: [PATCH 2/5] Document failure modes in a separate section --- R/DBConnection.R | 14 ++++++++++-- R/DBDriver.R | 1 + R/DBResult.R | 8 +++++++ R/quote.R | 4 ++++ R/transactions.R | 2 ++ man/dbBind.Rd | 44 ++++++++++++++++++++++---------------- man/dbClearResult.Rd | 10 +++++++-- man/dbColumnInfo.Rd | 11 ++++++++-- man/dbDataType.Rd | 10 +++++++-- man/dbDisconnect.Rd | 2 +- man/dbExecute.Rd | 14 ++++++++---- man/dbExistsTable.Rd | 13 +++++++---- man/dbFetch.Rd | 20 +++++++++++------ man/dbGetQuery.Rd | 20 +++++++++++------ man/dbGetRowCount.Rd | 10 +++++++-- man/dbGetRowsAffected.Rd | 10 +++++++-- man/dbGetStatement.Rd | 10 +++++++-- man/dbHasCompleted.Rd | 12 +++++++++-- man/dbListFields.Rd | 12 ++++++++--- man/dbListObjects.Rd | 10 +++++++-- man/dbListTables.Rd | 10 +++++++-- man/dbQuoteIdentifier.Rd | 12 ++++++++--- man/dbQuoteLiteral.Rd | 12 ++++++++--- man/dbQuoteString.Rd | 20 +++++++++++------ man/dbReadTable.Rd | 37 ++++++++++++++++++++++---------- man/dbRemoveTable.Rd | 16 +++++++++----- man/dbSendQuery.Rd | 20 +++++++++++------ man/dbSendStatement.Rd | 20 +++++++++++------ man/dbUnquoteIdentifier.Rd | 12 ++++++++--- man/dbWithTransaction.Rd | 16 +++++++++----- man/dbWriteTable.Rd | 24 +++++++++++++++------ man/transactions.Rd | 26 +++++++++++++--------- 32 files changed, 331 insertions(+), 131 deletions(-) diff --git a/R/DBConnection.R b/R/DBConnection.R index d5f1d561e..b2b0f3caf 100644 --- a/R/DBConnection.R +++ b/R/DBConnection.R @@ -59,7 +59,7 @@ show_connection <- function(object) { #' @templateVar method_name dbDisconnect #' #' @inherit DBItest::spec_connection_disconnect return -#' @inheritSection DBItest::spec_connection_disconnect Specification +#' @inheritSection DBItest::spec_connection_disconnect Failure modes #' #' @inheritParams dbGetQuery #' @family DBIConnection generics @@ -96,6 +96,7 @@ setGeneric("dbDisconnect", #' @templateVar method_name dbSendQuery #' #' @inherit DBItest::spec_result_send_query return +#' @inheritSection DBItest::spec_result_send_query Failure modes #' @inheritSection DBItest::spec_result_send_query Additional arguments #' @inheritSection DBItest::spec_result_send_query Specification #' @inheritSection DBItest::spec_result_send_query Specification for the `immediate` argument @@ -155,6 +156,7 @@ setGeneric("dbSendQuery", #' @templateVar method_name dbSendStatement #' #' @inherit DBItest::spec_result_send_statement return +#' @inheritSection DBItest::spec_result_send_statement Failure modes #' @inheritSection DBItest::spec_result_send_statement Additional arguments #' @inheritSection DBItest::spec_result_send_statement Specification #' @inheritSection DBItest::spec_result_send_statement Specification for the `immediate` argument @@ -236,6 +238,7 @@ setMethod( #' @templateVar method_name dbGetQuery #' #' @inherit DBItest::spec_result_get_query return +#' @inheritSection DBItest::spec_result_get_query Failure modes #' @inheritSection DBItest::spec_result_get_query Additional arguments #' @inheritSection DBItest::spec_result_get_query Specification #' @inheritSection DBItest::spec_result_get_query Specification for the `immediate` argument @@ -305,6 +308,7 @@ setMethod("dbGetQuery", signature("DBIConnection", "character"), #' performance optimization. #' #' @inherit DBItest::spec_result_execute return +#' @inheritSection DBItest::spec_result_execute Failure modes #' @inheritSection DBItest::spec_result_execute Additional arguments #' @inheritSection DBItest::spec_result_execute Specification #' @inheritSection DBItest::spec_result_execute Specification for the `immediate` argument @@ -386,6 +390,7 @@ setGeneric("dbListResults", #' @inheritParams dbReadTable #' #' @inherit DBItest::spec_sql_list_fields return +#' @inheritSection DBItest::spec_sql_list_fields Failure modes #' @inheritSection DBItest::spec_sql_list_fields Specification #' #' @family DBIConnection generics @@ -444,6 +449,7 @@ list_fields <- function(conn, name) { #' @templateVar method_name dbListTables #' #' @inherit DBItest::spec_sql_list_tables return +#' @inheritSection DBItest::spec_sql_list_tables Failure modes #' #' @inheritParams dbGetQuery #' @family DBIConnection generics @@ -477,7 +483,7 @@ setGeneric("dbListTables", #' @templateVar method_name dbListObjects #' #' @inherit DBItest::spec_sql_list_objects return -#' @inheritSection DBItest::spec_sql_list_objects Additional arguments +#' @inheritSection DBItest::spec_sql_list_objects Failure modes #' @inheritSection DBItest::spec_sql_list_objects Specification #' #' @inheritParams dbGetQuery @@ -524,6 +530,7 @@ setMethod("dbListObjects", signature("DBIConnection", "ANY"), #' @templateVar method_name dbReadTable #' #' @inherit DBItest::spec_sql_read_table return +#' @inheritSection DBItest::spec_sql_read_table Failure modes #' @inheritSection DBItest::spec_sql_read_table Additional arguments #' @inheritSection DBItest::spec_sql_read_table Specification #' @@ -592,6 +599,7 @@ setMethod("dbReadTable", signature("DBIConnection", "Id"), #' @templateVar method_name dbWriteTable #' #' @inherit DBItest::spec_sql_write_table return +#' @inheritSection DBItest::spec_sql_write_table Failure modes #' @inheritSection DBItest::spec_sql_write_table Additional arguments #' @inheritSection DBItest::spec_sql_write_table Specification #' @@ -637,6 +645,7 @@ setMethod("dbWriteTable", signature("DBIConnection", "Id", "ANY"), #' @templateVar method_name dbExistsTable #' #' @inherit DBItest::spec_sql_exists_table return +#' @inheritSection DBItest::spec_sql_exists_table Failure modes #' @inheritSection DBItest::spec_sql_exists_table Specification #' #' @inheritParams dbReadTable @@ -672,6 +681,7 @@ setMethod("dbExistsTable", signature("DBIConnection", "Id"), #' @templateVar method_name dbRemoveTable #' #' @inherit DBItest::spec_sql_remove_table return +#' @inheritSection DBItest::spec_sql_remove_table Failure modes #' @inheritSection DBItest::spec_sql_remove_table Additional arguments #' @inheritSection DBItest::spec_sql_remove_table Specification #' diff --git a/R/DBDriver.R b/R/DBDriver.R index d28ca27c5..7bfb8a75d 100644 --- a/R/DBDriver.R +++ b/R/DBDriver.R @@ -262,6 +262,7 @@ setGeneric("dbListConnections", #' @templateVar method_name dbDataType #' #' @inherit DBItest::spec_driver_data_type return +#' @inheritSection DBItest::spec_driver_data_type Failure modes #' @inheritSection DBItest::spec_driver_data_type Specification #' @inheritSection DBItest::spec_result_create_table_with_data_type Specification #' diff --git a/R/DBResult.R b/R/DBResult.R index 69377b3c8..97322de61 100644 --- a/R/DBResult.R +++ b/R/DBResult.R @@ -64,6 +64,7 @@ show_result <- function(object) { #' @templateVar method_name dbFetch #' #' @inherit DBItest::spec_result_fetch return +#' @inheritSection DBItest::spec_result_fetch Failure modes #' @inheritSection DBItest::spec_result_fetch Specification #' @inheritSection DBItest::spec_result_roundtrip Specification #' @@ -125,6 +126,7 @@ setGeneric("fetch", #' @templateVar method_name dbClearResult #' #' @inherit DBItest::spec_result_clear_result return +#' @inheritSection DBItest::spec_result_clear_result Failure modes #' @inheritSection DBItest::spec_result_clear_result Specification #' #' @param res An object inheriting from [DBIResult-class]. @@ -153,6 +155,7 @@ setGeneric("dbClearResult", #' @inheritParams dbClearResult #' #' @inherit DBItest::spec_meta_column_info return +#' @inheritSection DBItest::spec_meta_column_info Failure modes #' @inheritSection DBItest::spec_meta_column_info Specification #' #' @family DBIResult generics @@ -180,6 +183,7 @@ setGeneric("dbColumnInfo", #' @templateVar method_name dbGetStatement #' #' @inherit DBItest::spec_meta_get_statement return +#' @inheritSection DBItest::spec_meta_get_statement Failure modes #' #' @inheritParams dbClearResult #' @family DBIResult generics @@ -209,6 +213,7 @@ setGeneric("dbGetStatement", #' @templateVar method_name dbHasCompleted #' #' @inherit DBItest::spec_meta_has_completed return +#' @inheritSection DBItest::spec_meta_has_completed Failure modes #' @inheritSection DBItest::spec_meta_has_completed Specification #' #' @inheritParams dbClearResult @@ -243,6 +248,7 @@ setGeneric("dbHasCompleted", #' @templateVar method_name dbGetRowsAffected #' #' @inherit DBItest::spec_meta_get_rows_affected return +#' @inheritSection DBItest::spec_meta_get_rows_affected Failure modes #' #' @inheritParams dbClearResult #' @family DBIResult generics @@ -272,6 +278,7 @@ setGeneric("dbGetRowsAffected", #' @templateVar method_name dbGetRowCount #' #' @inherit DBItest::spec_meta_get_row_count return +#' @inheritSection DBItest::spec_meta_get_row_count Failure modes #' #' @inheritParams dbClearResult #' @family DBIResult generics @@ -352,6 +359,7 @@ setMethod("dbGetInfo", signature("DBIResult"), function(dbObj, ...) { #' @templateVar method_name dbBind #' #' @inherit DBItest::spec_meta_bind return +#' @inheritSection DBItest::spec_meta_bind Failure modes #' @inheritSection DBItest::spec_meta_bind Specification #' #' @inheritParams dbClearResult diff --git a/R/quote.R b/R/quote.R index 13ef48f4a..0ac0a7871 100644 --- a/R/quote.R +++ b/R/quote.R @@ -83,6 +83,7 @@ setMethod("show", "SQL", function(object) { #' @templateVar method_name dbQuoteIdentifier #' #' @inherit DBItest::spec_sql_quote_identifier return +#' @inheritSection DBItest::spec_sql_quote_identifier Failure modes #' @inheritSection DBItest::spec_sql_quote_identifier Specification #' #' @family DBIResult generics @@ -161,6 +162,7 @@ setMethod("dbQuoteIdentifier", signature("DBIConnection", "Id"), quote_identifie #' @templateVar method_name dbUnquoteIdentifier #' #' @inherit DBItest::spec_sql_unquote_identifier return +#' @inheritSection DBItest::spec_sql_unquote_identifier Failure modes #' @inheritSection DBItest::spec_sql_unquote_identifier Specification #' #' @family DBIResult generics @@ -251,6 +253,7 @@ as_table <- function(catalog, schema, table) { #' @templateVar method_name dbQuoteString #' #' @inherit DBItest::spec_sql_quote_string return +#' @inheritSection DBItest::spec_sql_quote_string Failure modes #' @inheritSection DBItest::spec_sql_quote_string Specification #' #' @family DBIResult generics @@ -321,6 +324,7 @@ setMethod("dbQuoteString", signature("DBIConnection", "SQL"), quote_string) #' @templateVar method_name dbQuoteLiteral #' #' @inherit DBItest::spec_sql_quote_literal return +#' @inheritSection DBItest::spec_sql_quote_literal Failure modes #' @inheritSection DBItest::spec_sql_quote_literal Specification #' #' @family DBIResult generics diff --git a/R/transactions.R b/R/transactions.R index 0552bacbb..1e0b36831 100644 --- a/R/transactions.R +++ b/R/transactions.R @@ -18,6 +18,7 @@ NULL #' @templateVar method_name transactions #' #' @inherit DBItest::spec_transaction_begin_commit_rollback return +#' @inheritSection DBItest::spec_transaction_begin_commit_rollback Failure modes #' @inheritSection DBItest::spec_transaction_begin_commit_rollback Specification #' #' @inheritParams dbGetQuery @@ -94,6 +95,7 @@ setGeneric("dbRollback", #' @templateVar method_name dbWithTransaction #' #' @inherit DBItest::spec_transaction_with_transaction return +#' @inheritSection DBItest::spec_transaction_with_transaction Failure modes #' @inheritSection DBItest::spec_transaction_with_transaction Specification #' #' @inheritParams dbGetQuery diff --git a/man/dbBind.Rd b/man/dbBind.Rd index b621d874e..2cbeecf6f 100644 --- a/man/dbBind.Rd +++ b/man/dbBind.Rd @@ -19,25 +19,6 @@ invisibly, for queries issued by \code{\link[=dbSendQuery]{dbSendQuery()}} and also for data manipulation statements issued by \code{\link[=dbSendStatement]{dbSendStatement()}}. -Calling \code{dbBind()} for a query without parameters -raises an error. -Binding too many -or not enough values, -or parameters with wrong names -or unequal length, -also raises an error. -If the placeholders in the query are named, -all parameter values must have names -(which must not be empty -or \code{NA}), -and vice versa, -otherwise an error is raised. -The behavior for mixing placeholders of different types -(in particular mixing positional and named placeholders) -is not specified. - -Calling \code{dbBind()} on a result set already cleared by \code{\link[=dbClearResult]{dbClearResult()}} -also raises an error. } \description{ For parametrized or prepared statements, @@ -76,6 +57,31 @@ Known examples are: \item \verb{:name} and \verb{$name} (named matching) in \pkg{RSQLite} } } +\section{Failure modes}{ + + +Calling \code{dbBind()} for a query without parameters +raises an error. +Binding too many +or not enough values, +or parameters with wrong names +or unequal length, +also raises an error. +If the placeholders in the query are named, +all parameter values must have names +(which must not be empty +or \code{NA}), +and vice versa, +otherwise an error is raised. +The behavior for mixing placeholders of different types +(in particular mixing positional and named placeholders) +is not specified. + +Calling \code{dbBind()} on a result set already cleared by \code{\link[=dbClearResult]{dbClearResult()}} +also raises an error. + +} + \section{Specification}{ diff --git a/man/dbClearResult.Rd b/man/dbClearResult.Rd index 588d0b6ff..d91579d43 100644 --- a/man/dbClearResult.Rd +++ b/man/dbClearResult.Rd @@ -15,8 +15,6 @@ dbClearResult(res, ...) \code{dbClearResult()} returns \code{TRUE}, invisibly, for result sets obtained from both \code{dbSendQuery()} and \code{dbSendStatement()}. -An attempt to close an already closed result set issues a warning -in both cases. } \description{ Frees all resources (local and remote) associated with a result set. In some @@ -25,6 +23,14 @@ exhausting resources (memory, file descriptors, etc.) \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbClearResult")} } +\section{Failure modes}{ + + +An attempt to close an already closed result set issues a warning +in both cases. + +} + \section{Specification}{ diff --git a/man/dbColumnInfo.Rd b/man/dbColumnInfo.Rd index 779c7913b..ad02a09a1 100644 --- a/man/dbColumnInfo.Rd +++ b/man/dbColumnInfo.Rd @@ -21,8 +21,6 @@ of the R columns of the data frame that is returned from \code{\link[=dbFetch]{d The \code{"type"} column is of type \code{character} and only for information. Do not compute on the \code{"type"} column, instead use \code{dbFetch(res, n = 0)} to create a zero-row data frame initialized with the correct data types. - -An attempt to query columns for a closed result set raises an error. } \description{ Produces a data.frame that describes the output of a query. The data.frame @@ -30,6 +28,13 @@ should have as many rows as there are output fields in the result set, and each column in the data.frame describes an aspect of the result set field (field name, type, etc.) } +\section{Failure modes}{ + + +An attempt to query columns for a closed result set raises an error. + +} + \section{Specification}{ @@ -38,8 +43,10 @@ A column named \code{row_names} is treated like any other column. The column names are always consistent with the data returned by \code{dbFetch()}. + If the query returns unnamed columns, non-empty and non-\code{NA} names are assigned. + Column names that correspond to SQL or R keywords are left unchanged. } diff --git a/man/dbDataType.Rd b/man/dbDataType.Rd index 925ec85aa..3d4beead8 100644 --- a/man/dbDataType.Rd +++ b/man/dbDataType.Rd @@ -20,8 +20,6 @@ as a non-empty character string. For data frames, a character vector with one element per column is returned. -An error is raised for invalid values for the \code{obj} argument such as a -\code{NULL} value. } \description{ Returns an SQL string that describes the SQL data type to be used for an @@ -47,6 +45,14 @@ integer vectors. Notice that many DBMS do not follow IEEE arithmetic, so there are potential problems with under/overflows and loss of precision. } +\section{Failure modes}{ + + +An error is raised for invalid values for the \code{obj} argument such as a +\code{NULL} value. + +} + \section{Specification}{ diff --git a/man/dbDisconnect.Rd b/man/dbDisconnect.Rd index e526a94ae..6d4ff8cd8 100644 --- a/man/dbDisconnect.Rd +++ b/man/dbDisconnect.Rd @@ -21,7 +21,7 @@ resources (e.g., memory, sockets). \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbDisconnect")} } -\section{Specification}{ +\section{Failure modes}{ A warning is issued on garbage collection when a connection has been diff --git a/man/dbExecute.Rd b/man/dbExecute.Rd index 57a701a37..1f3e80f78 100644 --- a/man/dbExecute.Rd +++ b/man/dbExecute.Rd @@ -20,10 +20,6 @@ scalar numeric that specifies the number of rows affected by the statement. -An error is raised when issuing a statement over a closed -or invalid connection, -if the syntax of the statement is invalid, -or if the statement is not a non-\code{NA} string. } \description{ Executes a statement and returns the number of rows affected. @@ -45,6 +41,16 @@ Subclasses should override this method only if they provide some sort of performance optimization. } +\section{Failure modes}{ + + +An error is raised when issuing a statement over a closed +or invalid connection, +if the syntax of the statement is invalid, +or if the statement is not a non-\code{NA} string. + +} + \section{Additional arguments}{ diff --git a/man/dbExistsTable.Rd b/man/dbExistsTable.Rd index 5b4186914..9f9ca4538 100644 --- a/man/dbExistsTable.Rd +++ b/man/dbExistsTable.Rd @@ -27,18 +27,23 @@ given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} specified by the \code{name} argument exists, \code{FALSE} otherwise. This includes temporary tables if supported by the database. +} +\description{ +Returns if a table given by name exists in the database. + +\Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbExistsTable")} +} +\section{Failure modes}{ + An error is raised when calling this method for a closed or invalid connection. An error is also raised if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or if this results in a non-scalar. -} -\description{ -Returns if a table given by name exists in the database. -\Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbExistsTable")} } + \section{Specification}{ diff --git a/man/dbFetch.Rd b/man/dbFetch.Rd index 9c8dbc6dd..d3f2bc248 100644 --- a/man/dbFetch.Rd +++ b/man/dbFetch.Rd @@ -27,13 +27,6 @@ columns as fields in the result set, even if the result is a single value or has one or zero rows. -An attempt to fetch from a closed result set raises an error. -If the \code{n} argument is not an atomic whole number -greater or equal to -1 or Inf, an error is raised, -but a subsequent call to \code{dbFetch()} with proper \code{n} argument succeeds. -Calling \code{dbFetch()} on a result set from a data manipulation query -created by \code{\link[=dbSendStatement]{dbSendStatement()}} -can be fetched and return an empty data frame, with a warning. } \description{ Fetch the next \code{n} elements (rows) from the result set and return them @@ -47,6 +40,19 @@ new code you are strongly encouraged to use \code{dbFetch()}. The default implementation for \code{dbFetch()} calls \code{fetch()} so that it is compatible with existing code. Modern backends should implement for \code{dbFetch()} only. } +\section{Failure modes}{ + + +An attempt to fetch from a closed result set raises an error. +If the \code{n} argument is not an atomic whole number +greater or equal to -1 or Inf, an error is raised, +but a subsequent call to \code{dbFetch()} with proper \code{n} argument succeeds. +Calling \code{dbFetch()} on a result set from a data manipulation query +created by \code{\link[=dbSendStatement]{dbSendStatement()}} +can be fetched and return an empty data frame, with a warning. + +} + \section{Specification}{ diff --git a/man/dbGetQuery.Rd b/man/dbGetQuery.Rd index d2887460d..1b2ace42f 100644 --- a/man/dbGetQuery.Rd +++ b/man/dbGetQuery.Rd @@ -21,13 +21,6 @@ columns as fields in the result set, even if the result is a single value or has one or zero rows. -An error is raised when issuing a query over a closed -or invalid connection, -if the syntax of the query is invalid, -or if the query is not a non-\code{NA} string. -If the \code{n} argument is not an atomic whole number -greater or equal to -1 or Inf, an error is raised, -but a subsequent call to \code{dbGetQuery()} with proper \code{n} argument succeeds. } \description{ Returns the result of a query as a data frame. @@ -57,6 +50,19 @@ Subclasses should override this method only if they provide some sort of performance optimization. } +\section{Failure modes}{ + + +An error is raised when issuing a query over a closed +or invalid connection, +if the syntax of the query is invalid, +or if the query is not a non-\code{NA} string. +If the \code{n} argument is not an atomic whole number +greater or equal to -1 or Inf, an error is raised, +but a subsequent call to \code{dbGetQuery()} with proper \code{n} argument succeeds. + +} + \section{Additional arguments}{ diff --git a/man/dbGetRowCount.Rd b/man/dbGetRowCount.Rd index 457cd105c..1d099beae 100644 --- a/man/dbGetRowCount.Rd +++ b/man/dbGetRowCount.Rd @@ -28,8 +28,6 @@ For data manipulation statements issued with \code{\link[=dbSendStatement]{dbSendStatement()}}, zero is returned before and after calling \code{dbFetch()}. -Attempting to get the row count for a result set cleared with -\code{\link[=dbClearResult]{dbClearResult()}} gives an error. } \description{ Returns the total number of rows actually fetched with calls to \code{\link[=dbFetch]{dbFetch()}} @@ -37,6 +35,14 @@ for this result set. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbGetRowCount")} } +\section{Failure modes}{ + + +Attempting to get the row count for a result set cleared with +\code{\link[=dbClearResult]{dbClearResult()}} gives an error. + +} + \examples{ con <- dbConnect(RSQLite::SQLite(), ":memory:") diff --git a/man/dbGetRowsAffected.Rd b/man/dbGetRowsAffected.Rd index 0e47cba45..ec70f9815 100644 --- a/man/dbGetRowsAffected.Rd +++ b/man/dbGetRowsAffected.Rd @@ -20,8 +20,6 @@ and does not change after calling \code{\link[=dbFetch]{dbFetch()}}. For queries issued with \code{\link[=dbSendQuery]{dbSendQuery()}}, zero is returned before and after the call to \code{dbFetch()}. -Attempting to get the rows affected for a result set cleared with -\code{\link[=dbClearResult]{dbClearResult()}} gives an error. } \description{ This method returns the number of rows that were added, deleted, or updated @@ -29,6 +27,14 @@ by a data manipulation statement. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbGetRowsAffected")} } +\section{Failure modes}{ + + +Attempting to get the rows affected for a result set cleared with +\code{\link[=dbClearResult]{dbClearResult()}} gives an error. + +} + \examples{ con <- dbConnect(RSQLite::SQLite(), ":memory:") diff --git a/man/dbGetStatement.Rd b/man/dbGetStatement.Rd index a5c7aff33..2d60b853e 100644 --- a/man/dbGetStatement.Rd +++ b/man/dbGetStatement.Rd @@ -15,8 +15,6 @@ dbGetStatement(res, ...) \code{dbGetStatement()} returns a string, the query used in either \code{\link[=dbSendQuery]{dbSendQuery()}} or \code{\link[=dbSendStatement]{dbSendStatement()}}. -Attempting to query the statement for a result set cleared with -\code{\link[=dbClearResult]{dbClearResult()}} gives an error. } \description{ Returns the statement that was passed to \code{\link[=dbSendQuery]{dbSendQuery()}} @@ -24,6 +22,14 @@ or \code{\link[=dbSendStatement]{dbSendStatement()}}. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbGetStatement")} } +\section{Failure modes}{ + + +Attempting to query the statement for a result set cleared with +\code{\link[=dbClearResult]{dbClearResult()}} gives an error. + +} + \examples{ con <- dbConnect(RSQLite::SQLite(), ":memory:") diff --git a/man/dbHasCompleted.Rd b/man/dbHasCompleted.Rd index d8071f59f..f5ce88175 100644 --- a/man/dbHasCompleted.Rd +++ b/man/dbHasCompleted.Rd @@ -18,8 +18,6 @@ For a query initiated by \code{\link[=dbSendQuery]{dbSendQuery()}} with non-empt and \code{TRUE} after calling \code{\link[=dbFetch]{dbFetch()}} without limit. For a query initiated by \code{\link[=dbSendStatement]{dbSendStatement()}}, \code{dbHasCompleted()} always returns \code{TRUE}. -Attempting to query completion status for a result set cleared with -\code{\link[=dbClearResult]{dbClearResult()}} gives an error. } \description{ This method returns if the operation has completed. @@ -28,6 +26,14 @@ A data manipulation statement is always completed. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbHasCompleted")} } +\section{Failure modes}{ + + +Attempting to query completion status for a result set cleared with +\code{\link[=dbClearResult]{dbClearResult()}} gives an error. + +} + \section{Specification}{ @@ -36,6 +42,8 @@ The completion status for a query is only guaranteed to be set to Therefore, for a query with an empty result set, the initial return value is unspecified, but the result value is \code{TRUE} after trying to fetch only one row. + + Similarly, for a query with a result set of length n, the return value is unspecified after fetching n rows, but the result value is \code{TRUE} after trying to fetch only one more diff --git a/man/dbListFields.Rd b/man/dbListFields.Rd index 9a484ad34..c1be146e1 100644 --- a/man/dbListFields.Rd +++ b/man/dbListFields.Rd @@ -29,6 +29,13 @@ that enumerates all fields in the table in the correct order. This also works for temporary tables if supported by the database. The returned names are suitable for quoting with \code{dbQuoteIdentifier()}. +} +\description{ +List field names of a remote table +} +\section{Failure modes}{ + + If the table does not exist, an error is raised. Invalid types for the \code{name} argument (e.g., \code{character} of length not equal to one, @@ -36,10 +43,9 @@ or numeric) lead to an error. An error is also raised when calling this method for a closed or invalid connection. + } -\description{ -List field names of a remote table -} + \section{Specification}{ diff --git a/man/dbListObjects.Rd b/man/dbListObjects.Rd index 3a7e7d5aa..0a6f585af 100644 --- a/man/dbListObjects.Rd +++ b/man/dbListObjects.Rd @@ -37,8 +37,6 @@ it is also removed from the data frame of database objects. The same applies to temporary objects if supported by the database. The returned names are suitable for quoting with \code{dbQuoteIdentifier()}. -An error is raised when calling this method for a closed -or invalid connection. } \description{ Returns the names of remote objects accessible through this connection @@ -53,6 +51,14 @@ namespace. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbListObjects")} } +\section{Failure modes}{ + + +An error is raised when calling this method for a closed +or invalid connection. + +} + \section{Specification}{ diff --git a/man/dbListTables.Rd b/man/dbListTables.Rd index 6f9012039..e2f0005ae 100644 --- a/man/dbListTables.Rd +++ b/man/dbListTables.Rd @@ -26,8 +26,6 @@ it is also removed from the list of database tables. The same applies to temporary tables if supported by the database. The returned names are suitable for quoting with \code{dbQuoteIdentifier()}. -An error is raised when calling this method for a closed -or invalid connection. } \description{ Returns the unquoted names of remote tables accessible through this @@ -37,6 +35,14 @@ This should include views and temporary objects, but not all database backends \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbListTables")} } +\section{Failure modes}{ + + +An error is raised when calling this method for a closed +or invalid connection. + +} + \examples{ con <- dbConnect(RSQLite::SQLite(), ":memory:") diff --git a/man/dbQuoteIdentifier.Rd b/man/dbQuoteIdentifier.Rd index fb6725b13..0435f0e74 100644 --- a/man/dbQuoteIdentifier.Rd +++ b/man/dbQuoteIdentifier.Rd @@ -25,9 +25,6 @@ argument, it is returned unchanged. Passing objects of class \link{SQL} should also return them unchanged. (For backends it may be most convenient to return \link{SQL} objects to achieve this behavior, but this is not required.) - -An error is raised if the input contains \code{NA}, -but not for an empty string. } \description{ Call this method to generate a string that is suitable for @@ -37,6 +34,15 @@ operation is \code{\link[=dbUnquoteIdentifier]{dbUnquoteIdentifier()}}. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbQuoteIdentifier")} } +\section{Failure modes}{ + + + +An error is raised if the input contains \code{NA}, +but not for an empty string. + +} + \section{Specification}{ diff --git a/man/dbQuoteLiteral.Rd b/man/dbQuoteLiteral.Rd index 1077dbacc..af709c8a0 100644 --- a/man/dbQuoteLiteral.Rd +++ b/man/dbQuoteLiteral.Rd @@ -41,6 +41,15 @@ generate valid SQL and protect against SQL injection attacks. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbQuoteLiteral")} } +\section{Failure modes}{ + + + +Passing a list +for the \code{x} argument raises an error. + +} + \section{Specification}{ @@ -60,9 +69,6 @@ The literals \code{"NA"} or \code{"NULL"} are not treated specially. so that the query \verb{SELECT * FROM (SELECT 1) a WHERE ... IS NULL} returns one row. -Passing a list -for the \code{x} argument raises an error. - } \examples{ diff --git a/man/dbQuoteString.Rd b/man/dbQuoteString.Rd index 1e6cbf1d5..54bcad16d 100644 --- a/man/dbQuoteString.Rd +++ b/man/dbQuoteString.Rd @@ -33,6 +33,19 @@ generate valid SQL and protect against SQL injection attacks. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbQuoteString")} } +\section{Failure modes}{ + + + +Passing a numeric, +integer, +logical, +or raw vector, +or a list +for the \code{x} argument raises an error. + +} + \section{Specification}{ @@ -57,13 +70,6 @@ The strings \code{"NA"} or \code{"NULL"} are not treated specially. so that the query \verb{SELECT * FROM (SELECT 1) a WHERE ... IS NULL} returns one row. -Passing a numeric, -integer, -logical, -or raw vector, -or a list -for the \code{x} argument raises an error. - } \examples{ diff --git a/man/dbReadTable.Rd b/man/dbReadTable.Rd index 8364a2ec8..ad85137c2 100644 --- a/man/dbReadTable.Rd +++ b/man/dbReadTable.Rd @@ -26,20 +26,21 @@ given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} \code{dbReadTable()} returns a data frame that contains the complete data from the remote table, effectively the result of calling \code{\link[=dbGetQuery]{dbGetQuery()}} with \verb{SELECT * FROM }. -An error is raised if the table does not exist. + An empty table is returned as a data frame with zero rows. The presence of \link{rownames} depends on the \code{row.names} argument, see \code{\link[=sqlColumnToRownames]{sqlColumnToRownames()}} for details: \itemize{ \item If \code{FALSE} or \code{NULL}, the returned data frame doesn't have row names. -\item If \code{TRUE}, a column named "row_names" is converted to row names, -an error is raised if no such column exists. +\item If \code{TRUE}, a column named "row_names" is converted to row names. +} + +\itemize{ \item If \code{NA}, a column named "row_names" is converted to row names if it exists, otherwise no translation occurs. \item If a string, this specifies the name of the column in the remote table -that contains the row names, -an error is raised if no such column exists. +that contains the row names. } The default is \code{row.names = FALSE}. @@ -49,6 +50,25 @@ the columns in the returned data frame are converted to valid R identifiers if the \code{check.names} argument is \code{TRUE}, If \code{check.names = FALSE}, the returned table has non-syntactic column names without quotes. +} +\description{ +Reads a database table to a data frame, optionally converting +a column to row names and converting the column names to valid +R identifiers. + +\Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbReadTable")} +} +\section{Failure modes}{ + + +An error is raised if the table does not exist. + + +An error is raised if \code{row.names} is \code{TRUE} and no "row_names" column exists, + + +An error is raised if \code{row.names} is set to a string and and no corresponding column exists. + An error is raised when calling this method for a closed or invalid connection. @@ -60,14 +80,9 @@ Unsupported values for \code{row.names} and \code{check.names} unsupported data types, \code{NA} for \code{check.names}) also raise an error. -} -\description{ -Reads a database table to a data frame, optionally converting -a column to row names and converting the column names to valid -R identifiers. -\Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbReadTable")} } + \section{Additional arguments}{ diff --git a/man/dbRemoveTable.Rd b/man/dbRemoveTable.Rd index c516ad901..4b47c2c92 100644 --- a/man/dbRemoveTable.Rd +++ b/man/dbRemoveTable.Rd @@ -24,6 +24,16 @@ given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} } \value{ \code{dbRemoveTable()} returns \code{TRUE}, invisibly. +} +\description{ +Remove a remote table (e.g., created by \code{\link[=dbWriteTable]{dbWriteTable()}}) +from the database. + +\Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbRemoveTable")} +} +\section{Failure modes}{ + + If the table does not exist, an error is raised. An attempt to remove a view with this function may result in an error. @@ -32,13 +42,9 @@ or invalid connection. An error is also raised if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or if this results in a non-scalar. -} -\description{ -Remove a remote table (e.g., created by \code{\link[=dbWriteTable]{dbWriteTable()}}) -from the database. -\Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbRemoveTable")} } + \section{Additional arguments}{ diff --git a/man/dbSendQuery.Rd b/man/dbSendQuery.Rd index 07a16e3e0..a4c0826a1 100644 --- a/man/dbSendQuery.Rd +++ b/man/dbSendQuery.Rd @@ -20,12 +20,6 @@ an S4 object that inherits from \linkS4class{DBIResult}. The result set can be used with \code{\link[=dbFetch]{dbFetch()}} to extract records. Once you have finished using a result, make sure to clear it with \code{\link[=dbClearResult]{dbClearResult()}}. -An error is raised when issuing a query over a closed -or invalid connection, -or if the query is not a non-\code{NA} string. -An error is also raised if the syntax of the query is invalid -and all query parameters are given (by passing the \code{params} argument) -or the \code{immediate} argument is set to \code{TRUE}. } \description{ The \code{dbSendQuery()} method only submits and synchronously executes the @@ -50,6 +44,20 @@ and transfer them piecemeal to R, others may transfer all the data to the client -- but not necessarily to the memory that R manages. See individual drivers' \code{dbSendQuery()} documentation for details. } +\section{Failure modes}{ + + +An error is raised when issuing a query over a closed +or invalid connection, +or if the query is not a non-\code{NA} string. +An error is also raised if the syntax of the query is invalid +and all query parameters are given (by passing the \code{params} argument) +or the \code{immediate} argument is set to \code{TRUE}. + + + +} + \section{Additional arguments}{ diff --git a/man/dbSendStatement.Rd b/man/dbSendStatement.Rd index 36a8c4e5c..6fe0d0fe5 100644 --- a/man/dbSendStatement.Rd +++ b/man/dbSendStatement.Rd @@ -21,12 +21,6 @@ The result set can be used with \code{\link[=dbGetRowsAffected]{dbGetRowsAffecte determine the number of rows affected by the query. Once you have finished using a result, make sure to clear it with \code{\link[=dbClearResult]{dbClearResult()}}. -An error is raised when issuing a statement over a closed -or invalid connection, -or if the statement is not a non-\code{NA} string. -An error is also raised if the syntax of the query is invalid -and all query parameters are given (by passing the \code{params} argument) -or the \code{immediate} argument is set to \code{TRUE}. } \description{ The \code{dbSendStatement()} method only submits and synchronously executes the @@ -44,6 +38,20 @@ that. For interactive use, you should almost always prefer forwards to \code{\link[=dbSendQuery]{dbSendQuery()}}, to support backends that only implement the latter. } +\section{Failure modes}{ + + +An error is raised when issuing a statement over a closed +or invalid connection, +or if the statement is not a non-\code{NA} string. +An error is also raised if the syntax of the query is invalid +and all query parameters are given (by passing the \code{params} argument) +or the \code{immediate} argument is set to \code{TRUE}. + + + +} + \section{Additional arguments}{ diff --git a/man/dbUnquoteIdentifier.Rd b/man/dbUnquoteIdentifier.Rd index 7f8692a76..67f9f507a 100644 --- a/man/dbUnquoteIdentifier.Rd +++ b/man/dbUnquoteIdentifier.Rd @@ -25,9 +25,6 @@ argument, it is returned unchanged (but wrapped in a list). Passing objects of class \link{Id} should also return them unchanged (but wrapped in a list). (For backends it may be most convenient to return \link{Id} objects to achieve this behavior, but this is not required.) - -An error is raised if plain character vectors are passed as the \code{x} -argument. } \description{ Call this method to convert a \link{SQL} object created by \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} @@ -35,6 +32,15 @@ back to a list of \link{Id} objects. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbUnquoteIdentifier")} } +\section{Failure modes}{ + + + +An error is raised if plain character vectors are passed as the \code{x} +argument. + +} + \section{Specification}{ diff --git a/man/dbWithTransaction.Rd b/man/dbWithTransaction.Rd index e02fa890d..8d56116d7 100644 --- a/man/dbWithTransaction.Rd +++ b/man/dbWithTransaction.Rd @@ -19,11 +19,6 @@ dbBreak() } \value{ \code{dbWithTransaction()} returns the value of the executed code. -Failure to initiate the transaction -(e.g., if the connection is closed -or invalid -of if \code{\link[=dbBegin]{dbBegin()}} has been called already) -gives an error. } \description{ Given that \link{transactions} are implemented, this function @@ -44,6 +39,17 @@ it can be called only inside \code{dbWithTransaction()}. DBI implements \code{dbWithTransaction()}, backends should need to override this generic only if they implement specialized handling. } +\section{Failure modes}{ + + +Failure to initiate the transaction +(e.g., if the connection is closed +or invalid +of if \code{\link[=dbBegin]{dbBegin()}} has been called already) +gives an error. + +} + \section{Specification}{ diff --git a/man/dbWriteTable.Rd b/man/dbWriteTable.Rd index e7d718d14..bc106ba26 100644 --- a/man/dbWriteTable.Rd +++ b/man/dbWriteTable.Rd @@ -26,6 +26,17 @@ given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} } \value{ \code{dbWriteTable()} returns \code{TRUE}, invisibly. +} +\description{ +Writes, overwrites or appends a data frame to a database table, optionally +converting row names to a column and specifying SQL data types for fields. +New code should prefer \code{\link[=dbCreateTable]{dbCreateTable()}} and \code{\link[=dbAppendTable]{dbAppendTable()}}. + +\Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbWriteTable")} +} +\section{Failure modes}{ + + If the table exists, and both \code{append} and \code{overwrite} arguments are unset, or \code{append = TRUE} and the data frame with the new data has different column names, @@ -46,14 +57,9 @@ duplicate or missing names, incompatible columns) also raise an error. -} -\description{ -Writes, overwrites or appends a data frame to a database table, optionally -converting row names to a column and specifying SQL data types for fields. -New code should prefer \code{\link[=dbCreateTable]{dbCreateTable()}} and \code{\link[=dbAppendTable]{dbAppendTable()}}. -\Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbWriteTable")} } + \section{Additional arguments}{ @@ -136,7 +142,8 @@ before and after a non-empty string (if supported by the database) \item date (if supported by the database; -returned as \code{Date}) +returned as \code{Date}), +also for dates prior to 1970 or 1900 or after 2038 \item time (if supported by the database; returned as objects that inherit from \code{difftime}) @@ -144,6 +151,9 @@ returned as objects that inherit from \code{difftime}) (if supported by the database; returned as \code{POSIXct} respecting the time zone but not necessarily preserving the +input time zone), +also for timestamps prior to 1970 or 1900 or after 2038 +respecting the time zone but not necessarily preserving the input time zone) } diff --git a/man/transactions.Rd b/man/transactions.Rd index 29fe1bf9c..c1176d8fc 100644 --- a/man/transactions.Rd +++ b/man/transactions.Rd @@ -21,16 +21,6 @@ dbRollback(conn, ...) } \value{ \code{dbBegin()}, \code{dbCommit()} and \code{dbRollback()} return \code{TRUE}, invisibly. -The implementations are expected to raise an error in case of failure, -but this is not tested. -In any way, all generics throw an error with a closed -or invalid connection. -In addition, a call to \code{dbCommit()} -or \code{dbRollback()} -without a prior call to \code{dbBegin()} raises an error. -Nested transactions are not supported by DBI, -an attempt to call \code{dbBegin()} twice -yields an error. } \description{ A transaction encapsulates several SQL statements in an atomic unit. @@ -47,6 +37,22 @@ Not all database engines implement transaction management, in which case these methods should not be implemented for the specific \linkS4class{DBIConnection} subclass. } +\section{Failure modes}{ + + +The implementations are expected to raise an error in case of failure, +but this is not tested. +In any way, all generics throw an error with a closed +or invalid connection. +In addition, a call to \code{dbCommit()} +or \code{dbRollback()} +without a prior call to \code{dbBegin()} raises an error. +Nested transactions are not supported by DBI, +an attempt to call \code{dbBegin()} twice +yields an error. + +} + \section{Specification}{ From f43bdcae2bfddec6bce7ee58b857cd2cf43e773f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Fri, 17 Dec 2021 08:39:50 +0100 Subject: [PATCH 3/5] Add specs to dbAppendTable() and dbCreateTable() --- R/table-create.R | 6 +++ R/table-insert.R | 5 ++ man/dbAppendTable.Rd | 106 +++++++++++++++++++++++++++++++++++++++++++ man/dbCreateTable.Rd | 70 ++++++++++++++++++++++++++++ 4 files changed, 187 insertions(+) diff --git a/R/table-create.R b/R/table-create.R index 4c38960db..7b6a50768 100644 --- a/R/table-create.R +++ b/R/table-create.R @@ -87,6 +87,12 @@ setMethod("sqlCreateTable", signature("DBIConnection"), #' @inheritParams dbReadTable #' @param row.names Must be `NULL`. #' @inheritParams sqlCreateTable +#' +#' @inherit DBItest::spec_sql_create_table return +#' @inheritSection DBItest::spec_sql_create_table Failure modes +#' @inheritSection DBItest::spec_sql_create_table Additional arguments +#' @inheritSection DBItest::spec_sql_create_table Specification +#' #' @family DBIConnection generics #' @export #' @examples diff --git a/R/table-insert.R b/R/table-insert.R index 912c3bebf..b4b7248a4 100644 --- a/R/table-insert.R +++ b/R/table-insert.R @@ -123,6 +123,11 @@ sqlAppendTableTemplate <- function(con, table, values, row.names = NA, prefix = #' with those in the target table in the database. #' @param row.names Must be `NULL`. #' @inheritParams sqlAppendTableTemplate +#' +#' @inherit DBItest::spec_sql_append_table return +#' @inheritSection DBItest::spec_sql_append_table Failure modes +#' @inheritSection DBItest::spec_sql_append_table Specification +#' #' @family DBIConnection generics #' @export #' @examples diff --git a/man/dbAppendTable.Rd b/man/dbAppendTable.Rd index 3d29f7856..9a042aca1 100644 --- a/man/dbAppendTable.Rd +++ b/man/dbAppendTable.Rd @@ -27,6 +27,11 @@ with those in the target table in the database.} \item{row.names}{Must be \code{NULL}.} } +\value{ +\code{dbAppendTable()} returns a +scalar +numeric. +} \description{ The \code{dbAppendTable()} method assumes that the table has been created beforehand, e.g. with \code{\link[=dbCreateTable]{dbCreateTable()}}. @@ -42,6 +47,107 @@ ways to create tables) need to override the \code{dbAppendTable()} method. The \code{row.names} argument is not supported by this method. Process the values with \code{\link[=sqlRownamesToColumn]{sqlRownamesToColumn()}} before calling this method. } +\section{Failure modes}{ + + +If the table does not exist, +or the new data in \code{values} is not a data frame or has different column names, +an error is raised; the remote table remains unchanged. + +An error is raised when calling this method for a closed +or invalid connection. +An error is also raised +if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} +or if this results in a non-scalar. +Invalid values for the \code{row.names} argument +(non-scalars, +unsupported data types, +\code{NA}) +also raise an error. + + +Passing a \code{value} argument different to \code{NULL} to the \code{row.names} argument +(in particular \code{TRUE}, +\code{NA}, +and a string) +raises an error. + +} + +\section{Specification}{ + + +SQL keywords can be used freely in table names, column names, and data. +Quotes, commas, spaces, and other special characters such as newlines and tabs, +can also be used in the data, +and, if the database supports non-syntactic identifiers, +also for table names +and column names. + +The following data types must be supported at least, +and be read identically with \code{\link[=dbReadTable]{dbReadTable()}}: +\itemize{ +\item integer +\item numeric +(the behavior for \code{Inf} and \code{NaN} is not specified) +\item logical +\item \code{NA} as NULL +\item 64-bit values (using \code{"bigint"} as field type); the result can be +\itemize{ +\item converted to a numeric, which may lose precision, +\item converted a character vector, which gives the full decimal +representation +\item written to another table and read again unchanged +} +\item character (in both UTF-8 +and native encodings), +supporting empty strings +(before and after non-empty strings) +\item factor (returned as character, +with a warning) +\item list of raw +(if supported by the database) +\item objects of type \link[blob:blob]{blob::blob} +(if supported by the database) +\item date +(if supported by the database; +returned as \code{Date}) +also for dates prior to 1970 or 1900 or after 2038 +\item time +(if supported by the database; +returned as objects that inherit from \code{difftime}) +\item timestamp +(if supported by the database; +returned as \code{POSIXct} +respecting the time zone but not necessarily preserving the +input time zone), +also for timestamps prior to 1970 or 1900 or after 2038 +respecting the time zone but not necessarily preserving the +input time zone) +} + +Mixing column types in the same table is supported. + + +The \code{name} argument is processed as follows, +to support databases that allow non-syntactic names for their objects: +\itemize{ +\item If an unquoted table name as string: \code{dbAppendTable()} will do the quoting, +perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} +\item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done +to support databases that allow non-syntactic names for their objects: +} + +The \code{row.names} argument must be \code{NULL}, the default value. +Row names are ignored. + + +The \code{value} argument must be a data frame +with a subset of the columns of the existing table. +The order of the columns does not matter. + +} + \examples{ con <- dbConnect(RSQLite::SQLite(), ":memory:") dbCreateTable(con, "iris", iris) diff --git a/man/dbCreateTable.Rd b/man/dbCreateTable.Rd index 647b8bc38..c01d7e4bf 100644 --- a/man/dbCreateTable.Rd +++ b/man/dbCreateTable.Rd @@ -35,6 +35,9 @@ A data frame: field types are generated using \item{temporary}{If \code{TRUE}, will generate a temporary table statement.} } +\value{ +\code{dbCreateTable()} returns \code{TRUE}, invisibly. +} \description{ The default \code{dbCreateTable()} method calls \code{\link[=sqlCreateTable]{sqlCreateTable()}} and \code{\link[=dbExecute]{dbExecute()}}. @@ -50,6 +53,73 @@ Process the values with \code{\link[=sqlRownamesToColumn]{sqlRownamesToColumn()} The argument order is different from the \code{sqlCreateTable()} method, the latter will be adapted in a later release of DBI. } +\section{Failure modes}{ + + +If the table exists, an error is raised; the remote table remains unchanged. + +An error is raised when calling this method for a closed +or invalid connection. +An error is also raised +if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} +or if this results in a non-scalar. +Invalid values for the \code{row.names} and \code{temporary} arguments +(non-scalars, +unsupported data types, +\code{NA}, +incompatible values, +duplicate names) +also raise an error. + +} + +\section{Additional arguments}{ + + +The following arguments are not part of the \code{dbCreateTable()} generic +(to improve compatibility across backends) +but are part of the DBI specification: +\itemize{ +\item \code{temporary} (default: \code{FALSE}) +} + +They must be provided as named arguments. +See the "Specification" and "Value" sections for details on their usage. + +} + +\section{Specification}{ + + +The \code{name} argument is processed as follows, +to support databases that allow non-syntactic names for their objects: +\itemize{ +\item If an unquoted table name as string: \code{dbCreateTable()} will do the quoting, +perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} +\item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done +} + +If the \code{temporary} argument is \code{TRUE}, the table is not available in a +second connection and is gone after reconnecting. +Not all backends support this argument. +A regular, non-temporary table is visible in a second connection, +in a pre-existing connection, +and after reconnecting to the database. + +SQL keywords can be used freely in table names, column names, and data. +Quotes, commas, and spaces can also be used for table names and column names, +if the database supports non-syntactic identifiers. + +The \code{row.names} argument must be missing +or \code{NULL}, the default value. +All other values for the \code{row.names} argument +(in particular \code{TRUE}, +\code{NA}, +and a string) +raise an error. + +} + \examples{ con <- dbConnect(RSQLite::SQLite(), ":memory:") dbCreateTable(con, "iris", iris) From 27d8750b3310a773d649895f72bf734ffdbaf967 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Fri, 17 Dec 2021 08:40:22 +0100 Subject: [PATCH 4/5] Fix bullet list --- R/table.R | 3 +++ man/Id.Rd | 3 ++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/R/table.R b/R/table.R index cc2ca7f18..195ac4fd2 100644 --- a/R/table.R +++ b/R/table.R @@ -6,17 +6,20 @@ setClass("Id", slots = list(name = "character")) #' Refer to a table nested in a hierarchy (e.g. within a schema) #' +#' @description #' Objects of class `Id` have a single slot `name`, which is a named #' character vector. #' The [dbQuoteIdentifier()] method converts `Id` objects to strings. #' Support for `Id` objects depends on the database backend. #' They can be used in the following methods as `name` or `table` argument: +#' #' - [dbCreateTable()] #' - [dbAppendTable()] #' - [dbReadTable()] #' - [dbWriteTable()] #' - [dbExistsTable()] #' - [dbRemoveTable()] +#' #' Objects of this class are also returned from [dbListObjects()]. #' #' @param ... Components of the hierarchy, e.g. `schema`, `table`, diff --git a/man/Id.Rd b/man/Id.Rd index 12e106267..609d2835d 100644 --- a/man/Id.Rd +++ b/man/Id.Rd @@ -28,8 +28,9 @@ They can be used in the following methods as \code{name} or \code{table} argumen \item \code{\link[=dbWriteTable]{dbWriteTable()}} \item \code{\link[=dbExistsTable]{dbExistsTable()}} \item \code{\link[=dbRemoveTable]{dbRemoveTable()}} -Objects of this class are also returned from \code{\link[=dbListObjects]{dbListObjects()}}. } + +Objects of this class are also returned from \code{\link[=dbListObjects]{dbListObjects()}}. } \examples{ Id(schema = "dbo", table = "Customer") From 29afda5b92ecd12fc286a3be8a298912b84bbce5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Fri, 17 Dec 2021 17:33:26 +0100 Subject: [PATCH 5/5] Bump