dbProject: database connection and table management

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.

See also

conn() S4 generic for dbData objects

Methods

Public methods

• dbProject$new()

• dbProject$disconnect()

• dbProject$reconnect()

• dbProject$set_dbdir()

• dbProject$get_conn()

• dbProject$get_board()

• dbProject$pin_write()

• dbProject$pin_delete()

• dbProject$pin_read()

• dbProject$restore()

• dbProject$dbRemoveTable()

• dbProject$dbRemoveView()

• dbProject$print()

• dbProject$is_connected()

• dbProject$clone()

---

Method new()

Create a new dbProject object.

Usage

dbProject$new(path, ...)

Arguments

path

A character string specifying the folder path for pins.

...

Additional arguments passed to connections::connection_open()

---

Method disconnect()

Close the current connection, if any.

Usage

dbProject$disconnect()

---

Method reconnect()

Reconnect to the database in the project.

Usage

dbProject$reconnect()

---

Method set_dbdir()

Update the project's cached DuckDB database path.

Usage

dbProject$set_dbdir(dbdir)

Arguments

dbdir

Path to the DuckDB database file.

Details

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.

---

Method get_conn()

Retrieve the DBI connection from the project, reconnecting if necessary.

Usage

dbProject$get_conn()

Returns

A DBIConnection object for direct database operations.

---

Method get_board()

Return the pins::board_folder() object used by the project.

Usage

dbProject$get_board()

Returns

The pins::board_folder() object.

---

Method pin_write()

Write a lazy database tbl to the project.

Usage

dbProject$pin_write(x, name)

Arguments

x

A dplyr::tbl object to be written to the board.

name

A character string specifying the name of the pin.

Returns

The materialized object (for dbMatrix or dbSpatial objects) pointing to permanent table, or invisibly returns the dbProject object for other types.

---

Method pin_delete()

Delete a pin from the project.

Usage

dbProject$pin_delete(name, ...)

Arguments

name

A character string specifying the name of the pin to delete.

...

Additional arguments passed to pins::pin_delete().

Returns

Invisibly returns the dbProject object for method chaining.

---

Method pin_read()

Read a pinned object from the project's board.

Usage

dbProject$pin_read(name)

Arguments

name

A character string specifying the name of the pin.

Returns

The object stored in the specified pin.

---

Method restore()

Restore all pins from the board manifest.

Usage

dbProject$restore()

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.

Returns

A named list of restored pinned objects (excluding the connection).

Examples

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 dbRemoveTable()

Remove a table from the connected database

Usage

dbProject$dbRemoveTable(name)

Arguments

name

A character string specifying the name of the table to remove

Returns

Invisibly returns the dbProject object for method chaining

---

Method dbRemoveView()

Remove a view from the connected database

Usage

dbProject$dbRemoveView(name)

Arguments

name

A character string specifying the name of the table to remove

Returns

Invisibly returns the dbProject object for method chaining

---

Method print()

Print summary information, including connection status, path, and board details.

Usage

dbProject$print(...)

Arguments

...

Unused arguments (for consistency with generic print method)

---

Method is_connected()

Check if there is an active database connection.

Usage

dbProject$is_connected()

Returns

A logical value indicating whether the project has an active connection.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

dbProject$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

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

project_path <- tempfile("dbproject-")
proj <- dbProject$new(path = project_path)
#> Creating new version '20260602T145728Z-72241'
#> Writing to pin 'cachedConnection'
#> Manifest file written to root folder of board, as `_pins.yaml`
proj$pin_write(data.frame(id = 1:3), "example")
#> Guessing `type = 'rds'`
#> Creating new version '20260602T145728Z-de4f9'
#> Writing to pin 'example'
#> Manifest file written to root folder of board, as `_pins.yaml`
restored <- proj$restore()
#> 
#> Attaching package: ‘connections’
#> The following objects are masked from ‘package:dbProject’:
#> 
#>     connection_pin_read, read_pin_conn, write_pin_conn
#> Loading required package: DBI
names(restored)
#> [1] "example"
proj$disconnect()
unlink(project_path, recursive = TRUE)