dbConnect {DBI}

Create a connection to a DBMS

Description

Connect to a DBMS going through the appropriate authentication 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 authentication mechanism is left unspecified, so check the documentation of individual drivers for details. Use dbCanConnect() to check if a connection can be established.

Usage

dbConnect(drv, ...)

Arguments

drv

an object that inherits from DBIDriver, or an existing DBIConnection object (in order to clone an existing connection).

...

authentication arguments needed by the DBMS instance; these typically include user, password, host, port, dbname, etc. For details see the appropriate DBIDriver.

Value

dbConnect() returns an S4 object that inherits from DBIConnection. This object is used to communicate with the database engine.

A format() method is defined for the connection object. It returns a string that consists of a single line of text.

Specification

DBI recommends using the following argument names for authentication parameters, with NULL default:

• user for the user name (default: current user)

• password for the password

• host for the host name (default: local connection)

• port for the port number (default: local connection)

• dbname for the name of the database on the host, or the database file name

The defaults should provide reasonable behavior, in particular a local connection for host = NULL. For some DBMS (e.g., PostgreSQL), this is different to a TCP/IP connection to localhost.

In addition, DBI supports the bigint argument that governs how 64-bit integer data is returned. The following values are supported:

• "integer": always return as integer, silently overflow

• "numeric": always return as numeric, silently round

• "character": always return the decimal representation as character

• "integer64": return as a data type that can be coerced using as.integer() (with warning on overflow), as.numeric() and as.character()

See Also

dbDisconnect() to disconnect from a database.

Other DBIDriver generics: DBIDriver-class, dbCanConnect(), dbDataType(), dbDriver(), dbGetInfo(), dbIsReadOnly(), dbIsValid(), dbListConnections()

Other DBIConnector generics: DBIConnector-class, dbDataType(), dbGetConnectArgs(), dbIsReadOnly()

Examples

# SQLite only needs a path to the database. (Here, ":memory:" is a special
# path that creates an in-memory database.) Other database drivers
# will require more details (like user, password, host, port, etc.)
con <- dbConnect(RSQLite::SQLite(), ":memory:")
con

dbListTables(con)

dbDisconnect(con)

# Bad, for subtle reasons:
# This code fails when RSQLite isn't loaded yet,
# because dbConnect() doesn't know yet about RSQLite.
dbListTables(con <- dbConnect(RSQLite::SQLite(), ":memory:"))