colincasey-sequel 2.10.0 → 2.10.1

data/lib/sequel_core/dataset/convenience.rb

@@ -0,0 +1,237 @@
+module Sequel
+  class Dataset
+    COMMA_SEPARATOR = ', '.freeze
+    COUNT_OF_ALL_AS_COUNT = SQL::Function.new(:count, '*'.lit).as(:count)
+
+    # Returns the first record matching the conditions.
+    def [](*conditions)
+      first(*conditions)
+    end
+
+    # Update all records matching the conditions
+    # with the values specified.
+    def []=(conditions, values)
+      filter(conditions).update(values)
+    end
+
+    # Returns the average value for the given column.
+    def avg(column)
+      get{|o| o.avg(column)}
+    end
+    
+    # Returns true if no records exists in the dataset
+    def empty?
+      get(1).nil?
+    end
+    
+    # Returns the first record in the dataset. If a numeric argument is
+    # given, it is interpreted as a limit, and then returns all 
+    # matching records up to that limit.  If no argument is passed,
+    # it returns the first matching record.  If any other type of
+    # argument(s) is passed, it is given to filter and the
+    # first matching record is returned. If a block is given, it is used
+    # to filter the dataset before returning anything.
+    #
+    # Examples:
+    # 
+    #   ds.first => {:id=>7}
+    #   ds.first(2) => [{:id=>6}, {:id=>4}]
+    #   ds.order(:id).first(2) => [{:id=>1}, {:id=>2}]
+    #   ds.first(:id=>2) => {:id=>2}
+    #   ds.first("id = 3") => {:id=>3}
+    #   ds.first("id = ?", 4) => {:id=>4}
+    #   ds.first{|o| o.id > 2} => {:id=>5}
+    #   ds.order(:id).first{|o| o.id > 2} => {:id=>3}
+    #   ds.first{|o| o.id > 2} => {:id=>5}
+    #   ds.first("id > ?", 4){|o| o.id < 6} => {:id=>5}
+    #   ds.order(:id).first(2){|o| o.id < 2} => [{:id=>1}]
+    def first(*args, &block)
+      ds = block ? filter(&block) : self
+
+      if args.empty?
+        ds.single_record
+      else
+        args = (args.size == 1) ? args.first : args
+        if Integer === args
+          ds.limit(args).all
+        else
+          ds.filter(args).single_record
+        end
+      end
+    end
+
+    # Return the column value for the first matching record in the dataset.
+    def get(column=nil, &block)
+      raise(Error, 'must provide argument or block to Dataset#get, not both') if column && block
+      (column ? select(column) : select(&block)).single_value
+    end
+
+    # Returns a dataset grouped by the given column with count by group.
+    def group_and_count(*columns)
+      group(*columns).select(*(columns + [COUNT_OF_ALL_AS_COUNT])).order(:count)
+    end
+    
+    # Returns the interval between minimum and maximum values for the given 
+    # column.
+    def interval(column)
+      get{|o| o.max(column) - o.min(column)}
+    end
+
+    # Reverses the order and then runs first.  Note that this
+    # will not necessarily give you the last record in the dataset,
+    # unless you have an unambiguous order.  If there is not
+    # currently an order for this dataset, raises an Error.
+    def last(*args, &block)
+      raise(Error, 'No order specified') unless @opts[:order]
+      reverse.first(*args, &block)
+    end
+    
+    # Maps column values for each record in the dataset (if a column name is
+    # given), or performs the stock mapping functionality of Enumerable.
+    def map(column_name = nil, &block)
+      if column_name
+        super() {|r| r[column_name]}
+      else
+        super(&block)
+      end
+    end
+
+    # Returns the maximum value for the given column.
+    def max(column)
+      get{|o| o.max(column)}
+    end
+
+    # Returns the minimum value for the given column.
+    def min(column)
+      get{|o| o.min(column)}
+    end
+
+    # Inserts multiple records into the associated table. This method can be
+    # to efficiently insert a large amounts of records into a table. Inserts
+    # are automatically wrapped in a transaction.
+    # 
+    # This method should be called with a columns array and an array of value arrays:
+    #
+    #   dataset.multi_insert([:x, :y], [[1, 2], [3, 4]])
+    #
+    # This method can also be called with an array of hashes:
+    # 
+    #   dataset.multi_insert({:x => 1}, {:x => 2})
+    #
+    # Be aware that all hashes should have the same keys if you use this calling method,
+    # otherwise some columns could be missed or set to null instead of to default
+    # values.
+    #
+    # The method also accepts a :slice or :commit_every option that specifies
+    # the number of records to insert per transaction. This is useful especially
+    # when inserting a large number of records, e.g.:
+    #
+    #   # this will commit every 50 records
+    #   dataset.multi_insert(lots_of_records, :slice => 50)
+    def multi_insert(*args)
+      if args.empty?
+        return
+      elsif args[0].is_a?(Array) && args[1].is_a?(Array)
+        columns, values, opts = *args
+      elsif args[0].is_a?(Array) && args[1].is_a?(Dataset)
+        table = @opts[:from].first
+        columns, dataset = *args
+        sql = "INSERT INTO #{quote_identifier(table)} (#{identifier_list(columns)}) VALUES #{literal(dataset)}"
+        return @db.transaction{execute_dui(sql)}
+      else
+        # we assume that an array of hashes is given
+        hashes, opts = *args
+        return if hashes.empty?
+        columns = hashes.first.keys
+        # convert the hashes into arrays
+        values = hashes.map {|h| columns.map {|c| h[c]}}
+      end
+      # make sure there's work to do
+      return if columns.empty? || values.empty?
+      
+      slice_size = opts && (opts[:commit_every] || opts[:slice])
+      
+      if slice_size
+        values.each_slice(slice_size) do |slice|
+          statements = multi_insert_sql(columns, slice)
+          @db.transaction{statements.each{|st| execute_dui(st)}}
+        end
+      else
+        statements = multi_insert_sql(columns, values)
+        @db.transaction{statements.each{|st| execute_dui(st)}}
+      end
+    end
+    alias_method :import, :multi_insert
+    
+    # Pretty prints the records in the dataset as plain-text table.
+    def print(*cols)
+      Sequel::PrettyTable.print(naked.all, cols.empty? ? columns : cols)
+    end
+    
+    # Returns a Range object made from the minimum and maximum values for the
+    # given column.
+    def range(column)
+      if r = select{|o| [o.min(column).as(:v1), o.max(column).as(:v2)]}.first
+        (r[:v1]..r[:v2])
+      end
+    end
+    
+    # Returns the first record in the dataset.
+    def single_record(opts = nil)
+      each((opts||{}).merge(:limit=>1)){|r| return r}
+      nil
+    end
+
+    # Returns the first value of the first record in the dataset.
+    # Returns nil if dataset is empty.
+    def single_value(opts = nil)
+      if r = single_record((opts||{}).merge(:graph=>false, :naked=>true))
+        r.values.first
+      end
+    end
+    
+    # Returns the sum for the given column.
+    def sum(column)
+      get{|o| o.sum(column)}
+    end
+
+    # Returns true if the table exists.  Will raise an error
+    # if the dataset has fixed SQL or selects from another dataset
+    # or more than one table.
+    def table_exists?
+      raise(Sequel::Error, "this dataset has fixed SQL") if @opts[:sql]
+      raise(Sequel::Error, "this dataset selects from multiple sources") if @opts[:from].size != 1
+      t = @opts[:from].first
+      raise(Sequel::Error, "this dataset selects from a sub query") if t.is_a?(Dataset)
+      @db.table_exists?(t)
+    end
+
+    # Returns a string in CSV format containing the dataset records. By 
+    # default the CSV representation includes the column titles in the
+    # first line. You can turn that off by passing false as the 
+    # include_column_titles argument.
+    #
+    # This does not use a CSV library or handle quoting of values in
+    # any way.  If any values in any of the rows could include commas or line
+    # endings, you probably shouldn't use this.
+    def to_csv(include_column_titles = true)
+      n = naked
+      cols = n.columns
+      csv = ''
+      csv << "#{cols.join(COMMA_SEPARATOR)}\r\n" if include_column_titles
+      n.each{|r| csv << "#{cols.collect{|c| r[c]}.join(COMMA_SEPARATOR)}\r\n"}
+      csv
+    end
+    
+    # Returns a hash with one column used as key and another used as value.
+    # If rows have duplicate values for the key column, the latter row(s)
+    # will overwrite the value of the previous row(s). If the value_column
+    # is not given or nil, uses the entire hash as the value.
+    def to_hash(key_column, value_column = nil)
+      inject({}) do |m, r|
+        m[r[key_column]] = value_column ? r[value_column] : r
+        m
+      end
+    end
+  end
+end

data/lib/sequel_core/dataset/pagination.rb

@@ -0,0 +1,96 @@
+module Sequel
+  class Dataset
+    # Returns a paginated dataset. The returned dataset is limited to
+    # the page size at the correct offset, and extended with the Pagination
+    # module.  If a record count is not provided, does a count of total
+    # number of records for this dataset.
+    def paginate(page_no, page_size, record_count=nil)
+      raise(Error, "You cannot paginate a dataset that already has a limit") if @opts[:limit]
+      paginated = limit(page_size, (page_no - 1) * page_size)
+      paginated.extend(Pagination)
+      paginated.set_pagination_info(page_no, page_size, record_count || count)
+    end
+      
+    # Yields a paginated dataset for each page and returns the receiver. Does
+    # a count to find the total number of records for this dataset.
+    def each_page(page_size, &block)
+      raise(Error, "You cannot paginate a dataset that already has a limit") if @opts[:limit]
+      record_count = count
+      total_pages = (record_count / page_size.to_f).ceil
+      (1..total_pages).each{|page_no| yield paginate(page_no, page_size, record_count)}
+      self
+    end
+
+    # Holds methods that only relate to paginated datasets. Paginated dataset
+    # have pages starting at 1 (page 1 is offset 0, page 1 is offset page_size).
+    module Pagination
+      # The number of records per page (the final page may have fewer than
+      # this number of records).
+      attr_accessor :page_size
+
+      # The number of pages in the dataset before pagination, of which
+      # this paginated dataset is one.
+      attr_accessor :page_count
+
+      # The current page of the dataset, starting at 1 and not 0.
+      attr_accessor :current_page
+
+      # The total number of records in the dataset before pagination.
+      attr_accessor :pagination_record_count
+
+      # Returns the record range for the current page
+      def current_page_record_range
+        return (0..0) if @current_page > @page_count
+        
+        a = 1 + (@current_page - 1) * @page_size
+        b = a + @page_size - 1
+        b = @pagination_record_count if b > @pagination_record_count
+        a..b
+      end
+
+      # Returns the number of records in the current page
+      def current_page_record_count
+        return 0 if @current_page > @page_count
+        
+        a = 1 + (@current_page - 1) * @page_size
+        b = a + @page_size - 1
+        b = @pagination_record_count if b > @pagination_record_count
+        b - a + 1
+      end
+
+      # Returns true if the current page is the first page
+      def first_page?
+        @current_page == 1
+      end
+
+      # Returns true if the current page is the last page
+      def last_page?
+        @current_page == @page_count
+      end
+
+      # Returns the next page number or nil if the current page is the last page
+      def next_page
+        current_page < page_count ? (current_page + 1) : nil
+      end
+      
+      # Returns the page range
+      def page_range
+        1..page_count
+      end
+      
+      # Returns the previous page number or nil if the current page is the first
+      def prev_page
+        current_page > 1 ? (current_page - 1) : nil
+      end
+
+      # Sets the pagination info for this paginated dataset, and returns self.
+      def set_pagination_info(page_no, page_size, record_count)
+        @current_page = page_no
+        @page_size = page_size
+        @pagination_record_count = record_count
+        @page_count = (record_count / page_size.to_f).ceil
+        self
+      end
+    end
+  end
+end

data/lib/sequel_core/dataset/prepared_statements.rb

@@ -0,0 +1,220 @@
+module Sequel 
+  class Dataset
+    PREPARED_ARG_PLACEHOLDER = '?'.lit.freeze
+    
+    # Default implementation of the argument mapper to allow
+    # native database support for bind variables and prepared
+    # statements (as opposed to the emulated ones used by default).
+    module ArgumentMapper
+      SQL_QUERY_TYPE = Hash.new{|h,k| h[k] = k}
+      SQL_QUERY_TYPE[:first] = SQL_QUERY_TYPE[:all] = :select
+      
+      # The name of the prepared statement, if any.
+      attr_accessor :prepared_statement_name
+      
+      # The bind arguments to use for running this prepared statement
+      attr_accessor :bind_arguments
+      
+      # Set the bind arguments based on the hash and call super.
+      def call(hash, &block)
+        ds = clone
+        ds.prepared_sql
+        ds.bind_arguments = ds.map_to_prepared_args(hash)
+        ds.prepared_args = hash
+        ds.run(&block)
+      end
+        
+      # Override the given *_sql method based on the type, and
+      # cache the result of the sql.
+      def prepared_sql
+        return @prepared_sql if @prepared_sql
+        @prepared_args ||= []
+        @prepared_sql = super
+        meta_def("#{sql_query_type}_sql"){|*args| prepared_sql}
+        @prepared_sql
+      end
+      
+      private
+      
+      # The type of query (:select, :insert, :delete, :update).
+      def sql_query_type
+        SQL_QUERY_TYPE[@prepared_type]
+      end
+    end
+
+    # Backbone of the prepared statement support.  Grafts bind variable
+    # support into datasets by hijacking #literal and using placeholders.
+    # By default, emulates prepared statements and bind variables by
+    # taking the hash of bind variables and directly substituting them
+    # into the query, which works on all databases, as it is no different
+    # from using the dataset without bind variables.
+    module PreparedStatementMethods
+      PLACEHOLDER_RE = /\A\$(.*)\z/
+      
+      # The type of prepared statement, should be one of :select, :first,
+      # :insert, :update, or :delete
+      attr_accessor :prepared_type
+      
+      # The bind variable hash to use when substituting
+      attr_accessor :prepared_args
+      
+      # The argument to supply to insert and update, which may use
+      # placeholders specified by prepared_args
+      attr_accessor :prepared_modify_values
+      
+      # Sets the prepared_args to the given hash and runs the
+      # prepared statement.
+      def call(hash, &block)
+        ds = clone
+        ds.prepared_args = hash
+        ds.run(&block)
+      end
+      
+      # Returns the SQL for the prepared statement, depending on
+      # the type of the statement and the prepared_modify_values.
+      def prepared_sql
+        case @prepared_type
+        when :select, :all
+          select_sql
+        when :first
+          select_sql(:limit=>1)
+        when :insert
+          insert_sql(@prepared_modify_values)
+        when :update
+          update_sql(@prepared_modify_values)
+        when :delete
+          delete_sql
+        end
+      end
+      
+      # Changes the values of symbols if they start with $ and
+      # prepared_args is present.  If so, they are considered placeholders,
+      # and they are substituted using prepared_arg.
+      def literal(v)
+        case v
+        when Symbol
+          if match = PLACEHOLDER_RE.match(v.to_s) and @prepared_args
+            super(prepared_arg(match[1].to_sym))
+          else
+            super
+          end
+        else
+          super
+        end
+      end
+      
+      # Programmer friendly string showing this is a prepared statement,
+      # with the prepared SQL it represents (which in general won't have
+      # substituted variables).
+      def inspect
+        "<#{self.class.name}/PreparedStatement #{prepared_sql.inspect}>"
+      end
+      
+      protected
+      
+      # Run the method based on the type of prepared statement, with
+      # :select running #all to get all of the rows, and the other
+      # types running the method with the same name as the type.
+      def run(&block)
+        case @prepared_type
+        when :select, :all
+          all(&block)
+        when :first
+          first
+        when :insert
+          insert(@prepared_modify_values)
+        when :update
+          update(@prepared_modify_values)
+        when :delete
+          delete
+        end
+      end
+      
+      private
+      
+      # Returns the value of the prepared_args hash for the given key.
+      def prepared_arg(k)
+        @prepared_args[k]
+      end
+
+      # Use a clone of the dataset extended with prepared statement
+      # support and using the same argument hash so that you can use
+      # bind variables/prepared arguments in subselects.
+      def subselect_sql(ds)
+        ps = ds.prepare(:select)
+        ps.prepared_args = prepared_args
+        ps.prepared_sql
+      end
+    end
+    
+    # Default implementation for an argument mapper that uses
+    # unnumbered SQL placeholder arguments.  Keeps track of which
+    # arguments have been used, and allows arguments to
+    # be used more than once.
+    module UnnumberedArgumentMapper
+      include ArgumentMapper
+      
+      protected
+      
+      # Returns a single output array mapping the values of the input hash.
+      # Keys in the input hash that are used more than once in the query
+      # have multiple entries in the output array.
+      def map_to_prepared_args(hash)
+        @prepared_args.map{|v| hash[v]}
+      end
+      
+      private
+      
+      # Associates the argument with name k with the next position in
+      # the output array.
+      def prepared_arg(k)
+        @prepared_args << k
+        prepared_arg_placeholder
+      end
+    end
+    
+    # For the given type (:select, :insert, :update, or :delete),
+    # run the sql with the bind variables
+    # specified in the hash.  values is a hash of passed to
+    # insert or update (if one of those types is used),
+    # which may contain placeholders.
+    def call(type, bind_variables={}, values=nil)
+      prepare(type, nil, values).call(bind_variables)
+    end
+    
+    # Prepare an SQL statement for later execution. This returns
+    # a clone of the dataset extended with PreparedStatementMethods,
+    # on which you can call call with the hash of bind variables to
+    # do substitution.  The prepared statement is also stored in
+    # the associated database.  The following usage is identical:
+    #
+    #   ps = prepare(:select, :select_by_name)
+    #   ps.call(:name=>'Blah')
+    #   db.call(:select_by_name, :name=>'Blah')
+    def prepare(type, name=nil, values=nil)
+      ps = to_prepared_statement(type, values)
+      db.prepared_statements[name] = ps if name
+      ps
+    end
+    
+    protected
+    
+    # Return a cloned copy of the current dataset extended with
+    # PreparedStatementMethods, setting the type and modify values.
+    def to_prepared_statement(type, values=nil)
+      ps = clone
+      ps.extend(PreparedStatementMethods)
+      ps.prepared_type = type
+      ps.prepared_modify_values = values
+      ps
+    end
+
+    private
+    
+    # The argument placeholder.  Most databases used unnumbered
+    # arguments with question marks, so that is the default.
+    def prepared_arg_placeholder
+      PREPARED_ARG_PLACEHOLDER
+    end
+  end
+end

data/lib/sequel_core/dataset/query.rb

@@ -0,0 +1,41 @@
+module Sequel
+  class Dataset
+    # Translates a query block into a dataset. Query blocks can be useful
+    # when expressing complex SELECT statements, e.g.:
+    #
+    #   dataset = DB[:items].query do
+    #     select :x, :y, :z
+    #     filter{|o| (o.x > 1) & (o.y > 2)}
+    #     order :z.desc
+    #   end
+    #
+    # Which is the same as:
+    #
+    #  dataset = DB[:items].select(:x, :y, :z).filter{|o| (o.x > 1) & (o.y > 2)}.order(:z.desc)
+    #
+    # Note that inside a call to query, you cannot call each, insert, update,
+    # or delete (or any method that calls those), or Sequel will raise an
+    # error.
+    def query(&block)
+      copy = clone({})
+      copy.extend(QueryBlockCopy)
+      copy.instance_eval(&block)
+      clone(copy.opts)
+    end
+
+    # Module used by Dataset#query that has the effect of making all
+    # dataset methods into !-style methods that modify the receiver.
+    module QueryBlockCopy
+      %w'each insert update delete'.each do |meth|
+        define_method(meth){|*args| raise Error, "##{meth} cannot be invoked inside a query block."}
+      end
+
+      # Merge the given options into the receiver's options and return the receiver
+      # instead of cloning the receiver.
+      def clone(opts = nil)
+        @opts.merge!(opts)
+        self
+      end
+    end
+  end
+end

data/lib/sequel_core/dataset/schema.rb

@@ -0,0 +1,15 @@
+module Sequel
+  class Dataset
+    # Creates a view in the database with the given named based
+    # on the current dataset.
+    def create_view(name)
+      @db.create_view(name, self)
+    end
+
+    # Creates or replaces a view in the database with the given
+    # named based on the current dataset.
+    def create_or_replace_view(name)
+      @db.create_or_replace_view(name, self)
+    end
+  end
+end