vertica 0.7.4 → 0.8.1

data/README.md

@@ -0,0 +1,85 @@
+# Vertica
+
+**WARNING:** This is not well tested software (yet) use at your own risk.
+
+## 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.
+
+# Install
+
+    $ gem install vertica
+
+# Source
+
+Vertica's git repo is available on GitHub, which can be browsed at:
+
+    http://github.com/sprsquish/vertica
+
+and cloned from:
+
+    git://github.com/sprsquish/vertica.git
+
+# Usage
+
+## Example Query
+
+### Connecting
+
+    vertica = Vertica.connect({
+      :user     => 'user',
+      :password => 'password',
+      :host     => 'db_server',
+      :port     => '5433',
+      :database => 'db
+    })
+
+### Buffered Rows
+
+All rows will first be fetched and buffered into a result object. Probably shouldn't use
+this for large result sets.
+
+    result = vertica.query("SELECT id, name FROM my_table")
+    result.each_row |row|
+      puts row # => {:id => 123, :name => "Jim Bob"}
+    end
+
+    result.rows # => [{:id => 123, :name => "Jim Bob"}, {:id => 456, :name => "Joe Jack"}]
+    result.row_count # => 2
+
+    vertica.close
+
+### Unbuffered Rows
+
+The vertica gem will not buffer incoming results. The gem will read a result off the
+socket and pass it to the provided block.
+
+    vertica.query("SELECT id, name FROM my_table") do |row|
+      puts row # => {:id => 123, :name => "Jim Bob"}
+    end
+    vertica.close
+
+### Example Prepared Statement
+
+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.
+
+    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
+
+# TODO
+
+ * Tests.
+ * Lots of tests.
+
+# Authors
+
+ * [Matt Bauer](http://github.com/mattbauer) all the hard work
+ * [Jeff Smick](http://github.com/sprsquish) current maintainer

data/Rakefile

@@ -1,44 +1,62 @@
 require 'rubygems'
-require 'rake/gempackagetask'
-require 'rake/rdoctask'
-require 'rake/testtask'
-
-load 'vertica.gemspec'
- 
-Rake::GemPackageTask.new(VERTICA_SPEC) do |pkg|
-    pkg.need_tar = true
-end
- 
-task :default => "test"
+require 'rake'
 
-desc "Clean"
-task :clean do
-  include FileUtils
-  rm_rf 'pkg'
-end
- 
-desc "Run tests"
-Rake::TestTask.new("test") do |t|
-  t.libs << ["test", "ext"]
-  t.pattern = 'test/*_test.rb'
-  t.verbose = true
-  t.warning = true
-end
- 
-task :doc => [:rdoc]
-namespace :doc do
-  Rake::RDocTask.new do |rdoc|
-    files = ["README", "lib/**/*.rb"]
-    rdoc.rdoc_files.add(files)
-    rdoc.main = "README.textile"
-    rdoc.title = "Vertica Docs"
-    rdoc.rdoc_dir = "doc"
-    rdoc.options << "--line-numbers" << "--inline-source"
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = 'vertica'
+    gem.summary = 'Pure ruby library for interacting with Vertica'
+    gem.description = 'Query Vertica with ruby'
+
+    gem.email = 'sprsquish@gmail.com'
+    gem.homepage = 'http://github.com/sprsquish/vertica'
+    gem.authors = ['Jeff Smick', 'Matt Bauer']
+
+    gem.files = FileList["[A-Z]*", 'lib/**/*.rb'].to_a
+
+    gem.test_files = FileList['test/**/*.rb']
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
 end
+#
+# require 'rake/testtask'
+# Rake::TestTask.new(:test) do |test|
+#   test.libs << 'lib' << 'spec'
+#   test.pattern = 'spec/**/*_spec.rb'
+#   test.verbose = true
+# end
+#
+# begin
+#   require 'rcov/rcovtask'
+#   Rcov::RcovTask.new do |test|
+#     test.libs << 'spec'
+#     test.pattern = 'spec/**/*_spec.rb'
+#     test.rcov_opts += ['--exclude \/Library\/Ruby,spec\/', '--xrefs']
+#     test.verbose = true
+#   end
+# rescue LoadError
+#   task :rcov do
+#     abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+#   end
+# end
+
 
-desc "Run rcov on current app"
-task :rcov do
-  system "rm -rf coverage && rcov -o coverage -x rcov.rb test/*_test.rb"
-  system("open coverage/index.html") if PLATFORM['darwin']
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.options = ['--no-private', '-m', 'markdown', '-o', './doc']
+  end
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
 end
+
+desc 'Generate documentation'
+task :doc => :yard
+task :default => :test

data/VERSION

@@ -0,0 +1 @@
+0.8.1

data/lib/vertica.rb

@@ -1,19 +1,67 @@
 module Vertica
-  
   class Error < StandardError
-    
     class ConnectionError < Error; end
-    
     class MessageError < Error; end
-    
   end
-  
+
   PROTOCOL_VERSION = 3 << 16
-  
-  VERSION = "0.7.3"
-  
+  VERSION = File.read(File.join(File.dirname(__FILE__), *%w[.. VERSION])).strip
+
+  def self.connect(*args)
+    Connection.new(*args)
+  end
 end
 
-require 'vertica/column'
-require 'vertica/result'
-require 'vertica/connection'
+%w[
+  socket
+  uri
+  openssl/ssl
+  bigdecimal
+  bigdecimal/util
+  date
+
+  vertica/core_ext/numeric
+  vertica/core_ext/string
+
+  vertica/bit_helper
+  vertica/vertica_socket
+
+  vertica/column
+  vertica/result
+  vertica/connection
+
+  vertica/messages/message
+
+  vertica/messages/backend_messages/authentication
+  vertica/messages/backend_messages/backend_key_data
+  vertica/messages/backend_messages/bind_complete
+  vertica/messages/backend_messages/close_complete
+  vertica/messages/backend_messages/command_complete
+  vertica/messages/backend_messages/data_row
+  vertica/messages/backend_messages/empty_query_response
+  vertica/messages/backend_messages/error_response
+  vertica/messages/backend_messages/no_data
+  vertica/messages/backend_messages/notice_response
+  vertica/messages/backend_messages/notification_response
+  vertica/messages/backend_messages/parameter_description
+  vertica/messages/backend_messages/parameter_status
+  vertica/messages/backend_messages/parse_complete
+  vertica/messages/backend_messages/portal_suspended
+  vertica/messages/backend_messages/ready_for_query
+  vertica/messages/backend_messages/row_description
+  vertica/messages/backend_messages/unknown
+
+  vertica/messages/frontend_messages/bind
+  vertica/messages/frontend_messages/cancel_request
+  vertica/messages/frontend_messages/close
+  vertica/messages/frontend_messages/describe
+  vertica/messages/frontend_messages/execute
+  vertica/messages/frontend_messages/flush
+  vertica/messages/frontend_messages/parse
+  vertica/messages/frontend_messages/password
+  vertica/messages/frontend_messages/query
+  vertica/messages/frontend_messages/ssl_request
+  vertica/messages/frontend_messages/startup
+  vertica/messages/frontend_messages/sync
+  vertica/messages/frontend_messages/terminate
+].each { |r| require r }

data/lib/vertica/bit_helper.rb

@@ -6,44 +6,27 @@ module Vertica
       raise "couldn't read #{n} characters" if s.nil? or s.size != n # TODO make into a Vertica Exception
       s
     end
-    
-    def write_byte(value)
-      write [value].pack('C')
-    end
-    
+
     def read_byte
-      readn(1).unpack('C').first
+      readn(1).to_byte
     end
 
-    def write_network_int16(value)
-      write [value].pack('n')
-    end
-    
     def read_network_int16
-      readn(2).unpack('n').first
-    end
-    
-    def write_network_int32(value)
-      write [value].pack('N')
-    end
-    
-    def read_network_int32
-      handle_endian_flavor(readn(4)).unpack('l').first
+      readn(2).to_network_int16
     end
 
-    def write_cstring(value)
-      raise ArgumentError, "Invalid cstring" if value.include?("\000")
-      write "#{value}\000"
+    def read_network_int32
+      handle_endian_flavor(readn(4)).to_network_int32
     end
 
     def read_cstring
-      readline("\000")[0..-2]
+      readline("\000").from_cstring
     end
 
     def handle_endian_flavor(s)
       little_endian? ? s.reverse : s
     end
-    
+
     def little_endian?
       @little_endian ||= ([0x12345678].pack("L") == "\x12\x34\x56\x78" ? false : true)
     end

data/lib/vertica/column.rb

@@ -6,63 +6,44 @@ module Vertica
     attr_reader :size
     attr_reader :data_type
 
-    DATA_TYPES = [
-      :unspecified,
-      :tuple,
-      :pos,
-      :record,
-      :unknown,
-      :bool,
-      :in,
-      :float,
-      :char,
-      :varchar,
-      :date,
-      :time,
-      :timestamp,
-      :timestamp_tz,
-      :interval,
-      :time_tz,
-      :numberic,
-      :bytea,
-      :rle_tuple
+    DATA_TYPE_CONVERSIONS = [
+      [:unspecified,  nil],
+      [:tuple,        nil],
+      [:pos,          nil],
+      [:record,       nil],
+      [:unknown,      nil],
+      [:bool,         lambda { |s| s == 't' }],
+      [:in,           lambda { |s| s.to_i }],
+      [:float,        lambda { |s| s.to_f }],
+      [:char,         nil],
+      [:varchar,      nil],
+      [:date,         lambda { |s| Date.new(*s.split("-").map{|x| x.to_i}) }],
+      [:time,         lambda { |s| Time.parse(s) }],
+      [:timestamp,    lambda { |s| DateTime.parse(s, true) }],
+      [:timestamp_tz, lambda { |s| DateTime.parse(s, true) }],
+      [:interval,     nil],
+      [:time_tz,      lambda { |s| Time.parse(s) }],
+      [:numeric,      lambda { |s| s.to_d }],
+      [:bytea,        nil],
+      [:rle_tuple,    nil]
     ]
-    
-    DATA_TYPE_CONVERSIONS = {
-      :unspecified    => nil,
-      :tuple          => nil,
-      :pos            => nil,
-      :record         => nil,
-      :unknown        => nil,
-      :bool           => lambda { |s| s == 't' },
-      :in             => lambda { |s| s.to_i },
-      :float          => lambda { |s| s.to_f },
-      :char           => nil,
-      :varchar        => nil,
-      :date           => lambda { |s| Date.new(*s.split("-").map{|x| x.to_i}) },
-      :time           => lambda { |s| Time.parse(s) },
-      :timestamp      => lambda { |s| DateTime.parse(s, true) },
-      :timestamp_tz   => lambda { |s| DateTime.parse(s, true) },
-      :interval       => nil,
-      :time_tz        => lambda { |s| Time.parse(s) },
-      :numberic       => lambda { |s| s.to_d },
-      :bytea          => nil,
-      :rle_tuple      => nil
-    }
 
-    def initialize(type_modifier, format_code, table_oid, name, attribute_number, data_type_oid, size)
-      @type_modifier = type_modifier
-      @format = (format_code == 0 ? :text : :binary)
-      @table_oid = table_oid
-      @name = name
-      @attribute_number = attribute_number
-      @data_type = DATA_TYPES[data_type_oid]
-      @size = size
+    DATA_TYPES = DATA_TYPE_CONVERSIONS.map { |t| t[0] }
+
+    def initialize(col)
+      @type_modifier    = col[:type_modifier]
+      @format           = col[:format_code] == 0 ? :text : :binary
+      @table_oid        = col[:table_oid]
+      @name             = col[:name].to_sym
+      @attribute_number = col[:attribute_number]
+      @data_type        = DATA_TYPE_CONVERSIONS[col[:data_type_oid]][0]
+      @converter        = DATA_TYPE_CONVERSIONS[col[:data_type_oid]][1]
+      @size             = col[:data_type_size]
     end
-    
+
     def convert(s)
-      l = DATA_TYPE_CONVERSIONS[@data_type]
-      l ? l.call(s) : s
+      return unless s
+      @converter ? @converter.call(s) : s
     end
   end
 end

data/lib/vertica/connection.rb

@@ -1,45 +1,78 @@
-require 'uri'
-require 'stringio'
-require 'vertica/vertica_socket'
-require 'vertica/messages/message'
-require 'openssl/ssl'
-
 module Vertica
-  
+
   class Connection
-    
+
+    STATUSES = {
+      ?I => :no_transaction,
+      ?T => :in_transaction,
+      ?E => :failed_transaction
+    }
+
+    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.connection.close
+    end
+
     def initialize(options = {})
       reset_values
 
       @options = options
-      establish_connection
-      
+
       unless options[:skip_startup]
-        Messages::Startup.new(@options[:user], @options[:database]).to_bytes(@conn)
+        connection.write Messages::Startup.new(@options[:user], @options[:database]).to_bytes
         process
       end
     end
-    
+
+    def connection
+      @connection ||= begin
+        conn = VerticaSocket.new(@options[:host], @options[:port].to_s)
+        if @options[:ssl]
+          conn.write Messages::SslRequest.new.to_bytes
+          if conn.read_byte == ?S
+            conn = OpenSSL::SSL::SSLSocket.new(conn, OpenSSL::SSL::SSLContext.new)
+            conn.sync = true
+            conn.connect
+          else
+            raise Error::ConnectionError.new("SSL requested but server doesn't support it.")
+          end
+        end
+        conn
+      end
+    end
+
+    def opened?
+      @connection && @backend_pid && @transaction_status
+    end
+
+    def closed?
+      !opened?
+    end
+
+    def write(message)
+      connection.write_message message
+    end
+
     def close
-      raise_if_not_open
-      Messages::Terminate.new.to_bytes(@conn)
-      @conn.shutdown
-    rescue Errno::ENOTCONN
-      # the backend closed the connection already
+      write Messages::Terminate.new
+      connection.shutdown
+      @connection = nil
+    rescue Errno::ENOTCONN # the backend closed the connection already
     ensure
       reset_values
     end
-    
+
     def reset
       close if opened?
       reset_values
-      establish_connection
     end
 
     def options
       @options.dup
     end
-    
+
     def transaction_status
       @transaction_status
     end
@@ -47,7 +80,7 @@ module Vertica
     def backend_pid
       @backend_pid
     end
-    
+
     def backend_key
       @backend_key
     end
@@ -55,7 +88,7 @@ module Vertica
     def notifications
       @notifications
     end
-    
+
     def parameters
       @parameters.dup
     end
@@ -63,150 +96,117 @@ module Vertica
     def put_copy_data; raise NotImplementedError.new; end
     def put_copy_end;  raise NotImplementedError.new; end
     def get_copy_data; raise NotImplementedError.new; end
-    
-    def opened?
-      @conn && @backend_pid && @transaction_status
-    end
-    
-    def closed?
-      !opened?
-    end
-    
-    def query(query_string)
+
+    def query(query_string, &block)
       raise ArgumentError.new("Query string cannot be blank or empty.") if query_string.nil? || query_string.empty?
-      raise_if_not_open
       reset_result
-
-      Messages::Query.new(query_string).to_bytes(@conn)
-      process(true)
+      write Messages::Query.new(query_string)
+      @process_row = block
+      result = process(true)
+      result unless @process_row
     end
-    
+
     def prepare(name, query, params_count = 0)
-      raise_if_not_open
-      
       param_types = Array.new(params_count).fill(0)
-      
-      Messages::Parse.new(name, query, param_types).to_bytes(@conn)
-      Messages::Describe.new(:prepared_statement, name).to_bytes(@conn)
-      Messages::Sync.new.to_bytes(@conn)
-      Messages::Flush.new.to_bytes(@conn)
-      
+
+      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)
-      raise_if_not_open
-      
       portal_name = "" # use the unnamed portal
       max_rows    = 0  # return all rows
-            
+
       reset_result
-      
-      Messages::Bind.new(portal_name, name, param_values).to_bytes(@conn)
-      Messages::Execute.new(portal_name, max_rows).to_bytes(@conn)
-      Messages::Sync.new.to_bytes(@conn)
-            
+
+      write Messages::Bind.new(portal_name, name, param_values)
+      write Messages::Execute.new(portal_name, max_rows)
+      write Messages::Sync.new
+
       result = process(true)
 
       # Close the portal
-      Messages::Close.new(:portal, portal_name).to_bytes(@conn)
-      Messages::Flush.new.to_bytes(@conn)
-      
+      write Messages::Close.new(:portal, portal_name)
+      write Messages::Flush.new
+
       process
-      
+
       # Return the result from the prepared statement
       result
     end
 
-    def self.cancel(existing_conn)
-      conn = new(existing_conn.options.merge(:skip_startup => true))
-      Messages::CancelRequest.new(existing_conn.backend_pid, existing_conn.backend_key).to_bytes(conn.send(:conn))
-      Messages::Flush.new.to_bytes(conn.send(:conn))
-      conn.close
-    end
-
     protected
-    
-    def establish_connection
-      @conn = VerticaSocket.new(@options[:host], @options[:port].to_s)
-      
-      if @options[:ssl]
-        Messages::SslRequest.new.to_bytes(@conn)
-        if @conn.read_byte == ?S
-          @conn = OpenSSL::SSL::SSLSocket.new(@conn, OpenSSL::SSL::SSLContext.new)
-          @conn.sync = true
-          @conn.connect
-        else
-          raise Error::ConnectionError.new("SSL requested but server doesn't support it.")
-        end
-      end      
-    end
-    
+
     def process(return_result = false)
+      result = return_result ? Result.new : nil
       loop do
-        message = Messages::BackendMessage.read(@conn)
-
-        case message
+        case message = connection.read_message
         when Messages::Authentication
           if message.code != Messages::Authentication::OK
-            Messages::Password.new(@options[:password], message.code, {:user => @options[:user], :salt => message.salt}).to_bytes(@conn)
+            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::BindComplete
-          :nothing
-        when Messages::CloseComplete
-          break
-        when Messages::CommandComplete
-          break
-        # when Messages::CopyData
-        #   # nothing
-        # when Messages::CopyDone
-        #   # nothing        
-        # when Messages::CopyInResponse
-        #   raise 'not done'
-        # when Messages::CopyOutResponse
-        #   raise 'not done'
+
         when Messages::DataRow
-          @field_values << message.fields
-        when Messages::EmptyQueryResponse
-          break
+          @process_row.call(result.format_row(message)) if @process_row && result
+          result.add_row(message) if result && !@process_row
+
         when Messages::ErrorResponse
           raise Error::MessageError.new(message.error)
-        when Messages::NoData
-          :nothing
+
         when Messages::NoticeResponse
           message.notices.each do |notice|
             @notices << Notice.new(notice[0], notice[1])
           end
+
         when Messages::NotificationResponse
-          @notifications << Notification.new(message.pid, message.condition, message.additional_info)        
-        when Messages::ParameterDescription
-          :nothing
+          @notifications << Notification.new(message.pid, message.condition, message.additional_info)
+
         when Messages::ParameterStatus
           @parameters[message.name] = message.value
-        when Messages::ParseComplete
-          break
-        when Messages::PortalSuspended
-          break
+
         when Messages::ReadyForQuery
-          @transaction_status = convert_transaction_status_to_sym(message.transaction_status)
+          @transaction_status = STATUSES[message.transaction_status]
           break unless return_result
+
         when Messages::RowDescription
-          @field_descriptions = message.fields
+          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
+        # when Messages::CopyData
+        #   # nothing
+        # when Messages::CopyDone
+        #   # nothing
+        # when Messages::CopyInResponse
+        #   raise 'not done'
+        # when Messages::CopyOutResponse
+        #   raise 'not done'
         end
       end
-      
-      return_result ? Result.new(@field_descriptions, @field_values) : nil
-    end
-    
-    def raise_if_not_open
-      raise ConnectionError.new("connection doesn't exist or is already closed") if @conn.nil?
+
+      result
     end
-    
+
     def reset_values
       reset_notifications
       reset_result
@@ -214,9 +214,10 @@ module Vertica
       @backend_pid        = nil
       @backend_key        = nil
       @transaction_status = nil
-      @conn               = nil
+      @connection         = nil
+      @process_row        = nil
     end
-    
+
     def reset_notifications
       @notifications      = []
     end
@@ -224,23 +225,6 @@ module Vertica
     def reset_result
       @field_descriptions = []
       @field_values       = []
-    end    
-    
-    def convert_transaction_status_to_sym(status)
-      case status
-      when ?I
-        :no_transaction
-      when ?T
-        :in_transaction
-      when ?E
-        :failed_transaction
-      else
-        nil
-      end
-    end
-
-    def conn
-      @conn
     end
 
   end