% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dbProject-R6.R
\name{dbProject}
\alias{dbProject}
\title{dbProject: database connection and table management}
\description{
R6 class for managing DuckDB connections and pinning lazy database tables.
Wraps a \code{\link[pins:board_folder]{pins::board_folder()}} with a cached connection object stored as
"cachedConnection" for automatic reconnection.
}
\examples{

## ------------------------------------------------
## Method `dbProject$restore`
## ------------------------------------------------

project_path <- tempfile("dbproject-")
proj <- dbProject$new(path = project_path)
proj$pin_write(data.frame(id = 1:3), "example")
restored <- proj$restore()
names(restored)
proj$disconnect()
unlink(project_path, recursive = TRUE)
}
\seealso{
\code{\link[=conn]{conn()}} S4 generic for dbData objects
}
\section{Methods}{
\subsection{Public methods}{
\itemize{
\item \href{#method-dbProject-new}{\code{dbProject$new()}}
\item \href{#method-dbProject-disconnect}{\code{dbProject$disconnect()}}
\item \href{#method-dbProject-reconnect}{\code{dbProject$reconnect()}}
\item \href{#method-dbProject-set_dbdir}{\code{dbProject$set_dbdir()}}
\item \href{#method-dbProject-get_conn}{\code{dbProject$get_conn()}}
\item \href{#method-dbProject-get_board}{\code{dbProject$get_board()}}
\item \href{#method-dbProject-pin_write}{\code{dbProject$pin_write()}}
\item \href{#method-dbProject-pin_delete}{\code{dbProject$pin_delete()}}
\item \href{#method-dbProject-pin_read}{\code{dbProject$pin_read()}}
\item \href{#method-dbProject-restore}{\code{dbProject$restore()}}
\item \href{#method-dbProject-dbRemoveTable}{\code{dbProject$dbRemoveTable()}}
\item \href{#method-dbProject-dbRemoveView}{\code{dbProject$dbRemoveView()}}
\item \href{#method-dbProject-print}{\code{dbProject$print()}}
\item \href{#method-dbProject-is_connected}{\code{dbProject$is_connected()}}
\item \href{#method-dbProject-clone}{\code{dbProject$clone()}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-new"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-new}{}}}
\subsection{Method \code{new()}}{
Create a new dbProject object.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$new(path, ...)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{path}}{A character string specifying the folder path for pins.}

\item{\code{...}}{Additional arguments passed to \code{\link[connections:connection_open]{connections::connection_open()}}}
}
\if{html}{\out{</div>}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-disconnect"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-disconnect}{}}}
\subsection{Method \code{disconnect()}}{
Close the current connection, if any.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$disconnect()}\if{html}{\out{</div>}}
}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-reconnect"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-reconnect}{}}}
\subsection{Method \code{reconnect()}}{
Reconnect to the database in the project.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$reconnect()}\if{html}{\out{</div>}}
}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-set_dbdir"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-set_dbdir}{}}}
\subsection{Method \code{set_dbdir()}}{
Update the project's cached DuckDB database path.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$set_dbdir(dbdir)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{dbdir}}{Path to the DuckDB database file.}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
Overwrites the "cachedConnection" pin with a connection that uses the
provided \code{dbdir}. Uses forced evaluation to avoid pins restoring a
connection that references an out-of-scope variable.
}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-get_conn"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-get_conn}{}}}
\subsection{Method \code{get_conn()}}{
Retrieve the DBI connection from the project, reconnecting if necessary.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$get_conn()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
A \code{DBIConnection} object for direct database operations.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-get_board"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-get_board}{}}}
\subsection{Method \code{get_board()}}{
Return the \code{\link[pins:board_folder]{pins::board_folder()}} object used by the project.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$get_board()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
The \code{\link[pins:board_folder]{pins::board_folder()}} object.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-pin_write"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-pin_write}{}}}
\subsection{Method \code{pin_write()}}{
Write a lazy database tbl to the project.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$pin_write(x, name)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{x}}{A \code{\link[dplyr:tbl]{dplyr::tbl}} object to be written to the board.}

\item{\code{name}}{A character string specifying the name of the pin.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
The materialized object (for dbMatrix or dbSpatial objects) pointing to permanent table,
or invisibly returns the dbProject object for other types.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-pin_delete"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-pin_delete}{}}}
\subsection{Method \code{pin_delete()}}{
Delete a pin from the project.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$pin_delete(name, ...)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{name}}{A character string specifying the name of the pin to delete.}

\item{\code{...}}{Additional arguments passed to \code{\link[pins:pin_delete]{pins::pin_delete()}}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly returns the dbProject object for method chaining.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-pin_read"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-pin_read}{}}}
\subsection{Method \code{pin_read()}}{
Read a pinned object from the project's board.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$pin_read(name)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{name}}{A character string specifying the name of the pin.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
The object stored in the specified pin.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-restore"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-restore}{}}}
\subsection{Method \code{restore()}}{
Restore all pins from the board manifest.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$restore()}\if{html}{\out{</div>}}
}

\subsection{Details}{
Reads the board manifest and restores the cached connection and all
pinned objects. The connection is restored internally, while other
pinned objects are returned as a named list for the user to assign.
}

\subsection{Returns}{
A named list of restored pinned objects (excluding the connection).
}
\subsection{Examples}{
\if{html}{\out{<div class="r example copy">}}
\preformatted{project_path <- tempfile("dbproject-")
proj <- dbProject$new(path = project_path)
proj$pin_write(data.frame(id = 1:3), "example")
restored <- proj$restore()
names(restored)
proj$disconnect()
unlink(project_path, recursive = TRUE)
}
\if{html}{\out{</div>}}

}

}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-dbRemoveTable"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-dbRemoveTable}{}}}
\subsection{Method \code{dbRemoveTable()}}{
Remove a table from the connected database
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$dbRemoveTable(name)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{name}}{A character string specifying the name of the table to remove}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly returns the dbProject object for method chaining
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-dbRemoveView"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-dbRemoveView}{}}}
\subsection{Method \code{dbRemoveView()}}{
Remove a view from the connected database
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$dbRemoveView(name)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{name}}{A character string specifying the name of the table to remove}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly returns the dbProject object for method chaining
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-print"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-print}{}}}
\subsection{Method \code{print()}}{
Print summary information, including connection status, path, and board details.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$print(...)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{...}}{Unused arguments (for consistency with generic print method)}
}
\if{html}{\out{</div>}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-is_connected"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-is_connected}{}}}
\subsection{Method \code{is_connected()}}{
Check if there is an active database connection.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$is_connected()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
A logical value indicating whether the project has an active connection.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-dbProject-clone"></a>}}
\if{latex}{\out{\hypertarget{method-dbProject-clone}{}}}
\subsection{Method \code{clone()}}{
The objects of this class are cloneable with this method.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{dbProject$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>}}
}
}
}
