% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/driver-databricks.R
\docType{class}
\name{databricks}
\alias{databricks}
\alias{DatabricksOdbcDriver-class}
\alias{dbConnect,DatabricksOdbcDriver-method}
\title{Helper for Connecting to Databricks via ODBC}
\usage{
databricks()

\S4method{dbConnect}{DatabricksOdbcDriver}(
  drv,
  httpPath,
  workspace = Sys.getenv("DATABRICKS_HOST"),
  useNativeQuery = TRUE,
  driver = NULL,
  HTTPPath,
  uid = NULL,
  pwd = NULL,
  ...
)
}
\arguments{
\item{drv}{an object that inherits from \link[DBI:DBIDriver-class]{DBI::DBIDriver},
or an existing \link[DBI:DBIConnection-class]{DBI::DBIConnection}
object (in order to clone an existing connection).}

\item{httpPath, HTTPPath}{To query a cluster, use the HTTP Path value found
under \verb{Advanced Options > JDBC/ODBC} in the Databricks UI. For SQL
warehouses, this is found under \verb{Connection Details} instead.}

\item{workspace}{The URL of a Databricks workspace, e.g.
\code{"https://example.cloud.databricks.com"}.}

\item{useNativeQuery}{Suppress the driver's conversion from ANSI SQL 92 to
HiveSQL? The default (\code{TRUE}), gives greater performance but means that
paramterised queries (and hence \code{dbWriteTable()}) do not work.}

\item{driver}{The name of the Databricks ODBC driver, or \code{NULL} to use the
default name.}

\item{uid, pwd}{Manually specify a username and password for authentication.
Specifying these options will disable automated credential discovery.}

\item{...}{Further arguments passed on to \code{\link[=dbConnect]{dbConnect()}}.}
}
\value{
An \code{OdbcConnection} object with an active connection to a Databricks
cluster or SQL warehouse.
}
\description{
Connect to Databricks clusters and SQL warehouses via the \href{https://www.databricks.com/spark/odbc-drivers-download}{Databricks ODBC driver}.

In particular, the custom \code{dbConnect()} method for the Databricks ODBC driver
implements a variant of Databricks's \href{https://docs.databricks.com/aws/en/dev-tools/auth/unified-auth}{unified authentication}
model when no \code{uid} or \code{pwd} is supplied, checking for ambient credentials in
the following order:
\itemize{
\item Viewer-based or service principal credentials supplied by Posit Connect
(requires the \pkg{connectcreds} package).
\item Personal access tokens.
\item Workload identity federation.
\item OAuth machine-to-machine credentials.
\item OAuth user-to-machine credentials suplied via Posit Workbench or the
Databricks CLI on desktop.
}

This aims to provide broad compatibility between \pkg{odbc} and the standard
environment variables used by Databricks SDKs in R and other languages.

In addition, on macOS platforms, the \code{dbConnect()} method will check
for irregularities with how the driver is configured,
and attempt to fix in-situ, unless the \code{odbc.no_config_override}
environment variable is set.
}
\examples{
\dontrun{
DBI::dbConnect(
  odbc::databricks(),
  httpPath = "sql/protocolv1/o/4425955464597947/1026-023828-vn51jugj"
)

# Use credentials from the viewer or a service principal (when possible) in
# a Shiny app deployed to Posit Connect.
library(connectcreds)
server <- function(input, output, session) {
  conn <- DBI::dbConnect(
    odbc::databricks(),
    workspace = "https://example.cloud.databricks.com",
    httpPath = "sql/protocolv1/o/4425955464597947/1026-023828-vn51jugj"
  )
}
}
}
