abstract class DB::Connection

Overview

Database driver implementors must subclass Connection.

Represents one active connection to a database.

Users should never instantiate a Connection manually. Use DB#open or Database#connection.

Refer to QueryMethods for documentation about querying the database through this connection.

Note to implementors

The connection must be initialized in #initialize and closed in #do_close.

Override #build_prepared_statement method in order to return a prepared Statement to allow querying. Override #build_unprepared_statement method in order to return a unprepared Statement to allow querying. See also Statement to define how the statements are executed.

Override #driver_name to return the name the driver is registered with. Override #server_name and #server_version to expose what the server reports about itself.

If at any give moment the connection is lost a DB::ConnectionLost should be raised. This will allow the connection pool to try to reconnect or use another connection if available.

Included Modules

Defined in:

db/connection.cr
db/error.cr

Constructors

Instance Method Summary

Instance methods inherited from module DB::BeginTransaction

begin_transaction : Transaction begin_transaction, transaction(& : Transaction -> T) : T | Nil forall T transaction

Instance methods inherited from module DB::SessionMethods(DB::Connection, DB::Statement)

build(query) : Stmt build, build_unprepared_statement(query) : Stmt build_unprepared_statement, fetch_or_build_prepared_statement(query) : Stmt fetch_or_build_prepared_statement, prepared(query)
prepared prepared, prepared_statements? : Bool prepared_statements?, prepared_statements_cache? : Bool prepared_statements_cache?, unprepared(query)
unprepared unprepared

Instance methods inherited from module DB::QueryMethods(DB::Statement)

exec(query, *args_, args : Enumerable | Nil = nil) exec, query(query, *args_, args : Enumerable | Nil = nil)
query(query, *args_, args : Enumerable | Nil = nil, &) query, query_all(query, *args_, args : Enumerable | Nil = nil, &block : ResultSet -> U) : Array(U) forall U
query_all(query, *args_, args : Enumerable | Nil = nil, as types : Tuple)
query_all(query, *args_, args : Enumerable | Nil = nil, as types : NamedTuple)
query_all(query, *args_, args : Enumerable | Nil = nil, as type : Class) query_all, query_each(query, *args_, args : Enumerable | Nil = nil, &) query_each, query_one(query, *args_, args : Enumerable | Nil = nil, &block : ResultSet -> U) : U forall U
query_one(query, *args_, args : Enumerable | Nil = nil, as types : Tuple)
query_one(query, *args_, args : Enumerable | Nil = nil, as types : NamedTuple)
query_one(query, *args_, args : Enumerable | Nil = nil, as type : Class) query_one, query_one?(query, *args_, args : Enumerable | Nil = nil, &block : ResultSet -> U) : U | Nil forall U
query_one?(query, *args_, args : Enumerable | Nil = nil, as types : Tuple)
query_one?(query, *args_, args : Enumerable | Nil = nil, as types : NamedTuple)
query_one?(query, *args_, args : Enumerable | Nil = nil, as type : Class) query_one?, scalar(query, *args_, args : Enumerable | Nil = nil) scalar

Instance methods inherited from module DB::Disposable

close close, closed? closed?

Constructor Detail

def self.new(options : Options) #

[View source]

Instance Method Detail

def begin_transaction : Transaction #
Description copied from module DB::BeginTransaction

Creates a transaction from the current context. If is expected that either Transaction#commit or Transaction#rollback are called explicitly to release the context.


[View source]
abstract def driver_name : String #

Returns the canonical name of the driver backing this connection.

The value is always one of the names the driver registers with DB.register_driver (e.g. "postgres", "mysql", "sqlite3").


[View source]
def prepared_statements? : Bool #
Description copied from module DB::SessionMethods(DB::Connection, DB::Statement)

Returns whether by default the statements should be prepared or not.


[View source]
def prepared_statements_cache? : Bool #

[View source]
def release #

return this connection to the pool managed by the database. Should be used only if the connection was obtained by Database#checkout.


[View source]
def server_name : String | Nil #

Returns the product name the server identifies as (e.g. "PostgreSQL", "MariaDB"), or nil if the driver can't tell.


[View source]
def server_version : String | Nil #

Returns the version string as reported by the server, unparsed (e.g. "8.4.9", "12.2.2-MariaDB-ubu2404"), or nil if the driver can't tell.

The format is server-specific.


[View source]