diff --git a/api/0.2.2/DB.html b/api/0.2.2/DB.html
new file mode 100644
index 0000000..0563c60
--- /dev/null
+++ b/api/0.2.2/DB.html
@@ -0,0 +1,532 @@
+
+
+
+ DB - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ module DB
+
+
+
+
+
+
+
+
Overview
+
+
The DB module is a unified interface to database access.
+Database dialects is supported by custom database driver shards.
+Check manastech/crystal-sqlite3 for example.
+
+
Drivers implementors check Driver
+
+
DB manage a connection pool. The connection pool can be configured by URI query. See Database
+
+
Usage
+
+
Assuming crystal-sqlite3 is included a sqlite3 database can be opened with #open
+
+
db = DB .open "sqlite3:./path/to/db/file.db"
+db.close
+
+
If a block is given to #open
+
+
DB .open "sqlite3:./file.db" do | db|
+ # work with db
+end # db is closed
+
+
In the code above db is a Database QueryMethods
+
+
Three kind of statements can be performed:
+
+
Database#exec waits no response from the database.Database#scalar reads a single value of the response.Database#query returns a ResultSet that allows iteration over the rows in the response and column information.
+
+
All of the above methods allows parametrised query. Either positional or named arguments.
+
+
Check a full working version:
+
+
require "db"
+require "sqlite3"
+
+DB .open "sqlite3:./file.db" do | db|
+ db.exec "create table contacts (name string, age integer)"
+ db.exec "insert into contacts values (?, ?)" , "John Doe" , 30
+
+ args = [] of DB :: Any
+ args << "Sarah"
+ args << 33
+ db.exec "insert into contacts values (?, ?)" , args
+
+ puts "max age:"
+ puts db.scalar "select max(age) from contacts" # => 33
+
+ puts "contacts:"
+ db.query "select name, age from contacts order by age desc" do | rs|
+ puts " #{ rs.column_name(0 )} (#{ rs.column_name(1 )} )"# => name (age)
+ rs.each do
+ puts " #{ rs.read(String )} (#{ rs.read(Int32 )} )"# => Sarah (33)
+ # => John Doe (30)
+ end
+ end
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db.cr
+
+
+
+
+
db/pool.cr
+
+
+
+
+
db/string_key_cache.cr
+
+
+
+
+
db/query_methods.cr
+
+
+
+
+
db/disposable.cr
+
+
+
+
+
db/database.cr
+
+
+
+
+
db/driver.cr
+
+
+
+
+
db/connection.cr
+
+
+
+
+
db/statement.cr
+
+
+
+
+
db/pool_statement.cr
+
+
+
+
+
db/result_set.cr
+
+
+
+
+
db/error.cr
+
+
+
+
+
db/mapping.cr
+
+
+
+
+
db/version.cr
+
+
+
+
+
+
+
+
Constant Summary
+
+
+
+
+ TYPES = [Nil , String , Int32 , Int64 , Float32 , Float64 , Bytes ]
+
+
+
+ Types supported to interface with database driver.
+These can be used in any ResultSet#read Database#query related
+method to be used as query parameters
+
+
+
+
+ VERSION = "0.2.2"
+
+
+
+
+
+
+
Class Method Summary
+
+
+
+
+
+
+
Macro Summary
+
+
+
+
+
+
+
+
+
+
Class Method Detail
+
+
+
+
+ def self.
open (uri : URI | String)
+
+
#
+
+
+
Opens a database using the specified uri .
+The scheme of the uri determines the driver to use.
+Returned database must be closed by Database#close
+
+
+
+
+
+
+
+
+ def self.
open (uri : URI | String, &block)
+
+
#
+
+
+
Same as #open
+
+
+
+
+
+
+
+
+ def self.
register_driver (driver_name, driver_class : Driver.class)
+
+
#
+
+
+
Registers a driver class for a given driver_name .
+Should be called by drivers implementors only.
+
+
+
+
+
+
+
+
+
+
+
Macro Detail
+
+
+
+
+ macro
mapping (properties, strict = true)
+
+
#
+
+
+
The DB.mapping
+
+
It takes hash literal as argument, in which attributes and types are defined.
+Once defined, DB::ResultSet#read(t)
+
+
require "db"
+
+class Employee
+ DB .mapping({
+ title: String ,
+ name: String ,
+ })
+end
+
+employees = Employee .from_rs(db.query("SELECT title, name FROM employees" ))
+employees[0 ].title # => "Manager"
+employees[0 ].name # => "John"
+
+
Attributes not mapped with DB.mapping DB::Exception.
+
+
You can also define attributes for each property.
+
+
class Employee
+ DB .mapping({
+ title: String ,
+ name: {
+ type : String ,
+ nilable: true ,
+ key: "firstname" ,
+ },
+ })
+end
+
+
Available attributes:
+
+
type (required) defines its type. In the example above, title: String is a shortcut to title: {type: String} .nilable defines if a property can be a Nil.default : value to use if the property is missing in the result set, or if it's null and nilable was not set to true. If the default value creates a new instance of an object (for example [1, 2, 3] or SomeObject.new), a different instance will be used each time a row is parsed.key defines which column to read from a reusltset. It defaults to the name of the property.converter takes an alternate type for parsing. It requires a #from_rs method in that class, and returns an instance of the given type.
+
+
The mapping also automatically defines Crystal properties (getters and setters) for each
+of the keys. It doesn't define a constructor accepting those arguments, but you can provide
+an overload.
+
+
The macro basically defines a constructor accepting a DB::ResultSet
+
+
This macro also declares instance variables of the types given in the mapping.
+
+
+
+
+
+
+
+
+ macro
mapping
+
+
#
+
+
+
+
+
+
+
+
+
DB::Any - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ alias DB::Any
+
+
+
+
+
+
+
+
+
+
Alias Definition
+
Float32 | Float64 | Int32 | Int64 | Slice(UInt8) | String | Nil
+
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db.cr
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
DB::Connection - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ abstract class DB::Connection
+
+
+
+
+
+
+
+
+
+
Overview
+
+
Database driver implementors must subclass Connection
+
+
Represents one active connection to a database.
+
+
Users should never instantiate a Connection DB#open Database#connection.
+
+
Refer to QueryMethods
+
+
Note to implementors
+
+
The connection must be initialized in #initialize and closed in #do_close.
+
+
Override #build_statement Statement Statement
+
+
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
+
+
+
+
+
+
+
+
+
Class Method Summary
+
+
+
+
+
Instance Method Summary
+
+
+
+
+
+
+
+
+
+
+
Instance methods inherited from module DB::QueryMethods
+
+
+
+ exec(query, *args)
+ exec ,
+
+
+
+ query(query, *args)
+ query ,
+
+
+
+ query_all(query, *args, &block : ResultSet -> U) : Array(U)
+ query_all ,
+
+
+
+ query_one(query, *args, &block : ResultSet -> U) : U
+ query_one ,
+
+
+
+ query_one?(query, *args, &block : ResultSet -> U) : U?
+ query_one? ,
+
+
+
+ scalar(query, *args)
+ scalar
+
+
+
+
+
+
+
+
+
+
+
Instance methods inherited from module DB::Disposable
+
+
+
+ close
+ close ,
+
+
+
+ closed?
+ closed?
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Class Method Detail
+
+
+
+
+ def self.
new (database :
Database )
+
+
#
+
+
+
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+ abstract
+ def
build_statement (query) :
Statement
+
+
#
+
+
+
+
+
+
+
+
+
+
+
DB::ConnectionLost - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ class DB::ConnectionLost
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/error.cr
+
+
+
+
+
+
+
+
+
Class Method Summary
+
+
+
+
+
Instance Method Summary
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Class Method Detail
+
+
+
+
+ def self.
new (connection)
+
+
#
+
+
+
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+
+
+
+
+
DB::Database - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ class DB::Database
+
+
+
+
+
+
+
+
+
+
Overview
+
+
Acts as an entry point for database access.
+Connections are managed by a pool.
+The connection pool can be configured from URI parameters:
+
+
initial_pool_size (default 1) max_pool_size (default 0 = unlimited) max_idle_pool_size (default 1) checkout_timeout (default 5.0) retry_attempts (default 1) retry_delay (in seconds, default 1.0)
+
+
It should be created from DB module. See DB#open
+
+
Refer to QueryMethods
+
+
+
+
+
+
Included Modules
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/database.cr
+
+
+
+
+
+
+
+
+
+
+
Instance Method Summary
+
+
+
+
+
+
+
+
+
+
+
Instance methods inherited from module DB::QueryMethods
+
+
+
+ exec(query, *args)
+ exec ,
+
+
+
+ query(query, *args)
+ query ,
+
+
+
+ query_all(query, *args, &block : ResultSet -> U) : Array(U)
+ query_all ,
+
+
+
+ query_one(query, *args, &block : ResultSet -> U) : U
+ query_one ,
+
+
+
+ query_one?(query, *args, &block : ResultSet -> U) : U?
+ query_one? ,
+
+
+
+ scalar(query, *args)
+ scalar
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+
+
Closes all connection to the database.
+
+
+
+
+
+
+
+
+ def
setup_connection (&proc :
Connection -> Nil)
+
+
#
+
+
+
+
+
+
+
+
+
+ def
uri : URI
+
+
#
+
+
+
Returns the uri with the connection settings to the database
+
+
+
+
+
+
+
+
+ def
using_connection (&block)
+
+
#
+
+
+
yields a connection from the pool
+the connection is returned to the pool after
+when the block ends
+
+
+
+
+
+
+
+
+
+
DB::Disposable - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ module DB::Disposable
+
+
+
+
+
+
+
+
Overview
+
+
Generic module to encapsulate disposable db resources.
+
+
+
+
+
+
+
+
+
+
+
+
Direct including types
+
+
+
+
+
+
Defined in:
+
+
+
db/disposable.cr
+
+
+
+
+
+
+
+
+
+
+
Instance Method Summary
+
+
+
+ #close
+
+
+ #closed? Returns true if this object is closed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+
+
+
+
Returns true if this object is closed. See #close
+
+
+
+
+
+
+
+
+
+
DB::Driver - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ abstract class DB::Driver
+
+
+
+
+
+
+
+
+
+
Overview
+
+
Database driver implementors must subclass Driver DB#register_driver #build_connection
+
+
require "db"
+
+class FakeDriver < Driver
+ def build_connection (db)
+ FakeConnection .new db
+ end
+end
+
+DB .register_driver "fake" , FakeDriver
+
+
Access to this fake datbase will be available with
+
+
DB .open "fake://..." do | db|
+ # ... use db ...
+end
+
+
Refer to Connection Statement ResultSet
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/driver.cr
+
+
+
+
+
+
+
+
+
+
+
Instance Method Summary
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+
+
+
+ def
connection_pool_options (params : HTTP::Params)
+
+
#
+
+
+
+
+
+
+
+
+
+
+
DB::Error - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ class DB::Error
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Direct Known Subclasses
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/error.cr
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
DB::ExecResult - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ struct DB::ExecResult
+
+
+
+
+
+
+
+
+
+
Overview
+
+
Result of a #exec statement.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db.cr
+
+
+
+
+
+
+
+
+
Class Method Summary
+
+
+
+
+
Instance Method Summary
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Class Method Detail
+
+
+
+
+ def self.
new (rows_affected : Int64, last_insert_id : Int64)
+
+
#
+
+
+
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+
+
+
+ def
last_insert_id : Int64
+
+
#
+
+
+
+
+
+
+
+
+
+
+
+ def
rows_affected : Int64
+
+
#
+
+
+
+
+
+
+
+
+
+
+
+
+
DB::Mappable - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ module DB::Mappable
+
+
+
+
+
+
+
+
Overview
+
+
Empty module used for marking a class as supporting DB:Mapping
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/mapping.cr
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
DB::MappingException - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ class DB::MappingException
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/error.cr
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
DB::Pool(T) - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ class DB::Pool(T)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/pool.cr
+
+
+
+
+
+
+
+
+
Class Method Summary
+
+
+
+
+
Instance Method Summary
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Class Method Detail
+
+
+
+
+ def self.
new (initial_pool_size =
1 , max_pool_size =
0 , max_idle_pool_size =
1 , checkout_timeout =
5.0 , retry_attempts =
1 , retry_delay =
0.2 , &factory : -> T)
+
+
#
+
+
+
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+
+ def
checkout : T
+
+
#
+
+
+
+
+
+
+
+
+
+ def
checkout_some (candidates : Enumerable(WeakRef(T))) : ::Tuple(T, Bool)
+
+
#
+
+
+
selected, is_candidate = pool.checkout_some(candidates)
+
+
selected be a resource from the candidates list and is_candidate == true
+or selected will be a new resource adn is_candidate == false
+
+
+
+
+
+
+
+
+ def
close : Nil
+
+
#
+
+
+
close all resources in the pool
+
+
+
+
+
+
+
+
+ def
release (resource : T) : Nil
+
+
#
+
+
+
+
+
+
+
+
+
+ def
retry (&block)
+
+
#
+
+
+
:nodoc:
+Will retry the block if a ConnectionLost retry_delay seconds delay.
+
+
+
+
+
+
+
+
+
+
DB::Pool::TimeoutHelper - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ class DB::Pool::TimeoutHelper
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/pool.cr
+
+
+
+
+
+
+
+
+
Class Method Summary
+
+
+
+
+
Instance Method Summary
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Class Method Detail
+
+
+
+
+ def self.
new (timeout : Float64)
+
+
#
+
+
+
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+
+
+
+ def
receive_select_action
+
+
#
+
+
+
+
+
+
+
+
+
+
+
+
+
DB::PoolRetryAttemptsExceeded - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ class DB::PoolRetryAttemptsExceeded
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/error.cr
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
DB::PoolStatement - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ class DB::PoolStatement
+
+
+
+
+
+
+
+
+
+
Overview
+
+
When a statement is to be executed in a DB that has a connection pool
+a statement from the DB needs to be able to represent a statement in any
+of the connections of the pool. Otherwise the user will need to deal with
+actual connections in some point.
+
+
+
+
+
+
Included Modules
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/pool_statement.cr
+
+
+
+
+
+
+
+
+
Class Method Summary
+
+
+
+
+
Instance Method Summary
+
+
+
+
+
+
+
+
+
+
Class Method Detail
+
+
+
+
+ def self.
new (db :
Database , query : String)
+
+
#
+
+
+
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
DB::PoolTimeout - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ class DB::PoolTimeout
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/error.cr
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
DB::QueryMethods - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ 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 ExecResult #scalar #query ResultSet
+
+
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 prepare(query) : Statement method that is not expected
+to be called directly.
+
+
+
+
+
+
+
+
+
+
+
+
Direct including types
+
+
+
+
+
+
Defined in:
+
+
+
db/query_methods.cr
+
+
+
+
+
+
+
+
+
+
+
Instance Method Summary
+
+
+
+ #exec (query, *args)
+
+
+ #query (query, *args)Executes a query and returns a ResultSet
+
+
+ #query (query, *args, &block)Executes a query and yields a ResultSet
+
+
+ #query_all (query, *args, &block : ResultSet -> U) : Array(U)Executes a query and yield a ResultSet
+
+
+ #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) : UExecutes a query that expects a single row and yields a ResultSet
+
+
+ #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
+
+
+ #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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+
+ def
exec (query, *args)
+
+
#
+
+
+
+
+
+
+
+
+
+
+
+ def
query (query, *args)
+
+
#
+
+
+
Executes a query and returns a ResultSet ResultSet
+
+
result = db.query "select name from contacts where id = ?" , 10
+begin
+ if result.move_next
+ id = result.read(Int32 )
+ end
+ensure
+ result.close
+end
+
+
+
+
+
+
+
+
+ def
query (query, *args, &block)
+
+
#
+
+
+
Executes a query and yields a ResultSet ResultSet
+
+
db.query("select name from contacts where age > ?" , 18 ) do | rs|
+ rs.each do
+ name = rs.read(String )
+ end
+end
+
+
+
+
+
+
+
+
+ def
query_all (query, *args, &block :
ResultSet -> U) : Array(U)
+
+
#
+
+
+
Executes a query and yield a ResultSet
+
+
names = db.query_all "select name from contacts" , & .read(String )
+
+
+
+
+
+
+
+
+ def
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 .
+
+
contacts = db.query_all "select name, age from contactas" , as : {String , Int32 }
+
+
+
+
+
+
+
+
+ def
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 .
+
+
names = db.query_all "select name from contactas" , as : String
+
+
+
+
+
+
+
+
+ def
query_one (query, *args, &block :
ResultSet -> U) : U
+
+
#
+
+
+
Executes a query that expects a single row and yields a ResultSet
+
+
The given block must not invoke move_next on the yielded result set.
+
+
Raises DB::Error
+
+
name = db.query_one "select name from contacts where id = ?" , 18 , & .read(String )
+
+
+
+
+
+
+
+
+ def
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 .
+
+
Raises DB::Error
+
+
db.query_one "select name, age from contacts where id = ?" , 1 , as : {String , Int32 }
+
+
+
+
+
+
+
+
+ def
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 .
+
+
Raises DB::Error
+
+
db.query_one "select name from contacts where id = ?" , 1 , as : String
+
+
+
+
+
+
+
+
+ def
query_one? (query, *args, &block :
ResultSet -> U) : U?
+
+
#
+
+
+
Executes a query that expects at most a single row and yields a ResultSet
+
+
Returns nil, not invoking the block, if there were no rows.
+
+
Raises DB::Error
+
+
name = db.query_one? "select name from contacts where id = ?" , 18 , & .read(String )
+typeof (name) # => String | Nil
+
+
+
+
+
+
+
+
+ def
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 .
+
+
Returns nil if there were no rows.
+
+
Raises DB::Error
+
+
result = db.query_one? "select name, age from contacts where id = ?" , 1 , as : {String , Int32 }
+typeof (result) # => Tuple(String, Int32) | Nil
+
+
+
+
+
+
+
+
+ def
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 .
+
+
Returns nil if there were no rows.
+
+
Raises DB::Error
+
+
name = db.query_one? "select name from contacts where id = ?" , 1 , as : String
+typeof (name) # => String?
+
+
+
+
+
+
+
+
+ def
scalar (query, *args)
+
+
#
+
+
+
Performs the #query
+
+
+
+
+
+
+
+
+
+
DB::ResultSet - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ abstract class DB::ResultSet
+
+
+
+
+
+
+
+
+
+
Overview
+
+
The response of a query performed on a Database
+
+
See DB
+
+
Each #read #move_next ResultSet #each #move_next
+
+
Note: depending on how the ResultSet #close. Check QueryMethods#query
+
+
Note to implementors
+
+
Override #move_next Override #read (Optional) Override #read(t) t for which custom logic other than a simple cast is needed. Override #column_count #column_name
+
+
+
+
+
+
Included Modules
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/result_set.cr
+
+
+
+
+
+
+
+
+
Class Method Summary
+
+
+
+
+
Instance Method Summary
+
+
+
+
+
+
+
+
+
+
Class Method Detail
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+ abstract
+ def
column_count : Int32
+
+
#
+
+
+
Returns the number of columns in the result
+
+
+
+
+
+
+
+ abstract
+ def
column_name (index : Int32) : String
+
+
#
+
+
+
Returns the name of the column in index 0-based position.
+
+
+
+
+
+
+
+
+ def
column_names
+
+
#
+
+
+
Returns the name of the columns.
+
+
+
+
+
+
+
+
+ def
each (&block)
+
+
#
+
+
+
Iterates over all the rows
+
+
+
+
+
+
+
+
+ def
each_column (&block)
+
+
#
+
+
+
Iterates over all the columns
+
+
+
+
+
+
+
+ abstract
+ def
move_next : Bool
+
+
#
+
+
+
Move the next row in the result.
+Return false if no more rows are available.
+See #each
+
+
+
+
+
+
+
+
+ def
read (type : DB::Mappable.class)
+
+
#
+
+
+
Reads the next columns and maps them to a class
+
+
+
+
+
+
+
+
+ def
read (type : T.class) : T forall T
+
+
#
+
+
+
Reads the next column value as a type
+
+
+
+
+
+
+
+ abstract
+ def
read
+
+
#
+
+
+
Reads the next column value
+
+
+
+
+
+
+
+
+ def
read (*types : Class)
+
+
#
+
+
+
Reads the next columns and returns a tuple of the values.
+
+
+
+
+
+
+
+
+
+
DB::Statement - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ abstract class DB::Statement
+
+
+
+
+
+
+
+
+
+
Overview
+
+
Represents a prepared query in a Connection QueryMethods
+
+
Note to implementors
+
+
Subclass Statements Statements are created from a custom driver Connection#prepare method.#perform_query executes a query that is expected to return a ResultSet #perform_exec executes a query that is expected to return an ExecResult #do_close is called to release the statement resources.
+
+
+
+
+
+
Included Modules
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/statement.cr
+
+
+
+
+
+
+
+
+
Class Method Summary
+
+
+
+
+
Instance Method Summary
+
+
+
+
+
+
+
+
+
+
Class Method Detail
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+
+ def
exec (args : Array)
+
+
#
+
+
+
+
+
+
+
+
+
+
+
+
+
+ def
exec (*args)
+
+
#
+
+
+
+
+
+
+
+
+
+
+
+ def
query (args : Array)
+
+
#
+
+
+
+
+
+
+
+
+
+
+
+
+
+ def
query (*args)
+
+
#
+
+
+
+
+
+
+
+
+
+
+
+ def
release_connection
+
+
#
+
+
+
+
+
+
+
+
+
+
+
DB::StatementMethods - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ module DB::StatementMethods
+
+
+
+
+
+
+
+
Overview
+
+
Common interface for connection based statements
+and for connection pool statements.
+
+
+
+
+
+
Included Modules
+
+
+
+
+
+
+
+
+
Direct including types
+
+
+
+
+
+
Defined in:
+
+
+
db/statement.cr
+
+
+
+
+
+
+
+
+
+
+
Instance Method Summary
+
+
+
+
+
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+ abstract
+ def
exec (args : Array) :
ExecResult
+
+
#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ def
query (*args, &block)
+
+
#
+
+
+
+
+
+
+
+
+
+
+ abstract
+ def
query (args : Array) :
ResultSet
+
+
#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ def
scalar (*args)
+
+
#
+
+
+
+
+
+
+
+
+
+
+
+
+
DB::StringKeyCache(T) - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+ class DB::StringKeyCache(T)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defined in:
+
+
+
db/string_key_cache.cr
+
+
+
+
+
+
+
+
+
+
+
Instance Method Summary
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Instance Method Detail
+
+
+
+
+
+
+ def
each_value (&block)
+
+
#
+
+
+
+
+
+
+
+
+
+ def
fetch (key : String, &block) : T
+
+
#
+
+
+
+
+
+
+
+
+
+
+
README - github.com/crystal-lang/crystal-db
+
+
+
+
+
+
+
+
+
crystal-db
+
+
Common db api for crystal. You will need to a specific driver to access a database.
+
+
+
+
Installation
+
+
Add this to your application's shard.yml:
+
+
dependencies:
+ db:
+ github: crystal-lang/crystal-db
+
+
Usage
+
+
Since this is an abstract db api, it's usage is through a concrete database driver.
+
+
require "db"
+require "sqlite3"
+
+DB .open "sqlite3:./file.db" do | db|
+ db.exec "create table contacts (name string, age integer)"
+ db.exec "insert into contacts values (?, ?)" , "John Doe" , 30
+
+ args = [] of DB :: Any
+ args << "Sarah"
+ args << 33
+ db.exec "insert into contacts values (?, ?)" , args
+
+ puts "max age:"
+ puts db.scalar "select max(age) from contacts" # => 33
+
+ puts "contacts:"
+ db.query "select name, age from contacts order by age desc" do | rs|
+ puts " #{ rs.column_name(0 )} (#{ rs.column_name(1 )} )"# => name (age)
+ rs.each do
+ puts " #{ rs.read(String )} (#{ rs.read(Int32 )} )"# => Sarah (33)
+ # => John Doe (30)
+ end
+ end
+end
+
+
Roadmap
+
+
Issues not yet addressed
+
+
[ ] Support non prepared statements. [ ] Time data type. [x] Data type extensibility. Allow each driver to extend the data types allowed. [ ] Transactions. [ ] Connection pool. [ ] Direct access to IO to avoid memory allocation for blobs.
+
+
Contributing
+
+
Fork it ( https://github.com/crystal-lang/crystal-db/fork ) Create your feature branch (git checkout -b my-new-feature) Commit your changes (git commit -am 'Add some feature') Push to the branch (git push origin my-new-feature) Create a new Pull Request
+
+
Contributors
+
+
bcardiff Brian J. Cardiff - creator, maintainer
+
