DBI/0000755000176000001440000000000012410453060010673 5ustar ripleyusersDBI/tests/0000755000176000001440000000000012230305013012027 5ustar ripleyusersDBI/tests/testthat.R0000644000176000001440000000004312230305013014007 0ustar ripleyuserslibrary(testthat) test_check("DBI")DBI/tests/testthat/0000755000176000001440000000000012410453060013675 5ustar ripleyusersDBI/tests/testthat/test-data-type.R0000644000176000001440000000031512230305013016656 0ustar ripleyuserscontext("dbDataType") test_that("dbDataType works on a data frame", { df <- data.frame(x = 1:10, y = runif(10)) types <- dbDataType(MockDriver(), df) expect_equal(types, c("int", "double")) })DBI/tests/testthat/helper-dummy.R0000644000176000001440000000037712230305013016431 0ustar ripleyusersMockObject <- setClass("MockObject", contains = "DBIObject") MockDriver <- setClass("MockDriver", contains = "DBIDriver") MockConnection <- setClass("MockConnection", contains = "DBIConnection") MockResult <- setClass("MockResult", contains = "DBIResult")DBI/NAMESPACE0000644000176000001440000000212512401615567012126 0ustar ripleyusers# Generated by roxygen2 (4.0.2): do not edit by hand export(.SQL92Keywords) export(SQL) export(SQLKeywords) export(dbBegin) export(dbCallProc) export(dbClearResult) export(dbColumnInfo) export(dbCommit) export(dbConnect) export(dbDataType) export(dbDisconnect) export(dbDriver) export(dbExistsTable) export(dbFetch) export(dbGetDBIVersion) export(dbGetException) export(dbGetInfo) export(dbGetQuery) export(dbGetRowCount) export(dbGetRowsAffected) export(dbGetStatement) export(dbHasCompleted) export(dbIsValid) export(dbListConnections) export(dbListFields) export(dbListResults) export(dbListTables) export(dbQuoteIdentifier) export(dbQuoteString) export(dbReadTable) export(dbRemoveTable) export(dbRollback) export(dbSendQuery) export(dbSetDataMappings) export(dbUnloadDriver) export(dbWriteTable) export(dbiCheckCompliance) export(fetch) export(isSQLKeyword) export(isSQLKeyword.default) export(make.db.names) export(make.db.names.default) export(print.list.pairs) exportClasses(DBIConnection) exportClasses(DBIDriver) exportClasses(DBIObject) exportClasses(DBIResult) exportClasses(SQL) import(methods) DBI/NEWS0000644000176000001440000001042412410364051011374 0ustar ripleyusers# Version 0.3.1 * Actually export `dbIsValid()` :/ * `dbGetQuery()` uses `dbFetch()` in the default implementation. # Version 0.3.0 ## New and enhanced generics * `dbIsValid()` returns a logical value describing whether a connection or result set (or other object) is still valid. (#12). * `dbQuoteString()` and `dbQuoteIdentifier()` to implement database specific quoting mechanisms. * `dbFetch()` added as alias to `fetch()` to provide consistent name. Implementers should define methods for both `fetch()` and `dbFetch()` until `fetch()` is deprecated in 2015. For now, the default method for `dbFetch()` calls `fetch()`. * `dbBegin()` begins a transaction (#17). If not supported, DB specific methods should throw an error (as should `dbCommit()` and `dbRollback()`). ## New default methods * `dbGetStatement()`, `dbGetRowsAffected()`, `dbHasCompleted()`, and `dbGetRowCount()` gain default methods that extract the appropriate elements from `dbGetInfo()`. This means that most drivers should no longer need to implement these methods (#13). * `dbGetQuery()` gains a default method for `DBIConnection` which uses `dbSendQuery()`, `fetch()` and `dbClearResult()`. ## Deprecated features * The following functions are soft-deprecated. They are going away, and developers who use the DBI should begin preparing. The formal deprecation process will begin in July 2015, where these function will emit warnings on use. * `fetch()` is replaced by `dbFetch()`. * `make.db.names()`, `isSQLKeyword()` and `SQLKeywords()`: a black list based approach is fundamentally flawed; instead quote strings and identifiers with `dbQuoteIdentifier()` and `dbQuoteString()`. * `dbGetDBIVersion()` is deprecated since it's now just a thin wrapper around `packageVersion("DBI")`. * `dbSetDataMappings()` (#9) and `dbCallProc()` (#7) are deprecated as no implementations were ever provided. ## Other improvements * `dbiCheckCompliance()` makes it easier for implementors to check that their package is in compliance with the DBI specification. * All examples now use the RSQLite package so that you can easily try out the code samples (#4). * `dbDriver()` gains a more effective search mechanism that doesn't rely on packages being loaded (#1). * DBI has been converted to use roxygen2 for documentation, and now most functions have their own documentation files. I would love your feedback on how we could make the documentation better! # Version 0.2-7 * Trivial changes (updated package fields, daj) # Version 0.2-6 * Removed deprecated \synopsis in some Rd files (thanks to Prof. Ripley) # Version 0.2-5 * Code cleanups contributed by Matthias Burger: avoid partial argument name matching and use TRUE/FALSE, not T/F. * Change behavior of make.db.names.default to quote SQL keywords if allow.keywords is FALSE. Previously, SQL keywords would be name mangled with underscores and a digit. Now they are quoted using '"'. # Version 0.2-4 * Changed license from GPL to LPGL * Fixed a trivial typo in documentation # Version 0.1-10 * Fixed documentation typos. # Version 0.1-9 * Trivial changes. # Version 0.1-8 * A trivial change due to package.description() being deprecated in 1.9.0. # Version 0.1-7 * Had to do a substantial re-formatting of the documentation due to incompatibilities introduced in 1.8.0 S4 method documentation. The contents were not changed (modulo fixing a few typos). Thanks to Kurt Hornik and John Chambers for their help. # Version 0.1-6 * Trivial documentation changes (for R CMD check's sake) # Version 0.1-5 * Removed duplicated setGeneric("dbSetDataMappings") # Version 0.1-4 * Removed the "valueClass" from some generic functions, namely, dbListConnections, dbListResults, dbGetException, dbGetQuery, and dbGetInfo. The reason is that methods for these generics could potentially return different classes of objects (e.g., the call dbGetInfo(res) could return a list of name-value pairs, while dbGetInfo(res, "statement") could be a character vector). * Added 00Index to inst/doc * Added dbGetDBIVersion() (simple wrapper to package.description). # Version 0.1-3 * ??? Minor changes? # Version 0.1-2 * An implementation based on version 4 classes and methods. * Incorporated (mostly Tim Keitt's) comments. DBI/R/0000755000176000001440000000000012400112061011064 5ustar ripleyusersDBI/R/DBResult.R0000644000176000001440000001557312400131065012713 0ustar ripleyusers#' DBIResult class. #' #' This virtual class describes the result and state of execution of #' a DBMS statement (any statement, query or non-query). The result set #' \code{res} keeps track of whether the statement produces output #' how many rows were affected by the operation, how many rows have been #' fetched (if statement is a query), whether there are more rows to fetch, #' etc. #' #' Individual drivers are free to allow single or multiple #' active results per connection. #' #' @name DBIResult-class #' @docType class #' @family DBI classes #' @export #' @include DBObject.R setClass("DBIResult", representation("DBIObject", "VIRTUAL")) #' Fetch records from a previously executed query. #' #' Fetch the next \code{n} elements (rows) from the result set and return them #' as a data.frame. #' #' \code{fetch} is provided for compatibility with older DBI clients - for all #' new code you are strongly encouraged to use \code{dbFetch}. The default #' method for \code{dbFetch} calls \code{fetch} so that it is compatible with #' existing code. Implementors should provide methods for both \code{fetch} and #' \code{dbFetch} until \code{fetch} is deprecated in 2015. #' #' @aliases dbFetch,DBIResult-method #' @param res An object inheriting from \code{\linkS4class{DBIResult}}. #' @param n maximum number of records to retrieve per fetch. Use \code{n = -1} #' to retrieve all pending records. Some implementations may recognize other #' special values. #' @param ... Other arguments passed on to methods. #' @return a data.frame with as many rows as records were fetched and as many #' columns as fields in the result set. #' @seealso close the result set with \code{\link{dbClearResult}} as soon as you #' finish retrieving the records you want. #' @family DBIResult generics #' @examples #' if (!require("RSQLite")) { #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' dbWriteTable(con, "mtcars", mtcars) #' #' # Fetch all results #' res <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4") #' dbFetch(res) #' dbClearResult(res) #' #' # Fetch in chunks #' res <- dbSendQuery(con, "SELECT * FROM mtcars") #' while (!dbHasCompleted(res)) { #' chunk <- fetch(res, 10) #' print(nrow(chunk)) #' } #' dbClearResult(res) #' dbDisconnect(con) #' } #' @export setGeneric("dbFetch", def = function(res, n = -1, ...) standardGeneric("dbFetch"), valueClass = "data.frame" ) setMethod("dbFetch", "DBIResult", function(res, n = -1, ...) { fetch(res, n = n, ...) }) #' @rdname dbFetch #' @export setGeneric("fetch", def = function(res, n = -1, ...) standardGeneric("fetch"), valueClass = "data.frame" ) #' Clear a result set. #' #' Frees all resources (local and remote) associated with a result set. It some #' cases (e.g., very large result sets) this can be a critical step to avoid #' exhausting resources (memory, file descriptors, etc.) #' #' @param res An object inheriting from \code{\linkS4class{DBIResult}}. #' @param ... Other arguments passed on to methods. #' @return a logical indicating whether clearing the #' result set was successful or not. #' @family DBIResult generics #' @export setGeneric("dbClearResult", def = function(res, ...) standardGeneric("dbClearResult"), valueClass = "logical" ) #' Information about result types. #' #' Produces a data.frame that describes the output of a query. The data.frame #' should have as many rows as there are output fields in the result set, and #' each column in the data.frame should describe an aspect of the result set #' field (field name, type, etc.) #' #' @inheritParams dbClearResult #' @return A data.frame with one row per output field in \code{res}. Methods #' MUST include \code{name}, \code{field.type} (the SQL type), #' and \code{data.type} (the R data type) columns, and MAY contain other #' database specific information like scale and precision or whether the #' field can store \code{NULL}s. #' @family DBIResult generics #' @export setGeneric("dbColumnInfo", def = function(res, ...) standardGeneric("dbColumnInfo"), valueClass = "data.frame" ) #' Get the statement associated with a result set #' #' The default method extracts \code{statement} from the result of #' \code{\link{dbGetInfo}(res)}. #' #' @inheritParams dbClearResult #' @aliases dbGetStatement,DBIResult-method #' @return a character vector #' @family DBIResult generics #' @export setGeneric("dbGetStatement", def = function(res, ...) standardGeneric("dbGetStatement"), valueClass = "character" ) setMethod("dbGetStatement", "DBIResult", function(res, ...) { dbGetInfo(res)$statement }) #' Has the operation completed? #' #' The default method extracts \code{has.completed} from the result of #' \code{\link{dbGetInfo}(res)}. #' #' @inheritParams dbClearResult #' @aliases dbHasCompleted,DBIResult-method #' @return a logical vector of length 1 #' @family DBIResult generics #' @export setGeneric("dbHasCompleted", def = function(res, ...) standardGeneric("dbHasCompleted"), valueClass = "logical" ) setMethod("dbHasCompleted", "DBIResult", function(res, ...) { dbGetInfo(res)$has.completed }) #' The number of rows affected by data modifying query. #' #' The default method extracts \code{rows.affected} from the result of #' \code{\link{dbGetInfo}(res)}. #' #' @inheritParams dbClearResult #' @aliases dbGetRowsAffected,DBIResult-method #' @return a numeric vector of length 1 #' @family DBIResult generics #' @export setGeneric("dbGetRowsAffected", def = function(res, ...) standardGeneric("dbGetRowsAffected"), valueClass = "numeric" ) setMethod("dbGetRowsAffected", "DBIResult", function(res, ...) { dbGetInfo(res)$rows.affected }) #' The number of rows fetched so far. #' #' The default method extracts \code{row.count} from the result of #' \code{\link{dbGetInfo}(res)}. #' #' @inheritParams dbClearResult #' @aliases dbGetRowCount,DBIResult-method #' @return a numeric vector of length 1 #' @family DBIResult generics #' @export setGeneric("dbGetRowCount", def = function(res, ...) standardGeneric("dbGetRowCount"), valueClass = "numeric" ) setMethod("dbGetRowCount", "DBIResult", function(res, ...) { dbGetInfo(res)$row.count }) #' Set data mappings between an DBMS and R. #' #' This generic is deprecated since no working implementation was ever produced. #' #' Sets one or more conversion functions to handle the translation of DBMS data #' types to R objects. This is only needed for non-primitive data, since all #' DBI drivers handle the common base types (integers, numeric, strings, etc.) #' #' The details on conversion functions (e.g., arguments, whether they can invoke #' initializers and/or destructors) have not been specified. #' #' @inheritParams dbClearResult #' @keywords internal #' @param flds a field description object as returned by \code{dbColumnInfo}. #' @export setGeneric("dbSetDataMappings", def = function(res, flds, ...) { .Deprecated() standardGeneric("dbSetDataMappings") }, valueClass = "logical" ) DBI/R/quote.R0000644000176000001440000000630512231555153012367 0ustar ripleyusers#' @include DBConnection.R NULL #' SQL quoting. #' #' This set of classes and generics make it possible to flexibly deal with SQL #' escaping needs. By default, any user supplied input to a query should be #' escaped using either \code{dbQuoteIdentifier} or \code{dbQuoteString} #' depending on whether it refers to a table or variable name, or is a literal #' string. #' #' The SQL class has associated \code{SQL()} constructor function. This class #' is used to prevent double escaping of SQL strings, and to make it possible #' to tell DBI functions that you've done the escaping yourself. #' #' @section Implementation notes: #' #' DBI provides default methods for SQL-92 compatible quoting. If the database #' uses a different convention, you will need to provide your own methods. #' Note that because of the way that S4 dispatch finds methods and because #' SQL inherits from character, if you implement (e.g.) a method for #' \code{dbQuoteString(MyConnection, character)}, you will also need to #' implement \code{dbQuoteString(MyConnection, SQL)} - this should simply #' return \code{x} unchanged. #' #' @param conn A subclass of \code{\linkS4class{DBIConnection}}, representing #' an active connection to an DBMS. #' @param x A character vector to label as being escaped SQL. #' @param ... Other arguments passed on to methods. Not otherwise used. #' @export #' @examples #' # Create a subclass of DBI connection since it's virtual #' MockConnection <- setClass("MockConnection", "DBIConnection") #' conn <- MockConnection() #' #' # Quoting ensures that arbitrary input is safe for use in a query #' name <- "Robert'); DROP TABLE Students;--" #' dbQuoteString(conn, name) #' dbQuoteIdentifier(conn, name) #' #' # SQL vectors are always passed through as is #' var_name <- SQL("select") #' var_name #' #' dbQuoteIdentifier(conn, var_name) #' dbQuoteString(conn, var_name) #' #' # This mechanism is used to prevent double escaping #' dbQuoteString(conn, dbQuoteString(conn, name)) SQL <- function(x) new("SQL", x) #' @rdname SQL #' @export #' @aliases #' SQL-class #' show,SQL-method setClass("SQL", contains = "character") setMethod("show", "SQL", function(object) { cat(paste0(" ", object@.Data, collapse = "\n")) }) #' @rdname SQL #' @export #' @aliases #' dbQuoteIdentifier,DBIConnection,character-method #' dbQuoteIdentifier,DBIConnection,SQL-method setGeneric("dbQuoteIdentifier", function(conn, x, ...) { standardGeneric("dbQuoteIdentifier") }) setMethod("dbQuoteIdentifier", c("DBIConnection", "character"), function(conn, x, ...) { x <- gsub('"', '""', x, fixed = TRUE) SQL(paste('"', x, '"', sep = "")) } ) setMethod("dbQuoteIdentifier", c("DBIConnection", "SQL"), function(conn, x, ...) { x } ) #' @rdname SQL #' @export #' @aliases #' dbQuoteString,DBIConnection,character-method #' dbQuoteString,DBIConnection,SQL-method setGeneric("dbQuoteString", function(conn, x, ...) { standardGeneric("dbQuoteString") }) setMethod("dbQuoteString", c("DBIConnection", "character"), function(conn, x, ...) { x <- gsub("'", "''", x, fixed = TRUE) SQL(paste("'", x, "'", sep = "")) } ) setMethod("dbQuoteString", c("DBIConnection", "SQL"), function(conn, x, ...) { x } ) DBI/R/DBDriver.R0000644000176000001440000001745512400132155012672 0ustar ripleyusers#' DBIDriver class. #' #' Base class for all DBMS drivers (e.g., RSQLite, MySQL, PostgreSQL). #' The virtual class \code{DBIDriver} defines the operations for creating #' connections and defining data type mappings. Actual driver classes, for #' instance \code{RPgSQL}, \code{RMySQL}, etc. implement these operations in a #' DBMS-specific manner. #' #' @docType class #' @name DBIDriver-class #' @family DBI classes #' @export #' @include DBObject.R setClass("DBIDriver", representation("DBIObject", "VIRTUAL")) #' Load and unload database drivers. #' #' \code{dbDriver} is a helper method used to create an new driver object #' given the name of a database or the corresponding R package. It works #' through convention: all DBI-extending packages should provide an exported #' object with the same name as the package. \code{dbDriver} just looks for #' this object in the right places: if you know what database you are connecting #' to, you should call the function directly. #' #' @section Side Effects: #' The client part of the database communication is #' initialized (typically dynamically loading C code, etc.) but note that #' connecting to the database engine itself needs to be done through calls to #' \code{dbConnect}. #' #' @param drvName character name of the driver to instantiate. #' @param drv an object that inherits from \code{DBIDriver} as created by #' \code{dbDriver}. #' @param ... any other arguments are passed to the driver \code{drvName}. #' @return In the case of \code{dbDriver}, an driver object whose class extends #' \code{DBIDriver}. This object may be used to create connections to the #' actual DBMS engine. #' #' In the case of \code{dbUnloadDriver}, a logical indicating whether the #' operation succeeded or not. #' @import methods #' @examples #' if (require("RSQLite")) { #' # Create a RSQLite driver with a string #' d <- dbDriver("SQLite") #' d #' #' # But better, access the object directly #' RSQLite::SQLite() #' } #' @aliases dbDriver,character-method #' @export setGeneric("dbDriver", def = function(drvName, ...) standardGeneric("dbDriver"), valueClass = "DBIDriver") setMethod("dbDriver", "character", definition = function(drvName, ...) { findDriver(drvName)(...) } ) findDriver <- function(drvName) { # If it exists in the global environment, use that d <- get2(drvName, globalenv()) if (!is.null(d)) return(d) # Otherwise, see if the appropriately named package is available if (is_attached(drvName)) { d <- get2(drvName, asNamespace(drvName)) if (!is.null(d)) return(d) } pkgName <- paste0("R", drvName) # First, see if package with name R + drvName is available if (is_attached(pkgName)) { d <- get2(drvName, asNamespace(pkgName)) if (!is.null(d)) return(d) } # Can't find it: stop("Couldn't find driver ", drvName, ". Looked in:\n", "* global namespace\n", "* in package called ", drvName, "\n", "* in package called ", pkgName, call. = FALSE) } get2 <- function(x, env) { if (!exists(x, envir = env)) return(NULL) get(x, envir = env) } is_attached <- function(x) { x %in% loadedNamespaces() } #' @rdname dbDriver #' @export setGeneric("dbUnloadDriver", def = function(drv, ...) standardGeneric("dbUnloadDriver"), valueClass = "logical" ) #' Create a connection to a DBMS. #' #' Connect to a DBMS going through the appropriate authorization procedure. #' Some implementations may allow you to have multiple connections open, so you #' may invoke this function repeatedly assigning its output to different #' objects. The authorization mechanism is left unspecified, so check the #' documentation of individual drivers for details. #' #' Each driver will define what other arguments are required, e.g., #' \code{"dbname"} for the database name, \code{"username"}, and #' \code{"password"}. #' #' @param drv an object that inherits from \code{\linkS4class{DBIDriver}}, or #' a character string specifying the name of DBMS driver, e.g., "RSQLite", #' "RMySQL", "RPostgreSQL", or an existing \code{\linkS4class{DBIConnection}} #' object (in order to clone an existing connection). #' @param ... authorization arguments needed by the DBMS instance; these #' typically include \code{user}, \code{password}, \code{dbname}, \code{host}, #' \code{port}, etc. For details see the appropriate \code{DBIDriver}. #' @return An object that extends \code{\linkS4class{DBIConnection}} in a #' database-specific manner. For instance \code{dbConnect("MySQL")} produces #' an object of class \code{MySQLConnection}. This object is used to direct #' commands to the database engine. #' @seealso \code{\link{dbDisconnect}} to disconnect from a database. #' @export #' @examples #' if (require("RSQLite")) { #' # SQLite only needs a path to the database. Other database drivers #' # will require more details (like username, password, host, port etc) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' con #' #' dbListTables(con) #' dbDisconnect(con) #' } setGeneric("dbConnect", def = function(drv, ...) standardGeneric("dbConnect"), valueClass = "DBIConnection" ) #' List currently open connections. #' #' Drivers that implement only a single connections MUST return a list #' containing a single element. If no connection are open, methods MUST #' return an empty list. #' #' @param drv A object inheriting from \code{\linkS4class{DBIDriver}} #' @param ... Other arguments passed on to methods. #' @export #' @return a list setGeneric("dbListConnections", def = function(drv, ...) standardGeneric("dbListConnections") ) #' Determine the SQL data type of an object. #' #' This is a generic function. The default method determines the SQL type of an #' R object according to the SQL 92 specification, which may serve as a starting #' point for driver implementations. The default method also provides a method #' for data.frame which will return a character vector giving the type for each #' column in the dataframe. #' #' The data types supported by databases are different than the data types in R, #' but the mapping between the primitve types is straightforward: Any of the #' many fixed and varying length character types are mapped to character #' vectors. Fixed-precision (non-IEEE) numbers are mapped into either numeric or #' integer vectors. #' #' Notice that many DBMS do not follow IEEE arithmetic, so there are potential #' problems with under/overflows and loss of precision. #' #' @aliases dbDataType,DBIObject-method #' @inheritParams dbListConnections #' @param dbObj A object inheriting from \code{\linkS4class{DBIDriver}} #' @param obj An R object whose SQL type we want to determine. #' @return A character string specifying the SQL data type for \code{obj}. #' @seealso \code{\link{isSQLKeyword}} \code{\link{make.db.names}} #' @examples #' if (require("RSQLite")) { #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbDataType(con, 1:5) #' dbDataType(con, 1L) #' dbDataType(con, TRUE) #' dbDataType(con, c("x", "abc")) #' #' dbDataType(con, mtcars) #' } #' @export setGeneric("dbDataType", def = function(dbObj, obj, ...) standardGeneric("dbDataType"), valueClass = "character" ) setMethod("dbDataType", "DBIObject", function(dbObj, obj, ...) { dbiDataType(obj) }) setGeneric("dbiDataType", function(x) standardGeneric("dbiDataType")) setMethod("dbiDataType", "data.frame", function(x) { vapply(x, dbiDataType, FUN.VALUE = character(1), USE.NAMES = FALSE) }) setMethod("dbiDataType", "integer", function(x) "int") setMethod("dbiDataType", "numeric", function(x) "double") setMethod("dbiDataType", "logical", function(x) "smallint") setMethod("dbiDataType", "Date", function(x) "date") setMethod("dbiDataType", "POSIXct", function(x) "timestamp") varchar <- function(x) { paste0("varchar(", max(nchar(as.character(x))), ")") } setMethod("dbiDataType", "character", varchar) setMethod("dbiDataType", "factor", varchar) DBI/R/DBObject.R0000644000176000001440000000702412401615564012647 0ustar ripleyusers#' DBIObject class. #' #' Base class for all other DBI classes (e.g., drivers, connections). This #' is a virtual Class: No objects may be created from it. #' #' More generally, the DBI defines a very small set of classes and methods that #' allows users and applications access DBMS with a common interface. The #' virtual classes are \code{DBIDriver} that individual drivers extend, #' \code{DBIConnection} that represent instances of DBMS connections, and #' \code{DBIResult} that represent the result of a DBMS statement. These three #' classes extend the basic class of \code{DBIObject}, which serves as the root #' or parent of the class hierarchy. #' #' @section Implementation notes: #' An implementation MUST provide methods for the following generics: #' #' \itemize{ #' \item \code{\link{dbGetInfo}}. #' } #' #' It MAY also provide methods for: #' #' \itemize{ #' \item \code{\link{summary}}. Print a concise description of the #' object. The default method invokes \code{dbGetInfo(dbObj)} and prints #' the name-value pairs one per line. Individual implementations may #' tailor this appropriately. #' } #' #' @docType class #' @family DBI classes #' @examples #' \dontrun{ #' drv <- dbDriver("MySQL") #' con <- dbConnect(drv, group = "rs-dbi") #' res <- dbSendQuery(con, "select * from vitalSuite") #' is(drv, "DBIObject") ## True #' is(con, "DBIObject") ## True #' is(res, "DBIObject") #' } #' @export #' @name DBIObject-class setClass("DBIObject", "VIRTUAL") #' Get DBMS metadata. #' #' @section Implementation notes: #' For \code{DBIDriver} subclasses, this should include the version of the #' package (\code{driver.version}), the version of the underlying client #' library (\code{client.version}), and the maximum number of connections #' (\code{max.connections}). #' #' For \code{DBIConnection} objects this should report the version of #' the DBMS engine (\code{db.version}), database name (\code{dbname}), #' username, (\code{username}), host (\code{host}), port (\code{port}), etc. #' It MAY also include any other arguments related to the connection #' (e.g., thread id, socket or TCP connection type). It MUST NOT include the #' password. #' #' For \code{DBIResult} objects, this should include the statement #' being executed (\code{statement}), how many rows have been fetched so far #' (in the case of queries) (\code{row.count}), how many rows were affected #' (deleted, inserted, changed, or total number of records to be fetched). #' (\code{rows.affected}), if the query is complete (\code{has.completed}), #' and whether or not the query generates output (\code{is.select}). #' #' @param dbObj An object inheriting from \code{\linkS4class{DBIObject}}, #' i.e. \code{\linkS4class{DBIDriver}}, \code{\linkS4class{DBIConnection}}, #' or a \code{\linkS4class{DBIResult}} #' @param ... Other arguments to methods. #' @family DBObject methods #' @return a named list #' @export setGeneric("dbGetInfo", def = function(dbObj, ...) standardGeneric("dbGetInfo") ) #' Is this DBMS object still valid? #' #' This generic tests whether a database object is still valid (i.e. it hasn't #' been disconnected or cleared). #' #' @inheritParams dbGetInfo #' @return a logical of length 1 #' @family DBObject methods #' @export setGeneric("dbIsValid", def = function(dbObj, ...) standardGeneric("dbIsValid"), valueClass = "logical") setGeneric("summary") setMethod("summary", "DBIObject", function(object, ...) { info <- dbGetInfo(dbObj = object, ...) cat(class(object), "\n") print.list.pairs(info) invisible(info) }) DBI/R/keywords.R0000644000176000001440000002060712400120727013073 0ustar ripleyusers#' Make R identifiers into legal SQL identifiers. #' #' These methods are DEPRECATED. Please use \code{\link{dbQuoteIdentifier}} #' (or possibly \code{\link{dbQuoteString}}) instead. #' #' The algorithm in \code{make.db.names} first invokes \code{make.names} and #' then replaces each occurrence of a dot ``.'' by an underscore ``\_''. If #' \code{allow.keywords} is \code{FALSE} and identifiers collide with SQL #' keywords, a small integer is appended to the identifier in the form of #' \code{"_n"}. #' #' The set of SQL keywords is stored in the character vector #' \code{.SQL92Keywords} and reflects the SQL ANSI/ISO standard as documented #' in "X/Open SQL and RDA", 1994, ISBN 1-872630-68-8. Users can easily #' override or update this vector. #' #' @section Bugs: #' The current mapping is not guaranteed to be fully reversible: some SQL #' identifiers that get mapped into R identifiers with \code{make.names} and #' then back to SQL with \code{\link{make.db.names}} will not be equal to the #' original SQL identifiers (e.g., compound SQL identifiers of the form #' \code{username.tablename} will loose the dot ``.''). #' #' @references The set of SQL keywords is stored in the character vector #' \code{.SQL92Keywords} and reflects the SQL ANSI/ISO standard as documented #' in "X/Open SQL and RDA", 1994, ISBN 1-872630-68-8. Users can easily #' override or update this vector. #' @aliases #' make.db.names #' make.db.names,DBIObject,character-method #' SQLKeywords #' SQLKeywords,DBIObject-method #' SQLKeywords,missing-method #' isSQLKeyword #' isSQLKeyword,DBIObject,character-method #' @param dbObj any DBI object (e.g., \code{DBIDriver}). #' @param snames a character vector of R identifiers (symbols) from which we #' need to make SQL identifiers. #' @param name a character vector with database identifier candidates we need #' to determine whether they are legal SQL identifiers or not. #' @param unique logical describing whether the resulting set of SQL names #' should be unique. Its default is \code{TRUE}. Following the SQL 92 #' standard, uniqueness of SQL identifiers is determined regardless of whether #' letters are upper or lower case. #' @param allow.keywords logical describing whether SQL keywords should be #' allowed in the resulting set of SQL names. Its default is \code{TRUE} #' @param keywords a character vector with SQL keywords, by default it's #' \code{.SQL92Keywords} defined by the DBI. #' @param case a character string specifying whether to make the comparison as #' lower case, upper case, or any of the two. it defaults to \code{any}. #' @param \dots any other argument are passed to the driver implementation. #' @return \code{make.db.names} returns a character vector of legal SQL #' identifiers corresponding to its \code{snames} argument. #' #' \code{SQLKeywords} returns a character vector of all known keywords for the #' database-engine associated with \code{dbObj}. #' #' \code{isSQLKeyword} returns a logical vector parallel to \code{name}. #' @export setGeneric("make.db.names", signature = c("dbObj", "snames"), function(dbObj, snames, keywords = .SQL92Keywords, unique = TRUE, allow.keywords = TRUE, ...) { standardGeneric("make.db.names") }, valueClass = "character" ) setMethod("make.db.names", signature(dbObj="DBIObject", snames="character"), definition = function(dbObj, snames, keywords, unique, allow.keywords, ...) { make.db.names.default(snames, keywords, unique, allow.keywords) }, valueClass = "character" ) ## produce legal SQL identifiers from strings in a character vector ## unique, in this function, means unique regardless of lower/upper case #' @rdname make.db.names #' @export make.db.names.default <- function(snames, keywords = .SQL92Keywords, unique = TRUE, allow.keywords = TRUE) { makeUnique <- function(x, sep = "_") { if(length(x)==0) return(x) out <- x lc <- make.names(tolower(x), unique=FALSE) i <- duplicated(lc) lc <- make.names(lc, unique = TRUE) out[i] <- paste(out[i], substring(lc[i], first=nchar(out[i])+1), sep=sep) out } ## Note: SQL identifiers *can* be enclosed in double or single quotes ## when they are equal to reserverd keywords. fc <- substring(snames, 1, 1) lc <- substring(snames, nchar(snames)) i <- match(fc, c("'", '"'), 0)>0 & match(lc, c("'", '"'), 0)>0 snames[!i] <- make.names(snames[!i], unique=FALSE) if(unique) snames[!i] <- makeUnique(snames[!i]) if(!allow.keywords){ kwi <- match(keywords, toupper(snames), nomatch = 0L) snames[kwi] <- paste('"', snames[kwi], '"', sep='') } gsub("\\.", "_", snames) } #' @rdname make.db.names #' @export setGeneric("isSQLKeyword", signature = c("dbObj", "name"), function(dbObj, name, keywords = .SQL92Keywords, case = c("lower", "upper", "any")[3], ...) { standardGeneric("isSQLKeyword") }, valueClass = "logical" ) setMethod("isSQLKeyword", signature(dbObj="DBIObject", name="character"), definition = function(dbObj, name, keywords, case, ...) isSQLKeyword.default(name, keywords, case), valueClass = "logical" ) #' @rdname make.db.names #' @export isSQLKeyword.default <- function(name, keywords = .SQL92Keywords, case = c("lower", "upper", "any")[3]) { n <- pmatch(case, c("lower", "upper", "any"), nomatch=0) if(n==0) stop('case must be one of "lower", "upper", or "any"') kw <- switch(c("lower", "upper", "any")[n], lower = tolower(keywords), upper = toupper(keywords), any = toupper(keywords)) if(n==3) name <- toupper(name) match(name, keywords, nomatch=0) > 0 } ## SQL ANSI 92 (plus ISO's) keywords --- all 220 of them! ## (See pp. 22 and 23 in X/Open SQL and RDA, 1994, isbn 1-872630-68-8) #' @export setGeneric("SQLKeywords", function(dbObj, ...) { standardGeneric("SQLKeywords") }, valueClass = "character" ) setMethod("SQLKeywords", "DBIObject", definition = function(dbObj, ...) .SQL92Keywords, valueClass = "character" ) setMethod("SQLKeywords", "missing", definition = function(dbObj, ...) .SQL92Keywords, valueClass = "character" ) #' @export .SQL92Keywords <- c("ABSOLUTE", "ADD", "ALL", "ALLOCATE", "ALTER", "AND", "ANY", "ARE", "AS", "ASC", "ASSERTION", "AT", "AUTHORIZATION", "AVG", "BEGIN", "BETWEEN", "BIT", "BIT_LENGTH", "BY", "CASCADE", "CASCADED", "CASE", "CAST", "CATALOG", "CHAR", "CHARACTER", "CHARACTER_LENGTH", "CHAR_LENGTH", "CHECK", "CLOSE", "COALESCE", "COLLATE", "COLLATION", "COLUMN", "COMMIT", "CONNECT", "CONNECTION", "CONSTRAINT", "CONSTRAINTS", "CONTINUE", "CONVERT", "CORRESPONDING", "COUNT", "CREATE", "CURRENT", "CURRENT_DATE", "CURRENT_TIMESTAMP", "CURRENT_TYPE", "CURSOR", "DATE", "DAY", "DEALLOCATE", "DEC", "DECIMAL", "DECLARE", "DEFAULT", "DEFERRABLE", "DEFERRED", "DELETE", "DESC", "DESCRIBE", "DESCRIPTOR", "DIAGNOSTICS", "DICONNECT", "DICTIONATRY", "DISPLACEMENT", "DISTINCT", "DOMAIN", "DOUBLE", "DROP", "ELSE", "END", "END-EXEC", "ESCAPE", "EXCEPT", "EXCEPTION", "EXEC", "EXECUTE", "EXISTS", "EXTERNAL", "EXTRACT", "FALSE", "FETCH", "FIRST", "FLOAT", "FOR", "FOREIGN", "FOUND", "FROM", "FULL", "GET", "GLOBAL", "GO", "GOTO", "GRANT", "GROUP", "HAVING", "HOUR", "IDENTITY", "IGNORE", "IMMEDIATE", "IN", "INCLUDE", "INDEX", "INDICATOR", "INITIALLY", "INNER", "INPUT", "INSENSITIVE", "INSERT", "INT", "INTEGER", "INTERSECT", "INTERVAL", "INTO", "IS", "ISOLATION", "JOIN", "KEY", "LANGUAGE", "LAST", "LEFT", "LEVEL", "LIKE", "LOCAL", "LOWER", "MATCH", "MAX", "MIN", "MINUTE", "MODULE", "MONTH", "NAMES", "NATIONAL", "NCHAR", "NEXT", "NOT", "NULL", "NULLIF", "NUMERIC", "OCTECT_LENGTH", "OF", "OFF", "ONLY", "OPEN", "OPTION", "OR", "ORDER", "OUTER", "OUTPUT", "OVERLAPS", "PARTIAL", "POSITION", "PRECISION", "PREPARE", "PRESERVE", "PRIMARY", "PRIOR", "PRIVILEGES", "PROCEDURE", "PUBLIC", "READ", "REAL", "REFERENCES", "RESTRICT", "REVOKE", "RIGHT", "ROLLBACK", "ROWS", "SCHEMA", "SCROLL", "SECOND", "SECTION", "SELECT", "SET", "SIZE", "SMALLINT", "SOME", "SQL", "SQLCA", "SQLCODE", "SQLERROR", "SQLSTATE", "SQLWARNING", "SUBSTRING", "SUM", "SYSTEM", "TABLE", "TEMPORARY", "THEN", "TIME", "TIMESTAMP", "TIMEZONE_HOUR", "TIMEZONE_MINUTE", "TO", "TRANSACTION", "TRANSLATE", "TRANSLATION", "TRUE", "UNION", "UNIQUE", "UNKNOWN", "UPDATE", "UPPER", "USAGE", "USER", "USING", "VALUE", "VALUES", "VARCHAR", "VARYING", "VIEW", "WHEN", "WHENEVER", "WHERE", "WITH", "WORK", "WRITE", "YEAR", "ZONE" ) DBI/R/util.R0000644000176000001440000000275512401400410012174 0ustar ripleyusers#' Determine the current version of the package. #' #' @export #' @keywords internal dbGetDBIVersion <- function() { .Deprecated("packageVersion('DBI')") packageVersion("DBI") } #' Print a list of pairs. #' #' @param x a list of key, value pairs #' @param ... additional arguments to be passed to \code{cat} #' @return the (invisible) value of x. #' @keywords internal #' @export print.list.pairs #' @examples #' print.list.pairs(list(a = 1, b = 2)) print.list.pairs <- function(x, ...) { for(key in names(x)){ value <- format(x[[key]]) if (identical(value, "")) next cat(key, "=", value, "\n") } invisible(x) } # Give a deprecation error, warning, or messsage, depending on version number. dbi_dep <- function(version, msg) { v <- as.package_version(version) cv <- packageVersion("DBI") # If current major number is greater than last-good major number, or if # current minor number is more than 1 greater than last-good minor number, # give error. if (cv[[1,1]] > v[[1,1]] || cv[[1,2]] > v[[1,2]] + 1) { stop(msg, " (Defunct; last used in version ", version, ")", call. = FALSE) } # If minor number differs by one, give warning if (cv[[1,2]] > v[[1,2]]) { warning(msg, " (Deprecated; last used in version ", version, ")", call. = FALSE) return(invisible()) } # If only subminor number is greater, give message if (cv[[1,3]] > v[[1,3]]) { message(msg, " (Deprecated; last used in version ", version, ")") } invisible() }DBI/R/compliance.R0000644000176000001440000000370312400115651013334 0ustar ripleyusers#' Check a driver for compliance with DBI. #' #' @param driver Driver name. #' @param pkg Package that driver lives in - is usually "Rdriver" #' @export #' @examples #' if (require("RSQLite")) { #' dbiCheckCompliance("SQLite") #' dbiCheckCompliance("NoDriver", "RSQLite") #' } dbiCheckCompliance <- function(driver, pkg = paste0("R", driver)) { cat("Compliance check for ", driver, "\n", sep = "") where <- asNamespace(pkg) classes <- paste0(driver, names(key_methods)) names(classes) <- names(key_methods) is_class <- vapply(classes, isClass, where = where, FUN.VALUE = logical(1)) if (!all(is_class)) { cat("NOT OK\n", " Missing definitions for classes: ", paste0(classes[!is_class], collapse = ", "), "\n", sep = "") return(invisible()) } methods <- Map(function(g, c) has_methods(g, c, where), key_methods, classes) names(methods) <- classes cat(unlist(Map(compliance_message, methods, names(methods))), sep = "\n") } has_methods <- function(generic, class, where) { vapply(generic, function(x) hasMethod(x, class, where), FUN.VALUE = logical(1)) } compliance_message <- function(methods, name) { if (all(methods)) return(paste0(name, ": OK")) methods <- paste0(names(methods)[!methods], collapse = ", ") paste0(name, ": NOT OK\n", paste0(strwrap(methods, indent = 2, exdent = 2), collapse = "\n")) } key_methods <- list( Driver = c( "dbGetInfo", "dbConnect", "dbUnloadDriver", "dbListConnections", "dbDataType" ), Connection = c( "dbDisconnect", "dbGetInfo", "dbGetQuery", "dbGetException", "dbListResults", "dbListFields", "dbListTables", "dbReadTable", "dbWriteTable", "dbExistsTable", "dbRemoveTable", "dbBegin", "dbCommit", "dbRollback", "dbIsValid", "dbQuoteString", "dbQuoteIdentifier" ), Result = c( "dbIsValid", "dbFetch", "dbClearResult", "dbColumnInfo" ) ) DBI/R/DBConnection.R0000644000176000001440000002245512410067062013537 0ustar ripleyusers#' DBIConnection class. #' #' This virtual class encapsulates the connection to a DBMS, and it provides #' access to dynamic queries, result sets, DBMS session management #' (transactions), etc. #' #' @section Implementation note: #' Individual drivers are free to implement single or multiple simultaneous #' connections. #' #' @docType class #' @name DBIConnection-class #' @family DBI classes #' @examples #' \dontrun{ #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' dbDisconnect(con) #' #' con <- dbConnect(RPostgreSQL::PostgreSQL(), "username", "passsword") #' dbDisconnect(con) #' } #' @export #' @include DBObject.R setClass("DBIConnection", representation("DBIObject", "VIRTUAL")) #' Disconnect (close) a connection #' #' This closes the connection, discards all pending work, and frees #' resources (e.g., memory, sockets). #' #' @param conn A \code{\linkS4class{DBIConnection}} object, as produced by #' \code{\link{dbConnect}}. #' @param ... Other parameters passed on to methods. #' @return a logical vector of length 1, indicating success or failure. #' @export #' @family connection methods #' @examples #' if (require("RSQLite")) { #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' dbDisconnect(con) #' } setGeneric("dbDisconnect", def = function(conn, ...) standardGeneric("dbDisconnect"), valueClass = "logical" ) #' Execute a statement on a given database connection. #' #' The function \code{dbSendQuery} only submits and synchronously executes the #' SQL statement to the database engine. It does \emph{not} extracts any #' records --- for that you need to use the function \code{\link{dbFetch}}, and #' then you must call \code{\link{dbClearResult}} when you finish fetching the #' records you need. #' #' @inheritParams dbDisconnect #' @param statement a character vector of length 1 containing SQL. #' @return An object that inherits from \code{\linkS4class{DBIResult}}. #' If the statement generates output (e.g., a \code{SELECT} statement) the #' result set can be used with \code{\link{fetch}} to extract records. #' #' @section Side Effects: #' The statement is submitted for synchronous execution to the server connected #' through the \code{conn} object. The DBMS executes the statement, possibly #' generating vast amounts of data. Where these data reside is driver-specific: #' some drivers may choose to leave the output on the server 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 the individual drivers' #' \code{\link{dbSendQuery}} method for implementation details. #' @family connection methods #' @examples #' if (require("RSQLite")) { #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' res <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4;") #' dbFetch(res) #' dbClearResult(res) #' #' dbDisconnect(con) #' } #' @export setGeneric("dbSendQuery", def = function(conn, statement, ...) standardGeneric("dbSendQuery"), valueClass = "DBIResult" ) #' Send query, retrieve results and then clear result set. #' #' \code{dbGetQuery} comes with a default implementation that calls #' \code{\link{dbSendQuery}}, then if \code{\link{dbHasCompleted}} is TRUE, #' it uses \code{\link{fetch}} to return the results. \code{\link{on.exit}} #' is used to ensure the result set is always freed by #' \code{\link{dbClearResult}}. Subclasses should override this method #' only if they provide some sort of performance optimisation. #' #' @inheritParams dbDisconnect #' @param statement a character vector of length 1 containing SQL. #' @aliases dbGetQuery,DBIConnection,character-method #' @family connection methods #' @export #' @examples #' if (require("RSQLite")) { #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' res <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4;") #' dbFetch(res) #' dbClearResult(res) #' #' dbDisconnect(con) #' } setGeneric("dbGetQuery", def = function(conn, statement, ...) standardGeneric("dbGetQuery") ) setMethod("dbGetQuery", signature("DBIConnection", "character"), function(conn, statement, ...) { rs <- dbSendQuery(conn, statement, ...) on.exit(dbClearResult(rs)) # no records to fetch, we're done if (dbHasCompleted(rs)) return(NULL) res <- dbFetch(rs, n = -1, ...) if (!dbHasCompleted(rs)) warning("pending rows") res } ) #' Get DBMS exceptions. #' #' @inheritParams dbDisconnect #' @family connection methods #' @return a list with elements \code{errNum} (an integer error number) and #' \code{errMsg} (a character string) describing the last error in the #' connection \code{conn}. #' @export setGeneric("dbGetException", def = function(conn, ...) standardGeneric("dbGetException") ) #' A list of all pending results. #' #' List of \linkS4class{DBIResult} objects currently active on the connection. #' #' @inheritParams dbDisconnect #' @family connection methods #' @return a list. If no results are active, an empty list. If only #' a single result is active, a list with one element. #' @export setGeneric("dbListResults", def = function(conn, ...) standardGeneric("dbListResults") ) #' List field names of a remote table. #' #' @inheritParams dbDisconnect #' @param name a character string with the name of the remote table. #' @return a character vector #' @family connection methods #' @seealso \code{\link{dbColumnInfo}} to get the type of the fields. #' @export setGeneric("dbListFields", def = function(conn, name, ...) standardGeneric("dbListFields"), valueClass = "character" ) #' List remote tables. #' #' This should, where possible, include temporary tables. #' #' @inheritParams dbDisconnect #' @return a character vector. If no tables present, a character vector #' of length 0. #' @family connection methods #' @export setGeneric("dbListTables", def = function(conn, ...) standardGeneric("dbListTables"), valueClass = "character" ) #' Copy data frames to and from database tables. #' #' \code{dbReadTable}: database table -> data frame; \code{dbWriteTable}: #' data frame -> database table. #' #' @note The translation of identifiers between R and SQL is done through calls #' to \code{\link{make.names}} and \code{\link{make.db.names}}, but we cannot #' guarantee that the conversion is reversible. For details see #' \code{\link{make.db.names}}. #' @inheritParams dbDisconnect #' @param name A character string specifying a DBMS table name. #' @param value a data.frame (or coercible to data.frame). #' @family connection methods #' @return a data.frame. #' @export #' @examples #' if (require("RSQLite")) { #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars[1:10, ]) #' dbReadTable(con, "mtcars") #' #' dbDisconnect(con) #' } setGeneric("dbReadTable", valueClass = "data.frame", signature = c("conn", "name"), function(conn, name, ...) { standardGeneric("dbReadTable") } ) #' @rdname dbReadTable #' @export setGeneric("dbWriteTable", valueClass = "logical", signature = c("conn", "name", "value"), function(conn, name, value, ...) { standardGeneric("dbWriteTable") } ) #' Does a table exist? #' #' @inheritParams dbDisconnect #' @param name A character string specifying a DBMS table name. #' @family connection methods #' @return a logical vector of length 1. #' @export setGeneric("dbExistsTable", def = function(conn, name, ...) standardGeneric("dbExistsTable"), valueClass = "logical" ) #' Remove a table from the database. #' #' Executes the sql \code{DROP TABLE name}. #' #' @inheritParams dbDisconnect #' @param name A character string specifying a DBMS table name. #' @family connection methods #' @return a logical vector of length 1 indicating success or failure. #' @export setGeneric("dbRemoveTable", def = function(conn, name, ...) standardGeneric("dbRemoveTable"), valueClass = "logical" ) #' Begin/commit/rollback SQL transactions #' #' Not all database engines implement transaction management, in which case #' these methods should not be implemented for the specific #' \code{\linkS4class{DBIConnection}} subclass. #' #' @section Side Effects: #' The current transaction on the connections \code{con} is committed or rolled #' back. #' #' @inheritParams dbDisconnect #' @return a logical indicating whether the operation succeeded or not. #' @examples #' \dontrun{ #' ora <- dbDriver("Oracle") #' con <- dbConnect(ora) #' rs <- dbSendQuery(con, #' "delete * from PURGE as p where p.wavelength<0.03") #' if(dbGetInfo(rs, what = "rowsAffected") > 250){ #' warning("dubious deletion -- rolling back transaction") #' dbRollback(con) #' } #' } #' @name transactions NULL #' @export #' @rdname transactions setGeneric("dbBegin", def = function(conn, ...) standardGeneric("dbBegin"), valueClass = "logical" ) #' @export #' @rdname transactions setGeneric("dbCommit", def = function(conn, ...) standardGeneric("dbCommit"), valueClass = "logical" ) #' @export #' @rdname transactions setGeneric("dbRollback", def = function(conn, ...) standardGeneric("dbRollback"), valueClass = "logical" ) #' Call an SQL stored procedure #' #' DEPRECATED #' #' @inheritParams dbDisconnect #' @keywords internal #' @export setGeneric("dbCallProc", def = function(conn, ...) { .Deprecated() standardGeneric("dbCallProc") }, valueClass = "logical" ) DBI/README.md0000644000176000001440000001723012401431163012155 0ustar ripleyusers# DBI [![Build Status](https://travis-ci.org/rstats-db/DBI.png?branch=master)](https://travis-ci.org/rstats-db/DBI) The DBI package defines a common interface between the R and database management systems (DBMS). The interface defines a small set of classes and methods similar in spirit to Perl's [DBI](http://dbi.perl.org/), Java's [JDBC](http://www.oracle.com/technetwork/java/javase/jdbc/index.html), Python's [DB-API](http://www.python.org/dev/peps/pep-0249/), and Microsoft's [ODBC]((http://en.wikipedia.org/wiki/ODBC)). It defines a set of classes and methods defines what operations are possible and how they are performed: * connect/disconnect to the DBMS * create and execute statements in the DBMS * extract results/output from statements * error/exception handling * information (meta-data) from database objects * transaction management (optional) DBI separates the connectivity to the DBMS into a "front-end" and a "back-end". Applications use only the exposed "front-end" API. The facilities that communicate with specific DBMSs (SQLite, MySQL, PostgreSQL, MonetDB, etc.) are provided by "drivers" (other packages) that get invoked automatically through S4 methods. The following example illustrates some of the DBI capabilities: ```R library(DBI) # Create an ephemeral in-memory RSQLite database con <- dbConnect(RSQLite::SQLite(), dbname = ":memory:") dbListTables(con) dbWriteTable(con, "mtcars", mtcars) dbListTables(con) dbListFields(con, "mtcars") dbReadTable(con, "mtcars") # You can fetch all results: res <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4") dbFetch(res) dbClearResult(res) # Or a chunk at a time res <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4") while(!dbHasCompleted(res)){ chunk <- dbFetch(res, n = 5) print(nrow(chunk)) } dbClearResult(res) dbDisconnect(con) ``` To install DBI: * Get the released version from CRAN: `install.packages("DBI")` * Get the development version from github: `devtools::install_github("rstats-db/DBI")` Discussions associated with DBI and related database packages take place on [R-SIG-DB](https://stat.ethz.ch/mailman/listinfo/r-sig-db). ## Class structure There are four main DBI classes. Three which are each extended by individual database backends: * `DBIObject`: a common base class for all DBI. * `DBIDriver`: a base class representing overall DBMS properties. Typically generator functions instantiate the driver objects like `RSQLite()`, `RPostgreSQL()`, `RMySQL()` etc. * `DBIConnection`: represents a connection to a specific database * `DBIResult`: the result of a DBMS query or statement. All classes are _virtual_: they cannot be instantiated directly and instead must be subclassed. ## History The following history of DBI was contributed by David James, the driving force behind the development of DBI, and many of the packages that implement it. The idea/work of interfacing S (originally S3 and S4) to RDBMS goes back to the mid- and late 1990's in Bell Labs. The first toy interface I did was to implement John Chamber's early concept of "Data Management in S" (1991). The implementation followed that interface pretty closely and immediately showed some of the limitations when dealing with very large databases; if my memory serves me, the issue was the instance-based of the language back then, e.g., if you attached an RDBMS to the `search()` path and then needed to resolve a symbol "foo", you effectively had to bring all the objects in the database to check their mode/class, i.e., the instance object had the metadata in itself as attributes. The experiment showed that the S3 implementation of "data management" was not really suitable to large external RDBMS (probably it was never intended to do that anyway). (Note however, that since then, John and Duncan Temple Lang generalized the data management in S4 a lot, including Duncan's implementation in his [RObjectTables](http://www.omegahat.org/RObjectTables/) package where he considered a lot of synchronization/caching issues relevant to DBI and, more generally, to most external interfaces). Back then we were working very closely with Lucent's microelectronics manufacturing --- our colleagues there had huge Oracle (mostly) databases that we needed to constantly query via [SQL*Plus](http://en.wikipedia.org/wiki/SQL*Plus). My colleague Jake Luciani was developing advanced applications in C and SQL, and the two of us came up with the first implementation of S3 directly connecting with Oracle. What I remember is that the Linux [PRO*C](http://en.wikipedia.org/wiki/Pro*C) pre-compiler (that embedded SQL in C code) was very buggy --- we spent a lot of time looking for workarounds and tricks until we got the C interface running. At the time, other projects within Bell Labs began using MySQL, and we moved to MySQL (with the help of Doug Bates' student Saikat DebRoy, then a summer intern) with no intentions of looking back at the very difficult Oracle interface. It was at this time that I moved all the code from S3 methods to S4 classes and methods and begun reaching out to the S/R community for suggestions, ideas, etc. All (most) of this work was on Bell Labs versions of S3 and S4, but I made sure it worked with S-Plus. At some point around 2000 (I don't remember exactly when), I ported all the code to R regressing to S3 methods, and later on (once S4 classes and methods were available in R) I re-implemented everything back to S4 classes and methods in R (a painful back-and-forth). It was at this point that I decided to drop S-Plus altogether. Around that time, I came across a very early implementation of SQLite and I was quite interested and thought it was a very nice RDBMS that could be used for all kinds of experimentation, etc., so it was pretty easy to implement on top of the DBI. Within the R community, there were quite a number of people that showed interest on defining a common interface to databases, but only a few folks actually provided code/suggestions/etc. (Tim Keitt was most active with the dbi/PostgreSQL packages --- he also was considering what he called "proxy" objects, which was reminiscent of what Duncan had been doing). Kurt Hornick, Vincent Carey, Robert Gentleman, and others provided suggestions/comments/support for the DBI definition. By around 2003, the DBI was more or less implemented as it is today. I'm sure I'll forget some (most should be in the THANKS sections of the various packages), but the names that come to my mind at this moment are Jake Luciani (ROracle), Don MacQueen and other early ROracle users (super helpful), Doug Bates and his student Saikat DebRoy for RMySQL, Fei Chen (at the time a student of Prof. Ripley) also contributed to RMySQL, Tim Keitt (working on an early S3 interface to PostgrSQL), Torsten Hothorn (worked with mSQL and also MySQL), Prof. Ripley working/extending the RODBC package, in addition to John Chambers and Duncan Temple-Lang who provided very important comments and suggestions. Actually, the real impetus behind the DBI was always to do distributed statistical computing --- *not* to provide a yet-another import/export mechanism --- and this perspective was driven by John and Duncan's vision and work on inter-system computing, COM, CORBA, etc. I'm not sure many of us really appreciated (even now) the full extent of those ideas and concepts. Just like in other languages (C's ODBC, Java's JDBC, Perl's DBI/DBD, Python dbapi), R/S DBI was meant to unify the interfacing to RDBMS so that R/S applications could be developed on top of the DBI and not be hard coded to any one relation database. The interface I tried to follow the closest was the Python's DBAPI --- I haven't worked on this topic for a while, but I still feel Python's DBAPI is the cleanest and most relevant for the S language. DBI/MD50000644000176000001440000000512012410453060011201 0ustar ripleyusers330fbe420a011017700986060a075128 *DESCRIPTION b881ed25a2b3ba147dae9c554513ad7b *NAMESPACE daf5a89eeafd8dc02522862a5f99e857 *NEWS b9f1bc7e5d0ef7077455645e6118b89c *R/DBConnection.R ba6ff1a9e0f53b8f11c06f78a03b7b11 *R/DBDriver.R 1b292f150e95850a019141caff9c7d50 *R/DBObject.R e731cbd4f2274977b5106b8a0e04754b *R/DBResult.R 0a19c4a59e30e5dc5081b851c8322f82 *R/compliance.R 0000f51ca286e70056527d8721dd912f *R/keywords.R 9452b23d4017b7e87caf47538633b734 *R/quote.R ea0117a43454d34671eb6e1cdc12939b *R/util.R 5996acffcac21cb8d3296a5a0507f00e *README.md 75bfc3473f0a485bc5bc1b8e629476f1 *man/DBIConnection-class.Rd 28a88bc96b92534e1be20f728c848e94 *man/DBIDriver-class.Rd 58915a39ada415f784e16fc77f1eb3c8 *man/DBIObject-class.Rd 45fc4de5b81be6873f4e3b02569f8c92 *man/DBIResult-class.Rd 3bc4b5a953ef592fa84ecbe9076116de *man/SQL.Rd fd904a593ec550dd9cb181be4ffdf619 *man/dbCallProc.Rd 88472085e25cff81dda3aea63a7f1f4c *man/dbClearResult.Rd 11af9423c8fbd7ffbfed1d539344399e *man/dbColumnInfo.Rd 7de69a3b87db85be7b3b3842b0ff41c0 *man/dbConnect.Rd 3c22a3733f8620fb4db1323277d5a6f9 *man/dbDataType.Rd 4bd339062e63aa6a3cf35823a51894ac *man/dbDisconnect.Rd 7068e28094729ab99ad02ad8271b1a33 *man/dbDriver.Rd d40bd70b47533a5d6603ca7a0f8779f4 *man/dbExistsTable.Rd 587231a60471096ae3f63c69b6bd90b2 *man/dbFetch.Rd 240780f1d8cbdfe454ba8101b060af85 *man/dbGetDBIVersion.Rd 3aafd649c10f92463fef0a869a4ccce0 *man/dbGetException.Rd ad54c491c26a4008e53da8a975f0b0fa *man/dbGetInfo.Rd 216cfe45f03374a3ccd52ee7df2d5c53 *man/dbGetQuery.Rd afd07278a98cc39a6ee60aa5a8e4e2c8 *man/dbGetRowCount.Rd 1b7338be90b84a922a3cbfc2f72128a0 *man/dbGetRowsAffected.Rd 013d4831ba9b6c21162ed1c18b16fcdb *man/dbGetStatement.Rd 60913893ccf7d6b7d086117c4a3d77ea *man/dbHasCompleted.Rd a87d17d341a869249faeb5bd3fedef1f *man/dbIsValid.Rd 149af3cced0d468254110d9bdf215c06 *man/dbListConnections.Rd 7845dcc55f16290950bf6aef9c2a599b *man/dbListFields.Rd 139dcc98339b3e7436cd79167b13d543 *man/dbListResults.Rd 1746c76e713095c991c5ce18d988ee70 *man/dbListTables.Rd d719c6556ff10a532f52d69d31327636 *man/dbReadTable.Rd 766b302b57339603380fb61607ab09c3 *man/dbRemoveTable.Rd 1f41be26960ddc558bbe76087adb9651 *man/dbSendQuery.Rd 38b0393016df55f1ce2fc719872f4cd5 *man/dbSetDataMappings.Rd 87563878f8ab6fa7621dca8e2ac3c4c5 *man/dbiCheckCompliance.Rd 98d459506e0b3c0055a6c090a3669664 *man/make.db.names.Rd bdb6e549e90a31f373683ec0ba8568c8 *man/print.list.pairs.Rd 3077ee0c1ecf43c93e6fd589356b09ef *man/transactions.Rd a4fe1ddf5f03bdcb9a22c2674a266e9e *tests/testthat.R a0e8f9eb80974345f902b315a0409281 *tests/testthat/helper-dummy.R 1334eb2a2e5a1428e0cef22435b7f86d *tests/testthat/test-data-type.R DBI/DESCRIPTION0000644000176000001440000000145112410453060012402 0ustar ripleyusersPackage: DBI Version: 0.3.1 Title: R Database Interface Author: R Special Interest Group on Databases (R-SIG-DB) Maintainer: Hadley Wickham Depends: R (>= 2.15.0), methods Suggests: testthat, RSQLite Description: A database interface (DBI) definition for communication between R and relational database management systems. All classes in this package are virtual and need to be extended by the various R/DBMS implementations. License: LGPL (>= 2) URL: https://github.com/rstats-db/DBI BugReports: https://github.com/rstats-db/DBI/issues Collate: 'DBObject.R' 'DBConnection.R' 'DBDriver.R' 'DBResult.R' 'compliance.R' 'keywords.R' 'quote.R' 'util.R' Packaged: 2014-09-23 21:42:02 UTC; hadley NeedsCompilation: no Repository: CRAN Date/Publication: 2014-09-24 07:27:12 DBI/man/0000755000176000001440000000000012400130254011442 5ustar ripleyusersDBI/man/dbListResults.Rd0000644000176000001440000000164612400165462014554 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbListResults} \alias{dbListResults} \title{A list of all pending results.} \usage{ dbListResults(conn, ...) } \arguments{ \item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by \code{\link{dbConnect}}.} \item{...}{Other parameters passed on to methods.} } \value{ a list. If no results are active, an empty list. If only a single result is active, a list with one element. } \description{ List of \linkS4class{DBIResult} objects currently active on the connection. } \seealso{ Other connection methods: \code{\link{dbDisconnect}}; \code{\link{dbExistsTable}}; \code{\link{dbGetException}}; \code{\link{dbGetQuery}}, \code{\link{dbGetQuery,DBIConnection,character-method}}; \code{\link{dbListFields}}; \code{\link{dbListTables}}; \code{\link{dbReadTable}}, \code{\link{dbWriteTable}}; \code{\link{dbRemoveTable}}; \code{\link{dbSendQuery}} } DBI/man/dbGetInfo.Rd0000644000176000001440000000302712400165462013605 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbGetInfo} \alias{dbGetInfo} \title{Get DBMS metadata.} \usage{ dbGetInfo(dbObj, ...) } \arguments{ \item{dbObj}{An object inheriting from \code{\linkS4class{DBIObject}}, i.e. \code{\linkS4class{DBIDriver}}, \code{\linkS4class{DBIConnection}}, or a \code{\linkS4class{DBIResult}}} \item{...}{Other arguments to methods.} } \value{ a named list } \description{ Get DBMS metadata. } \section{Implementation notes}{ For \code{DBIDriver} subclasses, this should include the version of the package (\code{driver.version}), the version of the underlying client library (\code{client.version}), and the maximum number of connections (\code{max.connections}). For \code{DBIConnection} objects this should report the version of the DBMS engine (\code{db.version}), database name (\code{dbname}), username, (\code{username}), host (\code{host}), port (\code{port}), etc. It MAY also include any other arguments related to the connection (e.g., thread id, socket or TCP connection type). It MUST NOT include the password. For \code{DBIResult} objects, this should include the statement being executed (\code{statement}), how many rows have been fetched so far (in the case of queries) (\code{row.count}), how many rows were affected (deleted, inserted, changed, or total number of records to be fetched). (\code{rows.affected}), if the query is complete (\code{has.completed}), and whether or not the query generates output (\code{is.select}). } \seealso{ Other DBObject methods: \code{\link{dbIsValid}} } DBI/man/dbSendQuery.Rd0000644000176000001440000000413712400165462014174 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbSendQuery} \alias{dbSendQuery} \title{Execute a statement on a given database connection.} \usage{ dbSendQuery(conn, statement, ...) } \arguments{ \item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by \code{\link{dbConnect}}.} \item{statement}{a character vector of length 1 containing SQL.} \item{...}{Other parameters passed on to methods.} } \value{ An object that inherits from \code{\linkS4class{DBIResult}}. If the statement generates output (e.g., a \code{SELECT} statement) the result set can be used with \code{\link{fetch}} to extract records. } \description{ The function \code{dbSendQuery} only submits and synchronously executes the SQL statement to the database engine. It does \emph{not} extracts any records --- for that you need to use the function \code{\link{dbFetch}}, and then you must call \code{\link{dbClearResult}} when you finish fetching the records you need. } \section{Side Effects}{ The statement is submitted for synchronous execution to the server connected through the \code{conn} object. The DBMS executes the statement, possibly generating vast amounts of data. Where these data reside is driver-specific: some drivers may choose to leave the output on the server 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 the individual drivers' \code{\link{dbSendQuery}} method for implementation details. } \examples{ if (require("RSQLite")) { con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) res <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4;") dbFetch(res) dbClearResult(res) dbDisconnect(con) } } \seealso{ Other connection methods: \code{\link{dbDisconnect}}; \code{\link{dbExistsTable}}; \code{\link{dbGetException}}; \code{\link{dbGetQuery}}, \code{\link{dbGetQuery,DBIConnection,character-method}}; \code{\link{dbListFields}}; \code{\link{dbListResults}}; \code{\link{dbListTables}}; \code{\link{dbReadTable}}, \code{\link{dbWriteTable}}; \code{\link{dbRemoveTable}} } DBI/man/dbListConnections.Rd0000644000176000001440000000077512400165462015377 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbListConnections} \alias{dbListConnections} \title{List currently open connections.} \usage{ dbListConnections(drv, ...) } \arguments{ \item{drv}{A object inheriting from \code{\linkS4class{DBIDriver}}} \item{...}{Other arguments passed on to methods.} } \value{ a list } \description{ Drivers that implement only a single connections MUST return a list containing a single element. If no connection are open, methods MUST return an empty list. } DBI/man/dbIsValid.Rd0000644000176000001440000000114512400165462013604 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbIsValid} \alias{dbIsValid} \title{Is this DBMS object still valid?} \usage{ dbIsValid(dbObj, ...) } \arguments{ \item{dbObj}{An object inheriting from \code{\linkS4class{DBIObject}}, i.e. \code{\linkS4class{DBIDriver}}, \code{\linkS4class{DBIConnection}}, or a \code{\linkS4class{DBIResult}}} \item{...}{Other arguments to methods.} } \value{ a logical of length 1 } \description{ This generic tests whether a database object is still valid (i.e. it hasn't been disconnected or cleared). } \seealso{ Other DBObject methods: \code{\link{dbGetInfo}} } DBI/man/dbiCheckCompliance.Rd0000644000176000001440000000075612400165462015441 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbiCheckCompliance} \alias{dbiCheckCompliance} \title{Check a driver for compliance with DBI.} \usage{ dbiCheckCompliance(driver, pkg = paste0("R", driver)) } \arguments{ \item{driver}{Driver name.} \item{pkg}{Package that driver lives in - is usually "Rdriver"} } \description{ Check a driver for compliance with DBI. } \examples{ if (require("RSQLite")) { dbiCheckCompliance("SQLite") dbiCheckCompliance("NoDriver", "RSQLite") } } DBI/man/DBIDriver-class.Rd0000644000176000001440000000112712400165462014620 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \docType{class} \name{DBIDriver-class} \alias{DBIDriver-class} \title{DBIDriver class.} \description{ Base class for all DBMS drivers (e.g., RSQLite, MySQL, PostgreSQL). The virtual class \code{DBIDriver} defines the operations for creating connections and defining data type mappings. Actual driver classes, for instance \code{RPgSQL}, \code{RMySQL}, etc. implement these operations in a DBMS-specific manner. } \seealso{ Other DBI classes: \code{\link{DBIConnection-class}}; \code{\link{DBIObject-class}}; \code{\link{DBIResult-class}} } DBI/man/dbFetch.Rd0000644000176000001440000000407212400165462013304 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbFetch} \alias{dbFetch} \alias{dbFetch,DBIResult-method} \alias{fetch} \title{Fetch records from a previously executed query.} \usage{ dbFetch(res, n = -1, ...) fetch(res, n = -1, ...) } \arguments{ \item{res}{An object inheriting from \code{\linkS4class{DBIResult}}.} \item{n}{maximum number of records to retrieve per fetch. Use \code{n = -1} to retrieve all pending records. Some implementations may recognize other special values.} \item{...}{Other arguments passed on to methods.} } \value{ a data.frame with as many rows as records were fetched and as many columns as fields in the result set. } \description{ Fetch the next \code{n} elements (rows) from the result set and return them as a data.frame. } \details{ \code{fetch} is provided for compatibility with older DBI clients - for all new code you are strongly encouraged to use \code{dbFetch}. The default method for \code{dbFetch} calls \code{fetch} so that it is compatible with existing code. Implementors should provide methods for both \code{fetch} and \code{dbFetch} until \code{fetch} is deprecated in 2015. } \examples{ if (!require("RSQLite")) { con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) # Fetch all results res <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4") dbFetch(res) dbClearResult(res) # Fetch in chunks res <- dbSendQuery(con, "SELECT * FROM mtcars") while (!dbHasCompleted(res)) { chunk <- fetch(res, 10) print(nrow(chunk)) } dbClearResult(res) dbDisconnect(con) } } \seealso{ close the result set with \code{\link{dbClearResult}} as soon as you finish retrieving the records you want. Other DBIResult generics: \code{\link{dbClearResult}}; \code{\link{dbColumnInfo}}; \code{\link{dbGetRowCount}}, \code{\link{dbGetRowCount,DBIResult-method}}; \code{\link{dbGetRowsAffected}}, \code{\link{dbGetRowsAffected,DBIResult-method}}; \code{\link{dbGetStatement}}, \code{\link{dbGetStatement,DBIResult-method}}; \code{\link{dbHasCompleted}}, \code{\link{dbHasCompleted,DBIResult-method}} } DBI/man/dbColumnInfo.Rd0000644000176000001440000000253212400165462014323 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbColumnInfo} \alias{dbColumnInfo} \title{Information about result types.} \usage{ dbColumnInfo(res, ...) } \arguments{ \item{res}{An object inheriting from \code{\linkS4class{DBIResult}}.} \item{...}{Other arguments passed on to methods.} } \value{ A data.frame with one row per output field in \code{res}. Methods MUST include \code{name}, \code{field.type} (the SQL type), and \code{data.type} (the R data type) columns, and MAY contain other database specific information like scale and precision or whether the field can store \code{NULL}s. } \description{ Produces a data.frame that describes the output of a query. The data.frame should have as many rows as there are output fields in the result set, and each column in the data.frame should describe an aspect of the result set field (field name, type, etc.) } \seealso{ Other DBIResult generics: \code{\link{dbClearResult}}; \code{\link{dbFetch}}, \code{\link{dbFetch,DBIResult-method}}, \code{\link{fetch}}; \code{\link{dbGetRowCount}}, \code{\link{dbGetRowCount,DBIResult-method}}; \code{\link{dbGetRowsAffected}}, \code{\link{dbGetRowsAffected,DBIResult-method}}; \code{\link{dbGetStatement}}, \code{\link{dbGetStatement,DBIResult-method}}; \code{\link{dbHasCompleted}}, \code{\link{dbHasCompleted,DBIResult-method}} } DBI/man/dbListFields.Rd0000644000176000001440000000165212400165462014316 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbListFields} \alias{dbListFields} \title{List field names of a remote table.} \usage{ dbListFields(conn, name, ...) } \arguments{ \item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by \code{\link{dbConnect}}.} \item{name}{a character string with the name of the remote table.} \item{...}{Other parameters passed on to methods.} } \value{ a character vector } \description{ List field names of a remote table. } \seealso{ \code{\link{dbColumnInfo}} to get the type of the fields. Other connection methods: \code{\link{dbDisconnect}}; \code{\link{dbExistsTable}}; \code{\link{dbGetException}}; \code{\link{dbGetQuery}}, \code{\link{dbGetQuery,DBIConnection,character-method}}; \code{\link{dbListResults}}; \code{\link{dbListTables}}; \code{\link{dbReadTable}}, \code{\link{dbWriteTable}}; \code{\link{dbRemoveTable}}; \code{\link{dbSendQuery}} } DBI/man/DBIConnection-class.Rd0000644000176000001440000000136312400165462015466 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \docType{class} \name{DBIConnection-class} \alias{DBIConnection-class} \title{DBIConnection class.} \description{ This virtual class encapsulates the connection to a DBMS, and it provides access to dynamic queries, result sets, DBMS session management (transactions), etc. } \section{Implementation note}{ Individual drivers are free to implement single or multiple simultaneous connections. } \examples{ \dontrun{ con <- dbConnect(RSQLite::SQLite(), ":memory:") dbDisconnect(con) con <- dbConnect(RPostgreSQL::PostgreSQL(), "username", "passsword") dbDisconnect(con) } } \seealso{ Other DBI classes: \code{\link{DBIDriver-class}}; \code{\link{DBIObject-class}}; \code{\link{DBIResult-class}} } DBI/man/print.list.pairs.Rd0000644000176000001440000000066512400165462015174 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{print.list.pairs} \alias{print.list.pairs} \title{Print a list of pairs.} \usage{ \method{print}{list.pairs}(x, ...) } \arguments{ \item{x}{a list of key, value pairs} \item{...}{additional arguments to be passed to \code{cat}} } \value{ the (invisible) value of x. } \description{ Print a list of pairs. } \examples{ print.list.pairs(list(a = 1, b = 2)) } \keyword{internal} DBI/man/dbHasCompleted.Rd0000644000176000001440000000164012400165462014621 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbHasCompleted} \alias{dbHasCompleted} \alias{dbHasCompleted,DBIResult-method} \title{Has the operation completed?} \usage{ dbHasCompleted(res, ...) } \arguments{ \item{res}{An object inheriting from \code{\linkS4class{DBIResult}}.} \item{...}{Other arguments passed on to methods.} } \value{ a logical vector of length 1 } \description{ The default method extracts \code{has.completed} from the result of \code{\link{dbGetInfo}(res)}. } \seealso{ Other DBIResult generics: \code{\link{dbClearResult}}; \code{\link{dbColumnInfo}}; \code{\link{dbFetch}}, \code{\link{dbFetch,DBIResult-method}}, \code{\link{fetch}}; \code{\link{dbGetRowCount}}, \code{\link{dbGetRowCount,DBIResult-method}}; \code{\link{dbGetRowsAffected}}, \code{\link{dbGetRowsAffected,DBIResult-method}}; \code{\link{dbGetStatement}}, \code{\link{dbGetStatement,DBIResult-method}} } DBI/man/dbDriver.Rd0000644000176000001440000000307212400165462013505 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbDriver} \alias{dbDriver} \alias{dbDriver,character-method} \alias{dbUnloadDriver} \title{Load and unload database drivers.} \usage{ dbDriver(drvName, ...) dbUnloadDriver(drv, ...) } \arguments{ \item{drvName}{character name of the driver to instantiate.} \item{...}{any other arguments are passed to the driver \code{drvName}.} \item{drv}{an object that inherits from \code{DBIDriver} as created by \code{dbDriver}.} } \value{ In the case of \code{dbDriver}, an driver object whose class extends \code{DBIDriver}. This object may be used to create connections to the actual DBMS engine. In the case of \code{dbUnloadDriver}, a logical indicating whether the operation succeeded or not. } \description{ \code{dbDriver} is a helper method used to create an new driver object given the name of a database or the corresponding R package. It works through convention: all DBI-extending packages should provide an exported object with the same name as the package. \code{dbDriver} just looks for this object in the right places: if you know what database you are connecting to, you should call the function directly. } \section{Side Effects}{ The client part of the database communication is initialized (typically dynamically loading C code, etc.) but note that connecting to the database engine itself needs to be done through calls to \code{dbConnect}. } \examples{ if (require("RSQLite")) { # Create a RSQLite driver with a string d <- dbDriver("SQLite") d # But better, access the object directly RSQLite::SQLite() } } DBI/man/DBIResult-class.Rd0000644000176000001440000000134012400165462014640 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \docType{class} \name{DBIResult-class} \alias{DBIResult-class} \title{DBIResult class.} \description{ This virtual class describes the result and state of execution of a DBMS statement (any statement, query or non-query). The result set \code{res} keeps track of whether the statement produces output how many rows were affected by the operation, how many rows have been fetched (if statement is a query), whether there are more rows to fetch, etc. } \details{ Individual drivers are free to allow single or multiple active results per connection. } \seealso{ Other DBI classes: \code{\link{DBIConnection-class}}; \code{\link{DBIDriver-class}}; \code{\link{DBIObject-class}} } DBI/man/dbGetRowsAffected.Rd0000644000176000001440000000167612400165462015276 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbGetRowsAffected} \alias{dbGetRowsAffected} \alias{dbGetRowsAffected,DBIResult-method} \title{The number of rows affected by data modifying query.} \usage{ dbGetRowsAffected(res, ...) } \arguments{ \item{res}{An object inheriting from \code{\linkS4class{DBIResult}}.} \item{...}{Other arguments passed on to methods.} } \value{ a numeric vector of length 1 } \description{ The default method extracts \code{rows.affected} from the result of \code{\link{dbGetInfo}(res)}. } \seealso{ Other DBIResult generics: \code{\link{dbClearResult}}; \code{\link{dbColumnInfo}}; \code{\link{dbFetch}}, \code{\link{dbFetch,DBIResult-method}}, \code{\link{fetch}}; \code{\link{dbGetRowCount}}, \code{\link{dbGetRowCount,DBIResult-method}}; \code{\link{dbGetStatement}}, \code{\link{dbGetStatement,DBIResult-method}}; \code{\link{dbHasCompleted}}, \code{\link{dbHasCompleted,DBIResult-method}} } DBI/man/dbRemoveTable.Rd0000644000176000001440000000163012400165462014455 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbRemoveTable} \alias{dbRemoveTable} \title{Remove a table from the database.} \usage{ dbRemoveTable(conn, name, ...) } \arguments{ \item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by \code{\link{dbConnect}}.} \item{name}{A character string specifying a DBMS table name.} \item{...}{Other parameters passed on to methods.} } \value{ a logical vector of length 1 indicating success or failure. } \description{ Executes the sql \code{DROP TABLE name}. } \seealso{ Other connection methods: \code{\link{dbDisconnect}}; \code{\link{dbExistsTable}}; \code{\link{dbGetException}}; \code{\link{dbGetQuery}}, \code{\link{dbGetQuery,DBIConnection,character-method}}; \code{\link{dbListFields}}; \code{\link{dbListResults}}; \code{\link{dbListTables}}; \code{\link{dbReadTable}}, \code{\link{dbWriteTable}}; \code{\link{dbSendQuery}} } DBI/man/dbGetException.Rd0000644000176000001440000000163112400165462014647 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbGetException} \alias{dbGetException} \title{Get DBMS exceptions.} \usage{ dbGetException(conn, ...) } \arguments{ \item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by \code{\link{dbConnect}}.} \item{...}{Other parameters passed on to methods.} } \value{ a list with elements \code{errNum} (an integer error number) and \code{errMsg} (a character string) describing the last error in the connection \code{conn}. } \description{ Get DBMS exceptions. } \seealso{ Other connection methods: \code{\link{dbDisconnect}}; \code{\link{dbExistsTable}}; \code{\link{dbGetQuery}}, \code{\link{dbGetQuery,DBIConnection,character-method}}; \code{\link{dbListFields}}; \code{\link{dbListResults}}; \code{\link{dbListTables}}; \code{\link{dbReadTable}}, \code{\link{dbWriteTable}}; \code{\link{dbRemoveTable}}; \code{\link{dbSendQuery}} } DBI/man/DBIObject-class.Rd0000644000176000001440000000303712400165462014575 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \docType{class} \name{DBIObject-class} \alias{DBIObject-class} \title{DBIObject class.} \description{ Base class for all other DBI classes (e.g., drivers, connections). This is a virtual Class: No objects may be created from it. } \details{ More generally, the DBI defines a very small set of classes and methods that allows users and applications access DBMS with a common interface. The virtual classes are \code{DBIDriver} that individual drivers extend, \code{DBIConnection} that represent instances of DBMS connections, and \code{DBIResult} that represent the result of a DBMS statement. These three classes extend the basic class of \code{DBIObject}, which serves as the root or parent of the class hierarchy. } \section{Implementation notes}{ An implementation MUST provide methods for the following generics: \itemize{ \item \code{\link{dbGetInfo}}. } It MAY also provide methods for: \itemize{ \item \code{\link{summary}}. Print a concise description of the object. The default method invokes \code{dbGetInfo(dbObj)} and prints the name-value pairs one per line. Individual implementations may tailor this appropriately. } } \examples{ \dontrun{ drv <- dbDriver("MySQL") con <- dbConnect(drv, group = "rs-dbi") res <- dbSendQuery(con, "select * from vitalSuite") is(drv, "DBIObject") ## True is(con, "DBIObject") ## True is(res, "DBIObject") } } \seealso{ Other DBI classes: \code{\link{DBIConnection-class}}; \code{\link{DBIDriver-class}}; \code{\link{DBIResult-class}} } DBI/man/make.db.names.Rd0000644000176000001440000000666312400165462014360 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{make.db.names} \alias{SQLKeywords} \alias{SQLKeywords,DBIObject-method} \alias{SQLKeywords,missing-method} \alias{isSQLKeyword} \alias{isSQLKeyword,DBIObject,character-method} \alias{isSQLKeyword.default} \alias{make.db.names} \alias{make.db.names,DBIObject,character-method} \alias{make.db.names.default} \title{Make R identifiers into legal SQL identifiers.} \usage{ make.db.names(dbObj, snames, keywords = .SQL92Keywords, unique = TRUE, allow.keywords = TRUE, ...) make.db.names.default(snames, keywords = .SQL92Keywords, unique = TRUE, allow.keywords = TRUE) isSQLKeyword(dbObj, name, keywords = .SQL92Keywords, case = c("lower", "upper", "any")[3], ...) isSQLKeyword.default(name, keywords = .SQL92Keywords, case = c("lower", "upper", "any")[3]) } \arguments{ \item{dbObj}{any DBI object (e.g., \code{DBIDriver}).} \item{snames}{a character vector of R identifiers (symbols) from which we need to make SQL identifiers.} \item{keywords}{a character vector with SQL keywords, by default it's \code{.SQL92Keywords} defined by the DBI.} \item{unique}{logical describing whether the resulting set of SQL names should be unique. Its default is \code{TRUE}. Following the SQL 92 standard, uniqueness of SQL identifiers is determined regardless of whether letters are upper or lower case.} \item{allow.keywords}{logical describing whether SQL keywords should be allowed in the resulting set of SQL names. Its default is \code{TRUE}} \item{name}{a character vector with database identifier candidates we need to determine whether they are legal SQL identifiers or not.} \item{case}{a character string specifying whether to make the comparison as lower case, upper case, or any of the two. it defaults to \code{any}.} \item{\dots}{any other argument are passed to the driver implementation.} } \value{ \code{make.db.names} returns a character vector of legal SQL identifiers corresponding to its \code{snames} argument. \code{SQLKeywords} returns a character vector of all known keywords for the database-engine associated with \code{dbObj}. \code{isSQLKeyword} returns a logical vector parallel to \code{name}. } \description{ These methods are DEPRECATED. Please use \code{\link{dbQuoteIdentifier}} (or possibly \code{\link{dbQuoteString}}) instead. } \details{ The algorithm in \code{make.db.names} first invokes \code{make.names} and then replaces each occurrence of a dot ``.'' by an underscore ``\_''. If \code{allow.keywords} is \code{FALSE} and identifiers collide with SQL keywords, a small integer is appended to the identifier in the form of \code{"_n"}. The set of SQL keywords is stored in the character vector \code{.SQL92Keywords} and reflects the SQL ANSI/ISO standard as documented in "X/Open SQL and RDA", 1994, ISBN 1-872630-68-8. Users can easily override or update this vector. } \section{Bugs}{ The current mapping is not guaranteed to be fully reversible: some SQL identifiers that get mapped into R identifiers with \code{make.names} and then back to SQL with \code{\link{make.db.names}} will not be equal to the original SQL identifiers (e.g., compound SQL identifiers of the form \code{username.tablename} will loose the dot ``.''). } \references{ The set of SQL keywords is stored in the character vector \code{.SQL92Keywords} and reflects the SQL ANSI/ISO standard as documented in "X/Open SQL and RDA", 1994, ISBN 1-872630-68-8. Users can easily override or update this vector. } DBI/man/dbConnect.Rd0000644000176000001440000000335512400165462013647 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbConnect} \alias{dbConnect} \title{Create a connection to a DBMS.} \usage{ dbConnect(drv, ...) } \arguments{ \item{drv}{an object that inherits from \code{\linkS4class{DBIDriver}}, or a character string specifying the name of DBMS driver, e.g., "RSQLite", "RMySQL", "RPostgreSQL", or an existing \code{\linkS4class{DBIConnection}} object (in order to clone an existing connection).} \item{...}{authorization arguments needed by the DBMS instance; these typically include \code{user}, \code{password}, \code{dbname}, \code{host}, \code{port}, etc. For details see the appropriate \code{DBIDriver}.} } \value{ An object that extends \code{\linkS4class{DBIConnection}} in a database-specific manner. For instance \code{dbConnect("MySQL")} produces an object of class \code{MySQLConnection}. This object is used to direct commands to the database engine. } \description{ Connect to a DBMS going through the appropriate authorization procedure. Some implementations may allow you to have multiple connections open, so you may invoke this function repeatedly assigning its output to different objects. The authorization mechanism is left unspecified, so check the documentation of individual drivers for details. } \details{ Each driver will define what other arguments are required, e.g., \code{"dbname"} for the database name, \code{"username"}, and \code{"password"}. } \examples{ if (require("RSQLite")) { # SQLite only needs a path to the database. Other database drivers # will require more details (like username, password, host, port etc) con <- dbConnect(RSQLite::SQLite(), ":memory:") con dbListTables(con) dbDisconnect(con) } } \seealso{ \code{\link{dbDisconnect}} to disconnect from a database. } DBI/man/dbExistsTable.Rd0000644000176000001440000000152712400165462014504 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbExistsTable} \alias{dbExistsTable} \title{Does a table exist?} \usage{ dbExistsTable(conn, name, ...) } \arguments{ \item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by \code{\link{dbConnect}}.} \item{name}{A character string specifying a DBMS table name.} \item{...}{Other parameters passed on to methods.} } \value{ a logical vector of length 1. } \description{ Does a table exist? } \seealso{ Other connection methods: \code{\link{dbDisconnect}}; \code{\link{dbGetException}}; \code{\link{dbGetQuery}}, \code{\link{dbGetQuery,DBIConnection,character-method}}; \code{\link{dbListFields}}; \code{\link{dbListResults}}; \code{\link{dbListTables}}; \code{\link{dbReadTable}}, \code{\link{dbWriteTable}}; \code{\link{dbRemoveTable}}; \code{\link{dbSendQuery}} } DBI/man/dbListTables.Rd0000644000176000001440000000154112400165462014317 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbListTables} \alias{dbListTables} \title{List remote tables.} \usage{ dbListTables(conn, ...) } \arguments{ \item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by \code{\link{dbConnect}}.} \item{...}{Other parameters passed on to methods.} } \value{ a character vector. If no tables present, a character vector of length 0. } \description{ This should, where possible, include temporary tables. } \seealso{ Other connection methods: \code{\link{dbDisconnect}}; \code{\link{dbExistsTable}}; \code{\link{dbGetException}}; \code{\link{dbGetQuery}}, \code{\link{dbGetQuery,DBIConnection,character-method}}; \code{\link{dbListFields}}; \code{\link{dbListResults}}; \code{\link{dbReadTable}}, \code{\link{dbWriteTable}}; \code{\link{dbRemoveTable}}; \code{\link{dbSendQuery}} } DBI/man/dbGetQuery.Rd0000644000176000001440000000266012400165462014021 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbGetQuery} \alias{dbGetQuery} \alias{dbGetQuery,DBIConnection,character-method} \title{Send query, retrieve results and then clear result set.} \usage{ dbGetQuery(conn, statement, ...) } \arguments{ \item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by \code{\link{dbConnect}}.} \item{statement}{a character vector of length 1 containing SQL.} \item{...}{Other parameters passed on to methods.} } \description{ \code{dbGetQuery} comes with a default implementation that calls \code{\link{dbSendQuery}}, then if \code{\link{dbHasCompleted}} is TRUE, it uses \code{\link{fetch}} to return the results. \code{\link{on.exit}} is used to ensure the result set is always freed by \code{\link{dbClearResult}}. Subclasses should override this method only if they provide some sort of performance optimisation. } \examples{ if (require("RSQLite")) { con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) res <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4;") dbFetch(res) dbClearResult(res) dbDisconnect(con) } } \seealso{ Other connection methods: \code{\link{dbDisconnect}}; \code{\link{dbExistsTable}}; \code{\link{dbGetException}}; \code{\link{dbListFields}}; \code{\link{dbListResults}}; \code{\link{dbListTables}}; \code{\link{dbReadTable}}, \code{\link{dbWriteTable}}; \code{\link{dbRemoveTable}}; \code{\link{dbSendQuery}} } DBI/man/dbGetStatement.Rd0000644000176000001440000000164412400165462014661 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbGetStatement} \alias{dbGetStatement} \alias{dbGetStatement,DBIResult-method} \title{Get the statement associated with a result set} \usage{ dbGetStatement(res, ...) } \arguments{ \item{res}{An object inheriting from \code{\linkS4class{DBIResult}}.} \item{...}{Other arguments passed on to methods.} } \value{ a character vector } \description{ The default method extracts \code{statement} from the result of \code{\link{dbGetInfo}(res)}. } \seealso{ Other DBIResult generics: \code{\link{dbClearResult}}; \code{\link{dbColumnInfo}}; \code{\link{dbFetch}}, \code{\link{dbFetch,DBIResult-method}}, \code{\link{fetch}}; \code{\link{dbGetRowCount}}, \code{\link{dbGetRowCount,DBIResult-method}}; \code{\link{dbGetRowsAffected}}, \code{\link{dbGetRowsAffected,DBIResult-method}}; \code{\link{dbHasCompleted}}, \code{\link{dbHasCompleted,DBIResult-method}} } DBI/man/dbDisconnect.Rd0000644000176000001440000000176612400165462014353 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbDisconnect} \alias{dbDisconnect} \title{Disconnect (close) a connection} \usage{ dbDisconnect(conn, ...) } \arguments{ \item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by \code{\link{dbConnect}}.} \item{...}{Other parameters passed on to methods.} } \value{ a logical vector of length 1, indicating success or failure. } \description{ This closes the connection, discards all pending work, and frees resources (e.g., memory, sockets). } \examples{ if (require("RSQLite")) { con <- dbConnect(RSQLite::SQLite(), ":memory:") dbDisconnect(con) } } \seealso{ Other connection methods: \code{\link{dbExistsTable}}; \code{\link{dbGetException}}; \code{\link{dbGetQuery}}, \code{\link{dbGetQuery,DBIConnection,character-method}}; \code{\link{dbListFields}}; \code{\link{dbListResults}}; \code{\link{dbListTables}}; \code{\link{dbReadTable}}, \code{\link{dbWriteTable}}; \code{\link{dbRemoveTable}}; \code{\link{dbSendQuery}} } DBI/man/SQL.Rd0000644000176000001440000000445412400165462012410 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \docType{class} \name{SQL} \alias{SQL} \alias{SQL-class} \alias{dbQuoteIdentifier} \alias{dbQuoteIdentifier,DBIConnection,SQL-method} \alias{dbQuoteIdentifier,DBIConnection,character-method} \alias{dbQuoteString} \alias{dbQuoteString,DBIConnection,SQL-method} \alias{dbQuoteString,DBIConnection,character-method} \alias{show,SQL-method} \title{SQL quoting.} \usage{ SQL(x) dbQuoteIdentifier(conn, x, ...) dbQuoteString(conn, x, ...) } \arguments{ \item{x}{A character vector to label as being escaped SQL.} \item{conn}{A subclass of \code{\linkS4class{DBIConnection}}, representing an active connection to an DBMS.} \item{...}{Other arguments passed on to methods. Not otherwise used.} } \description{ This set of classes and generics make it possible to flexibly deal with SQL escaping needs. By default, any user supplied input to a query should be escaped using either \code{dbQuoteIdentifier} or \code{dbQuoteString} depending on whether it refers to a table or variable name, or is a literal string. } \details{ The SQL class has associated \code{SQL()} constructor function. This class is used to prevent double escaping of SQL strings, and to make it possible to tell DBI functions that you've done the escaping yourself. } \section{Implementation notes}{ DBI provides default methods for SQL-92 compatible quoting. If the database uses a different convention, you will need to provide your own methods. Note that because of the way that S4 dispatch finds methods and because SQL inherits from character, if you implement (e.g.) a method for \code{dbQuoteString(MyConnection, character)}, you will also need to implement \code{dbQuoteString(MyConnection, SQL)} - this should simply return \code{x} unchanged. } \examples{ # Create a subclass of DBI connection since it's virtual MockConnection <- setClass("MockConnection", "DBIConnection") conn <- MockConnection() # Quoting ensures that arbitrary input is safe for use in a query name <- "Robert'); DROP TABLE Students;--" dbQuoteString(conn, name) dbQuoteIdentifier(conn, name) # SQL vectors are always passed through as is var_name <- SQL("select") var_name dbQuoteIdentifier(conn, var_name) dbQuoteString(conn, var_name) # This mechanism is used to prevent double escaping dbQuoteString(conn, dbQuoteString(conn, name)) } DBI/man/dbGetDBIVersion.Rd0000644000176000001440000000041012400165462014647 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbGetDBIVersion} \alias{dbGetDBIVersion} \title{Determine the current version of the package.} \usage{ dbGetDBIVersion() } \description{ Determine the current version of the package. } \keyword{internal} DBI/man/transactions.Rd0000644000176000001440000000207312400165462014454 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{transactions} \alias{dbBegin} \alias{dbCommit} \alias{dbRollback} \alias{transactions} \title{Begin/commit/rollback SQL transactions} \usage{ dbBegin(conn, ...) dbCommit(conn, ...) dbRollback(conn, ...) } \arguments{ \item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by \code{\link{dbConnect}}.} \item{...}{Other parameters passed on to methods.} } \value{ a logical indicating whether the operation succeeded or not. } \description{ Not all database engines implement transaction management, in which case these methods should not be implemented for the specific \code{\linkS4class{DBIConnection}} subclass. } \section{Side Effects}{ The current transaction on the connections \code{con} is committed or rolled back. } \examples{ \dontrun{ ora <- dbDriver("Oracle") con <- dbConnect(ora) rs <- dbSendQuery(con, "delete * from PURGE as p where p.wavelength<0.03") if(dbGetInfo(rs, what = "rowsAffected") > 250){ warning("dubious deletion -- rolling back transaction") dbRollback(con) } } } DBI/man/dbDataType.Rd0000644000176000001440000000304312400165462013763 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbDataType} \alias{dbDataType} \alias{dbDataType,DBIObject-method} \title{Determine the SQL data type of an object.} \usage{ dbDataType(dbObj, obj, ...) } \arguments{ \item{dbObj}{A object inheriting from \code{\linkS4class{DBIDriver}}} \item{obj}{An R object whose SQL type we want to determine.} \item{...}{Other arguments passed on to methods.} } \value{ A character string specifying the SQL data type for \code{obj}. } \description{ This is a generic function. The default method determines the SQL type of an R object according to the SQL 92 specification, which may serve as a starting point for driver implementations. The default method also provides a method for data.frame which will return a character vector giving the type for each column in the dataframe. } \details{ The data types supported by databases are different than the data types in R, but the mapping between the primitve types is straightforward: Any of the many fixed and varying length character types are mapped to character vectors. Fixed-precision (non-IEEE) numbers are mapped into either numeric or integer vectors. Notice that many DBMS do not follow IEEE arithmetic, so there are potential problems with under/overflows and loss of precision. } \examples{ if (require("RSQLite")) { con <- dbConnect(RSQLite::SQLite(), ":memory:") dbDataType(con, 1:5) dbDataType(con, 1L) dbDataType(con, TRUE) dbDataType(con, c("x", "abc")) dbDataType(con, mtcars) } } \seealso{ \code{\link{isSQLKeyword}} \code{\link{make.db.names}} } DBI/man/dbClearResult.Rd0000644000176000001440000000207512400165462014501 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbClearResult} \alias{dbClearResult} \title{Clear a result set.} \usage{ dbClearResult(res, ...) } \arguments{ \item{res}{An object inheriting from \code{\linkS4class{DBIResult}}.} \item{...}{Other arguments passed on to methods.} } \value{ a logical indicating whether clearing the result set was successful or not. } \description{ Frees all resources (local and remote) associated with a result set. It some cases (e.g., very large result sets) this can be a critical step to avoid exhausting resources (memory, file descriptors, etc.) } \seealso{ Other DBIResult generics: \code{\link{dbColumnInfo}}; \code{\link{dbFetch}}, \code{\link{dbFetch,DBIResult-method}}, \code{\link{fetch}}; \code{\link{dbGetRowCount}}, \code{\link{dbGetRowCount,DBIResult-method}}; \code{\link{dbGetRowsAffected}}, \code{\link{dbGetRowsAffected,DBIResult-method}}; \code{\link{dbGetStatement}}, \code{\link{dbGetStatement,DBIResult-method}}; \code{\link{dbHasCompleted}}, \code{\link{dbHasCompleted,DBIResult-method}} } DBI/man/dbGetRowCount.Rd0000644000176000001440000000164012400165462014471 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbGetRowCount} \alias{dbGetRowCount} \alias{dbGetRowCount,DBIResult-method} \title{The number of rows fetched so far.} \usage{ dbGetRowCount(res, ...) } \arguments{ \item{res}{An object inheriting from \code{\linkS4class{DBIResult}}.} \item{...}{Other arguments passed on to methods.} } \value{ a numeric vector of length 1 } \description{ The default method extracts \code{row.count} from the result of \code{\link{dbGetInfo}(res)}. } \seealso{ Other DBIResult generics: \code{\link{dbClearResult}}; \code{\link{dbColumnInfo}}; \code{\link{dbFetch}}, \code{\link{dbFetch,DBIResult-method}}, \code{\link{fetch}}; \code{\link{dbGetRowsAffected}}, \code{\link{dbGetRowsAffected,DBIResult-method}}; \code{\link{dbGetStatement}}, \code{\link{dbGetStatement,DBIResult-method}}; \code{\link{dbHasCompleted}}, \code{\link{dbHasCompleted,DBIResult-method}} } DBI/man/dbReadTable.Rd0000644000176000001440000000266712400165462014106 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbReadTable} \alias{dbReadTable} \alias{dbWriteTable} \title{Copy data frames to and from database tables.} \usage{ dbReadTable(conn, name, ...) dbWriteTable(conn, name, value, ...) } \arguments{ \item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by \code{\link{dbConnect}}.} \item{name}{A character string specifying a DBMS table name.} \item{...}{Other parameters passed on to methods.} \item{value}{a data.frame (or coercible to data.frame).} } \value{ a data.frame. } \description{ \code{dbReadTable}: database table -> data frame; \code{dbWriteTable}: data frame -> database table. } \note{ The translation of identifiers between R and SQL is done through calls to \code{\link{make.names}} and \code{\link{make.db.names}}, but we cannot guarantee that the conversion is reversible. For details see \code{\link{make.db.names}}. } \examples{ if (require("RSQLite")) { con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars[1:10, ]) dbReadTable(con, "mtcars") dbDisconnect(con) } } \seealso{ Other connection methods: \code{\link{dbDisconnect}}; \code{\link{dbExistsTable}}; \code{\link{dbGetException}}; \code{\link{dbGetQuery}}, \code{\link{dbGetQuery,DBIConnection,character-method}}; \code{\link{dbListFields}}; \code{\link{dbListResults}}; \code{\link{dbListTables}}; \code{\link{dbRemoveTable}}; \code{\link{dbSendQuery}} } DBI/man/dbCallProc.Rd0000644000176000001440000000056212400165462013752 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbCallProc} \alias{dbCallProc} \title{Call an SQL stored procedure} \usage{ dbCallProc(conn, ...) } \arguments{ \item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by \code{\link{dbConnect}}.} \item{...}{Other parameters passed on to methods.} } \description{ DEPRECATED } \keyword{internal} DBI/man/dbSetDataMappings.Rd0000644000176000001440000000160412400165462015275 0ustar ripleyusers% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbSetDataMappings} \alias{dbSetDataMappings} \title{Set data mappings between an DBMS and R.} \usage{ dbSetDataMappings(res, flds, ...) } \arguments{ \item{res}{An object inheriting from \code{\linkS4class{DBIResult}}.} \item{flds}{a field description object as returned by \code{dbColumnInfo}.} \item{...}{Other arguments passed on to methods.} } \description{ This generic is deprecated since no working implementation was ever produced. } \details{ Sets one or more conversion functions to handle the translation of DBMS data types to R objects. This is only needed for non-primitive data, since all DBI drivers handle the common base types (integers, numeric, strings, etc.) The details on conversion functions (e.g., arguments, whether they can invoke initializers and/or destructors) have not been specified. } \keyword{internal} DBI/.Rinstignore0000644000176000001440000000002512134704612013201 0ustar ripleyusersinst/doc/figure1.pdf