vertica 1.0.0.rc1 → 1.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d40466055bc43ffb3c72810432f2cf6738295399
-  data.tar.gz: c4c4c43a8cf12c22ce7cc3b46eadc68d90931453
+  metadata.gz: fd8271cb188eef45ec983912494a8ebb72209567
+  data.tar.gz: 730d859a30f294766df5e0a789ecb79de550771c
 SHA512:
-  metadata.gz: 5d9941765704d6e4c29efa04d1f7dbdf7f79ca787a6c8786019f8659c47f024f7245673cb7185cadce1ea6035bd8bbd2dfa4f526404ab0c922824309ce427c6b
-  data.tar.gz: aee68c7643bbafd0399cc3c8ff44b0ea13d9490a1ce553f426579ad87a0e28bf4fb0bc21f73f19bc9ebca85755195a4be485099775336b38a49e69127e4dd3a6
+  metadata.gz: 504edb900db1f059bb19cb9f619f8d5cf51586bbd8184fb0bfe1bad1f9b208cb49704c21f0e5b2c76de502103035e2f90d7d3086b7dcebc699f5e6b911c2172e
+  data.tar.gz: 4560a75f5a0f2926cf95f95ea3514b578c7779a082148e3af86b84e22091f392a788f084d46b0bcdda309c6a0040628db9e79e5ff44b28b162815312901b5325

data/.yardopts

@@ -0,0 +1,4 @@
+--hide-void-return
+--markup markdown
+--readme README.md
+--no-private

data/README.md

@@ -6,50 +6,56 @@ about Vertica at http://www.vertica.com.
 - Connecting, including over SSL.
 - Executing queries, with results as streaming rows or buffered resultsets.
 - `COPY table FROM STDIN` statement to load data from your application.
-- Confirmed to work with Ruby 1.9, 2.0, and 2.1; JRuby 1.7.23 and 9.0.4.0; and
-  with Vertica version 6.x, and 7.x.
 - The library is thread-safe as of version 0.11. However, you can only run one
-  statement at the time per connection, because the protocol is stateful.
+  statement at the time per connection, because the protocol is stateful. In a
+  multi-threaded environment, you may want to tthink about setting up a
+  connection pool.
 
 
 ## Installation
 
-    $ gem install vertica
+Add it to the Gemfile of your project:
 
-Or add it to your Gemfile:
-
-    gem 'vertica'
+    gem 'vertica', '~> 1.0'
     # gem 'vertica', git: 'git://github.com/wvanbergen/vertica.git' # HEAD version
 
-### Compatiblity
+Now, run `bundle install`.
 
-- Ruby 1.8 is no longer supported, but version 0.9.x should still support it.
-- Vertica versions 4.x, and 5.x worked with at some point with this gem, but
-  compatibility is no longer tested. It probably still works as the protocol hasn't
-  changed as far as I am aware.
+### Compatiblity
 
+- Ruby 2.0 or higher is required.
+- Compatibility is tested with Vertica 7.x community edition. Vertica versions 4.x, 5.x,
+  and 6.x worked with at some point with this gem, but compatibility is no longer tested.
 
 ## Usage
 
 ### 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.
-
-    connection = Vertica.connect(
-      :host     => 'db_server',
-      :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
-    )
-
-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.
+The `Vertica.connect` methods takes keyword arguments and returns a connection
+instance. For most options, the gem will use a default value if no value is provided.
+
+``` ruby
+connection = Vertica.connect(
+  host:     'db_server',
+  username: 'user',
+  password: 'password',
+
+  # ssl:           false, # use SSL for the connection
+  # port:          5433,  # default Vertica port: 5433
+  # database:      nil,   # there is only one database
+  # role:          nil,   # the (additional) role(s) to enable for the user.
+  # search_path:   nil,   # default: <user>,public,v_catalog
+  # timezone:      nil,   # the timezone for the connection to convert timestamps
+  # autocommit:    false, # automatically commit INSERT/UPDATE/DELETE queries
+  # interruptable: false, # set to true to allow sessions to be interrupted.
+  # read_timeout:  600,   # timeout in seconds when reading data
+  # debug:         false, # print all the messages back and forth to STDOUT.
+)
+```
+
+- To close the connection when you're done with it, run `connection.close`.
+- You can pass `OpenSSL::SSL::SSLContext` in `:ssl` to customize SSL connection options,
+  or `true` to use the default (`OpenSSL::SSL::SSLContext.new`).
 
 ### Running queries
 
@@ -59,10 +65,12 @@ 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
-      puts row['name'] # => 'Jim Bob'
-    end
+``` ruby
+connection.query("SELECT id, name FROM my_table") do |row|
+  puts row['id']   # => 123
+  puts row['name'] # => 'Unicorn'
+end
+```
 
 Note: you can only use the connection for one query at the time. If you try to run another
 query when the connection is still busy delivering the results of a previous query, a
@@ -71,42 +79,70 @@ problem.
 
 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
+``` ruby
+result = connection.query("SELECT id, name FROM my_table")
+connection.close # buffered result will be available even after closing the connection.
 
-    result.size # => 2
+result.size # => 2
 
-    result.each do |row|
-      puts row # => Vertica::Row[123, "Jim Bob"]>
-    end
+result.each do |row|
+  puts "Hello #{row['name']}, your ID is #{row['id']}."
+end
+```
 
 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.
 
-    result.each do |row|
-      puts row # => Vertica::Row[123, "Jim Bob"]>
+``` ruby
+result.each do |row|
+  p row # => Vertica::Row[123, "Unicorn"]>
 
-      puts row['id'], row[:id], row[]      # Three times '123'
-      puts row['name'], row[:name], row[1] # Three times 'Jim Bob'
-    end
+  puts row['id'], row[:id], row[0]     # Three times 123
+  puts row['name'], row[:name], row[1] # Three times 'Unicorn'
+end
+```
 
 ### Loading data into Vertica using COPY statements
 
-Using the COPY statement, you can load arbitrary data from your ruby script to the database.
+Using the `COPY FROM STDIN` statement, you can load arbitrary data from your ruby script to the database.
 
-    connection.copy("COPY table FROM STDIN ...") do |stdin|
-      File.open('data.tsv', 'r') do |f|
-        begin
-          stdin << f.gets
-        end until f.eof?
-      end
-    end
+``` ruby
+connection.copy("COPY table FROM STDIN ...") do |stdin|
+  File.open('data.tsv', 'r') do |f|
+    begin
+      stdin << f.gets
+    end until f.eof?
+  end
+end
+```
 
 You can also provide a filename or an IO object:
 
-    connection.copy("COPY table FROM STDIN ...", "data.csv")
-    connection.copy("COPY table FROM STDIN ...", io)
+``` ruby
+connection.copy("COPY table FROM STDIN ...", source: "data.csv")
+File.open('file.csv') do |io|
+  connection.copy("COPY table FROM STDIN ...", source: io)
+end
+```
 
+For more information, see [the Vertica documentation](https://my.vertica.com/docs/7.1.x/HTML/Content/Authoring/SQLReferenceManual/Statements/COPY/COPY.htm)
+
+### Interrupting sessions
+
+``` ruby
+connection = Vertica.connect(host: 'dbserver', ...)
+
+Thread.new do
+  sleep(60)
+  connection.interrupt
+end
+
+begin
+  result = connection.query('SELECT complicated_query FROM huge_table')
+rescue Vertica::Error::ConnectionError
+  # ...
+end
+```
 
 ## About
 
@@ -114,17 +150,15 @@ This package is MIT licensed. See the LICENSE file for more information.
 
 ### 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
+This project comes with a test suite. The unit tests in `/test/unit` do not need a database
+connection to run, the functional tests in `/test/functional` 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
+`/test/connection.yml.example` to `/test/connection.yml` 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>.
-
-The test suite is also run by Travis CI againast Vertica 7.0.1, and Ruby 1.9.3, 2.0.0, and 2.1.1.
+The `/vagrant` folder contains a Vagrantfile and a setup script to help you set up a development
+database that you can run the functional test suite against. The full test suite is also run by
+Travis CI against Vertica 7 CE, and against several Ruby versions.
 
 ### Authors
 
@@ -137,6 +171,7 @@ The test suite is also run by Travis CI againast Vertica 7.0.1, and Ruby 1.9.3,
 
 * [Website](http://vanbergen.org/vertica)
 * [API Documentation](http://www.rubydoc.info/gems/vertica/frames)
+* [Vertica documentation](https://my.vertica.com/docs/7.1.x/HTML/index.htm)
 * [sequel-vertica](https://github.com/camilo/sequel-vertica): Sequel integration
 * [newrelic-vertica](https://github.com/wvanbergen/newrelic-vertica): NewRelic monitoring of queries
 * [node-vertica](https://github.com/wvanbergen/node-vertica): node.js Vertica driver

data/lib/vertica.rb

@@ -23,7 +23,7 @@ module Vertica
   # 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.
+  # @param value [Object] The value to quote.
   # @return [String] The quoted value that can be safely included in SQL queries.
   def self.quote(value)
     case value
@@ -42,7 +42,7 @@ module Vertica
   end
 
   # Quotes an identifier for safe use within SQL queries, using double quotes.
-  # @param [:to_s] identifier The identifier to quote.
+  # @param identifier [:to_s] 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(/"/, '""')}\""
@@ -53,6 +53,7 @@ require 'vertica/version'
 require 'vertica/error'
 require 'vertica/connection'
 require 'vertica/query'
+require 'vertica/data_type'
 require 'vertica/column'
 require 'vertica/row_description'
 require 'vertica/row'

data/lib/vertica/column.rb

@@ -1,92 +1,58 @@
-module Vertica
-  class Column
-    attr_reader :name
-    attr_reader :table_oid
-    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') }
-
-    FLOAT_CONVERTER = lambda do |s|
-      case s
-      when 'Infinity'
-        Float::INFINITY
-      when '-Infinity'
-        -Float::INFINITY
-      when 'NaN'
-        Float::NAN
-      else
-        s.to_f
-      end
-    end
-
-    DATA_TYPE_CONVERSIONS = {
-      0   => [:unspecified,  nil],
-      1   => [:tuple,        nil],
-      2   => [:pos,          nil],
-      3   => [:record,       nil],
-      4   => [:unknown,      nil],
-      5   => [:bool,         lambda { |s| s == 't' }],
-      6   => [:integer,      lambda { |s| s.to_i }],
-      7   => [:float,        FLOAT_CONVERTER],
-      8   => [:char,         STRING_CONVERTER],
-      9   => [:varchar,      STRING_CONVERTER],
-      10  => [:date,         lambda { |s| Date.parse(s) }],
-      11  => [:time,         nil],
-      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) }],
-      17  => [:bytea,        lambda { |s| s.gsub(/\\([0-3][0-7][0-7])/) { $1.to_i(8).chr }} ],
-      18  => [:rle_tuple,    nil],
-      115 => [:long_varchar, STRING_CONVERTER],
-    }
-
-    DATA_TYPES = DATA_TYPE_CONVERSIONS.values.map { |t| t[0] }
-
-    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
-
-      @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
+# Class representing a column in a result.
+#
+# @attr_reader name [String] The name of the column
+# @attr_reader table_oid [Integer, nil] The OID of the table this column originates from. This can
+#   be nil if the volumn was computed, and was not soruced from a table
+# @attr_reader attribute_number [Integer, nil] The attribute index in the table this column originates from.
+#   This can be nil if the volumn was computed, and was not soruced from a table
+# @attr_reader data_type [Vertica::DataType] The type of the values in this column.
+#
+# @see Vertica::RowDescription
+# @see Vertica::DataType
+class Vertica::Column
+
+  # Builds a new column instance based on the values provided by a {Vertica::Protocol::RowDescription} message.
+  # @param name [String] The name of the column
+  # @param table_oid [Integer, nil] The OID of the table this column originates from. This can
+  #   be nil if the volumn was computed, and was not soruced from a table
+  # @param attribute_number [Integer, nil] The attribute index in the table this column originates from.
+  #   This can be nil if the volumn was computed, and was not soruced from a table
+  # @param data_type_oid [Integer] The object ID of the type.
+  # @param data_type_size [Integer] The size of the type.
+  # @param data_type_modifier [Integer] A modifier of the type.
+  # @param data_format [Integer] The serialization format of this type.
+  # @return [Vertica::Column]
+  def self.build(name: nil, table_oid: nil, attribute_number: nil, data_format: 0, data_type_oid: nil, data_type_size: nil, data_type_modifier: nil)
+    data_type = Vertica::DataType.build(oid: data_type_oid, size: data_type_size, modifier: data_type_modifier, format: data_format)
+    new(name: name, data_type: data_type, table_oid: table_oid, attribute_number: attribute_number)
+  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
+  attr_reader :name, :data_type, :table_oid, :attribute_number
 
-    alias_method :==, :eql?
+  # Initializes a new Vertica::Column.
+  # @see .build
+  def initialize(name: nil, data_type: nil, table_oid: nil, attribute_number: nil)
+    @name             = name
+    @table_oid        = table_oid
+    @attribute_number = attribute_number
+    @data_type        = data_type
+  end
 
-    def hash
-      [name, format, data_type, data_type_size, data_type_modifier, table_oid, attribute_number].hash
-    end
+  # @return [Boolean] Returns true iff this record is equal to the other provided object
+  def eql?(other)
+    self.class === other && other.name == name && other.data_type == data_type &&
+      other.table_oid == table_oid && other.attribute_number == attribute_number
+  end
 
-    def convert(s)
-      return unless s
-      @converter ? @converter.call(s) : s
-    end
+  alias_method :==, :eql?
 
-    private
+  # @return [Integer] Returns a hash digtest of this object.
+  def hash
+    [name, data_type, table_oid, attribute_number].hash
+  end
 
-    def column_type_from_oid(oid)
-      DATA_TYPE_CONVERSIONS.fetch(oid) do |unknown_oid|
-        raise Vertica::Error::UnknownTypeError, "Unknown type OID: #{unknown_oid}"
-      end
-    end
+  # @return [String] Returns a user-consumable string representation of this column.
+  def inspect
+    "#<#{self.class.name} name=#{name.inspect} data_type=#{data_type.inspect}>"
   end
 end

data/lib/vertica/connection.rb

@@ -1,12 +1,54 @@
 require 'socket'
 
+# A client for a Vertica server, which allows you to run queries against it.
+#
+# Use {Vertica.connect} to establish a connection. Then, the {#query} method will allow you
+# to run SQL queries against the database. For `COPY FROM STDIN` queries, use the {#copy} method
+# instead. You can use {#interrupt} to interrupt long running queries. {#close} will close the
+# connection to the server.
+#
+# @attr_reader transaction_status [:no_transaction, :in_transaction, :failed_transaction] The current
+#   transaction state of the session. This will be updated after every query.
+# @attr_reader parameters [Hash<String, String>] Connection parameters as provided by the server.
+# @attr_reader options [Hash] The connection options provided to the constructor. See {#initialize}.
+#
+# @example Running a buffered query against the database
+#   connection = Vertica.connect(host: 'db_server', username: 'user', password: 'password', ...)
+#   result = connection.query("SELECT id, name FROM my_table")
+#   result.each do |row|
+#     puts "Row: #row['id']: #{row['name']}"
+#   end
+#   connection.close
+#
+# @see Vertica.connect
+# @see Vertica::Result
 class Vertica::Connection
 
   attr_reader :transaction_status, :parameters, :options
 
-  # Opens a connectio the a Vertica server
-  # @param [Hash] options The connection options to use.
-  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)
+  # Creates a connection the a Vertica server.
+  # @param host [String] The hostname to connect to. E.g. `localhost`
+  # @param port [Integer] The port to connect to. Defaults to `5433`.
+  # @param username [String] The username for the session.
+  # @param password [String] The password for the session.
+  # @param interruptable [true, false] Whether to make this session interruptible. Setting this to true
+  #   allows you to interrupt sessions and queries, but requires running a query during startup in order
+  #   to obtain the session id.
+  # @param ssl [OpenSSL::SSL::SSLContext, Boolean] Set this to an OpenSSL::SSL::SSLContext instance to
+  #   require the connection to be encrypted using SSL/TLS. `true` will use the default SSL options.
+  #   Not every server has support for SSL encryption. In that case you'll have to leave this to false.
+  # @param read_timeout [Integer] The number of seconds to wait for data on the connection. You should
+  #   set this to a sufficiently high value when executing complicated queries that require a long time
+  #   to be evaluated.
+  # @param role [Array<String>, :all, :none, :default] A list of additional roles to enable for the session. See the
+  #   [Vertica documentation for `SET ROLE`](https://my.vertica.com/docs/7.1.x/HTML/Content/Authoring/SQLReferenceManual/Statements/SET/SETROLE.htm).
+  # @param timezone [String] The timezone to use for the session. See the
+  #   [Vertica documentation for `SET TIME ZONE`](https://my.vertica.com/docs/7.1.x/HTML/Content/Authoring/SQLReferenceManual/Statements/SET/SETTIMEZONE.htm).
+  # @param search_path [Array<String>] A list of schemas to use as search path. See the
+  #   [Vertica documentation for `SET SEARCH_PATH`](https://my.vertica.com/docs/7.1.x/HTML/Content/Authoring/SQLReferenceManual/Statements/SET/SETSEARCH_PATH.htm).
+  # @param debug [Boolean] Setting this to true will log all the communication between client and server
+  #   to STDOUT. Useful when developing this library.
+  def initialize(host: nil, port: 5433, username: nil, password: nil, database: nil, interruptable: false, ssl: false, 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
 
@@ -29,41 +71,110 @@ class Vertica::Connection
     boot_connection(skip_initialize: skip_initialize) unless skip_startup
   end
 
-  def on_notice(&block)
-    @notice_handler = block
-  end
-
+  # @return [Boolean] Returns true iff the connection is encrypted.
   def ssl?
     Object.const_defined?('OpenSSL') && @socket.kind_of?(OpenSSL::SSL::SSLSocket)
   end
 
+  # @return [Boolean] Returns true iff the connection to the server is opened.
+  # @note The connection will be opened automatically if you use it.
   def opened?
     @socket && @backend_pid && @transaction_status
   end
 
+  # @return [Boolean] Returns false iff the connection to the server is opened.
+  # @note Even if the connection is closed, it will be opened automatically if you use it.
   def closed?
     !opened?
   end
 
+  # @return [Boolean] Returns true iff the connection is in use.
   def busy?
     @mutex.locked?
   end
 
+  # @return [Boolean] Returns true iff the connection is ready to handle queries.
   def ready_for_query?
     !busy?
   end
 
+  # Returns true iff the connection can be interrupted.
+  #
+  # Connections can only be interrupted if the session ID is known, so it can
+  # run `SELECT CLOSE_SESSION(session_id)` using a separate connection. By passing
+  # `interruptable: true` as a connection parameter (see {#initialize}), the connection
+  # will discover its session id before you can use it, allowing it to be interrupted.
+  #
+  # @return [Boolean] Returns true iff the connection can be interrupted.
+  # @see {#interrupt}
   def interruptable?
     !session_id.nil?
   end
 
-  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 copy(sql, source: nil, **kwargs, &block)
+  # Runs a SQL query against the database.
+  #
+  # @overload query(sql)
+  #   Runs a query against the database, and return the full result as a {Vertica::Result}
+  #   instance.
+  #
+  #   @note This requires the entire result to be buffered in memory, which may cause problems
+  #     for queries with large results. Consider using the unbuffered version instead.
+  #
+  #   @param sql [String] The SQL command to run.
+  #   @return [Vertica::Result]
+  #   @raise [Vertica::Error::ConnectionError] The connection to the server failed.
+  #   @raise [Vertica::Error::QueryError] The server sent an error response indicating that
+  #     the provided query cannot be evaluated.
+  #
+  # @overload query(sql, &block)
+  #   Runs a query against the database, and yield every {Vertica::Row row} to the provided
+  #   block.
+  #
+  #   @param sql [String] The SQL command to run.
+  #   @yield The provided block will be called for every row in the result.
+  #   @yieldparam row [Vertica::Row]
+  #   @return [String] The kind of command that was executed, e.g. `"SELECT"`.
+  #   @raise [Vertica::Error::ConnectionError] The connection to the server failed.
+  #   @raise [Vertica::Error::QueryError] The server sent an error response indicating that
+  #     the provided query cannot be evaluated.
+  #
+  # @see https://my.vertica.com/docs/7.1.x/HTML/Content/Authoring/SQLReferenceManual/Statements/SELECT/SELECT.htm
+  #   Vertica's documentation for SELECT.
+  def query(sql, &block)
+    run_in_mutex(Vertica::Query.new(self, sql, row_handler: block))
+  end
+
+  # Loads data into Vertica using a `COPY table FROM STDIN` query.
+  #
+  # @param sql [String] The `COPY ... FROM STDIN` SQL command to run.
+  # @param source [String, IO] The source of the data to be copied. This can either be a filename, or
+  #   an IO object. If you don't specify a source, you'll need to provide a block that will provide the
+  #   data to be copied.
+  # @yield A block that will be called with a writer that you can provided data to. If an exception is
+  #   raised in the block, the `COPY` command will be cancelled.
+  # @yieldparam io [:write] An object that you can call write on to provide data to be loaded.
+  # @return [String] The kind of command that was executed on the server. This should always be `"COPY"`.
+  #
+  # @example Loading data using an IO object as source
+  #   connection = Vertica.connect(host: 'db_server', username: 'user', password: 'password', ...)
+  #   File.open("filename.csv", "r") do |io|
+  #     connection.copy("COPY my_table FROM STDIN ...", source: io)
+  #   end
+  #
+  # @example Loading data using a filename as source
+  #   connection = Vertica.connect(host: 'db_server', username: 'user', password: 'password', ...)
+  #   connection.copy("COPY my_table FROM STDIN ...", source: "filename.csv")
+  #
+  # @example Loading data using a callback
+  #   connection = Vertica.connect(host: 'db_server', username: 'user', password: 'password', ...)
+  #   connection.copy("COPY my_table FROM STDIN ...") do |io|
+  #     io.write("my data")
+  #     io.write("more data")
+  #   end
+  #
+  # @see https://my.vertica.com/docs/7.1.x/HTML/Content/Authoring/SQLReferenceManual/Statements/COPY/COPY.htm
+  #   Vertica's documentation for COPY.
+  def copy(sql, source: nil, &block)
     copy_handler = if block_given?
       block
     elsif source && File.exist?(source.to_s)
@@ -72,22 +183,33 @@ class Vertica::Connection
       lambda { |data| io_copy_handler(source, data) }
     end
 
-    job = Vertica::Query.new(self, sql, copy_handler: copy_handler, **kwargs)
-
-    run_with_mutex(job)
+    run_in_mutex(Vertica::Query.new(self, sql, copy_handler: copy_handler))
   end
 
+  # Returns a user-consumable string representation of this row.
+  # @return [String]
   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
 
+  # Closes the connection to the Vertica server.
+  # @return [void]
   def close
     write_message(Vertica::Protocol::Terminate.new)
   ensure
     close_socket
   end
 
+  # Cancels the current query.
+  #
+  # @note Vertica's protocol is based on the PostgreSQL protocol. This method to cancel sessions
+  #   in PostgreSQL is accepted by the Vertica server, but I haven't actually observed queries
+  #   actually being cancelled when using this method. Vertica provides an alternative method, by
+  #   running `SELECT CLOSE_SESSION(session_id)` as a query on a different connection. See {#interrupt}.
+  #
+  # @return [void]
+  # @see #interrupt
   def cancel
     conn = self.class.new(skip_startup: true, **options)
     conn.write_message(Vertica::Protocol::CancelRequest.new(backend_pid, backend_key))
@@ -95,6 +217,18 @@ class Vertica::Connection
     conn.close_socket
   end
 
+  # Interrupts this session to the Vertica server, which will cancel the running query.
+  #
+  # You'll have to call this method in a separate thread. It will open up a separate connection, and run
+  # `SELECT CLOSE_SESSION(current_session_id)` to close the current session. In order to be able to do this
+  # the client needs to know its session ID. You'll have to pass `interruptable: true` as a connection
+  # parameter (see {#initialize}) to make sure the connection will request its session id, by running
+  # `SELECT session_id FROM v_monitor.current_session` right after the connection is opened.
+  #
+  # @return [void]
+  # @see #interruptable?
+  # @see https://my.vertica.com/docs/7.1.x/HTML/Content/Authoring/SQLReferenceManual/Functions/VerticaFunctions/CLOSE_SESSION.htm
+  #   Vertica's documentation for CLOSE_SESSION
   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(skip_initialize: true, **options)
@@ -103,6 +237,20 @@ class Vertica::Connection
     conn.close if conn
   end
 
+  # Installs a hanlder for notices that may be sent from the server to the client.
+  #
+  # You can only install one handler; if you call this method again it will replace the
+  # previous handler.
+  #
+  # @return [void]
+  def on_notice(&block)
+    @notice_handler = block
+  end
+
+  # Writes a frontend message to the socket.
+  # @note This method is for internal use only; you should not call it directly.
+  # @return [void]
+  # @raise [Vertica::Error::ConnectionError]
   # @private
   def write_message(message)
     puts "=> #{message.inspect}" if options.fetch(:debug)
@@ -112,6 +260,10 @@ class Vertica::Connection
     raise Vertica::Error::ConnectionError.new(e.message)
   end
 
+  # Reads a backend message from the socket.
+  # @note This method is for internal use only; you should not call it directly.
+  # @return [Vertica::Protocol::BackendMessage]
+  # @raise [Vertica::Error::ConnectionError]
   # @private
   def read_message
     type, size = read_bytes(5).unpack('aN')
@@ -124,6 +276,9 @@ class Vertica::Connection
     raise Vertica::Error::ConnectionError.new(e.message)
   end
 
+  # Processes a backend message that was received from the socket.
+  # @note This method is for internal use only; you should not call it directly.
+  # @return [void]
   # @private
   def process_message(message)
     case message
@@ -168,7 +323,7 @@ class Vertica::Connection
     end
   end
 
-  def run_with_mutex(job)
+  def run_in_mutex(job)
     boot_connection if closed?
     if @mutex.try_lock
       begin