rdo 0.0.8 → 0.1.0

data/README.md

@@ -36,18 +36,18 @@ end
 conn.close
 ```
 
-## Why your ORM so shit?
+## Strange looking ORM you have there, Sir
 
-RDO provides access to a number of RDBMS's. It allows you to query using SQL
-and other things using DDL, as thinly as is necessary. It is absolutely not,
-nor is it trying to be an SQL abstraction layer, an ORM or anything of that
-nature. The intention is to provide a way to allow Ruby developers to write
-applications that use a database, but don't use an ORM (*scoff!*).
+It's not an ORM. RDO provides access to a number of RDBMS's. It allows you to
+query using pure SQL/DDL commands, as thinly as is necessary. It is absolutely
+not, nor is it trying to be an SQL abstraction layer, an ORM or anything of
+that nature. The intention is to provide a way to allow Ruby developers to
+write applications that use a database, but don't use an ORM (*scoff!*).
 
 Or perhaps you're actually writing the next kick-ass ORM? Either way, RDO
 just lets you talk directly to your database.
 
-## Meh, what does it provide?
+## What's the point?
 
 Let's face it, we've been writing database applications since the dark ages—
 it's not that hard. What's lacking from Ruby, however, is any consistency for
@@ -56,7 +56,7 @@ serve a different need. [DataMapper](https://github.com/datamapper/dm-core)
 has a layer underneath it called [data_objects](https://github.com/datamapper/do),
 but it isn't particularly user-friendly when used standalone and it requires
 jumping through hoops to deal with certain database RDBMS features, such as
-PostgreSQL bytea fields.
+PostgreSQL bytea fields (which, in RDO, "just work").
 
 RDO makes the following things standard:
 
@@ -65,11 +65,11 @@ RDO makes the following things standard:
   - **Prepared statements** where possible; emulated where not
   - **Type-casting** to equivalent Ruby types (e.g. Fixnum, BigDecimal,
     Float, even Array)
-  - **Buffered result sets** where possible–enumerate millions of rows
-    without memory issues
   - Access meta data after write operations, with insert IDs standardized
   - **Use simple core data types** (Hash) for reading values and field names
 
+Note that data-type support is limited to whatever the DBMS actually supports.
+
 ## Installation
 
 RDO doesn't do anything by itself. You need to also install the driver for
@@ -125,7 +125,10 @@ And then execute:
       <td>mysql</td>
       <td><a href="https://github.com/d11wtq/rdo-mysql">rdo-mysql</a></td>
       <td><a href="https://github.com/d11wtq">d11wtq</a></td>
-      <td>In development</td>
+      <td>
+        <img src="https://secure.travis-ci.org/d11wtq/rdo-mysql.png?branch=master"
+          alt="Build Status" title="Build Status" />
+      </td>
     </tr>
   </tbody>
 </table>
@@ -154,6 +157,10 @@ For semantic reasons, #connect is aliased to #open.
 If it is not possible to establish a connection an RDO::Exception is raised,
 which should provide any reason given by the DBMS.
 
+You can also pass a block to #connect. This has the same semantics as passing
+a block to File#open (i.e. it passes itself to the block, returns the value
+of the block and finally closes the connection).
+
 ### Disconnecting
 
 RDO will disconnect automatically when the connection is garbage-collected,
@@ -170,18 +177,6 @@ conn.open
 p conn.open? #=> true
 ```
 
-### One-time use connections
-
-If you pass a block to RDO.connect, RDO yields the connection into the block,
-returns the result of the block, then closes the connection.
-
-``` ruby
-puts RDO.open("sqlite:some.db") do |c|
-  c.execute("SELECT value FROM config WHERE name = ?", "api_key").first_value
-end
-# => "EXAMPLE_KEY"
-```
-
 ### Performing non-read commands
 
 All SQL and DDL (Data Definition Language) is executed with #execute, which
@@ -216,7 +211,7 @@ include any error messaage provided by the DBMS.
 ### Performing read queries
 
 There is no difference in the interface for reads or writes. Just call
-the #execute method—which always returns a RDO::Result—for both.
+the #execute method in both cases. This always returns a RDO::Result.
 RDO::Result includes the Enumerable module. Some operations, such as #count
 may be optimized by the driver.
 
@@ -298,6 +293,16 @@ This method returns nil if there are no rows, so if you need to distinguish
 between NULL and no rows, you will need to check the result contents the
 longer way around.
 
+### Logging Statements
+
+A Logger instance (with an interface like that in Ruby stdlib) may be passed
+in the options when creating a connection. All queries will be logged with
+DEBUG severity. Errors will be logged with FATAL severity.
+
+``` ruby
+RDO.connect("postgres://user:pass@host/db", logger: Logger.new(STDOUT))
+```
+
 ## Contributing
 
 If you find a bug in RDO, send a pull request if you think you can fix it.
@@ -330,6 +335,9 @@ drivers. If you have written a driver for RDO, please fork this git repo and
 edit this README to list it, then send a pull request. That way others will
 find it more easily.
 
+I'm particularly interested in drivers for Oracle and Microsoft SQL Server,
+though I don't personally use these.
+
 ## Copyright & Licensing
 
 Written and maintained by Chris Corbyn.

data/lib/rdo.rb

@@ -13,6 +13,7 @@ require "rdo/statement"
 require "rdo/emulated_statement_executor"
 require "rdo/result"
 require "rdo/util"
+require "rdo/colored_logger"
 
 # c extension
 require "rdo/rdo"
@@ -28,24 +29,36 @@ module RDO
     # closed at the end of the block, before this method finally returns
     # the result of the block.
     #
-    # @param [Object] options
-    #   either a connection URI string, or an option Hash
+    # @param [Object] uri
+    #   either a connection URI string, or an options Hash
+    #
+    # @param [Hash] options
+    #   if a URI is provided for the first argument, additional options may
+    #   be specified here. These may override settings in the first argument.
     #
     # @return [Connection]
     #   a Connection for the required driver
-    def connect(options)
+    def connect(uri, options = {})
       if block_given?
         begin
-          c = Connection.new(options)
+          c = Connection.new(uri, options)
           yield c
         ensure
           c.close unless c.nil?
         end
       else
-        Connection.new(options)
+        Connection.new(uri, options)
       end
     end
 
     alias_method :open, :connect
   end
+
+  # A suitable NULL device for writing nothing
+  DEV_NULL =
+    if defined? IO::NULL
+      IO::NULL
+    else
+      ENV["OS"] =~ /Windows/ ? "NUL" : "/dev/null"
+    end
 end

data/lib/rdo/colored_logger.rb

@@ -0,0 +1,25 @@
+##
+# RDO: Ruby Data Objects.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+require "logger"
+
+module RDO
+  # A Logger that outputs using color to highlight errors etc.
+  class ColoredLogger < Logger
+    def initialize(*)
+      super
+      self.formatter =
+        Proc.new do |severity, time, prog, msg|
+          case severity
+          when "DEBUG" then "\033[35mSQL\033[0m \033[36m~\033[0m %s\n" % msg
+          when "FATAL" then "\033[31mERROR ~ %s\033[0m\n" % msg
+          else "%s ~ %s\n" % [severity, msg]
+          end
+        end
+    end
+  end
+end

data/lib/rdo/connection.rb

@@ -7,6 +7,7 @@
 
 require "uri"
 require "cgi"
+require "logger"
 require "forwardable"
 
 module RDO
@@ -41,8 +42,11 @@ module RDO
     # Options passed to initialize.
     attr_reader :options
 
+    # A Logger (from ruby stdlib)
+    attr_accessor :logger
+
     # Most instance methods are delegated to the driver
-    def_delegators :@driver, :open, :open?, :close, :execute, :prepare, :quote
+    def_delegators :@driver, :open, :open?, :close, :quote
 
     # Initialize a new Connection.
     #
@@ -50,13 +54,18 @@ module RDO
     #
     # If no suitable driver is loaded, an RDO::Exception is raised.
     #
-    # @param [Object] options
-    #   either a connection URI, or a Hash of options
+    # @param [Object] uri
+    #   either a connection URI string, or an options Hash
+    #
+    # @param [Hash] options
+    #   if a URI is provided for the first argument, additional options may
+    #   be specified here. These may override settings in the first argument.
     #
     # @return [RDO::Connection]
     #   a Connection for the given options
-    def initialize(options)
-      @options = normalize_options(options)
+    def initialize(uri, options = {})
+      @options = normalize_options(uri).merge(normalize_options(options))
+      @logger  = @options.fetch(:logger, null_logger)
 
       unless self.class.drivers.key?(@options[:driver])
         raise RDO::Exception,
@@ -68,6 +77,47 @@ module RDO
         "Unable to connect, but the driver did not provide a reason"
     end
 
+    # 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.
+    #
+    # @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)
+      @driver.execute(statement, *bind_values).tap do
+        if logger.debug?
+          logger.debug("#{statement}#{" <Bind: #{bind_values.inspect}>" unless bind_values.empty?}")
+        end
+      end
+    rescue RDO::Exception => e
+      logger.fatal(e.message) if logger.fatal?
+      raise
+    end
+
+    # Create a prepared statement to later be executed with some inputs.
+    #
+    # Not all drivers support this natively, but it is emulated by default.
+    #
+    # @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(command)
+      Statement.new(@driver.prepare(command), logger)
+    end
+
     private
 
     # Normalizes the given options String or Hash into a Symbol-keyed Hash.
@@ -127,5 +177,9 @@ module RDO
     def parse_query_string(str)
       str.nil? ? {} : Hash[CGI.parse(str).map{|k,v| [k, v.size == 1 ? v.first : v]}]
     end
+
+    def null_logger
+      Logger.new(RDO::DEV_NULL).tap{|l| l.level = Logger::UNKNOWN}
+    end
   end
 end

data/lib/rdo/driver.rb

@@ -68,19 +68,19 @@ module RDO
     # @param [String] statement
     #   a string of SQL or DDL, with '?' placeholders for bind parameters
     #
-    # @return [Statement]
+    # @return [StatementExecutor]
     #   a prepared statement to later be executed
     def prepare(statement)
-      Statement.new(emulated_statement_executor(statement))
+      emulated_statement_executor(statement)
     end
 
     # Execute a statement against the RDBMS.
     #
-    # The statement can either by a read, or a write operation.
+    # 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 support bind parameters, this functionality is
+    # Where the RDBMS natively supports bind parameters, this functionality is
     # used; otherwise, the values are quoted using #quote.
     #
     # Drivers MUST override this.

data/lib/rdo/emulated_statement_executor.rb

@@ -9,20 +9,20 @@ 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.
+  # The #execute method simply delegates back to the driver.
   class EmulatedStatementExecutor
     attr_reader :command
 
-    # Initialize a new statement executor for the given connection & command.
+    # Initialize a new statement executor for the given driver & command.
     #
-    # @param [RDO::Connection] connection
-    #   the connection on which #prepare was invoked
+    # @param [RDO::Driver] driver
+    #   the Driver on which #prepare was invoked
     #
     # @param [String] command
     #   a string of SQL/DDL to execute
-    def initialize(connection, command)
-      @connection = connection
-      @command    = command
+    def initialize(driver, command)
+      @driver  = driver
+      @command = command
     end
 
     # Execute the command using the given bind values.
@@ -30,7 +30,7 @@ module RDO
     # @param [Object...] args
     #   bind parameters to use in place of '?'
     def execute(*args)
-      @connection.execute(command, *args)
+      @driver.execute(command, *args)
     end
   end
 end

data/lib/rdo/statement.rb

@@ -15,14 +15,36 @@ module RDO
   class Statement
     extend Forwardable
 
-    def_delegators :@executor, :command, :execute
+    def_delegators :@executor, :command
 
     # Initialize a new Statement wrapping the given StatementExecutor.
     #
     # @param [Object] executor
     #   any object that responds to #execute, #connection and #command
-    def initialize(executor)
+    def initialize(executor, logger)
       @executor = executor
+      @logger   = logger
+    end
+
+    # Execute the command using the given bind values.
+    #
+    # @param [Object...] args
+    #   bind parameters to use in place of '?'
+    def execute(*bind_values)
+      @executor.execute(*bind_values).tap do
+        if logger.debug?
+          logger.debug("#{command}#{" <Bind: #{bind_values.inspect}>" unless bind_values.empty?}")
+        end
+      end
+    rescue RDO::Exception => e
+      logger.fatal(e.message) if logger.fatal?
+      raise
+    end
+
+    private
+
+    def logger
+      @logger
     end
   end
 end

data/lib/rdo/version.rb

@@ -6,5 +6,5 @@
 ##
 
 module RDO
-  VERSION = "0.0.8"
+  VERSION = "0.1.0"
 end

data/spec/rdo/connection_spec.rb

@@ -1,4 +1,5 @@
 require "spec_helper"
+require "logger"
 
 describe RDO::Connection do
   after(:each) { RDO::Connection.drivers.clear }
@@ -193,16 +194,84 @@ describe RDO::Connection do
           and_return(result)
         connection.execute("SELECT * FROM bob WHERE ?", true).should == result
       end
+
+      context "with debug logging" do
+        before(:each) do
+          connection.logger.level = Logger::DEBUG
+          driver.stub(:execute).and_return(result)
+        end
+
+        it "logs the statement" do
+          connection.logger.should_receive(:debug).
+            with(/SELECT \* FROM bob WHERE \?.*?true/)
+          connection.execute("SELECT * FROM bob WHERE ?", true)
+        end
+      end
+
+      context "without debug logging" do
+        before(:each) do
+          connection.logger.level = Logger::INFO
+          driver.stub(:execute).and_return(result)
+        end
+
+        it "does not log the statement" do
+          connection.logger.should_not_receive(:debug)
+          connection.execute("SELECT * FROM bob WHERE ?", true)
+        end
+      end
+
+      context "when an RDO::Exception occurs" do
+        before(:each) do
+          driver.stub(:execute).and_raise(RDO::Exception.new("some error"))
+        end
+
+        context "with fatal logging" do
+          before(:each) do
+            connection.logger.level = Logger::FATAL
+          end
+
+          it "logs the error" do
+            begin
+              connection.logger.should_receive(:fatal).
+                with(/some error/)
+              connection.execute("SELECT * FROM bob WHERE ?", true)
+              fail("RDO::Exception should be raised")
+            rescue
+              # expected
+            end
+          end
+        end
+
+        context "without debug logging" do
+          before(:each) do
+            connection.logger.level = Logger::UNKNOWN
+          end
+
+          it "does not log the error" do
+            begin
+              connection.logger.should_not_receive(:fatal)
+              connection.execute("SELECT * FROM bob WHERE ?", true)
+              fail("RDO::Exception should be raised")
+            rescue
+              # expected
+            end
+          end
+        end
+      end
     end
 
     describe "#prepare" do
-      let(:stmt) { RDO::Statement.new(stub(:executor)) }
+      let(:command)  { "SELECT * FROM bob WHERE ?" }
+      let(:executor) { stub(command: command) }
 
       it "delegates to the driver" do
-        driver.should_receive(:prepare).
-          with("SELECT * FROM bob WHERE ?").
-          and_return(stmt)
-        connection.prepare("SELECT * FROM bob WHERE ?").should == stmt
+        driver.should_receive(:prepare).with(command).and_return(executor)
+        connection.prepare(command).command.should == command
+      end
+
+      it "returns a RDO::Statement" do
+        driver.stub(:prepare).and_return(executor)
+        connection.prepare(command).should be_a_kind_of(RDO::Statement)
       end
     end
 

data/spec/rdo/driver_spec.rb

@@ -10,12 +10,14 @@ describe RDO::Driver do
   describe "#prepare" do
     let(:driver) { RDO::DriverWithoutStatements.new }
 
-    it "returns a Statement" do
-      driver.prepare("SELECT * FROM bob WHERE ?").should be_a_kind_of(RDO::Statement)
+    it "returns a StatementExecutor" do
+      driver.prepare("SELECT * FROM bob WHERE ?").
+        should be_a_kind_of(RDO::EmulatedStatementExecutor)
     end
 
     it "has the correct command" do
-      driver.prepare("SELECT * FROM bob WHERE ?").command.should == "SELECT * FROM bob WHERE ?"
+      driver.prepare("SELECT * FROM bob WHERE ?").command.
+        should == "SELECT * FROM bob WHERE ?"
     end
 
     it "calls #execute on the driver" do

data/spec/rdo/statement_spec.rb

@@ -1,8 +1,10 @@
 require "spec_helper"
+require "logger"
 
 describe RDO::Statement do
+  let(:logger)   { Logger.new(RDO::DEV_NULL) }
   let(:executor) { double(:executor) }
-  let(:stmt)     { RDO::Statement.new(executor) }
+  let(:stmt)     { RDO::Statement.new(executor, logger) }
 
   describe "#command" do
     let(:command) { "SELECT * FROM users" }
@@ -14,11 +16,74 @@ describe RDO::Statement do
   end
 
   describe "#execute" do
-    let(:result) { stub(:result) }
+    let(:executor) { double(command: "SELECT * FROM bob WHERE ?", execute: result) }
+    let(:result)   { stub(:result) }
 
     it "delegates to the executor" do
       executor.should_receive(:execute).with(1, 2).and_return(result)
       stmt.execute(1, 2).should == result
     end
+
+    context "with debug logging" do
+      before(:each) do
+        logger.level = Logger::DEBUG
+        executor.stub(:execute).and_return(result)
+      end
+
+      it "logs the statement" do
+        logger.should_receive(:debug).with(/SELECT \* FROM bob WHERE \?.*?true/)
+        stmt.execute(true)
+      end
+    end
+
+    context "without debug logging" do
+      before(:each) do
+        logger.level = Logger::INFO
+        executor.stub(:execute).and_return(result)
+      end
+
+      it "does not log the statement" do
+        logger.should_not_receive(:debug)
+        stmt.execute(true)
+      end
+    end
+
+    context "when an RDO::Exception occurs" do
+      before(:each) do
+        executor.stub(:execute).and_raise(RDO::Exception.new("some error"))
+      end
+
+      context "with fatal logging" do
+        before(:each) do
+          logger.level = Logger::FATAL
+        end
+
+        it "logs the error" do
+          begin
+            logger.should_receive(:fatal).with(/some error/)
+            stmt.execute
+            fail("RDO::Exception should be raised")
+          rescue
+            # expected
+          end
+        end
+      end
+
+      context "without debug logging" do
+        before(:each) do
+          logger.level = Logger::UNKNOWN
+        end
+
+        it "does not log the error" do
+          begin
+            logger.should_not_receive(:fatal)
+            stmt.execute
+            fail("RDO::Exception should be raised")
+          rescue
+            # expected
+          end
+        end
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdo
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-30 00:00:00.000000000 Z
+date: 2012-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -77,6 +77,7 @@ files:
 - ext/rdo/extconf.rb
 - ext/rdo/rdo.c
 - lib/rdo.rb
+- lib/rdo/colored_logger.rb
 - lib/rdo/connection.rb
 - lib/rdo/driver.rb
 - lib/rdo/emulated_statement_executor.rb