vertica 0.9.0.beta3 → 0.9.0.beta4

data/Gemfile.lock

@@ -1,9 +1,3 @@
-PATH
-  remote: .
-  specs:
-    vertica (0.9.0.beta2)
-      vertica
-
 GEM
   remote: http://rubygems.org/
   specs:
@@ -21,4 +15,3 @@ PLATFORMS
 DEPENDENCIES
   jeweler
   rake
-  vertica!

data/README.md

@@ -1,12 +1,11 @@
 # Vertica
 
-**WARNING:** This is not well tested software (yet) use at your own risk.
+Vertica is a pure Ruby library for connecting to Vertica databases. You can learn more
+about Vertica at http://www.vertica.com.  
 
-## Description
-
-Vertica is a pure Ruby library for connecting to Vertica databases.  You can learn more
-about Vertica at http://www.vertica.com.  This library currently supports queries. Prepared
-statements still need a bit of work.
+This library currently supports simple queries. Prepared statements are currently not supported
+but are being worked on. The gem is tested against Vertica version 5.0 and should work in both 
+Ruby 1.8 and Ruby 1.9.
 
 # Install
 
@@ -24,62 +23,89 @@ and cloned from:
 
 # Usage
 
-## Example Query
+## Connecting
 
-### Connecting
+The <code>Vertica.connect</code> methods takes a connection parameter hash and returns a 
+connection object. For most options, the gem will use a default value if no value is provided.
 
-    vertica = Vertica.connect({
+    connection = Vertica.connect({
+      :host     => 'db_server',
       :user     => 'user',
       :password => 'password',
-      :host     => 'db_server',
-      :port     => '5433',
-      :database => 'db
+      # :ssl         => false, # use SSL for the connection
+      # :port        => 5433,  # default Vertica port: 5433
+      # :database    => 'db',  # there is only one database
+      # :role        => nil,   # the (additional) role(s) to enable for the user.
+      # :search_path => nil,   # default: <user>,public,v_catalog
+      # :row_style   => :hash  # can also be :array (see below)
     })
+    
+To close the connection when you're done with it, run <code>connection.close</code>.
+
+## Querying
 
-### Buffered Rows
+You can run simple queries using the <code>query</code> method, either in buffered and 
+unbuffered mode. For large result sets, you probably do not want to use buffered results.
 
-All rows will first be fetched and buffered into a result object. Probably shouldn't use
-this for large result sets.
+### Unbuffered result
 
-    result = vertica.query("SELECT id, name FROM my_table")
-    result.each_row |row|
+Get all the result rows without buffering by providing a block:
+
+    connection.query("SELECT id, name FROM my_table") do |row|
       puts row # => {:id => 123, :name => "Jim Bob"}
     end
+    
+    connection.close
+    
+### Buffered result
+
+Store the result of the query method as a variable to get a buffered resultset:
 
+    result = connection.query("SELECT id, name FROM my_table")
+    connection.close
+    
     result.rows # => [{:id => 123, :name => "Jim Bob"}, {:id => 456, :name => "Joe Jack"}]
     result.row_count # => 2
+    
+    result.each do |row|
+      puts row # => {:id => 123, :name => "Jim Bob"}
+    end
 
-    vertica.close
-
-### Unbuffered Rows
+### Row format
 
-The vertica gem will not buffer incoming results. The gem will read a result off the
-socket and pass it to the provided block.
+By default, rows are returned as hashes, using symbols for the column names. Rows can also 
+be returned as arrays by providing a row_style:
 
-    vertica.query("SELECT id, name FROM my_table") do |row|
-      puts row # => {:id => 123, :name => "Jim Bob"}
+    connection.query("SELECT id, name FROM my_table", :row_style => :array) do |row|
+      puts row # => [123, "Jim Bob"]
     end
-    vertica.close
+    
+By adding <code>:row_style => :array</code> to the connection hash, all results will be 
+returned as array.
 
-### Example Prepared Statement
+# About
 
-This is flaky at best right now and needs some work. This will probably fail and destroy
-your connection. You'll need to throw the connection away and start over.
+This package is MIT licensed. See the LICENSE file for more information.
 
-    vertica.prepare("my_prepared_statement", "SELECT * FROM my_table WHERE id = ?", 1)
-    result = vertica.execute_prepared("my_prepared_statement", 13)
-    result.each_rows |row|
-      puts row # => {:id => 123, :name => "Jim Bob"}
-    end
-    result.rows # => [{:id => 123, :name => "Jim Bob"}, {:id => 456, :name => "Joe Jack"}]
-    vertica.close
+## Development
+
+This project comes with a test suite. The unit tests in <tt>/test/unit</tt> do not need a database
+connection to run, the functional tests in <tt>/test/functional</tt> do need a working
+database connection. You can specify the connection parameters by copying the file
+<tt>/test/connection.yml.example</tt> to <tt>/test/connection.yml</tt> and filling out the 
+necessary fields. 
+
+Note that the test suite requires write access to the default schema of the provided connection, 
+although it tries to be as little invasive as possible: all tables it creates (and drops) are 
+prefixed with <tt>test_ruby_vertica_</tt>.
 
-# TODO
+### TODO
 
- * Tests.
- * Lots of tests.
+ * Prepared statements
+ * More tests
 
-# Authors
+## Authors
 
  * [Matt Bauer](http://github.com/mattbauer) all the hard work
  * [Jeff Smick](http://github.com/sprsquish) current maintainer
+ * [Willem van Bergen](http://github.com/wvanbergen) contributor

data/Rakefile

@@ -26,7 +26,7 @@ end
 
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
-  test.libs << 'test'
+  test.libs << 'test' << 'lib'
   test.pattern = 'test/**/*_test.rb'
   test.verbose = true
 end

data/VERSION

@@ -1 +1 @@
-0.9.0.beta3
+0.9.0.beta4

data/lib/vertica.rb

@@ -1,6 +1,10 @@
 require 'date'
 require 'bigdecimal'
 
+# Main module for this library. It contains the {.connect} method to return a
+# {Vertica::Connection} instance, and methods to quote values ({.quote}) and 
+# identifiers ({.quote_identifier}) to safely include those in SQL strings to
+# prevent SQL injection.
 module Vertica
   
   class Error < StandardError
@@ -9,13 +13,26 @@ module Vertica
     class QueryError < Error; end
   end
 
-  PROTOCOL_VERSION = 3 << 16
+  # The version number of this library.
   VERSION = File.read(File.join(File.dirname(__FILE__), *%w[.. VERSION])).strip
 
-  def self.connect(*args)
-    Connection.new(*args)
+  # The protocol version (3.0.0) implemented in this library.
+  PROTOCOL_VERSION = 3 << 16
+
+  # Opens a new connection to a Vertica database.
+  # @param (see Vertica::Connection#initialize)
+  # @return [Vertica::Connection] The created connection to Vertica, ready for queries.
+  def self.connect(options)
+    Vertica::Connection.new(options)
   end
   
+  # Properly quotes a value for safe usage in SQL queries.
+  #
+  # This method has quoting rules for common types. Any other object will be converted to
+  # a string using +:to_s+ and then quoted as a string.
+  #
+  # @param [Object] value The value to quote.
+  # @return [String] The quoted value that can be safely included in SQL queries.
   def self.quote(value)
     case value
       when nil        then 'NULL'
@@ -32,6 +49,9 @@ module Vertica
     end
   end
   
+  # Quotes an identifier for safe use within SQL queries, using double quotes.
+  # @param [:to_s] identifier The identifier to quote.
+  # @return [String] The quoted identifier that can be safely included in SQL queries.
   def self.quote_identifier(identifier)
     "\"#{identifier.to_s.gsub(/"/, '""')}\""
   end

data/lib/vertica/connection.rb

@@ -1,236 +1,187 @@
 require 'socket'
 
-module Vertica
-  class Connection
+class Vertica::Connection
 
-    STATUSES = {
-      'I' => :no_transaction,
-      'T' => :in_transaction,
-      'E' => :failed_transaction
-    }
+  attr_reader :options, :notices, :transaction_status, :backend_pid, :backend_key, :parameters, :notice_handler
 
-    attr_reader :options, :notices, :transaction_status, :backend_pid, :backend_key, :notifications, :parameters
+  attr_accessor :row_style, :debug
 
-    attr_accessor :row_style, :debug
+  def self.cancel(existing_conn)
+    conn = self.new(existing_conn.options.merge(:skip_startup => true))
+    conn.write Vertica::Messages::CancelRequest.new(existing_conn.backend_pid, existing_conn.backend_key)
+    conn.write Vertica::Messages::Flush.new
+    conn.socket.close
+  end
 
-    def self.cancel(existing_conn)
-      conn = self.new(existing_conn.options.merge(:skip_startup => true))
-      conn.write Messages::CancelRequest.new(existing_conn.backend_pid, existing_conn.backend_key)
-      conn.write Messages::Flush.new
-      conn.socket.close
-    end
+  # Opens a connectio the a Vertica server
+  # @param [Hash] options The connection options to use.
+  def initialize(options = {})
+    reset_values
 
-    def initialize(options = {})
-      reset_values
+    @options = {}
+    options.each { |key, value| @options[key.to_s.to_sym] = value }
+    @options[:port] ||= 5433
 
-      @options = {}
-      options.each { |key, value| @options[key.to_s.to_sym] = value }
-      
-      @notices = []
-      
-      @row_style = @options[:row_style] ? @options[:row_style] : :hash
-
-      unless options[:skip_startup]
-        write Messages::Startup.new(@options[:user], @options[:database])
-        process
-        
-        query("SET SEARCH_PATH TO #{options[:search_path]}") if options[:search_path]
-        query("SET ROLE #{options[:role]}") if options[:role]
-      end
+    @row_style = @options[:row_style] ? @options[:row_style] : :hash
+    unless options[:skip_startup]
+      startup_connection
+      initialize_connection
     end
-
-    def socket
-      @socket ||= begin
-        raw_socket = TCPSocket.new(@options[:host], @options[:port].to_s)
-        if @options[:ssl]
-          require 'openssl/ssl'
-          raw_socket.write Messages::SslRequest.new.to_bytes
-          if raw_socket.read(1) == 'S'
-            raw_socket = OpenSSL::SSL::SSLSocket.new(raw_socket, OpenSSL::SSL::SSLContext.new)
-            raw_socket.sync = true
-            raw_socket.connect
-          else
-            raise Error::ConnectionError.new("SSL requested but server doesn't support it.")
-          end
+  end
+  
+  def on_notice(&block)
+    @notice_handler = block
+  end
+  
+  def socket
+    @socket ||= begin
+      raw_socket = TCPSocket.new(@options[:host], @options[:port].to_i)
+      if @options[:ssl]
+        require 'openssl/ssl'
+        raw_socket.write Vertica::Messages::SslRequest.new.to_bytes
+        if raw_socket.read(1) == 'S'
+          raw_socket = OpenSSL::SSL::SSLSocket.new(raw_socket, OpenSSL::SSL::SSLContext.new)
+          raw_socket.sync = true
+          raw_socket.connect
+        else
+          raise Vertica::Error::ConnectionError.new("SSL requested but server doesn't support it.")
         end
-        
-        raw_socket
       end
+      
+      raw_socket
     end
+  end
 
-    def ssl?
-      socket.kind_of?(OpenSSL::SSL::SSLSocket)
-    end
-
-    def opened?
-      @socket && @backend_pid && @transaction_status
-    end
-
-    def closed?
-      !opened?
-    end
-
-    def write(message)
-      raise ArgumentError, "invalid message: (#{message.inspect})" unless message.respond_to?(:to_bytes)
-      puts "=> #{message.inspect}" if @debug
-      socket.write message.to_bytes
-    end
-
-    def close
-      write Messages::Terminate.new
-      socket.close
-      @socket = nil
-    rescue Errno::ENOTCONN # the backend closed the socket already
-    ensure
-      reset_values
-    end
-
-    def reset
-      close if opened?
-      reset_values
-    end
-
-    def query(query_string, &block)
-      raise ArgumentError.new("Query string cannot be blank or empty.") if query_string.nil? || query_string.empty?
-      reset_result
-      write Messages::Query.new(query_string)
-      @process_row = block
-      result = process(true)
-      result unless @process_row
-    end
-
-    def prepare(name, query, params_count = 0)
-      param_types = Array.new(params_count).fill(0)
-
-      write Messages::Parse.new(name, query, param_types)
-      write Messages::Describe.new(:prepared_statement, name)
-      write Messages::Sync.new
-      write Messages::Flush.new
-
-      process
-    end
-
-    def execute_prepared(name, *param_values)
-      portal_name = "" # use the unnamed portal
-      max_rows    = 0  # return all rows
-
-      reset_result
+  def ssl?
+    socket.kind_of?(OpenSSL::SSL::SSLSocket)
+  end
 
-      write Messages::Bind.new(portal_name, name, param_values)
-      write Messages::Execute.new(portal_name, max_rows)
-      write Messages::Sync.new
+  def opened?
+    @socket && @backend_pid && @transaction_status
+  end
 
-      result = process(true)
+  def closed?
+    !opened?
+  end
 
-      # Close the portal
-      write Messages::Close.new(:portal, portal_name)
-      write Messages::Flush.new
+  def write(message)
+    raise ArgumentError, "invalid message: (#{message.inspect})" unless message.respond_to?(:to_bytes)
+    puts "=> #{message.inspect}" if @debug
+    socket.write message.to_bytes
+  end
 
-      process
+  def close
+    write Vertica::Messages::Terminate.new
+    socket.close
+    @socket = nil
+  rescue Errno::ENOTCONN # the backend closed the socket already
+  ensure
+    reset_values
+  end
 
-      # Return the result from the prepared statement
-      result
+  def reset
+    close if opened?
+    reset_values
+  end
+  
+  def read_message
+    type = read_bytes(1)
+    size = read_bytes(4).unpack('N').first
+    raise Vertica::Error::MessageError.new("Bad message size: #{size}.") unless size >= 4
+    message = Vertica::Messages::BackendMessage.factory type, read_bytes(size - 4)
+    puts "<= #{message.inspect}" if @debug
+    return message
+  end
+  
+  def process_message(message)
+    case message
+    when Vertica::Messages::ErrorResponse
+      raise Vertica::Error::ConnectionError.new(message.error_message)
+    when Vertica::Messages::NoticeResponse
+      @notice_handler.call(message) if @notice_handler
+    when Vertica::Messages::BackendKeyData
+      @backend_pid = message.pid
+      @backend_key = message.key
+    when Vertica::Messages::ParameterStatus
+      @parameters[message.name] = message.value
+    when Vertica::Messages::ReadyForQuery
+      @transaction_status = message.transaction_status
+    else
+      raise Vertica::Error::MessageError, "Unhandled message: #{message.inspect}"
     end
+  end
+  
 
-    protected
-
-
-    def read_bytes(n)
-      bytes = socket.read(n)
-      raise Vertica::Error::ConnectionError.new("Couldn't read #{n} characters from socket.") if bytes.nil? || bytes.size != n
-      return bytes
+  def query(sql, options = {}, &block)
+    job = Vertica::Query.new(self, sql, { :row_style => @row_style }.merge(options))
+    job.row_handler = block if block_given?
+    return job.run
+  end
+  
+  def copy(sql, source = nil, &block)
+    job = Vertica::Query.new(self, sql, :row_style => @row_style)
+    if block_given?
+      job.copy_handler = block 
+    elsif source && File.exists?(source.to_s)
+      job.copy_handler = lambda { |data| file_copy_handler(source, data) }
+    elsif source.respond_to?(:read) && source.respond_to?(:eof?)
+      job.copy_handler = lambda { |data| io_copy_handler(source, data) }
+    end
+    return job.run
+  end
+  
+  protected
+  
+  def file_copy_handler(input_file, output)
+    File.open(input_file, 'r') do |input|
+      while data = input.read(4096)
+        output << data
+      end
     end
-    
-    def read_message
-      type = read_bytes(1)
-      size = read_bytes(4).unpack('N').first
-      raise Vertica::Error::MessageError.new("Bad message size: #{size}.") unless size >= 4
-      msg = Messages::BackendMessage.factory type, read_bytes(size - 4)
-      puts "<= #{msg.inspect}" if @debug
-      return msg
+  end
+  
+  def io_copy_handler(input, output)
+    until input.eof?
+      output << input.read(4096) 
     end
+  end
 
-
-    def process(return_result = false)
-      result = return_result ? Result.new(row_style) : nil
-      loop do
-        case message = read_message
-        when Messages::Authentication
-          if message.code != Messages::Authentication::OK
-            write Messages::Password.new(@options[:password], message.code, {:user => @options[:user], :salt => message.salt})
-          end
-
-        when Messages::BackendKeyData
-          @backend_pid = message.pid
-          @backend_key = message.key
-
-        when Messages::DataRow
-          @process_row.call(result.format_row(message)) if @process_row && result
-          result.add_row(message) if result && !@process_row
-
-        when Messages::ErrorResponse
-          error_class = result ? Vertica::Error::QueryError : Vertica::Error::ConnectionError
-          raise error_class.new(message.error_message)
+  def read_bytes(n)
+    bytes = socket.read(n)
+    raise Vertica::Error::ConnectionError.new("Couldn't read #{n} characters from socket.") if bytes.nil? || bytes.size != n
+    return bytes
+  end
   
-
-        when Messages::NoticeResponse
-          @notices << message.values
-
-        when Messages::NotificationResponse
-          @notifications << Notification.new(message.pid, message.condition, message.additional_info)
-
-        when Messages::ParameterStatus
-          @parameters[message.name] = message.value
-
-        when Messages::ReadyForQuery
-          @transaction_status = STATUSES[message.transaction_status]
-          break unless return_result
-
-        when Messages::RowDescription
-          result.descriptions = message if result
-
-        when Messages::Unknown
-          raise Error::MessageError.new("Unknown message type: #{message.message_id}")
-
-        when  Messages::BindComplete,
-              Messages::NoData,
-              Messages::EmptyQueryResponse,
-              Messages::ParameterDescription
-          :nothing
-
-        when  Messages::CloseComplete,
-              Messages::CommandComplete,
-              Messages::ParseComplete,
-              Messages::PortalSuspended
-          break
+  def startup_connection
+    write Vertica::Messages::Startup.new(@options[:user], @options[:database])
+    message = nil
+    begin 
+      case message = read_message
+      when Vertica::Messages::Authentication
+        if message.code != Vertica::Messages::Authentication::OK
+          write Vertica::Messages::Password.new(@options[:password], message.code, {:user => @options[:user], :salt => message.salt})
         end
+      else
+        process_message(message)
       end
+    end until message.kind_of?(Vertica::Messages::ReadyForQuery)
+  end
+  
+  def initialize_connection
+    query("SET SEARCH_PATH TO #{options[:search_path]}") if options[:search_path]
+    query("SET ROLE #{options[:role]}") if options[:role]
+  end
 
-      result
-    end
-
-    def reset_values
-      reset_notifications
-      reset_result
-      @parameters         = {}
-      @backend_pid        = nil
-      @backend_key        = nil
-      @transaction_status = nil
-      @socket             = nil
-      @process_row        = nil
-    end
-
-    def reset_notifications
-      @notifications      = []
-    end
-
-    def reset_result
-      @field_descriptions = []
-      @field_values       = []
-    end
+  def reset_values
+    @parameters         = {}
+    @backend_pid        = nil
+    @backend_key        = nil
+    @transaction_status = nil
+    @socket             = nil
   end
 end
 
+require 'vertica/query'
 require 'vertica/column'
 require 'vertica/result'
 require 'vertica/messages/message'