rdo 0.0.1

data/lib/rdo/driver.rb

@@ -0,0 +1,120 @@
+##
+# RDO: Ruby Data Objects.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+module RDO
+  # Abstract class that is subclassed by each specific driver.
+  #
+  # Driver developers should be able to subclass this, then write specs and
+  # override the behaviours they need to change.
+  #
+  # Ideally all instance method will be overridden by really robust drivers.
+  class Driver
+    # Options passed to initialize.
+    attr_reader :options
+
+    # Initialize the Driver with the given options.
+    #
+    # Drivers SHOULD call super if overriding.
+    #
+    # @param [Hash] options
+    #   all options passed to the Driver, as a Symbol-keyed Hash.
+    def initialize(options = {})
+      @options = options.dup
+    end
+
+    # Open a connection to the RDBMS, if it is not already open.
+    #
+    # If it is not possible to open a connection, an RDO::Exception is raised.
+    #
+    # This is a no-op: subclasses MUST override this.
+    #
+    # @return [Boolean]
+    #   true if a connection was opened or was already open, false if not.
+    def open
+      false
+    end
+
+    # Check if the connection is currently open or not.
+    #
+    # Drivers MUST override this.
+    #
+    # @return [Boolean]
+    #   true if the connection is open, false otherwise
+    def open?
+      false
+    end
+
+    # Close the current connection, if it is open.
+    #
+    # Drivers MUST override this.
+    #
+    # @return [Boolean]
+    #   true if the connection was closed or was already closed, false if not
+    def close
+      false
+    end
+
+    # Create a prepared statement to later be executed with some inputs.
+    #
+    # Not all drivers support this natively, but it is emulated by default.
+    #
+    # This is a default implementation for emulated prepared statements:
+    # drivers SHOULD override it if possible.
+    #
+    # @param [String] statement
+    #   a string of SQL or DDL, with '?' placeholders for bind parameters
+    #
+    # @return [Statement]
+    #   a prepared statement to later be executed
+    def prepare(statement)
+      Statement.new(emulated_statement_executor(statement))
+    end
+
+    # Execute a statement against the RDBMS.
+    #
+    # The statement can either by 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 support bind parameters, this functionality is
+    # used; otherwise, the values are quoted using #quote.
+    #
+    # Drivers MUST override this.
+    #
+    # @param [String] statement
+    #   a string of SQL or DDL to be executed
+    #
+    # @param [Array] *bind_values
+    #   a list of parameters to substitute in the statement
+    #
+    # @return [Result]
+    #   the result of the query
+    def execute(statement, *bind_values)
+      Result.new([])
+    end
+
+    # Escape a given value for safe interpolation into a statement.
+    #
+    # This should be avoided where the driver natively supports bind parameters.
+    #
+    # Drivers MUST override this with a RDBMS-specific solution.
+    #
+    # @param [Object] value
+    #   the value to quote
+    #
+    # @return [String]
+    #   a safely escaped value
+    def quote(value)
+    end
+
+    private
+
+    def emulated_statement_executor(stmt)
+      EmulatedStatementExecutor.new(self, stmt)
+    end
+  end
+end

data/lib/rdo/emulated_statement_executor.rb

@@ -0,0 +1,36 @@
+##
+# RDO: Ruby Data Objects.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+module RDO
+  # This StatementExecutor is used as a fallback for prepared statements.
+  #
+  # If a DBMS driver does not implement prepared statements, this is used instead.
+  # The #execute method simply delegates back to the connection object.
+  class EmulatedStatementExecutor
+    attr_reader :command
+
+    # Initialize a new statement executor for the given connection & command.
+    #
+    # @param [RDO::Connection] connection
+    #   the connection on which #prepare was invoked
+    #
+    # @param [String] command
+    #   a string of SQL/DDL to execute
+    def initialize(connection, command)
+      @connection = connection
+      @command    = command
+    end
+
+    # Execute the command using the given bind values.
+    #
+    # @param [Object...] args
+    #   bind parameters to use in place of '?'
+    def execute(*args)
+      @connection.execute(command, *args)
+    end
+  end
+end

data/lib/rdo/exception.rb

@@ -0,0 +1,11 @@
+##
+# RDO: Ruby Data Objects.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+module RDO
+  # This is the only type of Exception raised by RDO.
+  class Exception < RuntimeError; end
+end

data/lib/rdo/result.rb

@@ -0,0 +1,95 @@
+##
+# RDO: Ruby Data Objects.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+module RDO
+  # The standard Result class returned by Connection#execute.
+  #
+  # Both read and write queries receive results in this format.
+  class Result
+    include Enumerable
+
+    # Initialize a new Result.
+    #
+    # @param [Enumerable] tuples
+    #   a list of tuples, provided by the driver
+    #
+    # @param [Hash] info
+    #   information about the result, including:
+    #   - count
+    #   - rows_affected
+    #   - insert_id
+    #   - execution_time
+    def initialize(tuples, info = {})
+      @info   = info.dup
+      @tuples = tuples
+    end
+
+    # Get raw result info provided by the driver.
+    #
+    # @return [Hash]
+    #   aribitrary information provided about the result
+    def info
+      @info
+    end
+
+    # Return the inserted row ID.
+    #
+    # For some drivers this requires that a RETURNING clause by used in SQL.
+    # It may be more desirable to simply check the rows in the result.
+    #
+    # @return [Object]
+    #   the ID of the record just inserted, or nil
+    def insert_id
+      if info.key?(:insert_id)
+        info[:insert_id]
+      else
+        first_value
+      end
+    end
+
+    # If only one column and one row is expected in the result, fetch it.
+    #
+    # If no rows were returned, this method returns nil.
+    #
+    # @return [Object]
+    #   a single value at the first column in the first row of the result
+    def first_value
+      if row = first
+        row.values.first
+      end
+    end
+
+    # Return the number of rows affected by the query.
+    #
+    # @return [Fixnum]
+    #   the number of rows affected
+    def affected_rows
+      info[:affected_rows].to_i
+    end
+
+    # Get the number of rows in the result.
+    #
+    # Many drivers provide the count, otherwise it will be computed at runtime.
+    #
+    # @return Fixnum
+    #   the number of rows in the Result
+    def count
+      if info[:count].nil? || block_given?
+        super
+      else
+        info[:count]
+      end
+    end
+
+    # Iterate over all rows returned by the connection.
+    #
+    # For each row, a Symbol-keyed Hash is yielded into the block.
+    def each(&block)
+      tap{ @tuples.each(&block) }
+    end
+  end
+end

data/lib/rdo/statement.rb

@@ -0,0 +1,28 @@
+##
+# RDO: Ruby Data Objects.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+require "forwardable"
+
+module RDO
+  # Represents a prepared statement.
+  #
+  # This class actually just wraps a StatementExecutor,
+  # which only needs to conform to a duck-type
+  class Statement
+    extend Forwardable
+
+    def_delegators :@executor, :command, :execute
+
+    # Initialize a new Statement wrapping the given StatementExecutor.
+    #
+    # @param [Object] executor
+    #   any object that responds to #execute, #connection and #command
+    def initialize(executor)
+      @executor = executor
+    end
+  end
+end

data/lib/rdo/util.rb

@@ -0,0 +1,102 @@
+##
+# RDO: Ruby Data Objects.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+require "date"
+require "bigdecimal"
+
+module RDO
+  # This file contains methods useful for drivers to convert complex types.
+  #
+  # Performing these operations in C would not be any cheaper, since the data
+  # must first be converted into Ruby types anyway.
+  module Util
+    class << self
+      # Convert a String to a Float, taking into account Infinity and NaN.
+      #
+      # @param [String] s
+      #   a String that is formatted for a Float;
+      #   or Infinity, -Infinity or NaN.
+      #
+      # @return [Float]
+      #   a Float that is the same as the input
+      def float(s)
+        case s
+        when "Infinity"
+          Float::INFINITY
+        when "-Infinity"
+          -Float::INFINITY
+        when "NaN"
+          Float::NAN
+        else
+          Float(s)
+        end
+      end
+
+      # Convert a String to a BigDecimal.
+      #
+      # @param [String] s
+      #   a String that is formatted as a decimal, or NaN
+      #
+      # @return [BigDecimal]
+      #   the BigDecimal representation of this number
+      def decimal(s)
+        BigDecimal(s)
+      end
+
+      # Convert a date & time string, without a time zone, into a DateTime.
+      #
+      # This method will parse the DateTime using the system time zone.
+      #
+      # @param [String] s
+      #   a date & time string
+      #
+      # @return [DateTime]
+      #   a DateTime in the system time zone
+      def date_time_without_zone(s)
+        date_time_with_zone(s + system_time_zone)
+      end
+
+      # Convert a date & time string, with a time zone, into a DateTime.
+      #
+      # @param [String] s
+      #   a date & time string, including a time zone
+      #
+      # @return [DateTime]
+      #   a DateTime for this input
+      def date_time_with_zone(s)
+        DateTime.parse(s)
+      end
+
+      # Convert a date string into a Date.
+      #
+      # This method understands AD and BC.
+      #
+      # @param [String] s
+      #   a string representing a date, possibly BC
+      #
+      # @return [Date]
+      #   a Date for this input
+      def date(s)
+        Date.parse(s)
+      end
+
+      # Get the time zone of the local system.
+      #
+      # This is useful—in fact crucial—for ensuring times are represented
+      # correctly.
+      #
+      # Driver developers should use this, where possible, to notify the DBMS
+      # of the client's time zone.
+      #
+      # @return [String]
+      #   a string of the form '+10:00', or '-09:30'
+      def system_time_zone
+        DateTime.now.zone
+      end
+    end
+  end
+end

data/lib/rdo/version.rb

@@ -0,0 +1,3 @@
+module RDO
+  VERSION = "0.0.1"
+end

data/rdo.gemspec

@@ -0,0 +1,52 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/rdo/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["d11wtq"]
+  gem.email         = ["chris@w3style.co.uk"]
+
+  gem.description   = <<-TEXT.strip.gsub(/^ {2}/, "")
+  == Ruby Data Objects
+
+  If you're building something in Ruby that needs access to a database, you may
+  opt to use an ORM like ActiveRecord, DataMapper or Sequel. But if your needs
+  don't fit well with an ORM (maybe you're even writing an ORM?) then you'll
+  need some other way of talking to your database.
+
+  RDO provides a common interface to a number of RDBMS backends, using a clean
+  Ruby syntax, while supporting all the functionality you'd expect from a robust
+  database connection library:
+
+    - Connect to different types of RDBMS in a consistent way
+    - Type casting
+    - Safe parameterization of queries
+    - Buffered query results
+    - Fetching meta data from executed commands
+    - Access RETURNING values just like any read query
+    - Prepared statements (emulated where no native support exists)
+    - Simple core ruby data types
+
+  === RDBMS Support
+
+  Support for each RDBMS is provided in separate gems, so as to minimize the
+  installation requirements. Many gems are maintained by separate users who
+  work more closely with those RDBMS's.
+
+  Due to the nature of this gem, most of the nitty-gritty code is actually
+  written in C.
+
+  See the official README for full details.
+  TEXT
+
+  gem.summary       = "RDO—Ruby Data Objects—A robust RDBMS connection layer"
+  gem.homepage      = "https://github.com/d11wtq/rdo"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "rdo"
+  gem.require_paths = ["lib"]
+  gem.version       = RDO::VERSION
+
+  gem.add_development_dependency "rspec"
+end