The Engine class is a core component of the oRm framework, responsible for managing database connections and providing methods for interacting with the database. It supports both direct connections and connection pooling, offering flexibility in how database resources are managed.
Key features:
Manages database connections (single or pooled)
Provides methods for executing SQL queries and commands
Allows creation of TableModel objects for ORM operations
Supports persistent connections for improved performance
See also
[TableModel::new()]
[Engine$model()], [reflect_columns()]
[Engine$reflect()], [define_relationship()], [reflect_tables()]
[TableModel$print()], [Record$print()].
Public fields
conn_argsA list of arguments for establishing a connection
connActive database connection or pool
use_poolWhether to use connection pooling
persistWhether to keep connections open between operations
dialectDatabase dialect in use
schemaDefault schema applied to tables
Methods
Method new()
Create an Engine object
Arguments
...Additional arguments to be passed to DBI::dbConnect
conn_argsA list of arguments to be passed to DBI::dbConnect
.schemaCharacter. The default schema to apply to child TableModel objects
.read_onlyLogical. If TRUE, the engine refuses non-SELECT statements and applies dialect-specific connection-level read-only enforcement (SQLite: `SQLITE_RO` open flag; PostgreSQL: `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY`; MySQL: `SET SESSION TRANSACTION READ ONLY`).
use_poolLogical. Whether or not to make use of the pool package for connections to this engine
persistLogical. Whether to keep the connection open after operations (default: FALSE)
.dialectCharacter. Overrides automatic dialect detection, e.g. `"mssql"`. Needed when the driver cannot identify the backend on its own: every `odbc::odbc()` connection shares one driver class, so SQL Server is only auto-detected when the connection arguments name it. Any dialect string is accepted, so third-party dialects can be selected the same way.
.autoflushLogical. The default value of `flush_record` for [Record$create()] calls made inside a transaction (default: FALSE, a plain insert that leaves server-generated values unset). Set `TRUE` to have every create inside a [with.Engine()] block return its IDENTITY/SERIAL key and column defaults without having to ask per block. Individual blocks and creates can still override it, and creates outside a transaction always flush. Get a connection to the database
Reapplies the configured schema on every connection retrieval to ensure consistency after reconnects.
Method set_schema()
Set the default schema for the engine and active connection
Method create_schema()
Explicitly create a schema in the database
Method check_schema_exists()
Check if a schema exists in the database
Method model()
Create a new TableModel object for the specified table
Usage
Engine$model(
tablename,
...,
.data = list(),
.schema = NULL,
.default_mode = "all"
)Arguments
tablenameName of the table
...Additional arguments passed to the TableModel constructor. Include `Column` objects here to define the table structure.
.dataA named list of the arguments for the TableModel constructor. `Column` objects in this list also define table structure.
.schemaCharacter. The default schema to apply to the TableModel object
.default_modeCharacter. Default read mode for the TableModel.
Method reflect()
Build a TableModel by introspecting an existing database table.
Inspects the columns of an existing table and returns a ready-to-use TableModel, so basic CRUD is possible without pre-defining columns. The default reflection is best-effort and dialect-agnostic (column names and reported types only; see [reflect_columns()]). The PostgreSQL dialect reflects richer metadata: canonical types, primary keys, nullability, defaults, and foreign keys (as [ForeignKey] objects).
Usage
Engine$reflect(
tablename,
...,
include = NULL,
exclude = NULL,
.schema = NULL,
.default_mode = "all"
)Arguments
tablenameName of the existing table to reflect.
...Additional `Column`, `ForeignKey`, or `Method` objects to merge in. These take precedence over reflected columns of the same name, matching the behaviour of `model()`.
includeOptional character vector of column names to keep.
excludeOptional character vector of column names to drop.
.schemaCharacter. The default schema to apply to the TableModel.
.default_modeCharacter. Default read mode for the TableModel.
Method reflect_schema()
Reflect several tables from a schema at once and wire up the relationships implied by their foreign keys.
Each table is reflected via [Engine$reflect()]; afterwards, every reflected [ForeignKey] whose target is also among the reflected models is turned into a `many_to_one` relationship (with the reverse `one_to_many` backref) using [define_relationship()]. Foreign keys pointing at tables outside the reflected set are skipped with a warning. This is most useful with the PostgreSQL dialect, whose reflection captures foreign keys.
Usage
Engine$reflect_schema(
tables = NULL,
...,
.schema = NULL,
exclude = NULL,
.default_mode = "all",
wire_relationships = TRUE
)Arguments
tablesOptional character vector limiting which tables to reflect. When `NULL`, all tables in the schema are reflected (see [reflect_tables()]).
...Additional `Column`, `ForeignKey`, or `Method` objects passed to every `reflect()` call (overrides of reflected columns).
.schemaCharacter. Schema to reflect. Defaults to the engine schema.
excludeOptional character vector of table names to drop.
.default_modeCharacter. Default read mode for each TableModel.
wire_relationshipsLogical. Whether to auto-wire relationships from reflected foreign keys. Defaults to TRUE.
Method set_autoflush()
Set the flush default that [Record$create()] uses while a transaction is open, overriding the engine's `.autoflush` setting for the rest of the session. [with.Engine()] uses this to apply its own `.autoflush` argument for the duration of a block, restoring the previous value on exit. It is not read outside a transaction, where creates always flush.
Method set_transaction_connection()
Pin a single connection for the duration of a transaction so that [with.Engine()] and every operation inside the block share one connection. Used internally for pooled engines, where each call would otherwise check out a different connection. Pass `NULL` to clear.
Method push_savepoint()
Reserve a fresh savepoint name for a nested transaction block and bump the nesting depth.
Method qualify()
Qualify a table name with a schema
Method print()
Print a concise summary of the engine, including the SQL dialect, default schema, and connection status.
Examples
## ------------------------------------------------
## Method `Engine$model`
## ------------------------------------------------
# \donttest{
engine$model(
"users",
Column$new("id", "integer"),
Column$new("name", "text")
)
#> Error: object 'engine' not found
# }
## ------------------------------------------------
## Method `Engine$reflect`
## ------------------------------------------------
# \donttest{
# Given a table "users" that already exists in the database:
Users <- engine$reflect("users")
#> Error: object 'engine' not found
Users <- engine$reflect("users", include = c("id", "name"))
#> Error: object 'engine' not found
Users <- engine$reflect("users", exclude = c("hash", "configuration"))
#> Error: object 'engine' not found
# }
## ------------------------------------------------
## Method `Engine$reflect_schema`
## ------------------------------------------------
# \donttest{
models <- engine$reflect_schema()
#> Error: object 'engine' not found
models <- engine$reflect_schema(tables = c("users", "posts"))
#> Error: object 'engine' not found
posts <- models$posts
#> Error: object 'models' not found
# }