SAIL-Connection.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/connection.R
\name{Connection}
\alias{Connection}
\title{Connection}
\description{
SAILDB ODBC DBI connection
}
\details{
Available options:
\enumerate{
\item \code{SAILDB.USE.SECRETS}: Whether to use the saildb::Profile manager to store & load secrets, i.e. a password storage manager for each username used to authenticate database connections
\item \code{SAILDB.DROP.UDF}: Specifies whether the \code{saildb::Connection$drop()} method should use the SAIL user-defined function instead of using an anonymous procedure
\item \code{SAILDB.CHUNK.SIZE}: Describes the number of rows to be sent in each statement when saving a \code{data.frame} to the database; this can be reduced or increased depending on how wide your table structure is
\item \code{SAILDB.TIMEZONE}: Specifies the timezone used for \code{DATE}, \code{TIMESTAMP} and \code{DATE} columns
\item \code{SAILDB.DB2.CODEPAGE}: Set the desired DB2 code page for this system; code pages define the character sets used and the mapping between IBM <-> OS code sets. The default setting code page for SAIL's \code{PR_SAIL} is \code{1208}, \emph{i.e.} UTF-8 encoding. See IBM's code page documentation \href{https://www.ibm.com/docs/en/db2/11.1?topic=support-supported-territory-codes-code-pages}{here} for more details. \strong{PLEASE NOTE} that this will update your local account's system environment variables permanently; setting this option to \code{NA} will use your system defined variable and will not update it.
\item \code{SAILDB.QUIET}: Determines whether the \code{saildb::Connection} methods will send condition messages when operations are started / finished; can be used to measure performance and/or debug statement(s)
\item \code{SAILDB.NO.WARN}: Determines whether warnings will be logged to the console
\item \code{SAILDB.THROW.ERRORS}: Specifies whether the current thread should be halted when an error is encountered; you are expected to wrap your \code{saildb::Connection} calls with an error handler if you deactivate this option
}
}
\section{Public fields}{
\if{html}{\out{<div class="r6-fields">}}
\describe{
\item{\code{profile}}{(\code{Profile|NA})\cr
A private field referencing the R6 saildb::Profile class}

\item{\code{using.profile}}{(\code{logical})\cr
A private field specifying whether this connection is using a profile}
}
\if{html}{\out{</div>}}
}
\section{Active bindings}{
\if{html}{\out{<div class="r6-active-bindings">}}
\describe{
\item{\code{connected}}{(\code{S4|NA})\cr
A private field referencing the ODBC handle}

\item{\code{connected}}{(\code{character|NA})\cr
A private field referencing the sanitised connection string used to connect to the database}

\item{\code{profile}}{(\code{Profile|NA})\cr
A private field referencing the R6 saildb::Profile class}

\item{\code{using.profile}}{(\code{logical})\cr
A private field specifying whether this connection is using a profile}

\item{\code{connected}}{(\code{logical})\cr
A read-only field describing whether this connection is currently active and whether it is valid}

\item{\code{connected}}{(\code{character|NA})\cr
A read-only field describing the connection string used to connect to the database}

\item{\code{connected}}{(\code{character|NA})\cr
A read-only field referecing the username used to connect to the database}

\item{\code{connected}}{(\code{character|NA})\cr
A read-only field describing the name of the connected database}
}
\if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
\itemize{
\item \href{#method-Connection-new}{\code{Connection$new()}}
\item \href{#method-Connection-is.temporary}{\code{Connection$is.temporary()}}
\item \href{#method-Connection-exists}{\code{Connection$exists()}}
\item \href{#method-Connection-run}{\code{Connection$run()}}
\item \href{#method-Connection-query}{\code{Connection$query()}}
\item \href{#method-Connection-execute}{\code{Connection$execute()}}
\item \href{#method-Connection-transaction}{\code{Connection$transaction()}}
\item \href{#method-Connection-exit.transaction}{\code{Connection$exit.transaction()}}
\item \href{#method-Connection-save}{\code{Connection$save()}}
\item \href{#method-Connection-create.from}{\code{Connection$create.from()}}
\item \href{#method-Connection-map.from}{\code{Connection$map.from()}}
\item \href{#method-Connection-grant}{\code{Connection$grant()}}
\item \href{#method-Connection-drop}{\code{Connection$drop()}}
\item \href{#method-Connection-truncate}{\code{Connection$truncate()}}
\item \href{#method-Connection-get.hnd}{\code{Connection$get.hnd()}}
\item \href{#method-Connection-get.profile}{\code{Connection$get.profile()}}
\item \href{#method-Connection-clone}{\code{Connection$clone()}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-new"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-new}{}}}
\subsection{Method \code{new()}}{
Initialise a new connection
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$new(
  username = NA,
  password = NA,
  database = SAILDB.DEF$DATABASE,
  use.profile = getOption("SAILDB.USE.SECRETS", TRUE),
  codepage = getOption("SAILDB.DB2.CODEPAGE", SAILDB.DEF$CODEPAGE.VAL)
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{username}}{(\code{character})\cr
An optional username; defaults to the local machine's username if \code{use.profile} is flagged, otherwise prompts the client to enter their username}

\item{\code{password}}{(\code{character})\cr
An optional password}

\item{\code{database}}{(\code{character})\cr
An optional database name; defaults to \code{SAILDB.DEF$DATABASE} constant}

\item{\code{use.profile}}{(\code{logical})\cr
Specifies whether SAILDB should attempt to grab this database's password from the profile's keychain; defaults to \code{option(SAILDB.USE.PROFILE=TRUE)}

Note: you will be prompted to insert your username/password if we fail your user with any associated with a saildb::Profile keychain. Similarly, if
the connection fails to authenticate you will be prompted to re-enter your username and password}

\item{\code{codepage}}{(\code{integer|NA})\cr
An integer describing the desired database code page, see the \code{saildb::Connection}'s details section for more information on the code pages available. Specifying \code{NA} as the code page will use the client's \code{DB2CODEPAGE} variable; defaults to \code{option(SAILDB.DB2.CODEPAGE = SAILDB.DEF$CODEPAGE.VAL)}, \emph{i.e.} \code{1208L}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A new SAILDB connection
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-is.temporary"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-is.temporary}{}}}
\subsection{Method \code{is.temporary()}}{
Determines whether the given table is temporary or not based on its reference
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$is.temporary(table.reference)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{table.reference}}{(\code{character})\cr
The table schema & name reference in the shape of \code{[SCHEMA].[TABLE]}}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Either (a) a logical reflecting the table's expected temporary status; or (b) an \code{NA} value for an invalid table reference
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-exists"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-exists}{}}}
\subsection{Method \code{exists()}}{
Determines whether a table exists
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$exists(
  table.reference = NA,
  stop.on.error = getOption("SAILDB.THROW.ERRORS", TRUE),
  suppress.logs = getOption("SAILDB.QUIET", FALSE),
  suppress.warnings = getOption("SAILDB.NO.WARN", FALSE)
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{table.reference}}{(\code{character})\cr
The table schema & name reference in the shape of \code{[SCHEMA].[TABLE]}}

\item{\code{stop.on.error}}{(\code{logical})\cr
Whether to return a \code{FALSE} logical when an error is encountered instead of stopping the execution of the parent thread; defaults to \code{option(SAILDB.THROW.ERRORS=TRUE)}}

\item{\code{suppress.logs}}{(\code{logical})\cr
Whether to suppress message logs; defaults to \code{option(SAILDB.QUIET=FALSE)}}

\item{\code{suppress.warnings}}{(\code{logical})\cr
Whether to suppress warnings; defaults to \code{option(SAILDB.NO.WARN=FALSE)}}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Either (a) a logical reflecting a table's existence; or (b) an \code{NA} value for an invalid operation
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-run"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-run}{}}}
\subsection{Method \code{run()}}{
Sends and executes an SQL statement; accepts and handles both \code{SELECT} queries, stored procedure execution, the creation of tables, and/or data manipulation queries
like \code{INSERT} or \code{UPDATE}
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$run(
  stmt = NA,
  stop.on.error = getOption("SAILDB.THROW.ERRORS", TRUE),
  suppress.logs = getOption("SAILDB.QUIET", FALSE),
  suppress.warnings = getOption("SAILDB.NO.WARN", FALSE)
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{stmt}}{(\code{character})\cr
The SQL statement string}

\item{\code{stop.on.error}}{(\code{logical})\cr
Whether to return a \code{FALSE} logical when an error is encountered instead of stopping the execution of the parent thread; defaults to \code{option(SAILDB.THROW.ERRORS=TRUE)}}

\item{\code{suppress.logs}}{(\code{logical})\cr
Whether to suppress message logs; defaults to \code{option(SAILDB.QUIET=FALSE)}}

\item{\code{suppress.warnings}}{(\code{logical})\cr
Whether to suppress warnings; defaults to \code{option(SAILDB.NO.WARN=FALSE)}}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Either:
\enumerate{
\item The resulting data.frame if executing a query \emph{e.g.} a \code{SELECT} statement
\item OR; a logical value reflecting the success if executing a statement \emph{e.g.} an \code{INSERT} statement, or a function call \emph{etc};
}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-query"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-query}{}}}
\subsection{Method \code{query()}}{
Submits and synchronously executes the specified SQL query
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$query(
  stmt = NA,
  stop.on.error = getOption("SAILDB.THROW.ERRORS", TRUE),
  suppress.logs = getOption("SAILDB.QUIET", FALSE),
  suppress.warnings = getOption("SAILDB.NO.WARN", FALSE)
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{stmt}}{(\code{character})\cr
The SQL statement string}

\item{\code{stop.on.error}}{(\code{logical})\cr
Whether to return a \code{FALSE} logical when an error is encountered instead of stopping the execution of the parent thread; defaults to \code{option(SAILDB.THROW.ERRORS=TRUE)}}

\item{\code{suppress.logs}}{(\code{logical})\cr
Whether to suppress message logs; defaults to \code{option(SAILDB.QUIET=FALSE)}}

\item{\code{suppress.warnings}}{(\code{logical})\cr
Whether to suppress warnings; defaults to \code{option(SAILDB.NO.WARN=FALSE)}}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
The resulting data.frame from a \code{SELECT} statement; can return a logical if \code{stop.on.error} behaviour is inactive
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-execute"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-execute}{}}}
\subsection{Method \code{execute()}}{
Submits and synchronously executes an SQL statement
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$execute(
  stmt = NA,
  stop.on.error = getOption("SAILDB.THROW.ERRORS", TRUE),
  suppress.logs = getOption("SAILDB.QUIET", FALSE),
  suppress.warnings = getOption("SAILDB.NO.WARN", FALSE)
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{stmt}}{(\code{character})\cr
The SQL statement string}

\item{\code{stop.on.error}}{(\code{logical})\cr
Whether to return a \code{FALSE} logical when an error is encountered instead of stopping the execution of the parent thread; defaults to \code{option(SAILDB.THROW.ERRORS=TRUE)}}

\item{\code{suppress.logs}}{(\code{logical})\cr
Whether to suppress message logs; defaults to \code{option(SAILDB.QUIET=FALSE)}}

\item{\code{suppress.warnings}}{(\code{logical})\cr
Whether to suppress warnings; defaults to \code{option(SAILDB.NO.WARN=FALSE)}}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
The number of rows affected; can return a logical if \code{stop.on.error} behaviour is inactive
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-transaction"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-transaction}{}}}
\subsection{Method \code{transaction()}}{
Run sequential, synchronous \code{SALIR::Connection} method calls as a transation; rollbacks can be performed by exiting the transaction using the \code{SALIR::Connection$exit.transaction}.
Transactions are automatically committed at the end of the expression assuming no errors have occurred and/or no calls to \code{SALIR::Connection$exit.transaction} have
taken place
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$transaction(
  expr = NA,
  stop.on.error = getOption("SAILDB.THROW.ERRORS", TRUE),
  suppress.logs = getOption("SAILDB.QUIET", FALSE),
  suppress.warnings = getOption("SAILDB.NO.WARN", FALSE)
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{expr}}{(\code{expression})\cr
Some arbitrary transaction expression}

\item{\code{stop.on.error}}{(\code{logical})\cr
Whether to return a \code{FALSE} logical when an error is encountered instead of stopping the execution of the parent thread; defaults to \code{option(SAILDB.THROW.ERRORS=TRUE)}}

\item{\code{suppress.logs}}{(\code{logical})\cr
Whether to suppress message logs; defaults to \code{option(SAILDB.QUIET=FALSE)}}

\item{\code{suppress.warnings}}{(\code{logical})\cr
Whether to suppress warnings; defaults to \code{option(SAILDB.NO.WARN=FALSE)}}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A logical reflecting the success of the transaction
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-exit.transaction"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-exit.transaction}{}}}
\subsection{Method \code{exit.transaction()}}{
Used to exit a transaction and to perform a rollback from within a \code{saildb::Connection$transaction} expression
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$exit.transaction()}\if{html}{\out{</div>}}
}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-save"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-save}{}}}
\subsection{Method \code{save()}}{
Attempt to save a data.frame object to a table; either by creating a new table or appending it to an existing table; note that this operation is transactional, so the statements will
be rolled back if it fails at any point
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$save(
  table.reference = NA,
  table.data = NA,
  can.append = FALSE,
  can.overwrite = FALSE,
  sanitise.columns = TRUE,
  logical.as.integer = TRUE,
  parse.datetimes = FALSE,
  reduce.db.logging = TRUE,
  chunk.size = getOption("SAILDB.CHUNK.SIZE", SAILDB.DEF$MIN.CHUNK.SIZE),
  stop.on.error = getOption("SAILDB.THROW.ERRORS", TRUE),
  suppress.logs = getOption("SAILDB.QUIET", FALSE),
  suppress.warnings = getOption("SAILDB.NO.WARN", FALSE)
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{table.reference}}{(\code{character})\cr
The table schema & name reference in the shape of \code{[SCHEMA].[TABLE]}}

\item{\code{table.data}}{(\code{data.frame})\cr
The data.frame you wish to save}

\item{\code{can.append}}{(\code{logical})\cr
Whether to append to the table if it already exists; defaults to \code{FALSE}}

\item{\code{can.overwrite}}{(\code{logical})\cr
Whether to truncate and overwrite the table if it already exists; defaults to \code{FALSE}}

\item{\code{sanitise.columns}}{(\code{logical})\cr
Whether to strip all non-DB2 compliant characters from a column's name; defaults to \code{TRUE}}

\item{\code{logical.as.integer}}{(\code{logical})\cr
Whether to insert logical types as a \code{SMALLINT} datatype; otherwise resolves to a \code{VARCHAR} type; defaults to \code{TRUE}}

\item{\code{parse.datetimes}}{(\code{logical})\cr
Whether to attempt to parse character columns as one of \code{[ DATE | TIME | TIMESTAMP ]}; defaults to \code{FALSE}}

\item{\code{reduce.db.logging}}{(\code{logical})\cr
Alters global tables to stop initial logging; defaults to \code{TRUE}}

\item{\code{chunk.size}}{(\code{integer})\cr
Determines the size of insert statement chunks; defaults to \code{option(SAILDB.CHUNK.SIZE=SAILDB.DEF$MIN.CHUNK.SIZE)}}

\item{\code{stop.on.error}}{(\code{logical})\cr
Whether to return a \code{FALSE} logical when an error is encountered instead of stopping the execution of the parent thread; defaults to \code{option(SAILDB.THROW.ERRORS=TRUE)}}

\item{\code{suppress.logs}}{(\code{logical})\cr
Whether to suppress message logs; defaults to \code{option(SAILDB.QUIET=FALSE)}}

\item{\code{suppress.warnings}}{(\code{logical})\cr
Whether to suppress warnings; defaults to \code{option(SAILDB.NO.WARN=FALSE)}}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A logical describing the success of the action
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-create.from"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-create.from}{}}}
\subsection{Method \code{create.from()}}{
Wrapper method to create a new table from a \code{SELECT} statement; note that this operation is transactional, so the statements will
be rolled back if it fails at any point
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$create.from(
  table.reference = NA,
  stmt = NA,
  can.append = FALSE,
  can.overwrite = FALSE,
  reduce.db.logging = TRUE,
  stop.on.error = getOption("SAILDB.THROW.ERRORS", TRUE),
  suppress.logs = getOption("SAILDB.QUIET", FALSE),
  suppress.warnings = getOption("SAILDB.NO.WARN", FALSE)
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{table.reference}}{(\code{character})\cr
The table schema & name reference in the shape of \code{[SCHEMA].[TABLE]}}

\item{\code{stmt}}{(\code{character})\cr
The select query used to build your cloned table}

\item{\code{can.append}}{(\code{logical})\cr
Whether to append to the table if it already exists; defaults to \code{FALSE}}

\item{\code{can.overwrite}}{(\code{logical})\cr
Whether to truncate and overwrite the table if it already exists; defaults to \code{FALSE}}

\item{\code{reduce.db.logging}}{(\code{logical})\cr
Alters global tables to stop initial logging; defaults to \code{TRUE}}

\item{\code{stop.on.error}}{(\code{logical})\cr
Whether to return a \code{FALSE} logical when an error is encountered instead of stopping the execution of the parent thread; defaults to \code{option(SAILDB.THROW.ERRORS=TRUE)}}

\item{\code{suppress.logs}}{(\code{logical})\cr
Whether to suppress message logs; defaults to \code{option(SAILDB.QUIET=FALSE)}}

\item{\code{suppress.warnings}}{(\code{logical})\cr
Whether to suppress warnings; defaults to \code{option(SAILDB.NO.WARN=FALSE)}}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A logical describing the success of the action
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-map.from"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-map.from}{}}}
\subsection{Method \code{map.from()}}{
Wrapper method to create a new table from another table whilst mapping its columns to a different subset; note that this operation is transactional, so the statements will
be rolled back if it fails at any point
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$map.from(
  input.reference = NA,
  output.reference = NA,
  output.map = NA,
  can.overwrite = FALSE,
  reduce.db.logging = TRUE,
  stop.on.error = getOption("SAILDB.THROW.ERRORS", TRUE),
  suppress.logs = getOption("SAILDB.QUIET", FALSE),
  suppress.warnings = getOption("SAILDB.NO.WARN", FALSE)
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{input.reference}}{(\code{character})\cr
The input table to clone from in the shape of \code{[SCHEMA].[TABLE]}}

\item{\code{output.reference}}{(\code{character})\cr
The output table to map into, in the shape of \code{[SCHEMA].[TABLE]}}

\item{\code{output.map}}{(\code{list})\cr
A list of key-value pair characters describing the column name mapping and/or a subset of columns}

\item{\code{can.overwrite}}{(\code{logical})\cr
Whether to truncate and overwrite the table if it already exists; defaults to \code{FALSE}}

\item{\code{reduce.db.logging}}{(\code{logical})\cr
Alters global tables to stop initial logging; defaults to \code{TRUE}}

\item{\code{stop.on.error}}{(\code{logical})\cr
Whether to return a \code{FALSE} logical when an error is encountered instead of stopping the execution of the parent thread; defaults to \code{option(SAILDB.THROW.ERRORS=TRUE)}}

\item{\code{suppress.logs}}{(\code{logical})\cr
Whether to suppress message logs; defaults to \code{option(SAILDB.QUIET=FALSE)}}

\item{\code{suppress.warnings}}{(\code{logical})\cr
Whether to suppress warnings; defaults to \code{option(SAILDB.NO.WARN=FALSE)}}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A logical describing the success of the operation
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-grant"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-grant}{}}}
\subsection{Method \code{grant()}}{
Attempts to grant \code{SELECT} on the specified schema, or tables, to the specified user(s)
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$grant(
  schema = NA,
  tables = NA,
  users = NA,
  stop.on.error = getOption("SAILDB.THROW.ERRORS", TRUE),
  suppress.logs = getOption("SAILDB.QUIET", FALSE),
  suppress.warnings = getOption("SAILDB.NO.WARN", FALSE)
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{schema}}{(\code{character})\cr
The schema name}

\item{\code{tables}}{(\verb{character|list<character>})\cr
An optional list/vector of table names to grant access to; in the shape of either (a) a scalar character, (b) a character vector, or (c) a list of characters}

\item{\code{users}}{(\verb{character|list<character>})\cr
A list of users to grant \code{SELECT} permission to}

\item{\code{stop.on.error}}{(\code{logical})\cr
Whether to return a \code{FALSE} logical when an error is encountered instead of stopping the execution of the parent thread; defaults to \code{option(SAILDB.THROW.ERRORS=TRUE)}}

\item{\code{suppress.logs}}{(\code{logical})\cr
Whether to suppress message logs; defaults to \code{option(SAILDB.QUIET=FALSE)}}

\item{\code{suppress.warnings}}{(\code{logical})\cr
Whether to suppress warnings; defaults to \code{option(SAILDB.NO.WARN=FALSE)}}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A logical that describes whether the action was successful
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-drop"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-drop}{}}}
\subsection{Method \code{drop()}}{
Attempts to drop a table
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$drop(
  table.reference = NA,
  ignore.extinct = TRUE,
  use.udf = getOption("SAILDB.DROP.UDF", TRUE),
  stop.on.error = getOption("SAILDB.THROW.ERRORS", TRUE),
  suppress.logs = getOption("SAILDB.QUIET", FALSE),
  suppress.warnings = getOption("SAILDB.NO.WARN", FALSE)
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{table.reference}}{(\code{character})\cr
The table schema & name reference in the shape of \code{[SCHEMA].[TABLE]}}

\item{\code{ignore.extinct}}{(\code{logical})\cr
Whether to ignore non-existent tables; defaults to \code{TRUE}}

\item{\code{use.udf}}{(\code{logical})\cr
Whether to use the user-defined \code{DROP_IF_EXISTS} function found in the \code{PR_SAIL} database; defaults to \code{option(SAILDB.DROP.BY.UDF=TRUE)}}

\item{\code{stop.on.error}}{(\code{logical})\cr
Whether to return a \code{FALSE} logical when an error is encountered instead of stopping the execution of the parent thread; defaults to \code{option(SAILDB.THROW.ERRORS=TRUE)}}

\item{\code{suppress.logs}}{(\code{logical})\cr
Whether to suppress message logs; defaults to \code{option(SAILDB.QUIET=FALSE)}}

\item{\code{suppress.warnings}}{(\code{logical})\cr
Whether to suppress warnings; defaults to \code{option(SAILDB.NO.WARN=FALSE)}}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A logical that describes whether the action was successful
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-truncate"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-truncate}{}}}
\subsection{Method \code{truncate()}}{
Attempts to truncate a table
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$truncate(
  table.reference = NA,
  reuse.storage = FALSE,
  obey.del.triggers = FALSE,
  stop.on.error = getOption("SAILDB.THROW.ERRORS", TRUE),
  suppress.logs = getOption("SAILDB.QUIET", FALSE),
  suppress.warnings = getOption("SAILDB.NO.WARN", FALSE)
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{table.reference}}{(\code{character})\cr
The table schema & name reference in the shape of \code{[SCHEMA].[TABLE]}}

\item{\code{reuse.storage}}{(\code{logical})\cr
Whether to specify that all storage allocated to this table will continue to be allocated for the same table; defaults to \code{FALSE}}

\item{\code{obey.del.triggers}}{(\code{logical})\cr
Whether to specify that we want to throw an error if delete triggers are defined for this table; defaults to \code{FALSE}}

\item{\code{stop.on.error}}{(\code{logical})\cr
Whether to return a \code{FALSE} logical when an error is encountered instead of stopping the execution of the parent thread; defaults to \code{option(SAILDB.THROW.ERRORS=TRUE)}}

\item{\code{suppress.logs}}{(\code{logical})\cr
Whether to suppress message logs; defaults to \code{option(SAILDB.QUIET=FALSE)}}

\item{\code{suppress.warnings}}{(\code{logical})\cr
Whether to suppress warnings; defaults to \code{option(SAILDB.NO.WARN=FALSE)}}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A logical that describes whether the action was successful
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-get.hnd"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-get.hnd}{}}}
\subsection{Method \code{get.hnd()}}{
Attempts to retrieve the stored ODBC handle
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$get.hnd()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
Either (a) the stored \code{DBIConnection} handle of type \code{S4}; or (b) if not connected: \code{NA}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-get.profile"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-get.profile}{}}}
\subsection{Method \code{get.profile()}}{
Attempts to retrieve the stored \code{saildb::Profile}
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$get.profile()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
Either (a) the stored \code{saildb::Profile} of type \code{R6} if initialised; or (b) \code{NA}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Connection-clone"></a>}}
\if{latex}{\out{\hypertarget{method-Connection-clone}{}}}
\subsection{Method \code{clone()}}{
The objects of this class are cloneable with this method.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Connection$clone(deep = FALSE)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{deep}}{Whether to make a deep clone.}
}
\if{html}{\out{</div>}}
}
}
}