shard-crystal-db/src/db.cr

213 lines
6.5 KiB
Crystal
Raw Normal View History

2016-02-03 21:29:09 +00:00
require "uri"
require "log"
2016-02-03 21:29:09 +00:00
# The DB module is a unified interface for database access.
# Individual database systems are supported by specific database driver shards.
#
# Available drivers include:
# * [crystal-lang/crystal-sqlite3](https://github.com/crystal-lang/crystal-sqlite3) for SQLite
# * [crystal-lang/crystal-mysql](https://github.com/crystal-lang/crystal-mysql) for MySQL and MariaDB
# * [will/crystal-pg](https://github.com/will/crystal-pg) for PostgreSQL
# * [kaukas/crystal-cassandra](https://github.com/kaukas/crystal-cassandra) for Cassandra
#
# For basic instructions on implementing a new database driver, check `Driver` and the existing drivers.
#
# DB manages a connection pool. The connection pool can be configured by query parameters to the
# connection `URI` as described in `Database`.
#
# ### Usage
#
# Assuming `crystal-sqlite3` is included a SQLite3 database can be opened with `#open`.
#
# ```
2016-02-16 00:56:45 +00:00
# db = DB.open "sqlite3:./path/to/db/file.db"
# db.close
# ```
#
# If a block is given to `#open` the database is closed automatically
#
# ```
2016-02-16 00:56:45 +00:00
# DB.open "sqlite3:./file.db" do |db|
# # work with db
# end # db is closed
# ```
#
2016-02-16 00:56:45 +00:00
# In the code above `db` is a `Database`. Methods available for querying it are described in `QueryMethods`.
#
# Three kind of statements can be performed:
# 1. `Database#exec` waits no response from the database.
# 2. `Database#scalar` reads a single value of the response.
# 3. `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:
#
# The following example uses SQLite where `?` indicates the arguments. If PostgreSQL is used `$1`, `$2`, etc. should be used. `crystal-db` does not interpret the statements.
#
# ```
# require "db"
# require "sqlite3"
#
2016-02-16 00:56:45 +00:00
# DB.open "sqlite3:./file.db" do |db|
# # When using the pg driver, use $1, $2, etc. instead of ?
# db.exec "create table contacts (name text, 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: 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
# ```
#
2016-01-28 22:41:12 +00:00
module DB
Log = ::Log.for(self)
# Types supported to interface with database driver.
# These can be used in any `ResultSet#read` or any `Database#query` related
# method to be used as query parameters
TYPES = [Nil, String, Bool, Int32, Int64, Float32, Float64, Time, Bytes]
2016-06-21 15:08:51 +00:00
# See `DB::TYPES` in `DB`. `Any` is a union of all types in `DB::TYPES`
{% begin %}
alias Any = Union({{*TYPES}})
{% end %}
# Result of a `#exec` statement.
record ExecResult, rows_affected : Int64, last_insert_id : Int64
# :nodoc:
def self.driver_class(driver_name) : Driver.class
drivers[driver_name]? ||
raise(ArgumentError.new(%(no driver was registered for the schema "#{driver_name}", did you maybe forget to require the database driver?)))
2016-01-28 22:41:12 +00:00
end
2016-02-03 21:29:09 +00:00
# Registers a driver class for a given *driver_name*.
# Should be called by drivers implementors only.
def self.register_driver(driver_name, driver_class : Driver.class)
drivers[driver_name] = driver_class
end
private def self.drivers
2016-01-28 22:41:12 +00:00
@@drivers ||= {} of String => Driver.class
end
# Creates a `Database` pool and opens initial connection(s) as specified in the connection *uri*.
# Use `DB#connect` to open a single connection.
#
2016-02-03 21:29:09 +00:00
# The scheme of the *uri* determines the driver to use.
# Connection parameters such as hostname, user, database name, etc. are specified according
# to each database driver's specific format.
#
# The returned database must be closed by `Database#close`.
2016-02-03 21:29:09 +00:00
def self.open(uri : URI | String)
build_database(uri)
2016-01-28 22:41:12 +00:00
end
# Same as `#open` but the database is yielded and closed automatically at the end of the block.
2016-02-03 21:29:09 +00:00
def self.open(uri : URI | String, &block)
db = build_database(uri)
begin
yield db
ensure
db.close
end
end
2016-02-03 21:29:09 +00:00
# Opens a connection using the specified *uri*.
# The scheme of the *uri* determines the driver to use.
# Returned connection must be closed by `Connection#close`.
# If a block is used the connection is yielded and closed automatically.
def self.connect(uri : URI | String)
build_connection(uri)
end
# :ditto:
def self.connect(uri : URI | String, &block)
cnn = build_connection(uri)
begin
yield cnn
ensure
cnn.close
end
end
2016-02-03 21:29:09 +00:00
private def self.build_database(connection_string : String)
build_database(URI.parse(connection_string))
end
private def self.build_database(uri : URI)
driver = build_driver(uri)
params = HTTP::Params.parse(uri.query || "")
connection_options = driver.connection_options(params)
pool_options = driver.pool_options(params)
builder = driver.connection_builder(uri)
factory = ->{ builder.build }
Database.new(connection_options, pool_options, &factory)
end
private def self.build_connection(connection_string : String)
build_connection(URI.parse(connection_string))
end
private def self.build_connection(uri : URI)
build_driver(uri).connection_builder(uri).build
end
private def self.build_driver(uri : URI)
driver_class(uri.scheme).new
2016-02-03 21:29:09 +00:00
end
# :nodoc:
def self.fetch_bool(params : HTTP::Params, name, default : Bool)
case (value = params[name]?).try &.downcase
when nil
default
when "true"
true
when "false"
false
else
raise ArgumentError.new(%(invalid "#{value}" value for option "#{name}"))
end
end
2016-01-28 22:41:12 +00:00
end
require "./db/pool"
require "./db/string_key_cache"
require "./db/enumerable_concat"
require "./db/query_methods"
require "./db/session_methods"
require "./db/disposable"
require "./db/connection_builder"
require "./db/driver"
require "./db/statement"
require "./db/begin_transaction"
require "./db/connection_context"
require "./db/connection"
require "./db/transaction"
require "./db/statement"
require "./db/pool_statement"
require "./db/database"
require "./db/pool_prepared_statement"
require "./db/pool_unprepared_statement"
require "./db/result_set"
require "./db/error"
require "./db/mapping"
2019-10-31 14:34:23 +00:00
require "./db/serializable"