db.open: Open a new database connection

In blueraleigh/db: An R interface to SQLite

Open a new database connection

Description

Open a new database connection

Usage

db.open(
  file = ":memory:",
  functions = list(),
  modules = list(),
  views = list(),
  register = TRUE,
  mode = c("r+", "r")
)

Arguments

file	A character string specifying the database file. If it is the special string ':memory:', a new temporary database is created in computer memory. If it is an empty string, a new on-disk database is created in the system's temporary location. Otherwise it should specify a file path. If the path exists, the database is opened. If it does not exist a new on-disk database is created at that location and opened.
functions	A named list of functions. Each element is a user-defined SQL function to register with the database connection.
modules	A named list of virtual table module factories created by db.virtualtable. Each element should be a function that takes as a single parameter the database connection. When called the function will register the virtual table implementation, with the database connection.
views	A named list of functions. Each element is a function that implements a database documentation page. See db.httpd for details on how to write these.
register	A boolean. Should the database connection be registered with the internal registry? TRUE by default, in which case a request to open a database that is already opened will return the same connection. To open a second connection to the same database set register=FALSE. The documentation system only works on registered database connections.
mode	If mode = "r+" the database is opened for reading and writing and created if it does not already exist. If mode = "r" the database is opened for reading only. An error will be returned if the database does not exist or if a write attempt is made.

Details

When a database connection is opened the database is checked for the presence of a system table named dbpkg. This table can be used to register virtual table implementations, user-defined SQL functions, and documentation pages with the database connection. The dbpkg table should have the following schema

CREATE TABLE dbpkg (
   pkg TEXT NOT NULL PRIMARY KEY
)

where 'pkg' is the name of an R package that implements the various extensions. An R package that implements dbpkg extensions must contain three objects in its namespace named 'functions', 'modules', and 'views', each of which is expected to be a named list of functions to register with the newly formed database connection. Note that any functions passed in as arguments to db.open (via 'functions', 'modules', and 'views') take precedence over functions provided by dbpkg extensions.

Value

An S4 object of class "database". This object has three slots. the handle slot is an external pointer to the underlying sqlite3 database object. The file slot is a character string with the absolute path of the database file. The name slot is the name of the database file.

blueraleigh/db documentation built on Feb. 25, 2024, 9:13 a.m.