class Athena::ORM::Connection
inherits Reference
#
Wraps a DB::Connection, adding the database's AORM::Platforms::Platform, parameter conversion through AORM::Types::Types, and nested transactions.
Each AORM::EntityManager wraps the connection it's created with, available as AORM::EntityManager#connection.
It can be used to run SQL in the same connection, and transaction, as the entity manager.
connection = em.connection
# Each parameter is converted through the type at the same position before being bound.
connection.execute_statement "UPDATE posts SET published_at = ? WHERE id = ?", [Time.utc, 1], [AORM::Types::DATETIME, AORM::Types::INTEGER] of String? # => 1
connection.fetch_one "SELECT COUNT(*) FROM posts", [] of DB::Any, [] of String? # => 10
The DB::QueryMethods methods, such as #exec and #query, bind their arguments as given, without any conversion.
Other methods are forwarded to the wrapped connection.
Transactions#
#begin_transaction starts a transaction, or a savepoint within the active one when a transaction is already active.
#commit and #rollback end the innermost one, so a nested transaction can be rolled back without affecting the outer transaction.
connection.transactional do
connection.exec "DELETE FROM posts WHERE user_id = ?", 1
connection.exec "DELETE FROM users WHERE id = ?", 1
end
Since AORM::EntityManager#flush runs in a transaction of its own, it becomes a savepoint when called within one.
Tip
AORM::EntityManager#wrap_in_transaction also flushes the entity manager before committing, and closes it if anything raises.
Included modules
DB::QueryMethods
Constructors#
.new(wrapped : DB::Connection, driver : AORM::Driver = AORM::DriverManager.driver(wrapped))#
Wraps wrapped, using driver for what differs between driver shards, such as the platform of the database it's to.
Raises AORM::Exceptions::UnknownDriver if no driver is given and the ORM doesn't support wrapped's driver shard, see AORM::DriverManager.
Methods#
#begin_transaction : Nil#
Starts a transaction, or a savepoint if one is already active.
#commit : Nil#
Commits the innermost transaction, releasing its savepoint if it's nested.
Raises DB::Error if no transaction is active.
A commit that fails still ends the transaction.
#convert_to_database_value(value : _, type : String | Nil)#
Converts value to its database representation through the Types::Type registered as type.
Values without a type are returned unchanged.
#database_platform : Platforms::Platform#
Returns the platform of the database this connection is to.
#exec(query, *args_, args : Enumerable | Nil = nil) : DB::ExecResult#
Performs the query and returns an ExecResult
Also keeps the identifier the statement generated, see #last_insert_id.
#execute_query#
Executes sql, binding each of params converted through the type at the same position in types, and yields the result set. Returns the block's value.
#execute_query(sql : String, params : Array, types : Array(String | Nil)) : DB::ResultSet#
Executes sql, binding each of params converted through the type at the same position in types, and returns the result set. The caller is responsible for closing it.
#execute_statement(sql : String, params : Array, types : Array(String | Nil)) : Int64#
Executes sql, binding each of params converted through the type at the same position in types, and returns the number of affected rows.
#fetch_one(sql : String, params : Array, types : Array(String | Nil))#
Executes sql like #execute_query, returning the first column of the first row, or nil when there are no rows.
#last_insert_id : Int64#
Returns the identifier generated by the last statement executed via #exec.
Raises AORM::Exceptions::NoIdentityValue if that statement didn't generate one.
On Postgres, it's instead the value most recently generated by a sequence in this session, and the driver shard raises if no sequence was used yet.
#platform : Platforms::Platform#
Returns the platform of the database this connection is to.
#rollback : Nil#
Rolls back the innermost transaction, or to its savepoint if it's nested.
Raises DB::Error if no transaction is active.
#transaction_nesting_level : Int32#
Returns the number of active transactions, counting each savepoint as one.
#transactional : T#
Runs the block in a transaction, or a savepoint if one is already active. Commits if the block returns, returning its value, and rolls back if it raises.