Teradata Package for R Function Reference | 17.00 - 17.00 - dbConnect for NativeDriver - Teradata Package for R

Teradata® Package for R Function Reference

prodname
Teradata Package for R
vrm_release
17.00
created_date
July 2021
category
Programming Reference
featnum
B700-4007-090K

Description

Use the dbConnect(tdplyr::NativeDriver(), ...) function to establish a connection to Teradata Vantage using the Teradata SQL driver for R (also called the native driver for R) and initialize a context.

Note:

  • If there is no previous context, then a new context is initialized.

  • If the context already exists, then

    1. the previous context is overwritten and all non-persistent work tables are removed if the connection parameters host, uid and database (i.e., default schema) of the new connection object are different than those of the connection object from the previous context.

    2. the previous context is NOT overwritten and all non-persistent work tables remain in the session if the connection parameters are same for both the new connection object and the connection object from the previous context.

Usage

## S4 method for signature 'NativeDriver'
dbConnect(
  drv,
  host,
  uid,
  pwd = NULL,
  logmech = NULL,
  logdata = NULL,
  temp.database = NULL,
  log = 0,
  ...
)

Arguments

drv

Specifies a NativeDriver object obtained from tdplyr::NativeDriver().

host

Specifies the fully qualified domain name or IP address of a Teradata Vantage System.

uid

Specifies the username to connect with.

pwd

Specifies the password for the connecting user.

logmech

Specifies the logon authentication method. Permitted values are TD2, LDAP, TDNEGO, KRB5 for Kerberos, and JWT.

logdata

Specifies additional data for the chosen logon authentication method. If logmech = JWT, then JWT token should be provided with the key 'jwt.token' in the named list of this argument.

temp.database

Specifies the database name in which temporary database object (table/view), for processing data, are created. Such objects are garbage collected at the end of the session.
Make sure the user has privilege to create objects in this database, otherwise the functions that create temporary objects will fail.
If this argument is not supplied, default database of the connection is used for temporary objects. To get the temporary database name, use function td_get_context().

log

Specifies the controls for debug logging.
Note: The 1-bit governs function and method tracing, the 2-bit governs debug logging, the 4-bit governs transmit and receive message hex dumps, and the 8-bit governs timing.
Default Value: 0
Types: integer
Examples:

  1. If the user wants only debug logging, 2 (in bit representation: 0010) should be used as argument value.

  2. If the user wants timing and debug logging, 10 (in bit representation: 1010) should be used as argument value.

...

Specifies the additional connection parameters that are passed to Teradata SQL Driver for R. Please refer to https://github.com/Teradata/r-driver#ConnectionParameters to get information on connection parameters of the driver.
Note: When the type of a connection parameter is integer or boolean (eg: log, lob_support etc,.), pass integer or boolean value, instead of quoted integer or quoted boolean as suggested in the documentation.

Details

Note:

  1. tdplyr requires that the user has certain permissions on the user's default database or the initial default database specified using the "database" argument, or the temporary database when specified using "temp.database".
    These permissions allow the user to:

    1. Create tables to save results of Vantage analytic functions.

    2. Create views in the background for objects of class "tbl_teradata" based on query.

    It is expected that the user has the required permissions to create these objects in the database that will be used.
    For views based on Vantage Analytic Functions, additional permissions may be required, which can be granted using:
    GRANT EXECUTE FUNCTION ON SYSLIB ... WITH GRANT OPTION.
    The access to the views created may also require issuing additional permissions depending on which database is used and which object the view being created is based on, which can be granted using:
    GRANT SELECT ... WITH GRANT OPTION.

  2. The "temp.database" and "database" parameters help determine which database is used by default to lookup for tables/views while creating objects of class "tbl_teradata" and which database is used to create all internal temporary objects, as shown in the table below.

    Scenario tdplyr behaviour
    1. Both "database" and "temp.database" are provided Internal temporary objects are created in "temp.database", and database table/view lookup is done from "database".
    2. "database" is provided but "temp.database" is not Database table/view lookup and internal temporary objects are created in "database".
    3. "temp.database" is provided but "database" is not Internal temporary objects are created in "temp.database", database table/view lookup from the users default database.
    4. Neither "database" nor "temp.database" are provided Database table/view lookup and internal temporary objects are created in users default database.

Value

A "Teradata" connection object.

See Also

td_remove_context, td_create_context, td_get_context, td_set_context

Examples

# Establish a connection to Teradata Vantage using the dbConnect API and NativeDriver object.
# This will initialize the context based on the connection parameters, if the context does not
# exist.
con <- DBI::dbConnect(tdplyr::NativeDriver(), host = "<dbcname>", uid = "<tduser>",
                      pwd = "<tdpwd>")

# Establish a connection to Teradata Vantage using the dbConnect API and teradatasql
# TeradataDriver object.
# This will NOT initialize the context and td_get_context() function returns NULL if there is no
# previous context. One has to use td_set_context() function to initialize the context on
# TeradataDriver object.
con <- DBI::dbConnect(teradatasql::TeradataDriver(),
                      '{"host":"<dbcname>","user":"<tduser>","password":"<tdpwd>"}')

# Establish a connection to Teradata Vantage using the dbConnect API with additional connection
# parameters.
con <- DBI::dbConnect(tdplyr::NativeDriver(), host = "<dbcname>", uid = "<tduser>",
                      pwd = "<tdpwd>", tmode = 'ansi', log = 8, lob_support = FALSE)

# Establish a connection to Teradata Vantage using the dbConnect API with 'database' parameter.
con <- DBI::dbConnect(tdplyr::NativeDriver(), host = "<dbcname>", uid = "<tduser>",
                      pwd = "<tdpwd>", database = '<schema_name>')