vertica 0.12.0 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8a40a34bb03e1ca8ad79adeb83e8573146675288
-  data.tar.gz: e80aa43026917a4e59da7f794c4d45d23153c297
+  metadata.gz: d40466055bc43ffb3c72810432f2cf6738295399
+  data.tar.gz: c4c4c43a8cf12c22ce7cc3b46eadc68d90931453
 SHA512:
-  metadata.gz: e1430c2ed8107e26c1a0724d2f0c0ea9e3d21122958e2b9d2b5550a478e83f3a207dc6620a8aa05eb3e76793651237e683769b8ec2c3c4896a8460762b6508be
-  data.tar.gz: fe886807f5aa39f036dd7d975889fd989283f92068b7a357fa0e479c8af12c016b13a05f6eaa76f104087261ec88b88b2b1e1fa805710aeecf18dbb03f136e39
+  metadata.gz: 5d9941765704d6e4c29efa04d1f7dbdf7f79ca787a6c8786019f8659c47f024f7245673cb7185cadce1ea6035bd8bbd2dfa4f526404ab0c922824309ce427c6b
+  data.tar.gz: aee68c7643bbafd0399cc3c8ff44b0ea13d9490a1ce553f426579ad87a0e28bf4fb0bc21f73f19bc9ebca85755195a4be485099775336b38a49e69127e4dd3a6

data/README.md

@@ -36,31 +36,32 @@ Or add it to your Gemfile:
 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.
 
-    connection = Vertica.connect({
+    connection = Vertica.connect(
       :host     => 'db_server',
-      :user     => 'user',
+      :username => 'user',
       :password => 'password',
       # :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>.
 
 You can pass `OpenSSL::SSL::SSLContext` in `:ssl` to customize SSL connection options.
 
-### Querying with unbuffered result as streaming rows
+### Running queries
 
-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.
+You can run 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,
+because buffering the entire result may require a lot of memory.
 
 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"}
+      puts row['id']   # => 123
+      puts row['name'] # => 'Jim Bob'
     end
 
 Note: you can only use the connection for one query at the time. If you try to run another
@@ -73,26 +74,23 @@ 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.size # => 2
 
     result.each do |row|
-      puts row # => {:id => 123, :name => "Jim Bob"}
+      puts row # => Vertica::Row[123, "Jim Bob"]>
     end
 
-### Row format
+Rows are provided as `Vertica::Row` instances. You can access the individial fields by
+referring to their name as String or Symbol,  or the index of the field in the result.
 
-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:
+    result.each do |row|
+      puts row # => Vertica::Row[123, "Jim Bob"]>
 
-    connection.query("SELECT id, name FROM my_table", :row_style => :array) do |row|
-      puts row # => [123, "Jim Bob"]
+      puts row['id'], row[:id], row[]      # Three times '123'
+      puts row['name'], row[:name], row[1] # Three times 'Jim Bob'
     end
 
-By adding <code>:row_style => :array</code> to the connection hash, all results will be
-returned as array.
-
-### Loading data into Vertica using COPY
+### Loading data into Vertica using COPY statements
 
 Using the COPY statement, you can load arbitrary data from your ruby script to the database.
 

data/lib/vertica.rb

@@ -1,22 +1,23 @@
 require 'date'
+require 'time'
 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 
+# {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
-  
+
   # 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)
+  def self.connect(**kwargs)
+    Vertica::Connection.new(**kwargs)
   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
@@ -29,8 +30,8 @@ module Vertica
       when nil        then 'NULL'
       when false      then 'FALSE'
       when true       then 'TRUE'
-      when DateTime   then value.strftime("'%Y-%m-%d %H:%M:%S'::timestamp")
-      when Time       then value.strftime("'%Y-%m-%d %H:%M:%S'::timestamp")
+      when DateTime   then value.strftime("'%Y-%m-%dT%H:%M:%S.%6N%z'::timestamptz")
+      when Time       then value.strftime("'%Y-%m-%dT%H:%M:%S.%6N%z'::timestamptz")
       when Date       then value.strftime("'%Y-%m-%d'::date")
       when String     then "'#{value.gsub(/'/, "''")}'"
       when BigDecimal then value.to_s('F')
@@ -39,7 +40,7 @@ module Vertica
       else self.quote(value.to_s)
     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.
@@ -51,3 +52,9 @@ end
 require 'vertica/version'
 require 'vertica/error'
 require 'vertica/connection'
+require 'vertica/query'
+require 'vertica/column'
+require 'vertica/row_description'
+require 'vertica/row'
+require 'vertica/result'
+require 'vertica/protocol/message'

data/lib/vertica/column.rb

@@ -2,9 +2,11 @@ module Vertica
   class Column
     attr_reader :name
     attr_reader :table_oid
-    attr_reader :type_modifier
-    attr_reader :size
+    attr_reader :attribute_number
+    attr_reader :format
     attr_reader :data_type
+    attr_reader :data_type_size
+    attr_reader :data_type_modifier
 
     STRING_CONVERTER = lambda { |s| s.force_encoding('utf-8') }
 
@@ -32,10 +34,10 @@ module Vertica
       7   => [:float,        FLOAT_CONVERTER],
       8   => [:char,         STRING_CONVERTER],
       9   => [:varchar,      STRING_CONVERTER],
-      10  => [:date,         lambda { |s| Date.new(*s.split("-").map{|x| x.to_i}) }],
+      10  => [:date,         lambda { |s| Date.parse(s) }],
       11  => [:time,         nil],
-      12  => [:timestamp,    lambda { |s| DateTime.parse(s, true) }],
-      13  => [:timestamp_tz, lambda { |s| DateTime.parse(s, true) }],
+      12  => [:timestamp,    lambda { |s| Time.parse(s) }],
+      13  => [:timestamp_tz, lambda { |s| Time.parse(s) }],
       14  => [:interval,     nil],
       15  => [:time_tz,      nil],
       16  => [:numeric,      lambda { |s| BigDecimal.new(s) }],
@@ -46,15 +48,32 @@ module Vertica
 
     DATA_TYPES = DATA_TYPE_CONVERSIONS.values.map { |t| t[0] }
 
-    def initialize(col)
-      @type_modifier    = col.fetch(:type_modifier)
-      @format           = col.fetch(:format_code) == 0 ? :text : :binary
-      @table_oid        = col.fetch(:table_oid)
-      @name             = col.fetch(:name).to_sym
-      @attribute_number = col.fetch(:attribute_number)
-      @size             = col.fetch(:data_type_size)
+    def initialize(name: nil, table_oid: nil, attribute_number: nil, format_code: 0, data_type_oid: nil, data_type_size: nil, data_type_modifier: nil)
+      @name             = name
+      @table_oid        = table_oid
+      @attribute_number = attribute_number
 
-      @data_type, @converter = column_type_from_oid(col.fetch(:data_type_oid))
+      @format                = format_code == 0 ? :text : :binary
+      @data_type_size        = data_type_size
+      @data_type_modifier    = data_type_modifier
+      @data_type, @converter = column_type_from_oid(data_type_oid)
+    end
+
+    def eql?(other)
+      self.class === other &&
+        other.name == name &&
+        other.format == format &&
+        other.data_type == data_type &&
+        other.data_type_size == data_type_size &&
+        other.data_type_modifier == data_type_modifier &&
+        other.table_oid == table_oid &&
+        other.attribute_number == attribute_number
+    end
+
+    alias_method :==, :eql?
+
+    def hash
+      [name, format, data_type, data_type_size, data_type_modifier, table_oid, attribute_number].hash
     end
 
     def convert(s)

data/lib/vertica/connection.rb

@@ -2,56 +2,37 @@ require 'socket'
 
 class Vertica::Connection
 
-  attr_reader :notices, :transaction_status, :backend_pid, :backend_key, :parameters, :notice_handler, :session_id
-
-  attr_accessor :row_style, :debug, :options
-
-  def self.cancel(existing_conn)
-    existing_conn.cancel
-  end
+  attr_reader :transaction_status, :parameters, :options
 
   # Opens a connectio the a Vertica server
   # @param [Hash] options The connection options to use.
-  def initialize(options = {})
-    reset_values
+  def initialize(host: nil, port: 5433, username: nil, password: nil, database: nil, interruptable: false, ssl: nil, read_timeout: 600, debug: false, role: nil, search_path: nil, timezone: nil, autocommit: false, skip_startup: false, skip_initialize: false, user: nil)
+    reset_state
     @notice_handler = nil
 
-    @options = {}
-    @debug = false
-
-    options.each { |key, value| @options[key.to_s.to_sym] = value if value}
-
-    @options[:port] ||= 5433
-    @options[:read_timeout] ||= 600
-
-    @row_style = @options[:row_style] ? @options[:row_style] : :hash
-    boot_connection unless options[:skip_startup]
+    @options = {
+      host: host,
+      port: port.to_i,
+      username: username || user,
+      password: password,
+      database: database,
+      debug: debug,
+      ssl: ssl,
+      interruptable: interruptable,
+      read_timeout: read_timeout,
+      role: role,
+      search_path: search_path,
+      timezone: timezone,
+      autocommit: autocommit,
+    }
+
+    boot_connection(skip_initialize: skip_initialize) unless skip_startup
   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'
-        raw_socket.write Vertica::Messages::SslRequest.new.to_bytes
-        if raw_socket.read(1) == 'S'
-          ssl_context = @options[:ssl].is_a?(OpenSSL::SSL::SSLContext) ? @options[:ssl] : OpenSSL::SSL::SSLContext.new
-          raw_socket = OpenSSL::SSL::SSLSocket.new(raw_socket, ssl_context)
-          raw_socket.sync = true
-          raw_socket.connect
-        else
-          raise Vertica::Error::SSLNotSupported.new("SSL requested but server doesn't support it.")
-        end
-      end
-
-      raw_socket
-    end
-  end
-
   def ssl?
     Object.const_defined?('OpenSSL') && @socket.kind_of?(OpenSSL::SSL::SSLSocket)
   end
@@ -72,81 +53,90 @@ class Vertica::Connection
     !busy?
   end
 
-  def write_message(message)
-    puts "=> #{message.inspect}" if @debug
-    write_bytes message.to_bytes
-  rescue SystemCallError, IOError => e
-    close_socket
-    raise Vertica::Error::ConnectionError.new(e.message)
+  def interruptable?
+    !session_id.nil?
   end
 
-  def close
-    write_message Vertica::Messages::Terminate.new
-  ensure
-    close_socket
+  def query(sql, **kwargs, &block)
+    row_handler = block_given? ? block : nil
+    job = Vertica::Query.new(self, sql, row_handler: row_handler, **kwargs)
+    run_with_mutex(job)
   end
 
-  def close_socket
-    socket.close
-    @socket = nil
-  rescue SystemCallError, IOError
-  ensure
-    reset_values
+  def copy(sql, source: nil, **kwargs, &block)
+    copy_handler = if block_given?
+      block
+    elsif source && File.exist?(source.to_s)
+      lambda { |data| file_copy_handler(source, data) }
+    elsif source.respond_to?(:read) && source.respond_to?(:eof?)
+      lambda { |data| io_copy_handler(source, data) }
+    end
+
+    job = Vertica::Query.new(self, sql, copy_handler: copy_handler, **kwargs)
+
+    run_with_mutex(job)
   end
 
-  def reset_connection
-    close
-    boot_connection
+  def inspect
+    safe_options = @options.reject { |name, _| name == :password }
+    "#<Vertica::Connection:#{object_id} @parameters=#{@parameters.inspect} @backend_pid=#{@backend_pid}, @backend_key=#{@backend_key}, @transaction_status=#{@transaction_status}, @socket=#{@socket}, @options=#{safe_options.inspect}>"
   end
 
-  def boot_connection
-    startup_connection
-    initialize_connection
+  def close
+    write_message(Vertica::Protocol::Terminate.new)
+  ensure
+    close_socket
   end
 
   def cancel
-    conn = self.class.new(options.merge(:skip_startup => true))
-    conn.write_message Vertica::Messages::CancelRequest.new(backend_pid, backend_key)
-    conn.write_message Vertica::Messages::Flush.new
-    conn.socket.close
+    conn = self.class.new(skip_startup: true, **options)
+    conn.write_message(Vertica::Protocol::CancelRequest.new(backend_pid, backend_key))
+    conn.write_message(Vertica::Protocol::Flush.new)
+    conn.close_socket
   end
 
   def interrupt
     raise Vertica::Error::InterruptImpossible, "Session cannopt be interrupted because the session ID is not known!" if session_id.nil?
-    conn = self.class.new(options.merge(:interruptable => false, :role => nil, :search_path => nil))
-    response = conn.query("SELECT CLOSE_SESSION(#{Vertica.quote(session_id)})").the_value
-    conn.close
-    return response
+    conn = self.class.new(skip_initialize: true, **options)
+    conn.query("SELECT CLOSE_SESSION(#{Vertica.quote(session_id)})").the_value
+  ensure
+    conn.close if conn
   end
 
-  def interruptable?
-    !session_id.nil?
+  # @private
+  def write_message(message)
+    puts "=> #{message.inspect}" if options.fetch(:debug)
+    write_bytes(message.to_bytes)
+  rescue SystemCallError, IOError => e
+    close_socket
+    raise Vertica::Error::ConnectionError.new(e.message)
   end
 
+  # @private
   def read_message
-    type = read_bytes(1)
-    size = read_bytes(4).unpack('N').first
+    type, size = read_bytes(5).unpack('aN')
     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
+    message = Vertica::Protocol::BackendMessage.factory(type, read_bytes(size - 4))
+    puts "<= #{message.inspect}" if options.fetch(:debug)
     return message
   rescue SystemCallError, IOError => e
     close_socket
     raise Vertica::Error::ConnectionError.new(e.message)
   end
 
+  # @private
   def process_message(message)
     case message
-    when Vertica::Messages::ErrorResponse
+    when Vertica::Protocol::ErrorResponse
       raise Vertica::Error::ConnectionError.new(message.error_message)
-    when Vertica::Messages::NoticeResponse
+    when Vertica::Protocol::NoticeResponse
       @notice_handler.call(message) if @notice_handler
-    when Vertica::Messages::BackendKeyData
+    when Vertica::Protocol::BackendKeyData
       @backend_pid = message.pid
       @backend_key = message.key
-    when Vertica::Messages::ParameterStatus
+    when Vertica::Protocol::ParameterStatus
       @parameters[message.name] = message.value
-    when Vertica::Messages::ReadyForQuery
+    when Vertica::Protocol::ReadyForQuery
       @transaction_status = message.transaction_status
       @mutex.unlock
     else
@@ -154,30 +144,29 @@ class Vertica::Connection
     end
   end
 
-  def query(sql, options = {}, &block)
-    job = Vertica::Query.new(self, sql, { :row_style => @row_style }.merge(options))
-    job.row_handler = block if block_given?
-    run_with_mutex(job)
-  end
+  protected
 
-  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.exist?(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
-    run_with_mutex(job)
-  end
+  attr_reader :backend_pid, :backend_key,  :session_id
 
-  def inspect
-    safe_options = @options.reject{ |name, _| name == :password }
-    "#<Vertica::Connection:#{object_id} @parameters=#{@parameters.inspect} @backend_pid=#{@backend_pid}, @backend_key=#{@backend_key}, @transaction_status=#{@transaction_status}, @socket=#{@socket}, @options=#{safe_options.inspect}, @row_style=#{@row_style}>"
-  end
+  def socket
+    @socket ||= begin
+      raw_socket = TCPSocket.new(@options[:host], @options[:port].to_i)
+      if @options[:ssl]
+        require 'openssl'
+        raw_socket.write(Vertica::Protocol::SslRequest.new.to_bytes)
+        if raw_socket.read(1) == 'S'
+          ssl_context = @options[:ssl].is_a?(OpenSSL::SSL::SSLContext) ? @options[:ssl] : OpenSSL::SSL::SSLContext.new
+          raw_socket = OpenSSL::SSL::SSLSocket.new(raw_socket, ssl_context)
+          raw_socket.sync = true
+          raw_socket.connect
+        else
+          raise Vertica::Error::SSLNotSupported.new("SSL requested but server doesn't support it.")
+        end
+      end
 
-  protected
+      raw_socket
+    end
+  end
 
   def run_with_mutex(job)
     boot_connection if closed?
@@ -193,19 +182,18 @@ class Vertica::Connection
     end
   end
 
-  COPY_FROM_IO_BLOCK_SIZE = 1024 * 4096
+  DEFAULT_IO_COPY_HANDLER_BLOCK_SIZE = 1024 * 4096
+  private_constant :DEFAULT_IO_COPY_HANDLER_BLOCK_SIZE
 
   def file_copy_handler(input_file, output)
     File.open(input_file, 'r') do |input|
-      while data = input.read(COPY_FROM_IO_BLOCK_SIZE)
-        output << data
-      end
+      io_copy_handler(input, output)
     end
   end
 
   def io_copy_handler(input, output)
     until input.eof?
-      output << input.read(COPY_FROM_IO_BLOCK_SIZE)
+      output << input.read(DEFAULT_IO_COPY_HANDLER_BLOCK_SIZE)
     end
   end
 
@@ -241,27 +229,68 @@ class Vertica::Connection
   end
 
   def startup_connection
-    write_message Vertica::Messages::Startup.new(@options[:user] || @options[:username], @options[:database])
+    write_message(Vertica::Protocol::Startup.new(@options[:username], @options[:database]))
     message = nil
     begin
       case message = read_message
-      when Vertica::Messages::Authentication
-        if message.code != Vertica::Messages::Authentication::OK
-          write_message Vertica::Messages::Password.new(@options[:password], message.code, {:user => @options[:user], :salt => message.salt})
+      when Vertica::Protocol::Authentication
+        if message.code != Vertica::Protocol::Authentication::OK
+          write_message(Vertica::Protocol::Password.new(@options[:password], auth_method: message.code, user: @options[:username], salt: message.salt))
         end
       else
         process_message(message)
       end
-    end until message.kind_of?(Vertica::Messages::ReadyForQuery)
+    end until message.kind_of?(Vertica::Protocol::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]
     @session_id = query("SELECT session_id FROM v_monitor.current_session").the_value if options[:interruptable]
+    initialize_connection_with_role
+    initialize_connection_with_search_path
+    initialize_connection_with_timezone
+    initialize_connection_with_autocommit
+  end
+
+  def initialize_connection_with_role
+    case options[:role]
+    when :all, :none, :default
+      query("SET ROLE #{options[:role].to_s.upcase}")
+    when String, Array
+      query("SET ROLE #{Vertica.quote(options[:role])}")
+    end
   end
 
-  def reset_values
+  def initialize_connection_with_search_path
+    query("SET SEARCH_PATH TO #{Vertica.quote(options[:search_path])}") if options[:search_path]
+  end
+
+  def initialize_connection_with_timezone
+    query("SET TIME ZONE TO #{Vertica.quote(options[:timezone])}") if options[:timezone]
+  end
+
+  def initialize_connection_with_autocommit
+    query("SET AUTOCOMMIT TO ON") if options[:autocommit]
+  end
+
+  def close_socket
+    @socket.close if @socket
+  rescue SystemCallError, IOError
+    # ignore
+  ensure
+    reset_state
+  end
+
+  def reset_connection
+    close
+    boot_connection
+  end
+
+  def boot_connection(skip_initialize: false)
+    startup_connection
+    initialize_connection unless skip_initialize
+  end
+
+  def reset_state
     @parameters         = {}
     @session_id         = nil
     @backend_pid        = nil
@@ -271,8 +300,3 @@ class Vertica::Connection
     @mutex              = Mutex.new.lock
   end
 end
-
-require 'vertica/query'
-require 'vertica/column'
-require 'vertica/result'
-require 'vertica/messages/message'