class

Altair::Record::Connection

Inherits Reference < Object

Constructors

for(app : Altair::Application) : Connection

Returns the application's connection, opened lazily from config.db_url on first use. Raises when no URL is configured. The adapter is picked from the URL scheme: sqlite3:// uses SQLite, postgres:// and postgresql:// use the PostgreSQL adapter, which a project loads by requiring altair/record/adapters/postgresql (and declaring crystal-pg).

Source
new(adapter : Adapter, url : String, pool_options : DB::Pool::Options, query_timeout : Time::Span)
Source

Instance methods

adapter

The adapter in use.

Source
close

Closes the pool. Tests call this to release file handles.

Source
database

The underlying database pool.

Source
exec(sql : String, *db_args, args : Enumerable | Nil = nil) : DB::ExecResult

Executes a statement with bound parameters, notifying the instrumentation hooks. Every value travels as a bind parameter — never interpolated into the SQL string. Inside a transaction the statement runs on the calling fiber's transaction connection. Acquisition wait is excluded from reported SQL time: the granular QueryEvent carries checkout and sql durations separately. When no query or event handler is registered the connection takes its zero-cost path and never reads the clock.

Source
last_insert_id(result : DB::ExecResult) : Int64

Returns the last auto-generated id of an insert result.

Source
pool_stats

Pool statistics read on demand (for observability). Reading them is opt-in and never runs in the hot path.

Source
query(sql : String, *args, values : Enumerable | Nil = nil, &block : DB::ResultSet -> ) : Nil

Runs a query with bound parameters, yielding each row to the block. values: binds a variable-length collection, for IN (...) clauses. Row-reading time is tracked as decode time in the granular event, separate from the checkout wait.

Source
query_one(sql : String, *args, &block : DB::ResultSet -> U) : U forall U

Runs a query expecting a single row, yielded to the block.

Source
sql_template(key : String, & : -> String) : String

Returns the SQL template for key, building it with the block on first use and caching it for the connection's lifetime. The steady path is a hash lookup by an interned literal key; the block (and the build lock) runs only on a miss.

Source
sql_template(key : String) : String

Returns the cached template for key, raising when it was never built on this connection.

Source
transaction

Runs the block inside a transaction; the transaction rolls back when the block raises, and the raise propagates. Statements inside the block reuse the transaction's connection, so the pool is never double-checked-out. A nested call runs on a savepoint of the current transaction instead of checking out another connection. The active connection is tracked per fiber, so concurrent fibers each get an isolated transaction.

Source