module DB::QueryMethods
Overview
Methods to allow querying a database.
All methods accepts a query : String
and a set arguments.
Three kind of statements can be performed:
#exec
waits no record response from the database. AnExecResult
is returned.#scalar
reads a single value of the response. A union of possible values is returned.#query
returns aResultSet
that allows iteration over the rows in the response and column information.
Arguments can be passed by position
db.query("SELECT name FROM ... WHERE age > ?", age)
Convention of mapping how arguments are mapped to the query depends on each driver.
Including QueryMethods
requires a prepare(query) : Statement
method that is not expected
to be called directly.
Direct including types
Defined in:
db/query_methods.crInstance Method Summary
-
#exec(query, *args)
Performs the
#query
and returns anExecResult
-
#query(query, *args)
Executes a query and returns a
ResultSet
with the results. -
#query(query, *args, &block)
Executes a query and yields a
ResultSet
with the results. -
#query_all(query, *args, &block : ResultSet -> U) : Array(U)
Executes a query and yield a
ResultSet
positioned at the beginning of each row, returning an array of the values of the blocks. -
#query_all(query, *args, as types : Tuple)
Executes a query and returns an array where each row is read as a tuple of the given types.
-
#query_all(query, *args, as type : Class)
Executes a query and returns an array where there first column's value of each row is read as the given type.
-
#query_one(query, *args, &block : ResultSet -> U) : U
Executes a query that expects a single row and yields a
ResultSet
positioned at that first row. -
#query_one(query, *args, as types : Tuple)
Executes a query that expects a single row and returns it as a tuple of the given types.
-
#query_one(query, *args, as type : Class)
Executes a query that expects a single row and returns the first column's value as the given type.
-
#query_one?(query, *args, &block : ResultSet -> U) : U?
Executes a query that expects at most a single row and yields a
ResultSet
positioned at that first row. -
#query_one?(query, *args, as types : Tuple)
Executes a query that expects a single row and returns it as a tuple of the given types.
-
#query_one?(query, *args, as type : Class)
Executes a query that expects a single row and returns the first column's value as the given type.
-
#scalar(query, *args)
Performs the
#query
and returns a single scalar value puts db.scalar("SELECT MAX(name)").as(String) # => (a String)
Instance Method Detail
Executes a query and returns a ResultSet
with the results.
The ResultSet
must be closed manually.
result = db.query "select name from contacts where id = ?", 10
begin
if result.move_next
id = result.read(Int32)
end
ensure
result.close
end
Executes a query and yields a ResultSet
with the results.
The ResultSet
is closed automatically.
db.query("select name from contacts where age > ?", 18) do |rs|
rs.each do
name = rs.read(String)
end
end
Executes a query and yield a ResultSet
positioned at the beginning
of each row, returning an array of the values of the blocks.
names = db.query_all "select name from contacts", &.read(String)
Executes a query and returns an array where each row is read as a tuple of the given types.
contacts = db.query_all "select name, age from contactas", as: {String, Int32}
Executes a query and returns an array where there first column's value of each row is read as the given type.
names = db.query_all "select name from contactas", as: String
Executes a query that expects a single row and yields a ResultSet
positioned at that first row.
The given block must not invoke move_next
on the yielded result set.
Raises DB::Error
if there were no rows, or if there were more than one row.
name = db.query_one "select name from contacts where id = ?", 18, &.read(String)
Executes a query that expects a single row and returns it as a tuple of the given types.
Raises DB::Error
if there were no rows, or if there were more than one row.
db.query_one "select name, age from contacts where id = ?", 1, as: {String, Int32}
Executes a query that expects a single row and returns the first column's value as the given type.
Raises DB::Error
if there were no rows, or if there were more than one row.
db.query_one "select name from contacts where id = ?", 1, as: String
Executes a query that expects at most a single row and yields a ResultSet
positioned at that first row.
Returns nil
, not invoking the block, if there were no rows.
Raises DB::Error
if there were more than one row
(this ends up invoking the block once).
name = db.query_one? "select name from contacts where id = ?", 18, &.read(String)
typeof(name) # => String | Nil
Executes a query that expects a single row and returns it as a tuple of the given types.
Returns nil
if there were no rows.
Raises DB::Error
if there were more than one row.
result = db.query_one? "select name, age from contacts where id = ?", 1, as: {String, Int32}
typeof(result) # => Tuple(String, Int32) | Nil
Executes a query that expects a single row and returns the first column's value as the given type.
Returns nil
if there were no rows.
Raises DB::Error
if there were more than one row.
name = db.query_one? "select name from contacts where id = ?", 1, as: String
typeof(name) # => String?