[Rd] generic database access methods

Timothy H. Keitt
Mon, 19 Mar 2001 21:19:39 -0000

I've been putting together a package that defined generic methods for
database access.  The packages is called "Rdbi."  It borrows as much
as
possible from existing database packages / proposals.  I'd like to start
a discussion about the proposed interface.  Here's what I've come up
with so far:

#
# Rdbi: connectionMethods.R
#

dbConnect <- function(dbObj, ...) UseMethod("dbConnect")
#
# dbObj should be generated by an implementation defined function,
# e.g., RPgSQL(), which returns a object with an approprite class
# name, e.g., "PostgreSQL" or "MySQL".  The implementation
then
# provides a method that actually opens the connection.
#

dbConnect.default <- function(dbObj, ...) stop("Invalid database
class")
#
# User passed something other than a defined database class
#

dbDisconnect <- function(conn) UseMethod("dbDisconnect")
#
# Close connection and free resources
#

dbDisconnect.default <- function(conn) stop("Invalid connection
object")

dbReconnect <- function(conn) UseMethod("dbReconnect")
#
# The conn object should store the options passed to dbConnect so that
# it can reestablish the connection.
#

dbReconnect.default <- function(conn) stop("Invalid connection
object")
#
# User passed something other than a defined connection class
#

dbConnectionOK <- function(conn) UseMethod("dbConnectionOK")
#
# Returns TRUE if the connection object is valid and the connection
# can be used to communicate with the database backend.
#

dbConnectionOK.default <- function(conn) FALSE
#
# User passed something other than a defined connection class
#


#
# Rdbi: ioMethods.R
#

dbSendQuery <- function(conn, ...) UseMethod("dbSendQuery")
#
# This function submits a query string to the backend.  If the query
# generates any results, they should be returned in a data frame;
# otherwise the function returns NULL.  Printing error messgages is
# left to the implementation, but this function should not issue a
# call to error() or stop().  Error messages may be retrievable from
# the connection object depending on implementation.
#

dbSendQuery.default <- function(conn, ...) stop("Invalid connection
object")
#
# This means that the method was called on something other than a
# connection object.
#

dbListTables <- function(conn, ...) UseMethod("dbListTables")
#
# Output a list of table names associated with the connection object.
# Output should look like output from ls().
#

dbListTables.default <- function(conn, ...) stop("Invalid connection
object")

dbReadTable <- function(conn, ...) UseMethod("dbReadTable")
#
# Analog of the read.table() function.  Returns a data frame.  Some
# facility for converting DB types to R types is helpfull.  Generally,
# this will just pass a "select * from mytable" to dbSendQuery() which
# returns the data frame.
#

dbReadTable.default <- function(conn, ...) stop("Invalid connection
object")

dbWriteTable <- function(conn, ...) UseMethod("dbWriteTable")
#
# Analog of write.table().  It should assemble input into a data frame
# and write the frame into a table in database.
#

dbWriteTable.default <- function(conn, ...) stop("Invalid connection
object")


T.

--
Timothy H. Keitt
Department of Ecology and Evolution
State University of New York at Stony Brook
Phone: 631-632-1101, FAX: 631-632-7626