diff -Nru dbi-0.2-7/debian/changelog dbi-0.3.1/debian/changelog --- dbi-0.2-7/debian/changelog 2014-11-05 15:02:32.000000000 +0000 +++ dbi-0.3.1/debian/changelog 2014-11-05 15:02:32.000000000 +0000 @@ -1,3 +1,20 @@ +dbi (0.3.1-1) unstable; urgency=low + + * New upstream release + + * debian/control: Set Standards-Version: to current version + + -- Dirk Eddelbuettel Sat, 27 Sep 2014 11:45:08 -0500 + +dbi (0.3.0-1) unstable; urgency=low + + * New upstream release + + * debian/control: Set Standards-Version: to current version + * debian/control: Set Build-Depends: to current R version + + -- Dirk Eddelbuettel Tue, 02 Sep 2014 16:57:24 -0500 + dbi (0.2-7-1) unstable; urgency=low * New upstream release diff -Nru dbi-0.2-7/debian/control dbi-0.3.1/debian/control --- dbi-0.2-7/debian/control 2014-11-05 15:02:32.000000000 +0000 +++ dbi-0.3.1/debian/control 2014-11-05 15:02:32.000000000 +0000 @@ -2,8 +2,8 @@ Section: gnu-r Priority: optional Maintainer: Dirk Eddelbuettel -Build-Depends: debhelper (>= 7.0.0), cdbs, r-base-dev (>= 3.0.0) -Standards-Version: 3.9.4 +Build-Depends: debhelper (>= 7.0.0), cdbs, r-base-dev (>= 3.1.1) +Standards-Version: 3.9.6 Homepage: http://stat.bell-labs.com/RS-DBI Package: r-cran-dbi diff -Nru dbi-0.2-7/DESCRIPTION dbi-0.3.1/DESCRIPTION --- dbi-0.2-7/DESCRIPTION 2013-05-09 10:09:19.000000000 +0000 +++ dbi-0.3.1/DESCRIPTION 2014-09-24 05:27:12.000000000 +0000 @@ -1,18 +1,20 @@ Package: DBI -Version: 0.2-7 -Date: 2013-05-08 +Version: 0.3.1 Title: R Database Interface Author: R Special Interest Group on Databases (R-SIG-DB) -Maintainer: David A. James +Maintainer: Hadley Wickham Depends: R (>= 2.15.0), methods -Imports: 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. + 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) -Collate: DBI.R Util.R zzz.R +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 -Packaged: 2013-05-08 23:44:25 UTC; jamesda4 Repository: CRAN -Date/Publication: 2013-05-09 12:09:19 +Date/Publication: 2014-09-24 07:27:12 diff -Nru dbi-0.2-7/inst/doc/biblio.bib dbi-0.3.1/inst/doc/biblio.bib --- dbi-0.2-7/inst/doc/biblio.bib 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/inst/doc/biblio.bib 1970-01-01 00:00:00.000000000 +0000 @@ -1,132 +0,0 @@ -@manual{r-data-imp:2001, - author = {R Development Core Team}, - title = {R Data Import/Export}, - year = {2001}, - address = {\url{http://www.r-project.org}} -} - -@manual{mysql:2000, - author = "Axmark, David and Widenius, Michael and Cole, Jeremy and DuBois, Paul", - title = {MySQL Reference Manual}, - year = {2001}, - address = {\url{http://www.mysql.com/documentation/mysql}} -} - -@manual{jdbc:2000, - author = "Ellis, Jon and Ho, Linda and Fisher, Maydene", - title = {JDBC 3.0 Specification}, - organization = {Sun Microsystems, Inc}, - year = {2000}, - address = {\url{http://java.sun.com/Download4}} -} - - -@article{using-data:2001, - author = "Ripley, Brian D.", - title = {Using Databases with {R}}, - journal = {R {N}ews}, - year = {2001}, - month = {January}, - volume = {1}, - number = {1}, - pages = {18--20}, - address = {\url{http://www.r-project.org/doc/Rnews/}} -} - - -@Manual{odbc:2001, - title = {Microsoft {ODBC}}, - organization = {Microsoft Inc}, - address = {\url{http://www.microsoft.com/data/odbc/}}, - year = 2001 -} - - -@Book{PerlDBI:2000, - author = "Descartes, Alligator and Bunce, Tim", - title = {Programming the {P}erl {DBI}}, - publisher = {O'Reilly}, - year = 2000 -} - -@Book{Reese:2000, - author = "Reese, George", - title = {Database Programming with {JDBC} and {J}ava}, - publisher = {O'Reilly}, - year = 2000, - edition = {second} -} - -@book{Xopen-sql, - author = {X/Open Company Ltd.}, - title = {X/Open SQL and RDA Specification}, - publisher = {X/Open Company Ltd.}, - year = 1994 -} -@book{mysql-dubois, - author = "DuBois, Paul", - title = {MySQL}, - publisher = {New Riders}, - year = 2000 -} - -@techreport{data-management:1991, - author = "Chambers, John M.", - title = {Data Management in {S}}, - institution = {Bell Labs, Lucent Technologies}, - address = {\url{http://stat.bell-labs.com/stat/doc}}, - year = 1991 -} - -@techreport{database-classes:1999, - author = "Chambers, John M.", - title = {Database Classes}, - institution = {Bell Labs, Lucent Technologies}, - address = {\url{http://stat.bell-labs.com/stat/Sbook}}, - year = 1998 -} - -@inproceedings{R-dcom, - author = "Neuwirth, Erich and Baier, Thomas", - title = {Embedding {R} in Standard Software, and the other way around}, - organization = {Vienna University of Technology}, - year = 2001, - booktitle = {Proceedings of the Distributed Statistical Computing 2001 Workshop}, - address = {\url{http://www.ci.tuwien.ac.at/Conferences/DSC-2001}} -} - -@inproceedings{R-tcltk, - author = "Dalgaard, Peter", - title = {The {R}-{T}cl/{T}k Interface}, - organization = {Vienna University of Technology}, - year = 2001, - booktitle = {Proceedings of the Distributed Statistical Computing 2001 Workshop}, - address = {\url{http://www.ci.tuwien.ac.at/Conferences/DSC-2001}} -} - -@inproceedings{duncan-dsc2001, - author = "Temple Lang, Duncan", - title = {Embedding {S} in Other Languages and Environments}, - organization = {Vienna University of Technology}, - year = 2001, - booktitle = {Proceedings of the Distributed Statistical Computing 2001 Workshop}, - address = {\url{http://www.ci.tuwien.ac.at/Conferences/DSC-2001}} -} - -@inproceedings{BDR-RMR, - author = "Ripley, B. D. and Ripley, R. M.", - title = {Applications of {R} Clients and Servers}, - organization = {Vienna University of Technology}, - year = 2001, - booktitle = {Proceedings of the Distributed Statistical Computing 2001 Workshop}, - address = {\url{http://www.ci.tuwien.ac.at/Conferences/DSC-2001}} -} -@inproceedings{rsdbi-dsc2001, - author = "Hothorn, Torsten and James, David A. and Ripley, Brian D.", - title = {{R}/{S} Interfaces to Databases}, - organization = {Vienna University of Technology}, - year = 2001, - booktitle = {Proceedings of the Distributed Statistical Computing 2001 Workshop}, - address = {\url{http://www.ci.tuwien.ac.at/Conferences/DSC-2001}} -} - Binary files /tmp/2p_FQxGSBy/dbi-0.2-7/inst/doc/DBI.pdf and /tmp/WOHtpBDh7F/dbi-0.3.1/inst/doc/DBI.pdf differ diff -Nru dbi-0.2-7/inst/doc/DBI.R dbi-0.3.1/inst/doc/DBI.R --- dbi-0.2-7/inst/doc/DBI.R 2013-05-08 23:44:25.000000000 +0000 +++ dbi-0.3.1/inst/doc/DBI.R 1970-01-01 00:00:00.000000000 +0000 @@ -1,2 +0,0 @@ -### R code from vignette source 'DBI.Rnw' - diff -Nru dbi-0.2-7/inst/doc/DBI.Rnw dbi-0.3.1/inst/doc/DBI.Rnw --- dbi-0.2-7/inst/doc/DBI.Rnw 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/inst/doc/DBI.Rnw 1970-01-01 00:00:00.000000000 +0000 @@ -1,681 +0,0 @@ -% -% NOTE -- ONLY EDIT THE .Rnw FILE!!! The .tex file is -% likely to be overwritten. -% -%\VignetteIndexEntry{A Common Database Interface (DBI)} -%\VignetteDepends{} -%\VignetteKeywords{Databases, Relational DBMS, MySQL, SQLite, Oracle, PostgreSQL} -%\VignettePackage{DBI} -\documentclass{article} -% $Id$ - -\usepackage{graphicx,times} -\usepackage[% - bookmarks=true, - colorlinks=true, - backref=true, - hyperfigures=true, - pdfpagemode=UseOutlines, - pdfauthor={R-Databases Special Interest Group (R-SIG-DB)}, - pdftitle={A Common Database Interface (DBI)}, - pdfkeywords={Databases, Relational DBMS, R, S-Plus, - PostgreSQL, MySQL, mSQL, Microsoft SQL Server, - Oracle, SQLite, Inter-system communications, - Distributed computing} -]{hyperref} - -% R/S related commands -\newcommand{\sfun}[1]{\mbox{\tt #1()}} % print arg as an R/S fun() -\newcommand{\sobj}[1]{\mbox{\tt #1}} % print arg as an R/S object -\newcommand{\sexp}[1]{\mbox{\tt #1}} % print arg as an R/S expression -\newcommand{\sclass}[1]{\mbox{\tt #1}} % print arg as an R/S class -\newcommand{\smethod}[1]{\mbox{\tt #1}} % print arg as an R/S method -\begin{document} - -\title{A Common Database Interface (DBI)} -\author{ -R-Databases Special Interest Group\\ -\href{mailto:r-sig-db@stat.math.ethz.ch}{r-sig-db@stat.math.ethz.ch} -} - -\date{26 August 2002 (Updated 16 June 2003)} - -\maketitle -\tableofcontents - -\begin{abstract} -This document describes a common interface between the S language -(in its R and S-Plus implementations) and database management systems -(DBMS). The interface defines a small set of classes and methods -similar in spirit to Perl's DBI, Java's JDBC, Python's DB-API, -and Microsoft's ODBC. -\end{abstract} - -\section{Version}\label{sec:version} -This document describes version 0.1-6 of the database interface -API (application programming interface). - -\section{Introduction}\label{sec:intro} - -The database interface (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 DBMS (Oracle, PostgreSQL, etc.) are provided by ``device -drivers'' that get invoked automatically by the S language evaluator. -The following example illustrates some of the DBI capabilities: -\begin{verbatim} -## Choose the proper DBMS driver and connect to the server - -drv <- dbDriver("ODBC") -con <- dbConnect(drv, "dsn", "usr", "pwd") - -## The interface can work at a higher level importing tables -## as data.frames and exporting data.frames as DBMS tables. - -dbListTables(con) -dbListFields(con, "quakes") -if(dbExistsTable(con, "new_results")) - dbRemoveTable(con, "new_results") -dbWriteTable(con, "new_results", new.output) - -## The interface allows lower-level interface to the DBMS -res <- dbSendQuery(con, paste( - "SELECT g.id, g.mirror, g.diam, e.voltage", - "FROM geom_table as g, elec_measures as e", - "WHERE g.id = e.id and g.mirrortype = 'inside'", - "ORDER BY g.diam")) -out <- NULL -while(!dbHasCompleted(res)){ - chunk <- fetch(res, n = 10000) - out <- c(out, doit(chunk)) -} - -## Free up resources -dbClearResult(res) -dbDisconnect(con) -dbUnloadDriver(drv) -\end{verbatim} -(only the first 2 expressions are DBMS-specific -- all others are -independent of the database engine itself). - -Individual DBI drivers need not implement all the features we -list below (we indicate those that are optional). Furthermore, -drivers may extend the core DBI facilities, but we suggest to have -these extensions clearly indicated and documented. - -The following are the elements of the DBI: -\begin{enumerate} -\item A set of classes and methods (Section~\ref{sec:DBIClasses}) - that defines what operations are possible and how they are defined, - e.g.: - \begin{itemize} - \item connect/disconnect to the DBMS - \item create and execute statements in the DBMS - \item extract results/output from statements - \item error/exception handling - \item information (meta-data) from database objects - \item transaction management (optional) - \end{itemize} - - Some things are left explicitly unspecified, e.g., authentication - and even the query language, although it is hard to avoid references - to SQL and relational database management systems (RDBMS). - -\item Drivers - - Drivers are collection of functions that implement the functionality - defined above in the context of specific DBMS, e.g., mSQL, Informix. - -\item Data type mappings (Section~\ref{sec:data-mappings}.) - - Mappings and conversions between DBMS data types and R/S objects. - All drivers should implement the ``basic'' primitives (see below), - but may chose to add user-defined conversion function to handle - more generic objects (e.g., factors, ordered factors, time series, - arrays, images). - -\item Utilities (Section~\ref{sec:utilities}.) - - These facilities help with details such as mapping of identifiers - between S and DBMS (e.g., \texttt{"\_"} is illegal in R/S - names, and \texttt{"."} is used for constructing compound SQL - identifiers), etc. - -\end{enumerate} - -\section{DBI Classes and Methods}\label{sec:DBIClasses} -The following are the main DBI classes. They need to be extended -by individual database back-ends (Sybase, Oracle, etc.) Individual -drivers need to provide methods for the generic functions listed here -(those methods that are optional are so indicated). - -\emph{Note: Although R releases prior to 1.4 do not have a formal -concept of classes, we will use the syntax of the S Version -4 classes and methods (available in R releases 1.4 and later as -library \sobj{methods}) to convey precisely the DBI class hierarchy, -its methods, and intended behavior. -} - -The DBI classes are \sclass{DBIObject}, \sclass{DBIDriver}, -\sclass{DBIConnection} and \sclass{DBIResult}. All these are -\emph{virtual} classes. Drivers define new classes that extend -these, e.g., \sclass{PgSQLDriver}, \sclass{PgSQLConnection}, and -so on. -\begin{figure} -\includegraphics[width=\textwidth]{figure1} -\caption{Class hierarchy for the DBI. The top two layers -are comprised of virtual classes and each lower layer represents -a set of driver-specific implementation classes that provide -the functionality defined by the virtual classes above.} -\end{figure} -\begin{description} -\item[\sclass{DBIObject}:] - Virtual class\footnote{A virtual class allows us to group - classes that share some common characteristics, even if their - implementations are radically different.} that groups all other - DBI classes. - -\item[\sclass{DBIDriver}:] - Virtual class that groups all DBMS drivers. Each DBMS driver - extends this class. Typically generator functions instantiate - the actual driver objects, e.g., \sfun{PgSQL}, \sfun{HDF5}, - \sfun{BerkeleyDB}. - -\item[\sclass{DBIConnection}:] - Virtual class that encapsulates connections to DBMS. - -\item[\sclass{DBIResult}:] - Virtual class that describes the result of a DBMS query or statement. - - [Q: Should we distinguish between a simple result of DBMS statements - e.g., as \texttt{delete} from DBMS queries (i.e., those that generate - data).] - -\end{description} - -The methods \smethod{format}, \smethod{print}, \smethod{show}, -\smethod{dbGetInfo}, and \smethod{summary} -are defined (and \emph{implemented} in the \sobj{DBI} package) -for the \sclass{DBIObject} base class, thus available to all -implementations; individual drivers, however, are free to override -them as they see fit. -\begin{description} -\item[\smethod{format(x, ...)}:] - produces a concise character representation (label) for the - \sclass{DBIObject} \sobj{x}. - -\item[\smethod{print(x, ...)}/\smethod{show(x)}:] - prints a one-line identification of the object \sobj{x}. - -\item[\smethod{summary(object, ...)}:] - produces a concise description of the object. - The default method for \sclass{DBIObject} simply - invokes \sexp{dbGetInfo(dbObj)} and prints the name-value - pairs one per line. Individual implementations may tailor - this appropriately. - -\item[\smethod{dbGetInfo(dbObj, ...)}:] - extracts information (meta-data) relevant for the - \sclass{DBIObject} \sobj{dbObj}. It may return a list - of key/value pairs, individual meta-data if supplied - in the call, or \sobj{NULL} if the requested meta-data - is not available. - - \emph{Hint:} Driver implementations may choose to allow an - argument \sobj{what} to specify individual meta-data, e.g., - \sexp{dbGetInfo(drv, what = "max.connections")}. - -\end{description} - -In the next few sub-sections we describe in detail each of these -classes and their methods. - -\subsection{Class \sclass{DBIObject}}\label{sec:DBIObject} -This class simply groups all DBI classes, and thus all extend it. - -\subsection{Class \sclass{DBIDriver}}\label{sec:DBIDriver} -This class identifies the database management system. It needs to -be extended by individual back-ends (Oracle, PostgreSQL, etc.) - -The DBI provides the generator \sexp{dbDriver("driverName")} -which simply invokes the function \sfun{driverName}, which -in turn instantiates the corresponding driver object. - -The \sclass{DBIDriver} class defines the following methods: -\begin{description} - -\item[\sfun{driverName}:]\label{meth:driverName} - initializes the driver code. The name \sobj{driverName} refers to - the actual generator function for the DBMS, e.g., \sfun{RPgSQL}, - \sfun{RODBC}, \sfun{HDF5}. The driver instance object is used - with \smethod{dbConnect} (see page~\pageref{meth:dbConnect}) - for opening one or possibly more connections to one or more DBMS. - -\item[\smethod{dbListConnections(drv, ...)}:] - list of current connections being handled by the \sobj{drv} - driver. May be \sobj{NULL} if there are no open connections. - Drivers that do not support multiple connections may return the - one open connection. - -\item[\smethod{dbGetInfo(dbObj, ...)}:] - returns a list of name-value pairs of information about the - driver. - - \emph{Hint:} Useful entries could include - \begin{description} - \item[\sobj{name}:] the driver name (e.g., \sexp{"RODBC"}, \sexp{"RPgSQL"}); - \item[\sobj{driver.version}:] version of the driver; - \item[\sobj{DBI.version}:] the version of the DBI that the driver - implements, e.g., \sexp{"0.1-2"}; - \item[\sobj{client.version}:] of the client DBMS libraries (e.g., version - of the \texttt{libpq} library in the case of \sobj{RPgSQL}); - \item[\sobj{max.connections}:] maximum number of simultaneous - connections; - \end{description} - plus any other relevant information about the implementation, for instance, - how the driver handles upper/lower case in identifiers. - -\item[\smethod{dbUnloadDriver("driverName")} (optional):] - frees all resources (local and remote) used by the driver. - Returns a logical to indicate if it succeeded or not. - -\end{description} - -\subsection{Class \sclass{DBIConnection}}\label{sec:DBIConnection} -This virtual class encapsulates the connection to a DBMS, and -it provides access to dynamic queries, result sets, DBMS session -management (transactions), etc. - -\emph{Note:} Individual drivers are free to implement single or -multiple simultaneous connections. - -The methods defined by the \sclass{DBIConnection} class include: -\begin{description} -\item[\smethod{dbConnect(drv, ...)}:]\label{meth:dbConnect} - creates and opens a connection to the database implemented by the - driver \sobj{drv} (see Section~\ref{sec:DBIDriver}). Each driver will - define what other arguments are required, e.g., \sobj{"dbname"} or - \sobj{"dsn"} for the database name, \sobj{"user"}, and \sobj{"password"}. - It returns an object that extends \sclass{DBIConnection} in a - driver-specific manner (e.g., the MySQL implementation could - create an object of class \sclass{MySQLConnection} that extends - \sclass{DBIConnection}). - -\item[\smethod{dbDisconnect(conn, ...)}:] - closes the connection, discards all pending work, and frees - resources (e.g., memory, sockets). Returns a logical indicating - whether it succeeded or not. - -\item[\smethod{dbSendQuery(conn, statement, ...)}:] - submits one statement to the DBMS. It returns a \sclass{DBIResult} - object. This object is needed for fetching data in case - the statement generates output (see \smethod{fetch} on - page~\pageref{meth:fetch}), and it may be used for querying the - state of the operation; see \smethod{dbGetInfo} and other - meta-data methods on page~\pageref{meth:res-others}. - -\item[\smethod{dbGetQuery(conn, statement, ...)}:] - submit, execute, and extract output in one operation. - The resulting object may be a \sclass{data.frame} if - the \sobj{statement} generates output. Otherwise the - return value should be a logical indicating whether - the query succeeded or not. - -\item[\smethod{dbGetException(conn, ...)}:] - returns a list with elements \sobj{errNum} and \sobj{errMsg} - with the status of the last DBMS statement sent on a given - connection (this information may also be provided by the - \sfun{dbGetInfo} meta-data function on the \sobj{conn} object. - - \emph{Hint:} The ANSI SQL-92 defines both a status code and an - status message that could be return as members of the list. - -\item[\smethod{dbGetInfo(dbObj, ...)}:] - returns a list of name-value pairs describing the state of the - connection; it may return one or more meta-data, the actual driver - method allows to specify individual pieces of meta-data (e.g., - maximum number of open results/cursors). - - \emph{Hint:} Useful entries could include - \begin{description} - \item[\sobj{dbname}:] the name of the database in use; - \item[\sobj{db.version}:] the DBMS server version (e.g., - "Oracle 8.1.7 on Solaris"; - \item[\sobj{host}:] host where the database server resides; - \item[\sobj{user}:] user name; - \item[\sobj{password}:] password (is this safe?); - \end{description} - plus any other arguments related to the connection (e.g., thread id, - socket or TCP connection type). - -\item[\smethod{dbListResults(conn, ...)}:] - list of \sobj{DBIResult} objects currently active on the connection - \sobj{conn}. May be \sobj{NULL} if no result set is active - on \sobj{conn}. Drivers that implement only one result set per - connection could return that one object (no need to wrap it in - a list). - -\end{description} - -\emph{Note: The following are convenience methods that simplify - the import/export of (mainly) data.frames. The first five - methods implement the core methods needed to \sfun{attach} - remote DBMS to the S search path. (For details, see - \cite{data-management:1991,database-classes:1999}.) -} - -\emph{Hint:} For relational DBMS these methods may be easily implemented - using the core DBI methods \smethod{dbConnect}, \smethod{dbSendQuery}, - and \smethod{fetch}, due to SQL reflectance (i.e., one easily gets - this meta-data by querying the appropriate tables on the RDBMS). - -\begin{description} -\item[\smethod{dbListTables(conn, ...)}:] - returns a character vector (possibly of zero-length) of object (table) - names available on the \sobj{conn} connection. - -\item[\smethod{dbReadTable(conn, name, ...)}:] - imports the data stored remotely in the table \sobj{name} - on connection \sobj{conn}. Use the field \sobj{row.names} - as the \sexp{row.names} attribute of the output data.frame. - Returns a \sclass{data.frame}. - - [Q: should we spell out how row.names should be created? E.g., - use a field (with unique values) as row.names? Also, should - \smethod{dbReadTable} reproduce a data.frame exported with - \smethod{dbWriteTable}?] - -\item[\smethod{dbWriteTable(conn, name, value, ...)}:] - write the object \sobj{value} (perhaps after coercing it to - data.frame) into the remote object \sobj{name} in connection - \sobj{conn}. Returns a logical indicating whether the operation - succeeded or not. - -\item[\smethod{dbExistsTable(conn, name, ...)}:] - does remote object \sobj{name} exist on \sobj{conn}? - Returns a logical. - -\item[\smethod{dbRemoveTable(conn, name, ...)}:] - removes remote object \sobj{name} on connection \sobj{conn}. - Returns a logical indicating whether the operation succeeded or not. - -\item[\smethod{dbListFields(conn, name, ...)}:] returns a character vector -listing the field names of the remote table \sobj{name} on connection -\sobj{conn} (see \smethod{dbColumnInfo()} for extracting data type -on a table). - -\end{description} - -\emph{Note: The following methods deal with transactions and - stored procedures. All these functions are optional. -} -\begin{description} -\item[\smethod{dbCommit(conn, ...)}(optional):] - commits pending transaction on the connection and returns - \sobj{TRUE} or \sobj{FALSE} depending on whether the operation - succeeded or not. - -\item[\smethod{dbRollback(conn, ...)}(optional):] - undoes current transaction on the connection and returns - \sobj{TRUE} or \sobj{FALSE} depending on whether the operation - succeeded or not. - -\item[\smethod{dbCallProc(conn, storedProc, ...)}(optional):] - invokes a stored procedure in the DBMS and returns a \sclass{DBIResult} - object. - - [Stored procedures are \emph{not} part of the ANSI SQL-92 standard and - vary substantially from one RDBMS to another.] - -\end{description} - -\subsection{Class \sclass{DBIResult}}\label{sec:DBIResult} - -This virtual class describes the result and state of execution of -a DBMS statement (any statement, query or non-query). The result set -\sobj{res} keeps track of whether the statement produces output -for R/S, 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. - -\emph{Note: Individual drivers are free to allow single or multiple -active results per connection. -} - -[Q: Should we distinguish between results that return no data from those -that return data?] - -The class \sclass{DBIResult} defines the following methods: -\begin{description} -\item[\smethod{fetch(res, n, ...)}:]\label{meth:fetch} - fetches the next \sobj{n} elements (rows) from the result set - \sobj{res} and return them as a data.frame. A value of \sexp{n=-1} - is interpreted as ``return all elements/rows''. - -\item[\smethod{dbClearResult(res, ...)}:] - flushes any pending data and frees all resources (local and - remote) used by the object \sobj{res} on both sides of the - connection. Returns a logical indicating success or not. - -\item[\smethod{dbGetInfo(dbObj, ...)}:] - returns a name-value list with the state of the result set. - - \emph{Hint:} Useful entries could include - \begin{description} - \item[\sobj{statement}:] a character string representation of the - statement being executed; - \item[\sobj{rows.affected}:] number of affected records (changed, - deleted, inserted, or extracted); - \item[\sobj{row.count}:] number of rows fetched so far; - \item[\sobj{has.completed}:] has the statement (query) finished? - \item[\sobj{is.select}:] a logical describing whether or not the - statement generates output; - \end{description} - plus any other relevant driver-specific meta-data. - -\item[\smethod{dbColumnInfo(res, ...)}:] - 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.) - - \emph{Hint:} The data.frame columns could include - \begin{description} - \item[\sobj{field.name}:] DBMS field label; - \item[\sobj{field.type}:] DBMS field type (implementation-specific); - \item[\sobj{data.type}:] corresponding R/S data type, e.g., - \sexp{"integer"}; - \item[\sobj{precision}/\sobj{scale}:] (as in ODBC terminology), - display width and number of decimal digits, respectively; - \item[\sobj{nullable}:] whether the corresponding field may contain - (DBMS) \texttt{NULL} values; - \end{description} - plus other driver-specific information. - -\item[\smethod{dbSetDataMappings(flds, ...)}(optional):] - defines a conversion between internal DBMS data types - and R/S classes. We expect the default mappings (see - Section~\ref{sec:data-mappings}) to be by far the most - common ones, but users that need more control may specify - a class generator for individual fields in the result set. - [This topic needs further discussion.] - -\end{description} - -\emph{Note: The following are convenience methods that extract -information from the result object (they may be implemented -by invoking \sfun{dbGetInfo} with appropriate arguments). -} - -\begin{description}\label{meth:res-others} -\item[\smethod{dbGetStatement(res, ...)}(optional):] - returns the DBMS statement (as a character string) associated - with the result \sobj{res}. - -\item[\smethod{dbGetRowsAffected(res, ...)}(optional):] - returns the number of rows affected by the executed statement - (number of records deleted, modified, extracted, etc.) - -\item[\smethod{dbHasCompleted(res, ...)}(optional):] - returns a logical that indicates whether the operation has been - completed (e.g., are there more records to be fetched?). - -\item[\smethod{dbGetRowCount(res, ...)}(optional):] - returns the number of rows fetched so far. - -\end{description} - -\section{Data Type Mappings}\label{sec:data-mappings} -The data types supported by databases are different than the -data types in R and S, but the mapping between the ``primitive'' -types is straightforward: Any of the many fixed and varying -length character types are mapped to R/S \sobj{"character"}. -Fixed-precision (non-IEEE) numbers are mapped into either doubles -(\sobj{"numeric"}) or long (\sobj{"integer"}). Notice that many -DBMS do not follow the so-called IEEE arithmetic, so there are -potential problems with under/overflows and loss of precision, but -given the R/S primitive types we cannot do too much but identify -these situations and warn the application (how?). - -By default dates and date-time objects are mapped to character -using the appropriate \texttt{TO\_CHAR} function in the DBMS -(which should take care of any locale information). Some RDBMS -support the type \texttt{CURRENCY} or \texttt{MONEY} which should be -mapped to \sobj{"numeric"} (again with potential round off errors). -Large objects (character, binary, file, etc.) also need to be mapped. -User-defined functions may be specified to do the actual conversion -(as has been done in other inter-systems packages \footnote{ - Duncan Temple Lang has volunteered to port the data conversion - code found in R-Jave, R-Perl, and R-Python packages to the DBI}). - -Specifying user-defined conversion functions still needs to be -defined. - -\section{Utilities}\label{sec:utilities} -The core DBI implementation should make available to all -drivers some common basic utilities. For instance: -\begin{description} -\item[\smethod{dbGetDBIVersion}:] - returns the version of the currently attached DBI as a string. - -\item[\smethod{dbDataType(dbObj, obj, ...)}:] - returns a string with the (approximately) appropriate data type for - the R/S object \sobj{obj}. The DBI can implement this following - the ANSI-92 standard, but individual drivers may want/need to extend - it to make use of DBMS-specific types. - -\item[\smethod{make.db.names(dbObj, snames, ...)}:] - maps R/S names (identifiers) to SQL identifiers replacing - illegal characters (as \sobj{"."}) by the legal SQL \sobj{"\_"}. - -\item[\sobj{SQLKeywords(dbObj, ...)}:] - returns a character vector of SQL keywords (reserved words). - The default method returns the list of \sobj{.SQL92Keywords}, - but drivers should update this vector with the DBMS-specific - additional reserved words. - -\item[\smethod{isSQLKeyword(dbObj, name, ...)}:] - for each element in the character vector \sobj{name} determine - whether or not it is an SQL keyword, as reported by the - generic function \smethod{SQLKeywords}. Returns a logical vector - parallel to the input object \sobj{name}. - -\end{description} - -\section{Open Issues and Limitations}\label{sec:open-issues} -There are a number of issues and limitations that the current -DBI conscientiously does not address on the interest of simplicity. -We do list here the most important ones. -\begin{description} -\item[Non-SQL:] - Is it realistic to attempt to encompass non-relational databases, - like HDF5, Berkeley DB, etc.? - -\item[Security:] - allowing users to specify their passwords on R/S scripts may - be unacceptable for some applications. We need to consider - alternatives where users could store authentication on files - (perhaps similar to ODBC's \texttt{odbc.ini}) with more stringent - permissions. - -\item[Exceptions:] - the exception mechanism is a bit too simple, and it does not - provide for information when problems stem from the DBMS - interface itself. For instance, under/overflow or loss of - precision as we move numeric data from DBMS to the more limited - primitives in R/S. - -\item[Asynchronous communication:] - most DBMS support both synchronous and asynchronous communications, - allowing applications to submit a query and proceed while - the database server process the query. The application is then - notified (or it may need to poll the server) when the query has completed. - For large computations, this could be very useful, but the DBI - would need to specify how to interrupt the server (if necessary) - plus other details. Also, some DBMS require applications to use - threads to implement asynchronous communication, something that - neither R nor S-Plus currently addresses. - -\item[SQL scripts:] - the DBI only defines how to execute one SQL statement at a time, - forcing users to split SQL scripts into individual statements. - We need a mechanism by which users can submit SQL scripts that - could possibly generate multiple result sets; in this case we - may need to introduce new methods to loop over multiple results - (similar to Python's \texttt{nextResultSet}). - -\item[BLOBS/CLOBS:] - large objects (both character and binary) present some challenges both - to R and S-Plus. It is becoming more common to store images, sounds, - and other data types as binary objects in DBMS, some of which can - be in principle quite large. The SQL-92 ANSI standard allows up - to 2 gigabytes for some of these objects. We need to carefully - plan how to deal with binary objects. - -\item[Transactions:] - transaction management is not fully described. - -\item[Additional methods:] - Do we need any additional methods? (e.g., \sexp{dbListDatabases(conn)}, - \sexp{dbListTableIndices(conn, name)}, - how do we list all available drivers?) - -\item[Bind variables:] - the interface is heavily biased towards queries, as opposed to - general purpose database development. In particular we made - no attempt to define ``bind variables''; this is a mechanism - by which the contents of R/S objects are implicitly moved to - the database during SQL execution. For instance, the following - embedded SQL statement - -\begin{verbatim} - /* SQL */ - SELECT * from emp_table where emp_id = :sampleEmployee -\end{verbatim} - would take the vector \sobj{sampleEmployee} and iterate over each - of its elements to get the result. Perhaps the DBI could at some - point in the future implement this feature. - -\end{description} - -\section{Resources}\label{sec:resources} -The idea of a common interface to databases has been successfully -implemented in various environments, for instance: - -Java's Database Connectivity (JDBC) -(\href{http://www.javasoft.com/products/jdbc/index.html}{www.javasoft.com}). - -In C through the Open Database Connectivity (ODBC) -(\href{http://www.genix.net/unixODBC}{www.genix.net/unixODBC}). - -Python's Database Application Programming Interface -(\href{http://www.python.org/topics/database}{www.python.org}). - -Perl's Database Interface -(\href{http://dbi.perl.org}{dbi.perl.org}). - -\nocite{*} -\bibliography{biblio} -\bibliographystyle{plain} -\end{document} Binary files /tmp/2p_FQxGSBy/dbi-0.2-7/inst/doc/figure1.pdf and /tmp/WOHtpBDh7F/dbi-0.3.1/inst/doc/figure1.pdf differ diff -Nru dbi-0.2-7/inst/NEWS dbi-0.3.1/inst/NEWS --- dbi-0.2-7/inst/NEWS 2013-05-07 21:07:58.000000000 +0000 +++ dbi-0.3.1/inst/NEWS 1970-01-01 00:00:00.000000000 +0000 @@ -1,73 +0,0 @@ -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. diff -Nru dbi-0.2-7/inst/TODO dbi-0.3.1/inst/TODO --- dbi-0.2-7/inst/TODO 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/inst/TODO 1970-01-01 00:00:00.000000000 +0000 @@ -1,73 +0,0 @@ -Issues that R-SIG-DB hasn't addressed. - -1. Should we define separate classes for SQL queries that return data - from those that don't return data? E.g., the "DBIResult" could - represent the result of non-data queries (INSERT, DELETE, CREATE, - etc.) while "DBIResultSet" (or perhaps "DBICursor") could extend - "DBIResult" to represent results of queries that generate data - (primarily SELECT). - -2. (See ROracle version 0.5-3 for an initial implementation.) - Prepare statements need to be defined and methods for executing - them with S bindings. A mechanism to hook data in SQL - statements and, say, fields in data.frames needs to be defined. - Some databases' API explicitly defined these as placeholders, - e.g., ODBC identifies these as "?var" in dynamic SQL, Oracle as - ":var" --- in both of these cases "var" refers to a C variable, - possibly an array. An obvious R/S-Plus implementation would - be to interpret "?var" in SQL statements as variable "var" - in some data.frame. E.g., say, - - ps <- dbPrepare(connection =con, - statement = "select * from big_table where id = ?sample", - data = signature(sample = "numeric")) - - rs <- dbExecStatement(ps, data = mySampleIds1) # copy data to DBMS - data1 <- fetch(rs, n = -1) - rs <- dbExecStatement(ps, data = mySampleIds2) # copy more data - data2 <- fetch(rs, n = -1) - rs <- dbExecStatement(ps, data = mySampleIds3) # copy more data - data3 <- fetch(rs, n = -1) - .... - -3. Data conversion. We need a general method for specifying data - conversion. - - The data conversion mechanism used in other inter system packages - (e.g., RSPython, RSPerl) does not seem to be suitable without - modification. Those mechanism seem to be geared for converting - in one operation whole objects, while in the R/S-Plus DBMS case we - need to be able to allocate containers as columns of the R/S-Plus - result list/data.frame, and then transfer individual objects - (dates, BLOBS, CLOBS, numbers, strings) one at a time from the - DBMS into the container class inside the C fetching looping. - -4. Do we need more metadata? (e.g., table indices, privileges). - -5. (See ROracle version 0.5-3 for an initial implementation.) - Transaction management needs to be fully described. - -6. How do we run SQL scripts (not just single statements) and - stored procedures. - -7. Asynchronous operations (not only queries). Given current - limitations in both R and S-Plus implementations of S (e.g., - lack of threads), we probably should be thinking of some kind of - polling mechanism with which users specify whether an operation - should be asynchronous (say, through a flag to dbConnect, - dbSendQuery, etc.) and then define one of more methods, say, - dbHasCompleted, to poll the DBMS or driver for the status of - the operation. Another possibility could be to register S - callbacks for certain events, but it may be more complicated to - code events in the various drivers than simply poll [not if the - event identification and callback dispatching is centralized in - the RS_DBI level, above the actual R/C drivers code]. - -8. Additional helper functions. - - * dbBuildTableDefinition(con, name, obj, field.types, ....) - Then we could have methods for obj="data.frame", obj="array", etc. - By default the DBI method con=DBIObject would construct the - definition acording to the SQL92 or SQL99 standard(s), but - individual implementations could overwrite the methods. - diff -Nru dbi-0.2-7/man/dbCallProc.Rd dbi-0.3.1/man/dbCallProc.Rd --- dbi-0.2-7/man/dbCallProc.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/dbCallProc.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,31 +1,18 @@ -% $Id$ +% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbCallProc} \alias{dbCallProc} -\title{ - Call an SQL stored procedure -} -\description{ - Calls a stored procedure on a remote RDBMS -} +\title{Call an SQL stored procedure} \usage{ - dbCallProc(conn, ...) +dbCallProc(conn, ...) } \arguments{ -\item{conn}{ - a \code{DBIConnection} object. -} -\item{\dots }{ - additional arguments are passed to the implementing method. +\item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by +\code{\link{dbConnect}}.} + +\item{...}{Other parameters passed on to methods.} } +\description{ +DEPRECATED } -\details{ - Not yet implemented. -} -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. -} -\keyword{interface} -\keyword{database} -% vim: syntax=tex +\keyword{internal} + diff -Nru dbi-0.2-7/man/dbClearResult.Rd dbi-0.3.1/man/dbClearResult.Rd --- dbi-0.2-7/man/dbClearResult.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbClearResult.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,35 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbColumnInfo.Rd dbi-0.3.1/man/dbColumnInfo.Rd --- dbi-0.2-7/man/dbColumnInfo.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbColumnInfo.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,39 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbCommit.Rd dbi-0.3.1/man/dbCommit.Rd --- dbi-0.2-7/man/dbCommit.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/dbCommit.Rd 1970-01-01 00:00:00.000000000 +0000 @@ -1,63 +0,0 @@ -% $Id$ -\name{dbCommit} -\alias{dbCommit} -\alias{dbRollback} -\title{ - DBMS Transaction Management -} -\description{ - Commit/rollback SQL transactions -} -\usage{ - dbCommit(conn, ...) - dbRollback(conn, ...) -} -\arguments{ -\item{conn}{ - a \code{DBIConnection} object, as produced by the function -\code{dbConnect}. -} -\item{\dots }{ - any database-specific arguments. -} -} -\value{ - a logical indicating whether the operation succeeded or not. -} -\section{Side Effects}{ - The current transaction on the connections \code{con} - is committed or rolled back. -} -\details{ - Not all database engines implement transaction management, - older versions of MySQL, for instance. -} -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or - \url{http://developer.r-project.org/db}. -} -\seealso{ -\code{\link{dbConnect}} -\code{\link{dbSendQuery}} -\code{\link{dbGetQuery}} -\code{\link{fetch}} -\code{\link{dbCommit}} -\code{\link{dbGetInfo}} -\code{\link{dbReadTable}} -} -\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) -} -} -} -\keyword{interface} -\keyword{database} -% vim: syntax=tex diff -Nru dbi-0.2-7/man/dbConnect.Rd dbi-0.3.1/man/dbConnect.Rd --- dbi-0.2-7/man/dbConnect.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/dbConnect.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,94 +1,50 @@ -% $Id$ +% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbConnect} -\alias{dbDisconnect} \alias{dbConnect} -\title{ - Create a connection to a DBMS -} -\description{ - Connect to a DBMS going through the appropriate authorization - procedure. -} +\title{Create a connection to a DBMS.} \usage{ - dbConnect(drv, ...) - dbDisconnect(conn, ...) +dbConnect(drv, ...) } \arguments{ -\item{drv}{ - an object that inherits from \code{DBIDriver}, - a character string specifying the DBMS driver, e.g., "RPgSQL", - "ROracle", "Informix", or possibly another \code{dbConnect} object. - } -\item{conn}{ - a connection object as produced by \code{dbConnect}. - } -\item{\dots }{ - 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}. - } +\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{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. - - \code{dbDisconnect} returns a logical value indicating whether - the operation succeeded or not. +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. } -\section{Side Effects}{ - A connection between R/Splus and the database server is established, - and the R/Splus program becomes a client of the database engine. - Typically the connections is through the TCP/IP protocol, - but this will depend on vendor-specific details. +\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{ - 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. -} -\section{notes}{ - Make sure you close the connection using \code{dbDisconnect(conn)} - when it is not longer needed. -} -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. -} -\seealso{ - \code{\link{dbConnect}} - \code{\link{dbSendQuery}} - \code{\link{dbGetQuery}} - \code{\link{fetch}} - \code{\link{dbCommit}} - \code{\link{dbGetInfo}} - \code{\link{dbReadTable}} -} -\examples{\dontrun{ -# create an RODBC instance and create one connection. -m <- dbDriver("RODBC") - -# open the connection using user, passsword, etc., as -# specified in the file \file{\$HOME/.my.cnf} -con <- dbConnect(m, dsn="data.source", uid="user", pwd="password")) +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 -# Run an SQL statement by creating first a resultSet object -rs <- dbSendQuery(con, statement = paste( - "SELECT w.laser_id, w.wavelength, p.cut_off", - "FROM WL w, PURGE P", - "WHERE w.laser_id = p.laser_id", - "SORT BY w.laser_id") -# we now fetch records from the resultSet into a data.frame -data <- fetch(rs, n = -1) # extract all rows -dim(data) +dbListTables(con) +dbDisconnect(con) } } -\keyword{interface} -\keyword{database} -% vim: syntax=tex +\seealso{ +\code{\link{dbDisconnect}} to disconnect from a database. +} + diff -Nru dbi-0.2-7/man/dbDataType.Rd dbi-0.3.1/man/dbDataType.Rd --- dbi-0.2-7/man/dbDataType.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/dbDataType.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,53 +1,51 @@ -% $Id$ +% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbDataType} \alias{dbDataType} \alias{dbDataType,DBIObject-method} -\alias{dbDataType.default} -\title{ - Determine the SQL Data Type of an S object -} -\description{ - Determine an (approximately) appropriate SQL data type for an S object. -} +\title{Determine the SQL data type of an object.} \usage{ - dbDataType(dbObj, obj, ...) +dbDataType(dbObj, obj, ...) } \arguments{ -\item{dbObj}{ - a \code{DBIDriver} object, e.g., \code{ODBCDriver}, - \code{OracleDriver}. -} -\item{obj}{ - R/Splus object whose SQL type we want to determine. -} -\item{\dots }{ - any other parameters that individual methods may need. -} +\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}. +A character string specifying the SQL data type for \code{obj}. } -\details{ - This is a generic function. The default method determines the - SQL type of an R/Splus object according to the SQL 92 specification, - which may serve as a starting point for driver implementations. -} -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. +\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. } -\seealso{ - \code{\link{isSQLKeyword}} - \code{\link{make.db.names}} +\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) } -\examples{\dontrun{ -ora <- dbDriver("Oracle") -sql.type <- dbDataType(ora, x) } +\seealso{ +\code{\link{isSQLKeyword}} \code{\link{make.db.names}} } -\keyword{interface} -\keyword{database} -% docclass is function -% Converted by Sd2Rd version 1.15.2.1. -% vim: syntax=tex + diff -Nru dbi-0.2-7/man/dbDisconnect.Rd dbi-0.3.1/man/dbDisconnect.Rd --- dbi-0.2-7/man/dbDisconnect.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbDisconnect.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,36 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbDriver.Rd dbi-0.3.1/man/dbDriver.Rd --- dbi-0.2-7/man/dbDriver.Rd 2007-10-25 13:24:54.000000000 +0000 +++ dbi-0.3.1/man/dbDriver.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,97 +1,53 @@ -% $Id$ +% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbDriver} \alias{dbDriver} \alias{dbDriver,character-method} \alias{dbUnloadDriver} -\title{ - Database Interface (DBI) Classes and drivers -} -\description{ - These \emph{virtual} classes and their methods define the interface to - database management systems (DBMS). They are extended by packages - or drivers that implement the methods in the context of specific - DBMS (e.g., Berkeley DB, MySQL, Oracle, ODBC, PostgreSQL, SQLite). -} +\title{Load and unload database drivers.} \usage{ - dbDriver(drvName, ...) - dbUnloadDriver(drv, ...) ## free up all resources +dbDriver(drvName, ...) + +dbUnloadDriver(drv, ...) } \arguments{ -\item{drvName}{ - character name of the driver to instantiate. - } -\item{drv}{ - an object that inherits from \code{DBIDriver} as created by - \code{dbDriver}. -} -\item{...}{ - any other arguments are passed to the driver \code{drvName}. - } +\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. +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}. - -} -\details{ - 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. - - 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. -} - -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or - \url{http://developer.r-project.org/db}. -} -\seealso{ - \code{\link{dbConnect}}, - \code{\link{dbSendQuery}}, - \code{\link{dbGetQuery}}, - \code{\link{fetch}}, - \code{\link{dbCommit}}, - \code{\link{dbGetInfo}}, - \code{\link{dbListTables}}, - \code{\link{dbReadTable}}. -} -\examples{\dontrun{ -# create a MySQL instance for capacity of up to 25 simultaneous -# connections. -m <- dbDriver("MySQL", max.con = 25) -p <- dbDriver("PgSQL") - -# open the connection using user, password, etc., as -con <- dbConnect(m, user="ip", password = "traffic", dbname="iptraffic") -rs <- dbSubmitQuery(con, - "select * from HTTP_ACCESS where IP_ADDRESS = '127.0.0.1'") -df <- fetch(rs, n = 50) -df2 <- fetch(rs, n = -1) -dbClearResult(rs) - -pcon <- dbConnect(p, "user", "password", "dbname") -dbListTables(pcon) -} -} -\keyword{interface} -\keyword{database} -% vim: syntax=tex + +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() +} +} + diff -Nru dbi-0.2-7/man/dbExistsTable.Rd dbi-0.3.1/man/dbExistsTable.Rd --- dbi-0.2-7/man/dbExistsTable.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbExistsTable.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,31 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbFetch.Rd dbi-0.3.1/man/dbFetch.Rd --- dbi-0.2-7/man/dbFetch.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbFetch.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,70 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbGetDBIVersion.Rd dbi-0.3.1/man/dbGetDBIVersion.Rd --- dbi-0.2-7/man/dbGetDBIVersion.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbGetDBIVersion.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,12 @@ +% 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} + diff -Nru dbi-0.2-7/man/dbGetException.Rd dbi-0.3.1/man/dbGetException.Rd --- dbi-0.2-7/man/dbGetException.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbGetException.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,31 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbGetInfo.Rd dbi-0.3.1/man/dbGetInfo.Rd --- dbi-0.2-7/man/dbGetInfo.Rd 2009-12-21 18:15:33.000000000 +0000 +++ dbi-0.3.1/man/dbGetInfo.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,119 +1,45 @@ -% $Id$ +% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbGetInfo} \alias{dbGetInfo} -\alias{dbGetDBIVersion} -\alias{dbGetStatement} -\alias{dbGetRowCount} -\alias{dbGetRowsAffected} -\alias{dbColumnInfo} -\alias{dbHasCompleted} -\title{ - Database interface meta-data -} -\description{ - Extract meta-data associated with various objects -} +\title{Get DBMS metadata.} \usage{ - dbGetInfo(dbObj, ...) # meta-data for any DBIObject - dbGetDBIVersion() # DBI version - dbGetStatement(res, ...) # statement that produced result "res" - dbGetRowCount(res, ...) # number of rows fetched so far - dbGetRowsAffected(res, ...) # number of affected rows (e.g., DELETE) - dbColumnInfo(res, ...) # result set data types - dbHasCompleted(res, ...) # are there more rows to fetch on "res"? +dbGetInfo(dbObj, ...) } \arguments{ -\item{dbObj}{ - any object that implements some functionality in the R/Splus - interface to databases (a driver, a connection or a result set). -} -\item{res}{ - refers to a \code{DBIResult} object. -} -\item{\dots}{ - any driver-specific 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{ - \code{dbGetDBIVersion} returns a character string with the version - of the database interface API. - - \code{dbGetInfo} produces either a character vector or a named list - of (name, value) pairs. - - \code{dbGetStatement} returns a character string with the statement - associated with the result set \code{res}. - - \code{dbGetRowCount} returns the number of rows fetched so far. - - \code{dbGetRowsAffected} returns the number of affected rows (e.g., - how many rows were deleted, inserted). Some drivers may set this - to the total number of rows a query produces. - - \code{dbColumnInfo} returns a data.frame with one row per output field - in \code{res}. The columns should report field name, field data type, - scale and precision (as understood by the DBMS engine), whether the - field can store \code{NULL} values, and possibly other DBMS-specific - information. - - \code{dbHasCompleted} a logical describing whether the operations has - been completed by the DBMS or not. - +a named list } -\details{ - These functions implement a minimal set of meta-data describing the - most important aspects of the R/Splus to DBMS interface. - - The \code{dbGetInfo} works very similarly to the function - \code{options} in that it attempts to extract what the user may - request, possibly NULL if it can't locate the specific piece - of meta-data. -} -\section{Note}{ - Meta-data associated with a driver should include the version of the - package, plus the version of the underlying client library. Connection - objects should report the version of the DBMS engine, database name, user, - possibly password, etc. Results should include the statement being - executed, how many rows have been fetched so far (in the case of queries), - how many rows were affected (deleted, inserted, changed, or total number - of records to be fetched). -} -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. +\description{ +Get DBMS metadata. } -\seealso{ - \code{\link{dbDriver}}, - \code{\link{dbConnect}}, - \code{\link{dbSendQuery}}, - \code{\link{dbGetQuery}}, - \code{\link{fetch}}, - \code{\link{dbCommit}}, - \code{\link{dbGetInfo}}, - \code{\link{dbListTables}}, - \code{\link{dbReadTable}}. -} -\examples{\dontrun{ -drv <- dbDriver("SQLite") -con <- dbConnect(drv) - -dbListTables(con) +\section{Implementation notes}{ -rs <- dbSendQuery(con, query.sql) -dbGetStatement(rs) -dbHasCompleted(rs) - -info <- dbGetInfo(rs) -names(dbGetInfo(drv)) - -# DBIConnection info -names(dbGetInfo(con)) - -# DBIResult info -names(dbGetInfo(rs)) +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}} } -\keyword{interface} -\keyword{database} -% vim: syntax=tex + diff -Nru dbi-0.2-7/man/dbGetQuery.Rd dbi-0.3.1/man/dbGetQuery.Rd --- dbi-0.2-7/man/dbGetQuery.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbGetQuery.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,45 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbGetRowCount.Rd dbi-0.3.1/man/dbGetRowCount.Rd --- dbi-0.2-7/man/dbGetRowCount.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbGetRowCount.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,32 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbGetRowsAffected.Rd dbi-0.3.1/man/dbGetRowsAffected.Rd --- dbi-0.2-7/man/dbGetRowsAffected.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbGetRowsAffected.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,32 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbGetStatement.Rd dbi-0.3.1/man/dbGetStatement.Rd --- dbi-0.2-7/man/dbGetStatement.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbGetStatement.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,32 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbHasCompleted.Rd dbi-0.3.1/man/dbHasCompleted.Rd --- dbi-0.2-7/man/dbHasCompleted.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbHasCompleted.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,32 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbiCheckCompliance.Rd dbi-0.3.1/man/dbiCheckCompliance.Rd --- dbi-0.2-7/man/dbiCheckCompliance.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbiCheckCompliance.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,22 @@ +% 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") +} +} + diff -Nru dbi-0.2-7/man/DBIConnection-class.Rd dbi-0.3.1/man/DBIConnection-class.Rd --- dbi-0.2-7/man/DBIConnection-class.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/DBIConnection-class.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,91 +1,30 @@ -% $Id$ -\name{DBIConnection-class} +% Generated by roxygen2 (4.0.2): do not edit by hand \docType{class} +\name{DBIConnection-class} \alias{DBIConnection-class} -\title{Class DBIConnection} +\title{DBIConnection class.} \description{ - Base class for all DBMS connection classes. Individual - drivers (ODBC, Oracle, PostgreSQL, MySQL, etc.) - extend this class in a database-specific manner. -} -\section{Objects from the Class}{ - A virtual Class: No objects may be created from it. -} - -\section{Extends}{ -Class \code{"DBIObject"}, directly. -} -\section{Generator}{ - The main generator is \code{\link{dbConnect}}. - } -\section{Methods}{ - -The following methods take objects from classes derived -from \code{DBIConnection}: - - \describe{ -Create and close connections: - - \item{\link{dbConnect}}{\code{signature(drv = "DBIConnection")}: ... } - \item{\link{dbDisconnect}}{\code{signature(conn = "DBIConnection")}: ... } - -Execute SQL commands: - - \item{\link{dbSendQuery}}{\code{signature(conn = "DBIConnection", statement = "character")}: ... } - \item{\link{dbGetQuery}}{\code{signature(conn = "DBIConnection", statement = "character")}: ... } - - \item{\link{dbCallProc}}{\code{signature(conn = "DBIConnection")}: ... } +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) -Transaction management: - - \item{\link{dbCommit}}{\code{signature(conn = "DBIConnection")}: ... } - \item{\link{dbRollback}}{\code{signature(conn = "DBIConnection")}: ... } - -Meta-data: - \item{\link{dbListResults}}{\code{signature(conn = "DBIConnection")}: ... } - \item{\link{dbGetInfo}}{\code{signature(dbObj = "DBIConnection")}: ... } - \item{\link{summary}}{\code{signature(object = "DBIConnection")}: ... } - -Exceptions: - - \item{\link{dbGetException}}{\code{signature(conn = "DBIConnection")}: ... } - - \item{\link{dbListFields}}{\code{signature(conn = "DBIConnection", name = "character")}: ... } - - Convenience functions: - - \item{\link{dbListTables}}{\code{signature(conn = "DBIConnection")}: ... } - - \item{\link{dbReadTable}}{\code{signature(conn = "DBIConnection", name = "character")}: ... } - \item{\link{dbExistsTable}}{\code{signature(conn = "DBIConnection", name = "character")}: ... } - \item{\link{dbRemoveTable}}{\code{signature(conn = "DBIConnection", name = "character")}: ... } - \item{\link{dbWriteTable}}{\code{signature(conn = "DBIConnection", name = "character", value = "data.frame")}: ... } - } +con <- dbConnect(RPostgreSQL::PostgreSQL(), "username", "passsword") +dbDisconnect(con) } -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. } -\author{R-SIG-DB} - \seealso{ - DBI classes: - \code{\link{DBIObject-class}} - \code{\link{DBIDriver-class}} - \code{\link{DBIConnection-class}} - \code{\link{DBIResult-class}} +Other DBI classes: \code{\link{DBIDriver-class}}; + \code{\link{DBIObject-class}}; + \code{\link{DBIResult-class}} } -\examples{\dontrun{ -ora <- dbDriver("Oracle") -con <- dbConnect(ora, "user/password@dbname") - -pg <- dbDriver("PostgreSQL") -con <- dbConnect(pg, "user", "password") -} -} -\keyword{classes} -\keyword{database} -\keyword{interface} -% vim: syntax=tex diff -Nru dbi-0.2-7/man/DBIDriver-class.Rd dbi-0.3.1/man/DBIDriver-class.Rd --- dbi-0.2-7/man/DBIDriver-class.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/DBIDriver-class.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,63 +1,18 @@ -% $Id$ -\name{DBIDriver-class} +% Generated by roxygen2 (4.0.2): do not edit by hand \docType{class} - +\name{DBIDriver-class} \alias{DBIDriver-class} -\alias{summary,DBIObject-method} - -\title{Class DBIDriver} - -\description{ - Base class for all DBMS drivers (e.g., ODBC, Oracle, MySQL, PostgreSQL). -} -\section{Objects from the Class}{ - A virtual Class: No objects may be created from it. -} -\section{Extends}{ -Class \code{"DBIObject"}, directly. -} - -\section{Generator}{ - The generator for classes that extend \code{DBIDriver} is - \code{\link{dbDriver}}. -} -\section{Methods}{ - The following methods are defined for classes that extend - \code{DBIDriver}: - - \describe{ - \item{\link{dbUnloadDriver}}{\code{signature(drv = "DBIDriver")}: ... } - \item{\link{dbConnect}}{\code{signature(drv = "DBIDriver")}: ... } - \item{\link{dbGetInfo}}{\code{signature(dbObj = "DBIDriver")}: ... } - \item{\link{dbListConnections}}{\code{signature(drv = "DBIDriver")}: ... } - \item{\link{summary}}{\code{signature(object = "DBIDriver")}: ... } - } -} -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. +\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. } -\author{R-SIG-DB} \seealso{ - DBI classes: - \code{\link{DBIObject-class}} - \code{\link{DBIDriver-class}} - \code{\link{DBIConnection-class}} - \code{\link{DBIResult-class}} - - The function \code{\link{dbConnect}} is the main generator. - - In addition see the help of the methods above. +Other DBI classes: \code{\link{DBIConnection-class}}; + \code{\link{DBIObject-class}}; + \code{\link{DBIResult-class}} } -\examples{\dontrun{ -drv <- dbDriver("ODBC") -summary(drv) -dbListConnections(drv) -} -} -\keyword{classes} -\keyword{database} -\keyword{interface} -% vim: syntax=tex diff -Nru dbi-0.2-7/man/DBI-internal.Rd dbi-0.3.1/man/DBI-internal.Rd --- dbi-0.2-7/man/DBI-internal.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/DBI-internal.Rd 1970-01-01 00:00:00.000000000 +0000 @@ -1,49 +0,0 @@ -\name{DBI-internal} -%\alias{dbDataType.default} -\alias{make.db.names.default} -\alias{isSQLKeyword.default} -\alias{.SQL92Keywords} -%\alias{.__C__DBIDriver} -%\alias{.__C__DBIConnection} -%\alias{.__C__DBIDriver} -%\alias{.__C__DBIObject} -%\alias{.__C__DBIResult} -%\alias{.__M__dbCallProc} -%\alias{.__M__dbClearResult} -%\alias{.__M__dbColumnInfo} -%\alias{.__M__dbCommit} -%\alias{.__M__dbConnect} -%\alias{.__M__dbDataType} -%\alias{.__M__dbDisconnect} -%\alias{.__M__dbExistsTable} -%\alias{.__M__dbGetConnection} -%\alias{.__M__dbGetException} -%\alias{.__M__dbGetInfo} -%\alias{.__M__dbGetQuery} -%\alias{.__M__dbGetStatement} -%\alias{.__M__dbHasCompleted} -%\alias{.__M__dbListConnections} -%\alias{.__M__dbListFields} -%\alias{.__M__dbListResults} -%\alias{.__M__dbListTables} -%\alias{.__M__dbReadTable} -%\alias{.__M__dbRemoveTable} -%\alias{.__M__dbRollback} -%\alias{.__M__dbSendQuery} -%\alias{.__M__dbSetDataMappings} -%\alias{.__M__dbUnloadDriver} -%\alias{.__M__dbWriteTable} -%\alias{.__M__fetch} -%\alias{.__M__format} -%\alias{.__M__isSQLKeyword} -%\alias{.__M__make.db.names} -%\alias{.__M__print} -%\alias{.__M__SQLKeywords} -%\alias{.__M__summary} - -\title{Version 4 meta-objects} -\description{ - Helper functions and version 4 meta objects (many!). -} -\keyword{internal} -% vim: syntax=tex diff -Nru dbi-0.2-7/man/DBIObject-class.Rd dbi-0.3.1/man/DBIObject-class.Rd --- dbi-0.2-7/man/DBIObject-class.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/DBIObject-class.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,42 +1,40 @@ -% $Id$ -\name{DBIObject-class} +% Generated by roxygen2 (4.0.2): do not edit by hand \docType{class} +\name{DBIObject-class} \alias{DBIObject-class} -\title{Class DBIObject} -\description{ - Base class for all other DBI classes (e.g., drivers, connections). -} -\section{Objects from the Class}{ - A virtual Class: No objects may be created from it. -} -\section{Methods}{ - Methods defined for classes that extend \code{DBIObject}: - \describe{ - \item{\link{dbDataType}}{\code{signature(dbObj = "DBIObject")}: ... } - \item{\link{isSQLKeyword}}{\code{signature(dbObj = "DBIObject")}: ... } - \item{\link{make.db.names}}{\code{signature(dbObj = "DBIObject")}: ... } - \item{\link{SQLKeywords}}{\code{signature(dbObj = "DBIObject")}: ... } - \item{\link{summary}}{\code{signature(object = "DBIObject")}: ... } - } - Plus many other specific to the other DBI classes. -} -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or - \url{http://developer.r-project.org/db}. +\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. } -\author{R-SIG-DB} +\section{Implementation notes}{ -\seealso{ - DBI classes: - \code{\link{DBIObject-class}} - \code{\link{DBIDriver-class}} - \code{\link{DBIConnection-class}} - \code{\link{DBIResult-class}} +An implementation MUST provide methods for the following generics: + +\itemize{ + \item \code{\link{dbGetInfo}}. } -\examples{\dontrun{ +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") @@ -45,7 +43,9 @@ is(res, "DBIObject") } } -\keyword{classes} -\keyword{interface} -\keyword{database} -% vim: syntax=tex +\seealso{ +Other DBI classes: \code{\link{DBIConnection-class}}; + \code{\link{DBIDriver-class}}; + \code{\link{DBIResult-class}} +} + diff -Nru dbi-0.2-7/man/DBIResult-class.Rd dbi-0.3.1/man/DBIResult-class.Rd --- dbi-0.2-7/man/DBIResult-class.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/DBIResult-class.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,73 +1,23 @@ -% $Id$ -\name{DBIResult-class} +% Generated by roxygen2 (4.0.2): do not edit by hand \docType{class} +\name{DBIResult-class} \alias{DBIResult-class} -\title{Class DBIResult} +\title{DBIResult class.} \description{ - Base class for all DBMS-specific result objects. -} -\section{Objects from the Class}{ - A virtual Class: No objects may be created from it. -} -\section{Extends}{ - Class \code{"DBIObject"}, directly. -} -\section{Generator}{ - The main generator is \code{\link{dbSendQuery}}. -} -\section{Methods}{ - - \describe{ -Fetching methods: - - \item{\link{fetch}}{\code{signature(res = "DBIResult", n = "numeric")}: ... } - \item{\link{fetch}}{\code{signature(res = "DBIResult", n = "missing")}: ... } -Close result set: - - \item{\link{dbClearResult}}{\code{signature(res = "DBIResult")}: ... } - -Meta-data: - - \item{\link{dbColumnInfo}}{\code{signature(res = "DBIResult")}: ... } - \item{\link{dbGetException}}{\code{signature(conn = "DBIResult")}: ... } - \item{\link{dbGetInfo}}{\code{signature(dbObj = "DBIResult")}: ... } - \item{\link{dbGetRowCount}}{\code{signature(res = "DBIResult")}: ... } - \item{\link{dbGetRowsAffected}}{\code{signature(res = "DBIResult")}: ... } - \item{\link{dbGetStatement}}{\code{signature(res = "DBIResult")}: ... } - \item{\link{dbHasCompleted}}{\code{signature(res = "DBIResult")}: ... } - \item{\link{dbListFields}}{\code{signature(conn = "DBIResult", name = "missing")}: ... } - \item{summary}{\code{signature(object = "DBIResult")}: ... } - \item{\link{coerce}}{\code{signature(from = "DBIConnection", to = "DBIResult")}: ... } - } -} - -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. +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. } -\author{R-SIG-DB} - \seealso{ - DBI classes: - \code{\link{DBIObject-class}} - \code{\link{DBIDriver-class}} - \code{\link{DBIConnection-class}} - \code{\link{DBIResult-class}} +Other DBI classes: \code{\link{DBIConnection-class}}; + \code{\link{DBIDriver-class}}; + \code{\link{DBIObject-class}} } -\examples{\dontrun{ - drv <- dbDriver("Oracle") - con <- dbConnect(drv, "user/password@dbname") - res <- dbSendQuery(con, "select * from LASERS where prdata > '2002-05-01'") - summary(res) - while(dbHasCompleted(res)){ - chunk <- fetch(res, n = 1000) - process(chunk) - } -} -} -\keyword{classes} -\keyword{interface} -\keyword{database} -% vim: syntax=tex diff -Nru dbi-0.2-7/man/dbIsValid.Rd dbi-0.3.1/man/dbIsValid.Rd --- dbi-0.2-7/man/dbIsValid.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbIsValid.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,25 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbListConnections.Rd dbi-0.3.1/man/dbListConnections.Rd --- dbi-0.2-7/man/dbListConnections.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbListConnections.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,21 @@ +% 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. +} + diff -Nru dbi-0.2-7/man/dbListFields.Rd dbi-0.3.1/man/dbListFields.Rd --- dbi-0.2-7/man/dbListFields.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbListFields.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,33 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbListResults.Rd dbi-0.3.1/man/dbListResults.Rd --- dbi-0.2-7/man/dbListResults.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbListResults.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,30 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbListTables.Rd dbi-0.3.1/man/dbListTables.Rd --- dbi-0.2-7/man/dbListTables.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/dbListTables.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,68 +1,30 @@ -% $Id$ +% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbListTables} \alias{dbListTables} -\alias{dbListFields} -\alias{dbListConnections} -\alias{dbListResults} -\title{ - List items from a remote DBMS and from objects that implement - the database interface DBI. -} -\description{ - List remote tables, fields of a remote table, opened connections - and pending statements in a connection. -} +\title{List remote tables.} \usage{ - dbListTables(conn, ...) - dbListFields(conn, name, ...) - dbListConnections(drv, ...) - dbListResults(conn, ...) +dbListTables(conn, ...) } \arguments{ +\item{conn}{A \code{\linkS4class{DBIConnection}} object, as produced by +\code{\link{dbConnect}}.} - \item{drv}{a driver object (e.g., \code{ODBC}, \code{Oracle})} - \item{conn}{a connection object} - \item{name}{a character string with the name of the remote table.} - \item{\dots}{optional arguments for the actual driver implementation.} - +\item{...}{Other parameters passed on to methods.} } \value{ - \code{dbListTables} returns a character vector with the names of the - tables in the remote database associated with the connection in - \code{conn} object. - - \code{dbListFields} returns a character vector with the names of the - fields of the \code{res} result object (it must be a query statement). - - \code{dbListConnections} returns a list of all currently open - connections on driver \code{drv}. Drivers that implement single - connections would return the one single connection object. - - \code{dbListResults} returns a list of objects for all pending results - (statements) on the \code{conn} connection. +a character vector. If no tables present, a character vector + of length 0. } -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or - \url{http://developer.r-project.org/db}. +\description{ +This should, where possible, include temporary tables. } \seealso{ - \code{\link{dbGetInfo}}, - \code{\link{dbColumnInfo}}, - \code{\link{dbDriver}}, - \code{\link{dbConnect}}, - \code{\link{dbSendQuery}} +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}} } -\examples{\dontrun{ -odbc <- dbDriver("ODBC") -# after working awhile... -for(con in dbListConnections(odbc)){ - dbGetStatement(dbListResults(con)) -} -} -} -\keyword{interface} -\keyword{database} -% vim: syntax=tex diff -Nru dbi-0.2-7/man/dbReadTable.Rd dbi-0.3.1/man/dbReadTable.Rd --- dbi-0.2-7/man/dbReadTable.Rd 2013-04-21 06:36:22.000000000 +0000 +++ dbi-0.3.1/man/dbReadTable.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,120 +1,53 @@ -% $Id$ +% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbReadTable} \alias{dbReadTable} \alias{dbWriteTable} -\alias{dbExistsTable} -\alias{dbRemoveTable} -\title{ - Convenience functions for Importing/Exporting DBMS tables -} -\description{ - These functions mimic their R/Splus counterpart - \code{get}, - \code{assign}, - \code{exists}, - \code{remove}, and - \code{objects}, - except that they generate code that gets remotely executed - in a database engine. -} +\title{Copy data frames to and from database tables.} \usage{ - dbReadTable(conn, name, ...) - dbWriteTable(conn, name, value, ...) - dbExistsTable(conn, name, ...) - dbRemoveTable(conn, name, ...) +dbReadTable(conn, name, ...) + +dbWriteTable(conn, name, value, ...) } \arguments{ - \item{conn}{ - a database connection object. - } - \item{name}{ - a character string specifying a DBMS table name. - } - \item{value}{ - a data.frame (or coercible to data.frame). - } - \item{\dots }{ - any optional arguments that the underlying database driver - supports, e.g. - \describe{ - \item{row.names}{ - in the case of \code{dbReadTable}, this argument can be a string - or an index specifying the column in the DBMS table to be used - as \code{row.names} in the output data.frame (a \code{NULL}, - \code{""}, or 0 specifies that no column should be used as - \code{row.names} in the output). In the case of - \code{dbWriteTable}, this argument should be a logical - specifying whether the \code{row.names} should be output to the - output DBMS table; if \code{TRUE}, the extra field name will be - whatever the S identifier \code{"row.names"} maps to the DBMS - (see \code{\link{make.db.names}}). - } - \item{overwrite}{ - a logical specifying whether to overwrite an existing table - or not. Its default is \code{FALSE}. - } - \item{append}{ - a logical specifying whether to append to an existing table - in the DBMS. - Its default is \code{FALSE}. - } - } - } -} +\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{ - \code{dbReadTable} returns a data.frame; all other functions - return \code{TRUE} or \code{FALSE} denoting whether the operation - was successful or not. -} - -\section{Side Effects}{ -A DBMS statement is generated and remotely executed on a database -engine; the result set it produces is fetched in its entirety. -These operations may failed if the underlying database driver runs -out of available connections and/or result sets, or the operation -violates DBMS integrity constraints (e.g., attempting to write -duplicate values on a field that's defined as a primary key). - -The semantics of \code{assign} are slightly extended to allow -overwriting or appending to an existing table. -} -\note{The translation of identifiers between R/Splus 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}}. -} -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. +a data.frame. } -\seealso{ - \code{\link{dbDriver}}, - \code{\link{dbConnect}}, - \code{\link{dbSendQuery}}, - \code{\link{dbGetQuery}}, - \code{\link{fetch}}, - \code{\link{dbCommit}}, - \code{\link{dbGetInfo}}, - \code{\link{dbListTables}}, - \code{\link{dbReadTable}}. -} -\examples{\dontrun{ -conn <- dbConnect("MySQL", group = "vitalAnalysis") -con2 <- dbConnect("ODBC", "dsn", "user", "pwd") -if(dbExistsTable(con2, "fuel_frame")){ - fuel.frame <- dbReadTable(con2, "fuel_frame") - dbRemoveTable(conn, "fuel_frame") - dbWriteTable(conn, "fuel_frame", fuel.frame) -} -if(dbExistsTable(conn, "RESULTS")){ - dbWriteTable(conn, "RESULTS", results2000, append = T) -else - dbWriteTable(conn, "RESULTS", results2000) +\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) } } -\keyword{interface} -\keyword{database} -% vim: syntax=tex +\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}} +} + diff -Nru dbi-0.2-7/man/dbRemoveTable.Rd dbi-0.3.1/man/dbRemoveTable.Rd --- dbi-0.2-7/man/dbRemoveTable.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/dbRemoveTable.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,31 @@ +% 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}} +} + diff -Nru dbi-0.2-7/man/dbSendQuery.Rd dbi-0.3.1/man/dbSendQuery.Rd --- dbi-0.2-7/man/dbSendQuery.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/dbSendQuery.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,97 +1,59 @@ -% $Id$ +% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbSendQuery} \alias{dbSendQuery} -\alias{dbGetQuery} -\alias{dbClearResult} -\alias{dbGetException} -\title{ - Execute a statement on a given database connection -} -\description{ - Submits and executes an arbitrary SQL statement on a - specific connection. Also, clears (closes) a result set. -} +\title{Execute a statement on a given database connection.} \usage{ - dbSendQuery(conn, statement, ...) - dbGetQuery(conn, statement, ...) - dbClearResult(res, ...) - dbGetException(conn, ...) +dbSendQuery(conn, statement, ...) } \arguments{ -\item{conn}{ - a connection object. -} -\item{statement}{ - a character vector of length 1 with the SQL statement. -} -\item{res}{ - a result set object (i.e., the value of \code{dbSendQuery}). -} -\item{\dots }{ - database-specific parameters may be specified. -} +\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{ - \code{dbSendQuery} returns a result set object, i.e., an object - that inherits from \code{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. - - \code{dbGetQuery} returns a data.frame with the output (if any) - of the query. - - \code{dbClearResult} returns a logical indicating whether clearing - the result set was successful or not. - - \code{dbGetException} returns 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}. +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/Splus, others may - transfer all the data to the client -- but not necessarily to the - memory that R/Splus manages. See the individual drivers' - \code{\link{dbSendQuery}} method for implementation details. -} -\details{ - 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{fetch}} (make sure you invoke \code{dbClearResult} when you - finish fetching the records you need). - - The function \code{dbGetQuery} does all these in one operation (submits - the statement, fetches all output records, and clears the result set). - - \code{dbClearResult} 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.) -} -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. + +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{ - \code{\link{dbDriver}} - \code{\link{dbConnect}} - \code{\link{fetch}} - \code{\link{dbCommit}} - \code{\link{dbGetInfo}} - \code{\link{dbReadTable}} -} -\examples{\dontrun{ -drv <- dbDriver("MySQL") -con <- dbConnect(drv) -res <- dbSendQuery(con, "SELECT * from liv25") -data <- fetch(res, n = -1) -} -} -\keyword{interface} -\keyword{database} -% vim: syntax=tex +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}} +} + diff -Nru dbi-0.2-7/man/dbSetDataMappings.Rd dbi-0.3.1/man/dbSetDataMappings.Rd --- dbi-0.2-7/man/dbSetDataMappings.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/dbSetDataMappings.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,69 +1,27 @@ -% $Id$ +% Generated by roxygen2 (4.0.2): do not edit by hand \name{dbSetDataMappings} \alias{dbSetDataMappings} -\title{ - Set data mappings between an DBMS and R/Splus -} -\description{ - Sets one or more conversion functions to handle the translation - of DBMS data types to R/Splus objects. - This is only needed for non-primitive data, since all DBI drivers - handle the common base types (integers, numeric, strings, etc.) -} +\title{Set data mappings between an DBMS and R.} \usage{ - dbSetDataMappings(res, flds, ...) +dbSetDataMappings(res, flds, ...) } \arguments{ -\item{res}{ - a \code{DBIResult} object as returned by \code{dbSendQuery}. - } -\item{flds}{ - a field description object as returned by \code{dbColumnInfo}. - } -\item{\dots }{ - any additional arguments are passed to the implementing method. - } -} -\value{ - a logical specifying whether the conversion functions were - successfully installed or not. +\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.} } -\section{Side Effects}{ - Conversion functions are set up to be invoked for each element of - the corresponding fields in the result set. +\description{ +This generic is deprecated since no working implementation was ever produced. } \details{ - The details on conversion functions (e.g., arguments, - whether they can invoke initializers and/or destructors) - have not been specified. -} -\note{ - No driver has yet implemented this functionality. -} -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. -} -\seealso{ - \code{\link{dbSendQuery}}, - \code{\link{fetch}}, - \code{\link{dbColumnInfo}}. -} -\examples{\dontrun{ -makeImage <- function(x) { - .C("make_Image", as.integer(x), length(x)) -} +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.) -res <- dbSendQuery(con, statement) -flds <- dbColumnInfo(res) -flds[3, "Sclass"] <- makeImage - -dbSetDataMappings(rs, flds) - -im <- fetch(rs, n = -1) +The details on conversion functions (e.g., arguments, whether they can invoke +initializers and/or destructors) have not been specified. } -} -\keyword{interface} -\keyword{database} -% vim: syntax=tex +\keyword{internal} + diff -Nru dbi-0.2-7/man/fetch.Rd dbi-0.3.1/man/fetch.Rd --- dbi-0.2-7/man/fetch.Rd 2007-04-25 16:43:10.000000000 +0000 +++ dbi-0.3.1/man/fetch.Rd 1970-01-01 00:00:00.000000000 +0000 @@ -1,83 +0,0 @@ -% $Id$ -\name{fetch} -\alias{fetch} -\title{ - Fetch records from a previously executed query -} -\description{ - Fetch records from a previously executed query. -} -\usage{ - fetch(res, n, ...) -} -\arguments{ - -\item{res}{ - a result set object (one whose class extends \code{DBIResult}). - This object needs to be the result of a statement that produces - output, such as SQL's \code{SELECT} or \code{SELECT}-like statement, - this object \code{res} is typically produced by a call to - or \code{dbSendQuery}. - } -\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{\dots }{ - any other database-engine specific arguments. - } -} - -\value{ - a data.frame with as many rows as records were fetched - and as many columns as fields in the result set. -} - -\section{Side Effects}{ - As the R/Splus client fetches records the remote database server - updates its cursor accordingly. -} -\details{ - See the notes for the various database server implementations. -} -\note{ - Make sure you close the result set with \code{\link{dbClearResult}} - as soon as you finish retrieving the records you want. -} -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. -} -\seealso{ - \code{\link{dbConnect}}, - \code{\link{dbSendQuery}}, - \code{\link{dbGetQuery}}, - \code{\link{dbClearResult}}, - \code{\link{dbCommit}}, - \code{\link{dbGetInfo}}, - \code{\link{dbReadTable}}. -} -\examples{\dontrun{ -# Run an SQL statement by creating first a resultSet object -drv <- dbDriver("ODBC") -con <- dbConnect(drv, ...) -res <- dbSendQuery(con, statement = paste( - "SELECT w.laser_id, w.wavelength, p.cut_off", - "FROM WL w, PURGE P", - "WHERE w.laser_id = p.laser_id", - "ORDER BY w.laser_id")) -# we now fetch the first 100 records from the resultSet into a data.frame -data1 <- fetch(res, n = 100) -dim(data1) - -dbHasCompleted(res) - -# let's get all remaining records -data2 <- fetch(res, n = -1) -} -} -\keyword{interface} -\keyword{database} -% vim: syntax=tex diff -Nru dbi-0.2-7/man/make.db.names.Rd dbi-0.3.1/man/make.db.names.Rd --- dbi-0.2-7/man/make.db.names.Rd 2009-12-01 20:57:22.000000000 +0000 +++ dbi-0.3.1/man/make.db.names.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,125 +1,90 @@ -% $Id$ +% Generated by roxygen2 (4.0.2): do not edit by hand \name{make.db.names} -\alias{make.db.names} -\alias{make.db.names,DBIObject,character-method} \alias{SQLKeywords} \alias{SQLKeywords,DBIObject-method} \alias{SQLKeywords,missing-method} \alias{isSQLKeyword} \alias{isSQLKeyword,DBIObject,character-method} -\title{ - Make R/Splus identifiers into legal SQL identifiers -} -\description{ - Produce legal SQL identifiers from a character vector. -} +\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, unique=TRUE, allow.keywords=TRUE, ...) - SQLKeywords(dbObj, ...) - isSQLKeyword(dbObj, name, keywords=.SQL92Keywords, - case=c("lower", "upper", "any")[3], ...) +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/Splus identifiers (symbols) from which - we need to make SQL identifiers. - } -\item{name}{ - a character vector with database identifier candidates we need to - determine whether they are legal SQL identifiers or not. - } -\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{keywords}{ - a character vector with SQL keywords, by default it's - \code{.SQL92Keywords} defined by the DBI. - } -\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. -} +\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 +\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}. + \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. +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 S 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 ``.''). + +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. - - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. -} -\seealso{ - \code{\link{dbReadTable}}, - \code{\link{dbWriteTable}}, - \code{\link{dbExistsTable}}, - \code{\link{dbRemoveTable}}, - \code{\link{dbListTables}}. -} -\examples{\dontrun{ -# This example shows how we could export a bunch of data.frames -# into tables on a remote database. - -con <- dbConnect("Oracle", user="iptraffic", pass = pwd) - -export <- c("trantime.email", "trantime.print", "round.trip.time.email") -tabs <- make.db.names(export, unique = T, allow.keywords = T) - -for(i in seq(along = export) ) - dbWriteTable(con, name = tabs[i], get(export[i])) - -# Oracle's extensions to SQL keywords -oracle.keywords <- c("CLUSTER", "COLUMN", "MINUS", "DBNAME") -isSQLKeyword(nam, c(.SQL92Keywords, oracle.keywords)) -[1] T T T F -} -} -\keyword{interface} -\keyword{database} -% vim: syntax=tex +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. +} + diff -Nru dbi-0.2-7/man/print.list.pairs.Rd dbi-0.3.1/man/print.list.pairs.Rd --- dbi-0.2-7/man/print.list.pairs.Rd 2013-04-21 06:37:36.000000000 +0000 +++ dbi-0.3.1/man/print.list.pairs.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -1,38 +1,23 @@ +% Generated by roxygen2 (4.0.2): do not edit by hand \name{print.list.pairs} \alias{print.list.pairs} -\alias{print} -\alias{summary} -\alias{format} -\title{Support functions} -\description{ - Some of these functions are conditionally elevated to - generic functions (e.g., \code{print}, \code{summary}). - Others are low-level support functions. -} +\title{Print a list of pairs.} \usage{ \method{print}{list.pairs}(x, ...) } \arguments{ - \item{x}{a list of key, value pairs} - \item{\dots}{additional arguments to be passed to \code{cat}} +\item{x}{a list of key, value pairs} + +\item{...}{additional arguments to be passed to \code{cat}} } \value{ - the (invisible) value of x. -} -\references{ - See the Database Interface definition document - \code{DBI.pdf} in the base directory of this package - or \url{http://developer.r-project.org/db}. +the (invisible) value of x. } -\seealso{ - \code{\link{print.default}}, - \code{\link{summary.default}}, - \code{\link{cat}}. +\description{ +Print a list of pairs. } -\examples{\dontrun{ +\examples{ print.list.pairs(list(a = 1, b = 2)) } -} -\keyword{interface} -\keyword{database} -% vim: syntax=tex +\keyword{internal} + diff -Nru dbi-0.2-7/man/SQL.Rd dbi-0.3.1/man/SQL.Rd --- dbi-0.2-7/man/SQL.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/SQL.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,72 @@ +% 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)) +} + diff -Nru dbi-0.2-7/man/transactions.Rd dbi-0.3.1/man/transactions.Rd --- dbi-0.2-7/man/transactions.Rd 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/man/transactions.Rd 2014-08-29 21:05:54.000000000 +0000 @@ -0,0 +1,46 @@ +% 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) +} +} +} + diff -Nru dbi-0.2-7/MD5 dbi-0.3.1/MD5 --- dbi-0.2-7/MD5 2013-05-09 10:09:19.000000000 +0000 +++ dbi-0.3.1/MD5 2014-09-24 05:27:12.000000000 +0000 @@ -1,30 +1,50 @@ -3bca877cf52647b8221330f0aa86525d *DESCRIPTION -f0c336b7e23bf19ae9ce1cf79bad79a3 *NAMESPACE -3dc2a00ac59e22e06614af00cadeb183 *R/DBI.R -f5b2fb5ef2aa0ab237bc08b0288872d3 *R/Util.R -807773b767201e73f9aaaf5114831ac1 *R/zzz.R -a6cdd130fd6a39b59d69913fc9764e24 *inst/NEWS -1bf1f66f982e2809aeb67f8c48ec71eb *inst/TODO -4d7e4e45aa0c67165a76849c98eb32b5 *inst/doc/DBI.R -6ea5a2220f6e1680c6f7b8b7d911392d *inst/doc/DBI.Rnw -6e0dbaf13420e604044e4bff71aed186 *inst/doc/DBI.pdf -1c73d69eca009d56f6fe4ffe1401c13c *inst/doc/biblio.bib -42726a6f197ca8e2256828c2535cbc2d *inst/doc/figure1.pdf -f2eef96e8e9a0ce20fcba2ae548bcf5c *man/DBI-internal.Rd -fa34bb4cd3e758be72ffe5d171fba028 *man/DBIConnection-class.Rd -b607090137148606195ece23e0500caa *man/DBIDriver-class.Rd -6dfd542dd524a8a6bfce7c910f433a36 *man/DBIObject-class.Rd -c6a7af100befd0dfd9f7c180138dba5b *man/DBIResult-class.Rd -55168caf5845842721f7aa110715ebd6 *man/dbCallProc.Rd -f69746c2a3bdb4b1b776e5b74484bcd5 *man/dbCommit.Rd -6e31210a5176e0fc9dfe41f16b885a86 *man/dbConnect.Rd -5aa4e30163c0ed0eb4d1295d04598c9c *man/dbDataType.Rd -e63a20c58adfd08452b158bff30856a1 *man/dbDriver.Rd -83dd7a74122ac0578739264e0866d1a9 *man/dbGetInfo.Rd -f3cacab14d001ad46a65ed36f1484d45 *man/dbListTables.Rd -180d6159df9b3ee5a39dd0106bc04108 *man/dbReadTable.Rd -924206604e6dbf827fdd9b73905947ab *man/dbSendQuery.Rd -0028527a8962e37c73111bf1294f9eb8 *man/dbSetDataMappings.Rd -1da0ce75b07b07867c41f340478fa656 *man/fetch.Rd -d56daa962819a19a7f1338fabc4cea9c *man/make.db.names.Rd -4cf73543ff477ae3b7ad62405d163140 *man/print.list.pairs.Rd +330fbe420a011017700986060a075128 *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 diff -Nru dbi-0.2-7/NAMESPACE dbi-0.3.1/NAMESPACE --- dbi-0.2-7/NAMESPACE 2007-04-29 00:37:48.000000000 +0000 +++ dbi-0.3.1/NAMESPACE 2014-09-03 13:45:27.000000000 +0000 @@ -1,55 +1,51 @@ -import(methods) - -## regular functions: -export( - .SQL92Keywords, - dbDataType.default, - dbGetDBIVersion, - isSQLKeyword.default, - make.db.names.default, - print.list.pairs -) +# Generated by roxygen2 (4.0.2): do not edit by hand -## Classes -exportClasses( - DBIConnection, - DBIDriver, - DBIObject, - DBIResult -) - -## Methods/Generics -exportMethods( - dbCallProc, - dbClearResult, - dbColumnInfo, - dbCommit, - dbConnect, - dbDataType, - dbDisconnect, - dbDriver, - dbExistsTable, - dbGetException, - dbGetInfo, - dbGetQuery, - dbGetRowCount, - dbGetRowsAffected, - dbGetStatement, - dbHasCompleted, - dbListConnections, - dbListFields, - dbListResults, - dbListTables, - dbReadTable, - dbRemoveTable, - dbRollback, - dbSendQuery, - dbSetDataMappings, - dbUnloadDriver, - dbWriteTable, - fetch, - isSQLKeyword, - make.db.names, - SQLKeywords, - summary -) +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) diff -Nru dbi-0.2-7/NEWS dbi-0.3.1/NEWS --- dbi-0.2-7/NEWS 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/NEWS 2014-09-23 21:37:45.000000000 +0000 @@ -0,0 +1,141 @@ +# 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. diff -Nru dbi-0.2-7/R/compliance.R dbi-0.3.1/R/compliance.R --- dbi-0.2-7/R/compliance.R 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/R/compliance.R 2014-08-29 15:26:33.000000000 +0000 @@ -0,0 +1,77 @@ +#' 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" + ) +) diff -Nru dbi-0.2-7/R/DBConnection.R dbi-0.3.1/R/DBConnection.R --- dbi-0.2-7/R/DBConnection.R 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/R/DBConnection.R 2014-09-22 18:45:06.000000000 +0000 @@ -0,0 +1,310 @@ +#' 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" +) diff -Nru dbi-0.2-7/R/DBDriver.R dbi-0.3.1/R/DBDriver.R --- dbi-0.2-7/R/DBDriver.R 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/R/DBDriver.R 2014-08-29 17:12:13.000000000 +0000 @@ -0,0 +1,217 @@ +#' 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) + diff -Nru dbi-0.2-7/R/DBI.R dbi-0.3.1/R/DBI.R --- dbi-0.2-7/R/DBI.R 2009-11-04 20:04:14.000000000 +0000 +++ dbi-0.3.1/R/DBI.R 1970-01-01 00:00:00.000000000 +0000 @@ -1,223 +0,0 @@ -## $Id$ -## -## -## Database Interface Definition -## -## Define all the classes and methods to be used by an implementation -## of the Database Interface (DBI). All these classes are virtual and -## each driver should extend them to provide the actual implementation. -## See the files DBI.RODBC, DBI.PgSQL, and DBI.RMySQL for concrete -## implementations. -## -## Class hierarchy: (the "*" prefix indicates a virtual class.) -## -## *DBIObject -## | -## |- *DBIDriver -## | |- ODBCDriver -## | |- PgSQLDriver -## | |- MySQLDriver -## | |- ... -## |- *DBIConnection -## | |- ODBCConnection -## | |- PgSQLDConnection -## | |- MySQLDConnection -## | |- .... -## |- *DBIResult -## | |- ODBCResult -## | |- PgSQLResult -## | |- MySQLResult -## | |- ... -## |- *DBIResultSet (NOTE: this has not been agreed upon) -## |- ODBCResultSet -## |- PgSQLResultSet -## |- MySQLResultSet -## |- ... -## - -## -## DBIObject and its methods (generics, to be more precise). This is -## the base class for all objects that implement R/S DBMS connectivity -## -setClass("DBIObject", "VIRTUAL") - -## this is the main meta-data function; each DBI class should have -## this method return version info, and whatever other info is -## relevant (e.g., user, password(?), dbname for connections) -setGeneric("dbGetInfo", - def = function(dbObj, ...) standardGeneric("dbGetInfo") -) - -## implementations may overload this method for all or some of its classes -setMethod("summary", "DBIObject", - definition = function(object, ...){ - info <- dbGetInfo(dbObj = object, ...) - cat(class(object),"\n") - print.list.pairs(info) - invisible(info) - } -) - -## -## DBIDriver class and its methods. -## -## Should we define methods for querying the interface API to find what -## drivers are available on the current R/Splus instance? Perhaps something -## reminescent of library()? DBIDriver() and DBIDriver(help = "RODBC"), say? -## (JDBC driver manager's class idea would be cleaner.) -## - -setClass("DBIDriver", representation("DBIObject", "VIRTUAL")) - -## The following function "loads" the specific "driver" or package, e.g., -## drv <- dbDriver("MySQL") -## Typically, drivers are expected to have a function of the same name -## that does the actual initialization, e.g., Oracle(), MySQL(), ODBC(), -## SQLite(), .... - -setGeneric("dbDriver", - def = function(drvName, ...) standardGeneric("dbDriver"), - valueClass = "DBIDriver") - -setMethod("dbDriver", "character", - definition = function(drvName, ...) { - do.call(as.character(drvName), list(...)) - } -) -setGeneric("dbListConnections", - def = function(drv, ...) standardGeneric("dbListConnections") -) -setGeneric("dbUnloadDriver", - def = function(drv, ...) standardGeneric("dbUnloadDriver"), - valueClass = "logical" -) - -## -## DBIConnection class and methods -## -setClass("DBIConnection", representation("DBIObject", "VIRTUAL")) - -## create a connection to the DBMS and return its handle object -setGeneric("dbConnect", - def = function(drv, ...) standardGeneric("dbConnect"), - valueClass = "DBIConnection" -) -setGeneric("dbDisconnect", - def = function(conn, ...) standardGeneric("dbDisconnect"), - valueClass = "logical" -) -## submit a statement to the DBMS, return the handle of the result object -setGeneric("dbSendQuery", - def = function(conn, statement, ...) standardGeneric("dbSendQuery"), - valueClass = "DBIResult" -) -## submit, execute, and fetch a statement (all in one operation) -setGeneric("dbGetQuery", - def = function(conn, statement, ...) standardGeneric("dbGetQuery") -) -setGeneric("dbGetException", - def = function(conn, ...) standardGeneric("dbGetException") -) -## return a container with all result objects open in a connection -## (some implementation may only allow one open result set per connection) -setGeneric("dbListResults", - def = function(conn, ...) standardGeneric("dbListResults") -) - -## Convenience DBIConnection functions, most return a logical -## to indicate whether the operation succeeded or not. -## These mimic objects(), get(), exists(), remove(), and assign(), -## and names() - -setGeneric("dbListTables", - def = function(conn, ...) standardGeneric("dbListTables"), - valueClass = "character" -) -setGeneric("dbReadTable", - def = function(conn, name, ...) standardGeneric("dbReadTable"), - valueClass = "data.frame" -) -setGeneric("dbWriteTable", - def = function(conn, name, value, ...) standardGeneric("dbWriteTable"), - valueClass = "logical" -) -setGeneric("dbExistsTable", - def = function(conn, name, ...) standardGeneric("dbExistsTable"), - valueClass = "logical" -) -setGeneric("dbRemoveTable", - def = function(conn, name, ...) standardGeneric("dbRemoveTable"), - valueClass = "logical" -) -## this is equivalent to names() on a remote table "name" -setGeneric("dbListFields", - def = function(conn, name, ...) standardGeneric("dbListFields"), - valueClass = "character" -) - -## -## data conversion -## -setGeneric("dbSetDataMappings", - def = function(res, flds, ...) standardGeneric("dbSetDataMappings"), - valueClass = "logical" -) - -## -## Transaction management -## -setGeneric("dbCommit", - def = function(conn, ...) standardGeneric("dbCommit"), - valueClass = "logical" -) -setGeneric("dbRollback", - def = function(conn, ...) standardGeneric("dbRollback"), - valueClass = "logical" -) - -## -## Stored procedures (untested) -## -setGeneric("dbCallProc", - def = function(conn, ...) standardGeneric("dbCallProc"), - valueClass = "logical" -) - -## -## Class: dbResult -## This is a base class for arbitrary results from the DBMS -## Shoud we also define dbResultSets/dbCursors? -## -setClass("DBIResult", representation("DBIObject", "VIRTUAL")) - -setGeneric("fetch", - def = function(res, n = -1, ...) standardGeneric("fetch"), - valueClass = "data.frame" -) -## close remote result and free resource on both sides of the connection -setGeneric("dbClearResult", - def = function(res, ...) standardGeneric("dbClearResult"), - valueClass = "logical" -) -## return a data.frame with columns describing the fields in the -## result (one row per result field). -setGeneric("dbColumnInfo", - def = function(res, ...) standardGeneric("dbColumnInfo"), - valueClass = "data.frame" -) -setGeneric("dbGetStatement", - def = function(res, ...) standardGeneric("dbGetStatement"), - valueClass = "character" -) -setGeneric("dbHasCompleted", - def = function(res, ...) standardGeneric("dbHasCompleted"), - valueClass = "logical" -) -setGeneric("dbGetRowsAffected", - def = function(res, ...) standardGeneric("dbGetRowsAffected"), - valueClass = "numeric" -) -setGeneric("dbGetRowCount", - def = function(res, ...) standardGeneric("dbGetRowCount"), - valueClass = "numeric" -) diff -Nru dbi-0.2-7/R/DBObject.R dbi-0.3.1/R/DBObject.R --- dbi-0.2-7/R/DBObject.R 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/R/DBObject.R 2014-09-03 13:45:24.000000000 +0000 @@ -0,0 +1,97 @@ +#' 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) +}) diff -Nru dbi-0.2-7/R/DBResult.R dbi-0.3.1/R/DBResult.R --- dbi-0.2-7/R/DBResult.R 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/R/DBResult.R 2014-08-29 17:02:45.000000000 +0000 @@ -0,0 +1,214 @@ +#' 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" +) diff -Nru dbi-0.2-7/R/keywords.R dbi-0.3.1/R/keywords.R --- dbi-0.2-7/R/keywords.R 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/R/keywords.R 2014-08-29 15:52:55.000000000 +0000 @@ -0,0 +1,189 @@ +#' 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" +) diff -Nru dbi-0.2-7/R/quote.R dbi-0.3.1/R/quote.R --- dbi-0.2-7/R/quote.R 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/R/quote.R 2013-10-22 20:04:59.000000000 +0000 @@ -0,0 +1,101 @@ +#' @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 + } +) diff -Nru dbi-0.2-7/R/util.R dbi-0.3.1/R/util.R --- dbi-0.2-7/R/util.R 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/R/util.R 2014-09-02 17:40:24.000000000 +0000 @@ -0,0 +1,53 @@ +#' 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() +} \ No newline at end of file diff -Nru dbi-0.2-7/R/Util.R dbi-0.3.1/R/Util.R --- dbi-0.2-7/R/Util.R 2013-04-21 06:31:34.000000000 +0000 +++ dbi-0.3.1/R/Util.R 1970-01-01 00:00:00.000000000 +0000 @@ -1,183 +0,0 @@ -## -## $Id$ -## -## Utilities. These actually have been implemented by the DBI, -## but individual driver could overload them; for instance, the -## set of SQL keywords should be extended by the various packages. -## - -"dbGetDBIVersion" <- -function() -{ -## packageDescription("DBI", fields = "Version") - packageVersion("DBI") -} - -"print.list.pairs" <- function(x, ...) -{ - for(key in names(x)){ - value <- format(x[[key]]) - if(value=="") next - cat(key, "=", value, "\n") - } - invisible(x) -} -## return a string indicating the "closest" SQL type for an R/S object -setGeneric("dbDataType", - def = function(dbObj, obj, ...) standardGeneric("dbDataType"), - valueClass = "character" -) -## by defualt use the SQL92 data types -- individual drivers may need to -## overload this -setMethod("dbDataType", signature(dbObj="DBIObject", obj="ANY"), - definition = function(dbObj, obj, ...) dbDataType.default(obj, ...), - valueClass = "character" -) - -"dbDataType.default" <- -function(obj, ...) -## find a suitable SQL data type for the R/S object obj -## (this method most likely should be overriden by each driver) -## TODO: Lots and lots!! (this is a very rough first draft) -{ - rs.class <- data.class(obj) - rs.mode <- storage.mode(obj) - if(rs.class=="numeric" || rs.class=="integer"){ - sql.type <- if(rs.mode=="integer") "int" else "double precision" - } - else { - varchar <- function(x, width=0){ - nc <- ifelse(width>0, width, max(nchar(as.character(x)))) - paste("varchar(", nc, ")", sep="") - } - sql.type <- switch(rs.class, - logical = "smallint", - factor = , character = , ordered = , varchar(obj)) - } - sql.type -} - -## map R/S identifiers into SQL identifiers (careful with keywords) -setGeneric("make.db.names", - signature=c("dbObj", "snames"), - def = 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" -) - -"make.db.names.default" <- -function(snames, keywords = .SQL92Keywords, unique = TRUE, - allow.keywords = TRUE) -## produce legal SQL identifiers from strings in a character vector -## unique, in this function, means unique regardless of lower/upper case -{ - "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) -} - -setGeneric("isSQLKeyword", - signature = c("dbObj", "name"), - def = 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" -) - -"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) - -setGeneric("SQLKeywords", - def = function(dbObj, ...) standardGeneric("SQLKeywords"), - valueClass = "character" -) -setMethod("SQLKeywords", "DBIObject", - definition = function(dbObj, ...) .SQL92Keywords, - valueClass = "character" -) -setMethod("SQLKeywords", "missing", - definition = function(dbObj, ...) .SQL92Keywords, - valueClass = "character" -) -".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" - ) diff -Nru dbi-0.2-7/R/zzz.R dbi-0.3.1/R/zzz.R --- dbi-0.2-7/R/zzz.R 2013-04-21 06:30:09.000000000 +0000 +++ dbi-0.3.1/R/zzz.R 1970-01-01 00:00:00.000000000 +0000 @@ -1 +0,0 @@ -.conflicts.OK <- TRUE diff -Nru dbi-0.2-7/README.md dbi-0.3.1/README.md --- dbi-0.2-7/README.md 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/README.md 2014-09-02 21:11:15.000000000 +0000 @@ -0,0 +1,81 @@ +# 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. diff -Nru dbi-0.2-7/tests/testthat/helper-dummy.R dbi-0.3.1/tests/testthat/helper-dummy.R --- dbi-0.2-7/tests/testthat/helper-dummy.R 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/tests/testthat/helper-dummy.R 2013-10-18 19:20:43.000000000 +0000 @@ -0,0 +1,4 @@ +MockObject <- setClass("MockObject", contains = "DBIObject") +MockDriver <- setClass("MockDriver", contains = "DBIDriver") +MockConnection <- setClass("MockConnection", contains = "DBIConnection") +MockResult <- setClass("MockResult", contains = "DBIResult") \ No newline at end of file diff -Nru dbi-0.2-7/tests/testthat/test-data-type.R dbi-0.3.1/tests/testthat/test-data-type.R --- dbi-0.2-7/tests/testthat/test-data-type.R 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/tests/testthat/test-data-type.R 2013-10-18 19:20:43.000000000 +0000 @@ -0,0 +1,9 @@ +context("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")) + +}) \ No newline at end of file diff -Nru dbi-0.2-7/tests/testthat.R dbi-0.3.1/tests/testthat.R --- dbi-0.2-7/tests/testthat.R 1970-01-01 00:00:00.000000000 +0000 +++ dbi-0.3.1/tests/testthat.R 2013-10-18 19:20:43.000000000 +0000 @@ -0,0 +1,2 @@ +library(testthat) +test_check("DBI") \ No newline at end of file