viking-sequel 3.10.0

data/doc/virtual_rows.rdoc

@@ -0,0 +1,205 @@
+= Virtual Row Blocks
+
+Dataset methods filter, order, and select all take blocks that are referred to as
+virtual row blocks.  Many other dataset methods pass the blocks
+they are given into one of those three methods, so there are actually
+many Sequel::Dataset methods that take virtual row blocks.
+
+== Regular Proc vs InstanceEvaled Procs
+
+Virtual row blocks behave differently depending on whether the block accepts
+an argument.  If the block accepts an argument, it is called with an instance
+of Sequel::SQL::VirtualRow.  If it does not accept an argument, it is
+evaluated in the context of an instance of Sequel::SQL::VirtualRow.
+
+  ds = DB[:items]
+  # Regular proc
+  ds.filter{|o| o.column > 1}
+  # WHERE column > 1
+  
+  # Instance-evaled proc
+  ds.filter{column > 1}
+  # WHERE column > 1
+  
+If you aren't familiar with the difference between regular blocks and instance
+evaled blocks, you should probably consult a general ruby reference, but briefly,
+with regular procs, methods called without an explicit receiver inside the
+proc call the method on the receiver in the surrounding scope, while instance
+evaled procs call the method on the receiver of the instance_eval call.  However,
+in both cases, local variables available in the surrounding scope will be available
+inside the proc.  If that doesn't make sense, maybe this example will help:
+
+  def self.a
+    42
+  end
+  b = 32
+  
+  # Regular proc
+  ds.filter{|o| o.c > a - b}
+  # WHERE c > 10
+  
+  # Instance-evaled proc
+  ds.filter{c > a - b}
+  # WHERE c > (a - 32)
+  
+There are two related differences here.  First is the usage of "o.c" vs "c",
+and second is the difference between the the use of "a".  In the regular proc,
+you couldn't call c without an explicit receiver in the proc, unless the self of the
+surrounding scope responded to it.  For a, note how ruby calls the method on
+the receiver of the surrounding scope in the regular proc, which returns an integer,
+and does the substraction before Sequel gets access to it.  In the instance evaled
+proc, calling a without a receiver calls the a method on the VirtualRow instance.
+For b, note that it operates the same in both cases, as it is a local variable.
+
+Basically, the choice for whether to use a regular proc or an instance evaled proc is
+completely up to you.  The same things can be accomplished with both.
+Instance evaled procs tend to produce shorter code, but by modifying the scope
+can be more difficult for a new user to understand.  That being said, I usually
+use instance evaled procs unless I need to call methods on the receiver of the
+surrounding scope inside the proc.
+
+== Local Variables vs Method Calls
+
+If you have a method that accepts 0 arguments and has the same name as a local
+variable, you can call it with () to differentiate the method call from the
+local variable access.  This is mostly useful in instance_evaled procs:
+
+  b = 32
+  ds.filter{b() > b}
+  # WHERE b > 32
+
+== VirtualRow Methods
+
+VirtualRow is a class that returns SQL::Identifiers, SQL::QualifiedIdentifiers,
+SQL::Functions, or SQL::WindowFunctions depending on how it is called.
+
+== SQL::Identifiers - Regular columns
+
+SQL::Identifiers can be thought of as regular column references in SQL,
+not qualified by any table. You get an SQL::Identifier if the method is called
+without a block or arguments, and doesn't have a double underscore in the method
+name:
+
+  ds.filter{|o| o.column > 1}
+  ds.filter{column > 1}
+  # WHERE column > 1
+  
+== SQL::QualifiedIdentifiers - Qualified columns
+
+SQL::QualifiedIdentifiers can be thought of as column references in SQL that
+are qualified to a specific table.  You get an SQL::QualifiedIdentifier if
+the method is called without a block or arguments, and has a double underscore
+in the method name:
+
+  ds.filter{|o| o.table__column > 1}
+  ds.filter{table__column > 1}
+  # WHERE table.column > 1
+
+Using the double underscore for SQL::QualifiedIdentifiers was done to make
+usage very similar to using symbols, which also translate the double underscore
+into a qualified column.
+
+== SQL::Functions - SQL function calls
+
+SQL::Functions can be thought of as function calls in SQL.  You get a simple
+function call if you call a method with arguments and without a block:
+
+  ds.filter{|o| o.function(1) > 1}
+  ds.filter{function(1) > 1}
+  # WHERE function(1) > 1
+  
+To call a SQL function with multiple arguments, just use those arguments in
+your function call:
+  
+  ds.filter{|o| o.function(1, o.a) > 1}
+  ds.filter{function(1, a) > 1}
+  # WHERE function(1, a) > 1
+
+If the SQL function does not accept any arguments, you need to provide an empty
+block to the method to distinguish it from a call that will produce an
+SQL::Identifier:
+
+  ds.select{|o| o.version{}}
+  ds.select{version{}}
+  # SELECT version()
+  
+To use the SQL wildcard (*) as the sole argument in a function call (most often
+used with the count function), you should provide :* as the sole argument to
+the method, and provide an empty block to the method:
+  
+  ds.select{|o| o.count(:*){}}
+  ds.select{count(:*){}}
+  # SELECT count(*)
+
+To append the DISTINCT keyword before the method arguments, you need to make
+:distinct the first argument of the method call, and provide an empty block to
+the method:
+
+  ds.select{|o| o.count(:distinct, o.col1){}}
+  ds.select{count(:distinct, col1){}}
+  # SELECT count(DISTINCT col1)
+  
+To use multiple columns with the DISTINCT keyword, use multiple arguments in
+the method call:
+
+  ds.select{|o| o.count(:distinct, o.col1, o.col2){}}
+  ds.select{count(:distinct, col1, col2){}}
+  # SELECT count(DISTINCT col1, col2)
+  
+== SQL::WindowFunctions - SQL window function calls
+
+SQL::WindowFunctions can be thought of as calls to SQL window functions.  Not
+all databases support them, but they are very helpful for certain types of
+queries.  To use them, you need to make :over the first argument of the method
+call, with an optional hash as the second argument: Here are some examples of use:
+
+  ds.select{|o| o.rank(:over){}}
+  ds.select{rank(:over){}}
+  # SELECT rank() OVER ()
+  
+  ds.select{|o| o.count(:over, :*=>true){}}
+  ds.select{count(:over, :*=>true){}}
+  # SELECT count(*) OVER ()
+  
+  ds.select{|o| o.sum(:over, :args=>o.col1, :partition=>o.col2, :order=>o.col3){}}
+  ds.select{sum(:over, :args=>col1, :partition=>col2, :order=>col3){}}
+  # SELECT sum(col1) OVER (PARTITION BY col2 ORDER BY col3)
+
+== Returning multiple values
+
+It's common when using select and order virtual row blocks to want to
+return multiple values.  If you want to do that, you just need to return a single
+array:
+
+  ds.select{|o| [o.column1, o.sum(o.column2).as(o.sum)]}
+  ds.select{[column1, sum(column2).as(sum)]}
+  # SELECT column1, sum(column2) AS sum
+  
+Note that if you forget the array brackets, you'll end up with a syntax error:
+
+  # Invalid ruby syntax
+  ds.select{|o| o.column1, o.sum(o.column2).as(o.sum)}
+  ds.select{column1, sum(column2).as(sum)}
+  
+== Alternative Description of the VirtualRow method call rules
+
+* If a block is given:
+  * The block is currently not called.  This may change in a future version.
+  * If there are no arguments, an SQL::Function with the name of
+    method used, and no arguments.
+  * If the first argument is :*, an SQL::Function is created with a single
+    wildcard argument (*).
+  * If the first argument is :distinct, an SQL::Function is created with
+    the keyword DISTINCT prefacing all remaining arguments.
+  * If the first argument is :over, the second argument if provided should
+    be a hash of options to pass to SQL::Window.  The options hash can also
+    contain :*=>true to use a wildcard argument as the function argument, or
+    :args=>... to specify an array of arguments to use as the function arguments.
+* If a block is not given:
+  * If there are arguments, an SQL::Function is returned with the
+    name of the method used and the arguments given.
+  * If there are no arguments and the method contains a double
+    underscore, split on the double underscore and return an
+    SQL::QualifiedIdentifier with the table and column.
+  * Otherwise, create an SQL::Identifier with the name of the
+    method.

data/lib/sequel.rb

@@ -0,0 +1 @@
+require 'sequel/model'

data/lib/sequel/adapters/ado.rb

@@ -0,0 +1,90 @@
+require 'win32ole'
+
+module Sequel
+  # The ADO adapter provides connectivity to ADO databases in Windows.
+  module ADO
+    class Database < Sequel::Database
+      set_adapter_scheme :ado
+
+      def initialize(opts)
+        super
+        @opts[:driver] ||= 'SQL Server'
+        case @opts[:driver]
+        when 'SQL Server'
+          Sequel.ts_require 'adapters/ado/mssql'
+          extend Sequel::ADO::MSSQL::DatabaseMethods
+        end
+      end
+
+      # Connect to the database. In addition to the usual database options,
+      # the following options have an effect:
+      #
+      # * :command_timeout - Sets the time in seconds to wait while attempting
+      #   to execute a command before cancelling the attempt and generating
+      #   an error. Specifically, it sets the ADO CommandTimeout property.
+      #   If this property is not set, the default of 30 seconds is used.
+      # * :conn_string - The full ADO connection string.  If this is provided,
+      #   the usual options are ignored.
+      # * :provider - Sets the Provider of this ADO connection (for example, "SQLOLEDB")
+      def connect(server)
+        opts = server_opts(server)
+        s = opts[:conn_string] || "driver=#{opts[:driver]};server=#{opts[:host]};database=#{opts[:database]}#{";uid=#{opts[:user]};pwd=#{opts[:password]}" if opts[:user]}"
+        handle = WIN32OLE.new('ADODB.Connection')
+        handle.CommandTimeout = opts[:command_timeout] if opts[:command_timeout]
+        handle.Provider = opts[:provider] if opts[:provider]
+        handle.Open(s)
+        handle
+      end
+      
+      def dataset(opts = nil)
+        ADO::Dataset.new(self, opts)
+      end
+    
+      def execute(sql, opts={})
+        synchronize(opts[:server]) do |conn|
+          begin
+            r = log_yield(sql){conn.Execute(sql)}
+            yield(r) if block_given?
+          rescue ::WIN32OLERuntimeError => e
+            raise_error(e)
+          end
+        end
+        nil
+      end
+      alias do execute
+
+      private
+      
+      # The ADO adapter doesn't support transactions, since it appears not to
+      # use a single native connection for each connection in the pool
+      def _transaction(conn)
+        th = Thread.current
+        begin
+          @transactions << th
+          yield conn
+        rescue Sequel::Rollback
+        ensure
+          @transactions.delete(th)
+        end
+      end
+      
+      def disconnect_connection(conn)
+        conn.Close
+      end
+    end
+    
+    class Dataset < Sequel::Dataset
+      def fetch_rows(sql)
+        execute(sql) do |s|
+          @columns = cols = s.Fields.extend(Enumerable).map{|column| output_identifier(column.Name)}
+          s.getRows.transpose.each{|r| yield cols.inject({}){|m,c| m[c] = r.shift; m}} unless s.eof
+        end
+      end
+      
+      # ADO returns nil for all for delete and update statements.
+      def provides_accurate_rows_matched?
+        false
+      end
+    end
+  end
+end

data/lib/sequel/adapters/ado/mssql.rb

@@ -0,0 +1,30 @@
+Sequel.require 'adapters/shared/mssql'
+
+module Sequel
+  module ADO
+    # Database and Dataset instance methods for MSSQL specific
+    # support via ADO.
+    module MSSQL
+      module DatabaseMethods
+        include Sequel::MSSQL::DatabaseMethods
+        
+        # Return instance of Sequel::ADO::MSSQL::Dataset with the given opts.
+        def dataset(opts=nil)
+          Sequel::ADO::MSSQL::Dataset.new(self, opts)
+        end
+      end
+      
+      class Dataset < ADO::Dataset
+        include Sequel::MSSQL::DatasetMethods
+        
+        # Use a nasty hack of multiple SQL statements in the same call and
+        # having the last one return the most recently inserted id.  This
+        # is necessary as ADO doesn't provide a consistent native connection.
+        def insert(*values)
+          return super if @opts[:sql]
+          with_sql("SET NOCOUNT ON; #{insert_sql(*values)}; SELECT CAST(SCOPE_IDENTITY() AS INTEGER)").single_value
+        end
+      end
+    end
+  end
+end

data/lib/sequel/adapters/amalgalite.rb

@@ -0,0 +1,176 @@
+require 'amalgalite'
+Sequel.require 'adapters/shared/sqlite'
+
+module Sequel
+  # Top level module for holding all Amalgalite-related modules and classes
+  # for Sequel.
+  module Amalgalite
+    # Type conversion map class for Sequel's use of Amalgamite
+    class SequelTypeMap < ::Amalgalite::TypeMaps::DefaultMap
+      methods_handling_sql_types.delete('string')
+      methods_handling_sql_types.merge!(
+        'datetime' => %w'datetime timestamp',
+        'time' => %w'time',
+        'float' => ['float', 'double', 'real', 'double precision'],
+        'decimal' => %w'numeric decimal money'
+      )
+      
+      # Return blobs as instances of Sequel::SQL::Blob instead of
+      # Amalgamite::Blob
+      def blob(s)
+        SQL::Blob.new(s)
+      end
+      
+      # Return numeric/decimal types as instances of BigDecimal
+      # instead of Float
+      def decimal(s)
+        BigDecimal.new(s)
+      end
+      
+      # Return datetime types as instances of Sequel.datetime_class
+      def datetime(s)
+        Sequel.database_to_application_timestamp(s)
+      end
+      
+      # Don't raise an error if the value is a string and the declared
+      # type doesn't match a known type, just return the value.
+      def result_value_of(declared_type, value)
+        if value.is_a?(::Amalgalite::Blob)
+          SQL::Blob.new(value.source)
+        elsif value.is_a?(String) && declared_type
+          (meth = self.class.sql_to_method(declared_type.downcase)) ? send(meth, value) : value
+        else
+          super
+        end
+      end
+    end
+    
+    # Database class for SQLite databases used with Sequel and the
+    # amalgalite driver.
+    class Database < Sequel::Database
+      include ::Sequel::SQLite::DatabaseMethods
+      
+      set_adapter_scheme :amalgalite
+      
+      # Mimic the file:// uri, by having 2 preceding slashes specify a relative
+      # path, and 3 preceding slashes specify an absolute path.
+      def self.uri_to_options(uri) # :nodoc:
+        { :database => (uri.host.nil? && uri.path == '/') ? nil : "#{uri.host}#{uri.path}" }
+      end
+      private_class_method :uri_to_options
+      
+      # Connect to the database.  Since SQLite is a file based database,
+      # the only options available are :database (to specify the database
+      # name), and :timeout, to specify how long to wait for the database to
+      # be available if it is locked, given in milliseconds (default is 5000).
+      def connect(server)
+        opts = server_opts(server)
+        opts[:database] = ':memory:' if blank_object?(opts[:database])
+        db = ::Amalgalite::Database.new(opts[:database])
+        db.busy_handler(::Amalgalite::BusyTimeout.new(opts.fetch(:timeout, 5000)/50, 50))
+        db.type_map = SequelTypeMap.new
+        db
+      end
+      
+      # Amalgalite is just the SQLite database without a separate SQLite installation.
+      def database_type
+        :sqlite
+      end
+
+      # Return instance of Sequel::Amalgalite::Dataset with the given options.
+      def dataset(opts = nil)
+        Amalgalite::Dataset.new(self, opts)
+      end
+      
+      # Run the given SQL with the given arguments. Returns nil.
+      def execute_ddl(sql, opts={})
+        _execute(sql, opts){|conn| log_yield(sql){conn.execute_batch(sql)}}
+        nil
+      end
+      
+      # Run the given SQL with the given arguments and return the number of changed rows.
+      def execute_dui(sql, opts={})
+        _execute(sql, opts){|conn| log_yield(sql){conn.execute_batch(sql)}; conn.row_changes}
+      end
+      
+      # Run the given SQL with the given arguments and return the last inserted row id.
+      def execute_insert(sql, opts={})
+        _execute(sql, opts){|conn| log_yield(sql){conn.execute_batch(sql)}; conn.last_insert_rowid}
+      end
+      
+      # Run the given SQL with the given arguments and yield each row.
+      def execute(sql, opts={})
+        _execute(sql, opts) do |conn|
+          begin
+            yield(stmt = log_yield(sql){conn.prepare(sql)})
+          ensure
+            stmt.close if stmt
+          end
+        end
+      end
+      
+      # Run the given SQL with the given arguments and return the first value of the first row.
+      def single_value(sql, opts={})
+        _execute(sql, opts){|conn| log_yield(sql){conn.first_value_from(sql)}}
+      end
+      
+      private
+      
+      # Yield an available connection.  Rescue
+      # any Amalgalite::Errors and turn them into DatabaseErrors.
+      def _execute(sql, opts)
+        begin
+          synchronize(opts[:server]){|conn| yield conn}
+        rescue ::Amalgalite::Error, ::Amalgalite::SQLite3::Error => e
+          raise_error(e)
+        end
+      end
+      
+      # The Amagalite adapter does not need the pool to convert exceptions.
+      # Also, force the max connections to 1 if a memory database is being
+      # used, as otherwise each connection gets a separate database.
+      def connection_pool_default_options
+        o = super.dup
+        # Default to only a single connection if a memory database is used,
+        # because otherwise each connection will get a separate database
+        o[:max_connections] = 1 if @opts[:database] == ':memory:' || blank_object?(@opts[:database])
+        o
+      end
+      
+      # Both main error classes that Amalgalite raises
+      def database_error_classes
+        [::Amalgalite::Error, ::Amalgalite::SQLite3::Error]
+      end
+
+      # Disconnect given connections from the database.
+      def disconnect_connection(c)
+        c.close
+      end
+    end
+    
+    # Dataset class for SQLite datasets that use the amalgalite driver.
+    class Dataset < Sequel::Dataset
+      include ::Sequel::SQLite::DatasetMethods
+      
+      # Yield a hash for each row in the dataset.
+      def fetch_rows(sql)
+        execute(sql) do |stmt|
+          @columns = cols = stmt.result_fields.map{|c| output_identifier(c)}
+          col_count = cols.size
+          stmt.each do |result|
+            row = {}
+            col_count.times{|i| row[cols[i]] = result[i]}
+            yield row
+          end
+        end
+      end
+
+      private
+      
+      # Quote the string using the adapter instance method.
+      def literal_string(v)
+        db.synchronize{|c| c.quote(v)}
+      end
+    end
+  end
+end