class DB::Database

Overview

Acts as an entry point for database access. Connections are managed by a pool. Use DB#open to create a Database instance.

Refer to QueryMethods and SessionMethods for documentation about querying the database.

Database URI

Connection parameters are usually in a URI. The format is specified by the individual database drivers, yet there are some common properties names usually shared. See the reference book for examples.

The connection pool can be configured from URI parameters:

When querying a database, prepared statements are used by default. This can be changed from the prepared_statements URI parameter:

Included Modules

Defined in:

db/database.cr

Constructors

Instance Method Summary

Instance methods inherited from module DB::ConnectionContext

discard(connection : Connection) discard, release(connection : Connection) release

Instance methods inherited from module DB::SessionMethods(DB::Database, DB::PoolStatement)

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?, unprepared(query)
unprepared unprepared

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

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

Constructor Detail

def self.new(connection_options : Connection::Options, pool_options : Pool::Options, &factory : -> Connection) #

Initialize a database with the specified options and connection factory. This covers more advanced use cases that might not be supported by an URI connection string such as tunneling connection.


[View source]

Instance Method Detail

def checkout #

returns a connection from the pool the returned connection must be returned to the pool by explictly calling Connection#release


[View source]
def close #

Closes all connection to the database.


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

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


[View source]
def setup_connection(&proc : Connection -> Nil) #

Run the specified block every time a new connection is established, yielding the new connection to the block.

db = DB.open(DB_URL)
db.setup_connection do |connection|
  connection.exec "SET TIME ZONE 'America/New_York'"
end

[View source]
def transaction(&) #

yields a Transaction from a connection of the pool Refer to BeginTransaction#transaction for documentation.


[View source]
def using_connection(&) #

yields a connection from the pool the connection is returned to the pool when the block ends


[View source]