Class: RDO::Connection

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/rdo/connection.rb

Overview

Wrapper class to manage Driver classes.

This is the user-facing connection class. Users do not instantiate drivers directly.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(uri, options = {}) ⇒ RDO::Connection

Initialize a new Connection.

This method instantiates the necessary driver.

If no suitable driver is loaded, an RDO::Exception is raised.

Parameters:

  • uri (Object) —

    either a connection URI string, or an options Hash

  • options (Hash) (defaults to: {}) —

    if a URI is provided for the first argument, additional options may be specified here. These may override settings in the first argument.



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/rdo/connection.rb', line 65

def initialize(uri, options = {})
  @options = normalize_options(uri).merge(normalize_options(options))

  @logger       = @options.fetch(:logger, default_logger)
  @logger.level = @options[:log_level] if @options.key?(:log_level)

  unless self.class.drivers.key?(@options[:driver])
    raise RDO::Exception,
      "Unregistered driver #{@options[:driver].inspect}"
  end

  @driver = self.class.drivers[@options[:driver]].new(@options)
  @driver.open or raise RDO::Exception,
    "Unable to connect, but the driver did not provide a reason"
end

Instance Attribute Details

#logger ⇒ Object

A Logger (from ruby stdlib)



45
46
47
 
# File 'lib/rdo/connection.rb', line 45

def logger
  @logger
end

#options ⇒ Object (readonly)

Options passed to initialize.



42
43
44
 
# File 'lib/rdo/connection.rb', line 42

def options
  @options
end

Class Method Details

.drivers ⇒ Hash

List all known drivers, as a Hash mapping the URI scheme to the Class.

Returns:

  • (Hash) —

    the mapping of driver names to class names



23
24
25
 
# File 'lib/rdo/connection.rb', line 23

def drivers
  @drivers ||= {}
end

.register_driver(name, klass) ⇒ Object

Register a known driver class for the given URI scheme name.

Parameters:

  • name (String) —

    the name of the URI scheme (e.g. sqlite)

  • klass (Class<RDO::Driver>) —

    a subclass of RDO::Driver that provides the driver



34
35
36
 
# File 'lib/rdo/connection.rb', line 34

def register_driver(name, klass)
  drivers[name.to_s] = klass
end

Instance Method Details

#debug ⇒ Object

Use debug log level in the context of a block.



131
132
133
134
135
136
137
138
139
 
# File 'lib/rdo/connection.rb', line 131

def debug
  raise ArgumentError,
    "RDO::Connection#debug requires a block" unless block_given?

  reset, logger.level = logger.level, Logger::DEBUG
  yield
ensure
  logger.level = reset
end

#execute(statement, *bind_values) ⇒ Result

Execute a statement with the configured Driver.

The statement can either be a read, or a write operation. Placeholders marked by ‘?’ may be interpolated in the statement, so that bind parameters can be safely provided.

Where the RDBMS natively supports bind parameters, this functionality is used; otherwise, the values are quoted using #quote.

Parameters:

  • statement (String) —

    a string of SQL or DDL to be executed

  • *bind_values (Array) —

    a list of parameters to substitute in the statement

Returns:

  • (Result) —

    the result of the query



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/rdo/connection.rb', line 98

def execute(statement, *bind_values)
  t = Time.now
  @driver.execute(statement, *bind_values).tap do |rs|
    rs.info[:execution_time] ||= Time.now - t
    if logger.debug?
      logger.debug(
        "(%.6f) %s %s" % [
          rs.execution_time,
          statement,
          ("<Bind: #{bind_values.inspect}>" unless bind_values.empty?)
        ]
      )
    end
  end
rescue RDO::Exception => e
  logger.fatal(e.message) if logger.fatal?
  raise
end

#prepare(command) ⇒ Statement

Create a prepared statement to later be executed with some inputs.

Not all drivers support this natively, but it is emulated by default.

Parameters:

  • statement (String) —

    a string of SQL or DDL, with ‘?’ placeholders for bind parameters

Returns:

  • (Statement) —

    a prepared statement to later be executed



126
127
128
 
# File 'lib/rdo/connection.rb', line 126

def prepare(command)
  Statement.new(@driver.prepare(command), logger)
end