| Title: | Database Connection Management and Utilities for 'dbverse' |
|---|---|
| Description: | Provides an R6-based project container for managing 'DuckDB' connections, reconnecting lazy database tables after session restarts, and storing metadata for database-backed objects used by packages in the 'dbverse'. The package supplies S4 base classes and generics for database-backed data, helpers for validating 'DuckDB' connections and table names, utilities for creating persistent database views, and methods for writing and restoring pinned lazy tables through the 'pins' package. These tools help package authors and analysts keep database paths, cached connections, and table references synchronized across interactive sessions and project directories. |
| Authors: | Edward C. Ruiz [aut, cre] (ORCID: <https://orcid.org/0000-0002-9174-5387>), Jiaji George Chen [aut], Ruben Dries [aut] |
| Maintainer: | Edward C. Ruiz <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.1 |
| Built: | 2026-06-02 18:55:44 UTC |
| Source: | https://github.com/cran/dbProject |
Read a pinned dbMatrix object from a board
connection_pin_read(board, name, version = NULL)connection_pin_read(board, name, version = NULL)
board |
A pins board object |
name |
The name of the pin |
version |
The version of the pin to get (optional) |
A dbMatrix object (dbSparseMatrix or dbDenseMatrix)
dbData is a virtual base class for database-backed objects in the dbverse ecosystem.
This class provides a common interface for objects that are backed by database tables.
It is extended by concrete classes like dbMatrix and dbSpatial that provide specific
implementations.
valuetbl_duckdb_connection that represents the data in the database
namename of table within database that contains the data
When creating a new type of database-backed object, extend this class to ensure compatibility with the dbverse ecosystem.
These methods provide a unified interface for accessing and setting database connections across all dbverse packages. They handle different connection storage patterns across various subclasses.
Get or set the database connection for a dbData object.
conn(x) conn(x) <- value ## S4 method for signature 'dbData' conn(x) ## S4 replacement method for signature 'dbData' conn(x) <- valueconn(x) conn(x) <- value ## S4 method for signature 'dbData' conn(x) ## S4 replacement method for signature 'dbData' conn(x) <- value
x |
A |
value |
A |
The connection accessor methods support multiple implementation patterns:
Nested connection: Some classes (like dbMatrix) store connections in value$src$con
dbplyr connections: Objects with tbl_duckdb_connection values can use dbplyr::remote_con()
The implementation automatically tries these access patterns in order of specificity, falling back to more generic approaches if needed.
Auto-reconnects if the current connection is invalid.
For getter: The database connection. For setter: The updated object
For getter: DBIConnection. For setter: Updated object.
Provides extraction ([) and replacement ([<-) methods for dbData objects.
The extractor attempts to auto-reconnect via dbReconnect() before returning
the underlying database-backed value.
x |
A |
... |
Additional arguments passed to the extractor. |
value |
Replacement value for |
For [: the underlying value stored in the object. For [<-: the updated dbData.
A generic function to list tables, temporary tables, and views in a database connection. This provides an enhanced view over DBI::dbListTables with categorization.
dbList(conn, ...)dbList(conn, ...)
conn |
A DBI database connection |
... |
Additional arguments passed to methods |
Method implementations may return different formats, typically a categorized list
Pretty prints tables, temporary tables, and views in the database.
## S4 method for signature 'DBIConnection' dbList(conn)## S4 method for signature 'DBIConnection' dbList(conn)
conn |
A DBIConnection object, as returned by |
Similar to DBI::dbListTables, but categorizes tables into three categories:
Tables
Temporary Tables (these will be removed when the connection is closed)
Views (these may be removed when the connection is closed)
Generic function to reconstruct dbverse objects (dbMatrix, dbSpatial, etc.) from tables stored in a database connection.
dbLoad(conn, name, class, ...)dbLoad(conn, name, class, ...)
conn |
A DBI database connection |
name |
Character name of the table/view in the database |
class |
Character class name of the object to load (e.g., "dbMatrix", "dbSpatial") |
... |
Additional arguments passed to specific methods |
A dbverse object of the specified class
R6 class for managing DuckDB connections and pinning lazy database tables.
Wraps a pins::board_folder() with a cached connection object stored as
"cachedConnection" for automatic reconnection.
new()
Create a new dbProject object.
dbProject$new(path, ...)
pathA character string specifying the folder path for pins.
...Additional arguments passed to connections::connection_open()
disconnect()
Close the current connection, if any.
dbProject$disconnect()
reconnect()
Reconnect to the database in the project.
dbProject$reconnect()
set_dbdir()
Update the project's cached DuckDB database path.
dbProject$set_dbdir(dbdir)
dbdirPath to the DuckDB database file.
Overwrites the "cachedConnection" pin with a connection that uses the
provided dbdir. Uses forced evaluation to avoid pins restoring a
connection that references an out-of-scope variable.
get_conn()
Retrieve the DBI connection from the project, reconnecting if necessary.
dbProject$get_conn()
A DBIConnection object for direct database operations.
get_board()
Return the pins::board_folder() object used by the project.
dbProject$get_board()
The pins::board_folder() object.
pin_write()
Write a lazy database tbl to the project.
dbProject$pin_write(x, name)
xA dplyr::tbl object to be written to the board.
nameA character string specifying the name of the pin.
The materialized object (for dbMatrix or dbSpatial objects) pointing to permanent table, or invisibly returns the dbProject object for other types.
pin_delete()
Delete a pin from the project.
dbProject$pin_delete(name, ...)
nameA character string specifying the name of the pin to delete.
...Additional arguments passed to pins::pin_delete().
Invisibly returns the dbProject object for method chaining.
pin_read()
Read a pinned object from the project's board.
dbProject$pin_read(name)
nameA character string specifying the name of the pin.
The object stored in the specified pin.
restore()
Restore all pins from the board manifest.
dbProject$restore()
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.
A named list of restored pinned objects (excluding the connection).
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)
dbRemoveTable()
Remove a table from the connected database
dbProject$dbRemoveTable(name)
nameA character string specifying the name of the table to remove
Invisibly returns the dbProject object for method chaining
dbRemoveView()
Remove a view from the connected database
dbProject$dbRemoveView(name)
nameA character string specifying the name of the table to remove
Invisibly returns the dbProject object for method chaining
print()
Print summary information, including connection status, path, and board details.
dbProject$print(...)
...Unused arguments (for consistency with generic print method)
is_connected()
Check if there is an active database connection.
dbProject$is_connected()
A logical value indicating whether the project has an active connection.
clone()
The objects of this class are cloneable with this method.
dbProject$clone(deep = FALSE)
deepWhether to make a deep clone.
conn() S4 generic for dbData objects
## ------------------------------------------------ ## 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)## ------------------------------------------------ ## 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)
Reconnects invalid database connections for dbData objects, updating the object with the new valid connection.
dbReconnect(x) ## S4 method for signature 'dbData' dbReconnect(x) ## S4 method for signature 'DBIConnection' dbReconnect(x) ## S4 method for signature 'connConnection' dbReconnect(x)dbReconnect(x) ## S4 method for signature 'dbData' dbReconnect(x) ## S4 method for signature 'DBIConnection' dbReconnect(x) ## S4 method for signature 'connConnection' dbReconnect(x)
x |
A dbData object |
The dbData object with an updated connection
Generic function for reading connection objects from a pins board
read_pin_conn(x)read_pin_conn(x)
x |
A pinned connection object |
S3 method for reading dbMatrix objects from a pins board. Reconstructs the full dbMatrix object.
## S3 method for class 'conn_matrix_table' read_pin_conn(x)## S3 method for class 'conn_matrix_table' read_pin_conn(x)
x |
A pinned conn_matrix_table object |
A dbMatrix object (dbSparseMatrix or dbDenseMatrix)
Read a pinned dbSpatial object from a pins board
## S3 method for class 'conn_spatial_table' read_pin_conn(x)## S3 method for class 'conn_spatial_table' read_pin_conn(x)
x |
A pinned conn_spatial_table object |
A dbSpatial object
Convert lazy table to named view
to_view(x, name, temporary = TRUE, overwrite = TRUE, ...)to_view(x, name, temporary = TRUE, overwrite = TRUE, ...)
x |
A lazy table object (tbl_duckdb_connection) |
name |
Character name to assign view within database |
temporary |
Logical, if TRUE (default), the view will be deleted after the session ends |
overwrite |
Logical, if TRUE (default), the view will overwrite an existing view |
... |
Additional arguments passed to DBI::dbExecute |
Convert lazy table to named VIEW
## S4 method for signature 'ANY' to_view(x, name, temporary = TRUE, overwrite = TRUE, ...)## S4 method for signature 'ANY' to_view(x, name, temporary = TRUE, overwrite = TRUE, ...)
x |
|
name |
|
temporary |
|
overwrite |
|
... |
Additional arguments passed to |
Generic function for writing connection objects to a pins board
write_pin_conn(x, board, ...)write_pin_conn(x, board, ...)
x |
Object to write |
board |
A pins board object |
... |
Additional arguments passed to methods |
S3 method for writing dbMatrix objects to a pins board while maintaining connection state and metadata consistent with the connections package.
## S3 method for class 'dbMatrix' write_pin_conn(x, board, name, ...)## S3 method for class 'dbMatrix' write_pin_conn(x, board, name, ...)
x |
A dbMatrix object (dbSparseMatrix or dbDenseMatrix) |
board |
A pins |
name |
Name for the pin (required) |
... |
Additional arguments passed to |
Invisibly returns the input object
Write a dbSpatial object to a pins board
## S3 method for class 'dbSpatial' write_pin_conn(x, board, name, ...)## S3 method for class 'dbSpatial' write_pin_conn(x, board, name, ...)
x |
A dbSpatial object |
board |
A pins board object |
name |
Name for the pin |
... |
Additional arguments passed to pins::pin_write |
Invisibly returns the input object
Fallback method for non-database objects. Delegates directly to pins::pin_write() for regular R objects (matrices, data.frames, vectors, etc.)
## Default S3 method: write_pin_conn(x, board, ...)## Default S3 method: write_pin_conn(x, board, ...)
x |
Any R object |
board |
A pins board object |
... |
Additional arguments passed to pins::pin_write() |
Invisibly returns the input object