sequel 2.3.0 → 2.4.0

data/lib/sequel_core/adapters/shared/mssql.rb

@@ -0,0 +1,106 @@
+module Sequel
+  module MSSQL
+    module DatabaseMethods
+      AUTO_INCREMENT = 'IDENTITY(1,1)'.freeze
+      
+      def auto_increment_sql
+        AUTO_INCREMENT
+      end
+      
+      def dataset(opts = nil)
+        ds = super
+        ds.extend(DatasetMethods)
+        ds
+      end
+    end
+  
+    module DatasetMethods
+      def complex_expression_sql(op, args)
+        case op
+        when :'||'
+          super(:+, args)
+        else
+          super(op, args)
+        end
+      end
+      
+      def full_text_search(cols, terms, opts = {})
+        filter("CONTAINS (#{literal(cols)}, #{literal(terms)})")
+      end
+      
+      # Allows you to do .nolock on a query
+      def nolock
+        clone(:with => "(NOLOCK)")
+      end
+
+      # Formats a SELECT statement using the given options and the dataset
+      # options.
+      def select_sql(opts = nil)
+        opts = opts ? @opts.merge(opts) : @opts
+
+        if sql = opts[:sql]
+          return sql
+        end
+
+        # ADD TOP to SELECT string for LIMITS
+        if limit = opts[:limit]
+          top = "TOP #{limit} "
+          raise Error, "Offset not supported" if opts[:offset]
+        end
+
+        columns = opts[:select]
+        # We had to reference const WILDCARD with its full path, because
+        # the Ruby constant scope rules played against us (it was resolving it
+        # as Sequel::Dataset::DatasetMethods::WILDCARD).
+        select_columns = columns ? column_list(columns) : Sequel::Dataset::WILDCARD
+
+        if distinct = opts[:distinct]
+          distinct_clause = distinct.empty? ? "DISTINCT" : "DISTINCT ON (#{expression_list(distinct)})"
+          sql = "SELECT #{top}#{distinct_clause} #{select_columns}"
+        else
+          sql = "SELECT #{top}#{select_columns}"
+        end
+
+        if opts[:from]
+          sql << " FROM #{source_list(opts[:from])}"
+        end
+
+        # ADD WITH to SELECT string for NOLOCK
+        if with = opts[:with]
+          sql << " WITH #{with}"
+        end
+
+        if join = opts[:join]
+          join.each{|j| sql << literal(j)}
+        end
+
+        if where = opts[:where]
+          sql << " WHERE #{literal(where)}"
+        end
+
+        if group = opts[:group]
+          sql << " GROUP BY #{expression_list(group)}"
+        end
+
+        if order = opts[:order]
+          sql << " ORDER BY #{expression_list(order)}"
+        end
+
+        if having = opts[:having]
+          sql << " HAVING #{literal(having)}"
+        end
+
+        if union = opts[:union]
+          sql << (opts[:union_all] ? \
+            " UNION ALL #{union.sql}" : " UNION #{union.sql}")
+        end
+        
+        raise Error, "Intersect not supported" if opts[:intersect]
+        raise Error, "Except not supported" if opts[:except]
+        
+        sql
+      end
+      alias_method :sql, :select_sql
+    end
+  end
+end

data/lib/sequel_core/adapters/shared/mysql.rb

@@ -1,5 +1,7 @@
 module Sequel
   module MySQL
+    # Methods shared by Database instances that connect to MySQL,
+    # currently supported by the native and JDBC adapters.
     module DatabaseMethods
       AUTO_INCREMENT = 'AUTO_INCREMENT'.freeze
       NOT_NULL = Sequel::Schema::SQL::NOT_NULL
@@ -12,6 +14,8 @@ module Sequel
       UNIQUE = Sequel::Schema::SQL::UNIQUE
       UNSIGNED = Sequel::Schema::SQL::UNSIGNED
       
+      # Use MySQL specific syntax for rename column, set column type, and
+      # drop index cases.
       def alter_table_sql(table, op)
         type = type_literal(op[:type])
         type << '(255)' if type == 'varchar'
@@ -27,10 +31,12 @@ module Sequel
         end
       end
       
+      # Use MySQL specific AUTO_INCREMENT text.
       def auto_increment_sql
         AUTO_INCREMENT
       end
       
+      # Handle MySQL specific column syntax (not sure why).
       def column_definition_sql(column)
         if column[:type] == :check
           return constraint_definition_sql(column)
@@ -53,7 +59,8 @@ module Sequel
         end
         sql
       end
-
+      
+      # Handle MySQL specific index SQL syntax
       def index_definition_sql(table_name, index)
         index_name = index[:name] || default_index_name(table_name, index[:columns])
         unique = "UNIQUE " if index[:unique]
@@ -69,16 +76,14 @@ module Sequel
         end
       end
       
-      def serial_primary_key_options
-        {:primary_key => true, :type => :integer, :auto_increment => true}
-      end
-      
+      # Get version of MySQL server, used for determined capabilities.
       def server_version
         m = /(\d+)\.(\d+)\.(\d+)/.match(get(:version[]))
         @server_version ||= (m[1].to_i * 10000) + (m[2].to_i * 100) + m[3].to_i
       end
       
-      # Changes the database in use by issuing a USE statement.
+      # Changes the database in use by issuing a USE statement.  I would be
+      # very careful if I used this.
       def use(db_name)
         disconnect
         @opts[:database] = db_name if self << "USE #{db_name}"
@@ -88,12 +93,17 @@ module Sequel
       
       private
       
+      # Always quote identifiers for the schema parser dataset.
       def schema_ds_dataset
         ds = schema_utility_dataset.clone
         ds.quote_identifiers = true
         ds
       end
       
+      # Allow other database schema's to be queried using the :database
+      # option.  Allow all database's schema to be used by setting
+      # the :database option to nil.  If the database option is not specified,
+      # uses the currently connected database.
       def schema_ds_filter(table_name, opts)
         filt = super
         # Restrict it to the given or current database, unless specifically requesting :database = nil
@@ -101,16 +111,20 @@ module Sequel
         filt
       end
 
+      # MySQL doesn't support table catalogs, so just join on schema and table name.
       def schema_ds_join(table_name, opts)
         [:information_schema__columns, {:table_schema => :table_schema, :table_name => :table_name}, :c]
       end
     end
   
+    # Dataset methods shared by datasets that use MySQL databases.
     module DatasetMethods
       BOOL_TRUE = '1'.freeze
       BOOL_FALSE = '0'.freeze
       COMMA_SEPARATOR = ', '.freeze
       
+      # MySQL specific syntax for LIKE/REGEXP searches, as well as
+      # string concatenation.
       def complex_expression_sql(op, args)
         case op
         when :~, :'!~', :'~*', :'!~*', :LIKE, :'NOT LIKE', :ILIKE, :'NOT ILIKE'
@@ -141,6 +155,7 @@ module Sequel
         sql
       end
 
+      # MySQL specific full text search syntax.
       def full_text_search(cols, terms, opts = {})
         mode = opts[:boolean] ? " IN BOOLEAN MODE" : ""
         s = if Array === terms
@@ -160,34 +175,22 @@ module Sequel
         @opts[:having] = {}
         x = filter(*cond, &block)
       end
-
+      
+      # MySQL doesn't use the SQL standard DEFAULT VALUES.
       def insert_default_values_sql
         "INSERT INTO #{source_list(@opts[:from])} () VALUES ()"
       end
 
-      # Returns a join clause based on the specified join type
-      # and condition.  MySQL's NATURAL join is 'semantically
-      # equivalent to a JOIN with a USING clause that names all
-      # columns that exist in both tables.  The constraint
-      # expression may be nil, so join expression can accept two
-      # arguments.
-      #
-      # === Note
-      # Full outer joins (:full_outer) are not implemented in
-      # MySQL (as of v6.0), nor is there currently a work around
-      # implementation in Sequel.  Straight joins with 'ON
-      # <condition>' are not yet implemented.
-      #
-      # === Example
-      #   @ds = MYSQL_DB[:nodes]
-      #   @ds.join_table(:natural_left_outer, :nodes)
-      #   # join SQL is 'NATURAL LEFT OUTER JOIN nodes'
+      # Transforms an CROSS JOIN to an INNER JOIN if the expr is not nil.
+      # Raises an error on use of :full_outer type, since MySQL doesn't support it.
       def join_table(type, table, expr=nil, table_alias=nil)
         type = :inner if (type == :cross) && !expr.nil?
-        raise(Sequel::Error::InvalidJoinType, "MySQL doesn't support FULL OUTER JOIN") if type == :full_outer
+        raise(Sequel::Error, "MySQL doesn't support FULL OUTER JOIN") if type == :full_outer
         super(type, table, expr, table_alias)
       end
       
+      # Transforms :natural_inner to NATURAL LEFT JOIN and straight to
+      # STRAIGHT_JOIN.
       def join_type_sql(join_type)
         case join_type
         when :straight then 'STRAIGHT_JOIN'
@@ -195,7 +198,8 @@ module Sequel
         else super
         end
       end
-
+      
+      # Override the default boolean values.
       def literal(v)
         case v
         when true
@@ -207,16 +211,20 @@ module Sequel
         end
       end
       
+      # MySQL specific syntax for inserting multiple values at once.
       def multi_insert_sql(columns, values)
         columns = column_list(columns)
         values = values.map {|r| literal(Array(r))}.join(COMMA_SEPARATOR)
         ["INSERT INTO #{source_list(@opts[:from])} (#{columns}) VALUES #{values}"]
       end
       
+      # MySQL uses the nonstandard ` (backtick) for quoting identifiers.
       def quoted_identifier(c)
         "`#{c}`"
       end
       
+      # MySQL specific syntax for REPLACE (aka UPSERT, or update if exists,
+      # insert if it doesn't).
       def replace_sql(*values)
         from = source_list(@opts[:from])
         if values.empty?

data/lib/sequel_core/adapters/shared/postgres.rb

@@ -1,7 +1,10 @@
 module Sequel
   module Postgres
+    # Array of exceptions that need to be converted.  JDBC
+    # uses NativeExceptions, the native adapter uses PGError.
     CONVERTED_EXCEPTIONS = []
-  
+    
+    # Methods shared by adapter/connection instances.
     module AdapterMethods
       SELECT_CURRVAL = "SELECT currval('%s')".freeze
       SELECT_PK = <<-end_sql
@@ -45,8 +48,11 @@ module Sequel
           AND dep.refobjid = '%s'::regclass
       end_sql
       
+      # Depth of the current transaction on this connection, used
+      # to implement multi-level transactions with savepoints.
       attr_accessor :transaction_depth
       
+      # Get the last inserted value for the given table.
       def last_insert_id(table)
         @table_sequences ||= {}
         if !@table_sequences.include?(table)
@@ -63,6 +69,7 @@ module Sequel
         end
       end
       
+      # Get the primary key and sequence for the given table.
       def pkey_and_sequence(table)
         execute(SELECT_PK_AND_SERIAL_SEQUENCE % table) do |r|
           vals = result_set_values(r, 2, 2)
@@ -74,14 +81,17 @@ module Sequel
         end
       end
       
+      # Get the primary key for the given table.
       def primary_key(table)
         execute(SELECT_PK % table) do |r|
           result_set_values(r, 0)
         end
       end
     end
-
+    
+    # Methods shared by Database instances that connect to PostgreSQL.
     module DatabaseMethods
+      PREPARED_ARG_PLACEHOLDER = '$'.lit.freeze
       RE_CURRVAL_ERROR = /currval of sequence "(.*)" is not yet defined in this session/.freeze
       RELATION_QUERY = {:from => [:pg_class], :select => [:relname]}.freeze
       RELATION_FILTER = "(relkind = 'r') AND (relname !~ '^pg|sql')".freeze
@@ -93,23 +103,12 @@ module Sequel
       SQL_RELEASE_SAVEPOINT = 'RELEASE SAVEPOINT autopoint_%d'.freeze
       SYSTEM_TABLE_REGEXP = /^pg|sql/.freeze
       
+      # Always CASCADE the table drop
       def drop_table_sql(name)
         "DROP TABLE #{name} CASCADE"
       end
       
-      def execute_insert(sql, table, values)
-        begin 
-          log_info(sql)
-          @pool.hold do |conn|
-            conn.execute(sql)
-            insert_result(conn, table, values)
-          end
-        rescue => e
-          log_info(e.message)
-          raise convert_pgerror(e)
-        end
-      end
-      
+      # PostgreSQL specific index SQL.
       def index_definition_sql(table_name, index)
         index_name = index[:name] || default_index_name(table_name, index[:columns])
         expr = literal(Array(index[:columns]))
@@ -129,6 +128,11 @@ module Sequel
         "CREATE #{unique}INDEX #{index_name} ON #{table_name} #{"USING #{index_type} " if index_type}#{expr}#{filter}"
       end
       
+      # The result of the insert for the given table and values.  Uses
+      # last insert id the primary key for the table if it exists,
+      # otherwise determines the primary key for the table and uses the
+      # value of the hash key.  If values is an array, assume the first
+      # value is the primary key value and return that.
       def insert_result(conn, table, values)
         begin
           result = conn.last_insert_id(table)
@@ -147,24 +151,31 @@ module Sequel
         end
       end
       
+      # Dataset containing all current database locks 
       def locks
-        dataset.from("pg_class, pg_locks").
-          select("pg_class.relname, pg_locks.*").
-          filter("pg_class.relfilenode=pg_locks.relation")
+        dataset.from(:pg_class, :pg_locks).
+          select(:pg_class__relname, :pg_locks.*).
+          filter(:pg_class__relfilenode=>:pg_locks__relation)
       end
-    
+      
+      # Returns primary key for the given table.  This information is
+      # cached, and if the primary key for a table is changed, the
+      # @primary_keys instance variable should be reset manually.
       def primary_key_for_table(conn, table)
         @primary_keys ||= {}
         @primary_keys[table] ||= conn.primary_key(table)
       end
       
+      # PostgreSQL uses SERIAL psuedo-type instead of AUTOINCREMENT for
+      # managing incrementing primary keys.
       def serial_primary_key_options
         {:primary_key => true, :type => :serial}
       end
       
-      def server_version
+      # The version of the PostgreSQL server, used for determining capability.
+      def server_version(server=nil)
         return @server_version if @server_version
-        @server_version = pool.hold do |conn|
+        @server_version = synchronize(server) do |conn|
           (conn.server_version rescue nil) if conn.respond_to?(:server_version)
         end
         unless @server_version
@@ -174,12 +185,14 @@ module Sequel
         @server_version
       end
       
+      # Array of symbols specifying table names in the current database.
       def tables
-        dataset(RELATION_QUERY).filter(RELATION_FILTER).map {|r| r[:relname].to_sym}
+        dataset(RELATION_QUERY).filter(RELATION_FILTER).map{|r| r[:relname].to_sym}
       end
       
-      def transaction
-        @pool.hold do |conn|
+      # PostgreSQL supports multi-level transactions using save points.
+      def transaction(server=nil)
+        synchronize(server) do |conn|
           conn.transaction_depth = 0 if conn.transaction_depth.nil?
           if conn.transaction_depth > 0
             log_info(SQL_SAVEPOINT % conn.transaction_depth)
@@ -222,10 +235,20 @@ module Sequel
 
       private
       
+      # Convert the exception to a Sequel::Error if it is in CONVERTED_EXCEPTIONS.
       def convert_pgerror(e)
         e.is_one_of?(*CONVERTED_EXCEPTIONS) ? Error.new(e.message) : e
       end
-
+      
+      # Use a dollar sign instead of question mark for the argument
+      # placeholder.
+      def prepared_arg_placeholder
+        PREPARED_ARG_PLACEHOLDER
+      end
+      
+      # When the :schema option is used, use the the given schema.
+      # When the :schema option is nil, return results for all schemas.
+      # If the :schema option is not used, use the public schema.
       def schema_ds_filter(table_name, opts)
         filt = super
         # Restrict it to the given or public schema, unless specifically requesting :schema = nil
@@ -233,7 +256,8 @@ module Sequel
         filt
       end
     end
-  
+    
+    # Instance methods for datasets that connect to a PostgreSQL database.
     module DatasetMethods
       ACCESS_SHARE = 'ACCESS SHARE'.freeze
       ACCESS_EXCLUSIVE = 'ACCESS EXCLUSIVE'.freeze
@@ -253,7 +277,8 @@ module Sequel
       SHARE = 'SHARE'.freeze
       SHARE_ROW_EXCLUSIVE = 'SHARE ROW EXCLUSIVE'.freeze
       SHARE_UPDATE_EXCLUSIVE = 'SHARE UPDATE EXCLUSIVE'.freeze
-
+      
+      # Return the results of an ANALYZE query as a string
       def analyze(opts = nil)
         analysis = []
         fetch_rows(EXPLAIN_ANALYZE + select_sql(opts)) do |r|
@@ -262,6 +287,7 @@ module Sequel
         analysis.join("\r\n")
       end
       
+      # Return the results of an EXPLAIN query as a string
       def explain(opts = nil)
         analysis = []
         fetch_rows(EXPLAIN + select_sql(opts)) do |r|
@@ -270,14 +296,18 @@ module Sequel
         analysis.join("\r\n")
       end
       
+      # Return a cloned dataset with a :share lock type.
       def for_share
         clone(:lock => :share)
       end
-    
+      
+      # Return a cloned dataset with a :update lock type.
       def for_update
         clone(:lock => :update)
       end
-
+      
+      # PostgreSQL specific full text search syntax, using tsearch2 (included
+      # in 8.3 by default, and available for earlier versions as an add-on).
       def full_text_search(cols, terms, opts = {})
         lang = opts[:language] ? "#{literal(opts[:language])}, " : ""
         cols = cols.is_a?(Array) ? cols.map {|c| literal(c)}.join(" || ") : literal(cols)
@@ -285,11 +315,14 @@ module Sequel
         filter("to_tsvector(#{lang}#{cols}) @@ to_tsquery(#{lang}#{terms})")
       end
       
+      # Insert given values into the database.
       def insert(*values)
-        @db.execute_insert(insert_sql(*values), source_list(@opts[:from]),
-          values.size == 1 ? values.first : values)
+        execute_insert(insert_sql(*values), :table=>source_list(@opts[:from]),
+          :values=>values.size == 1 ? values.first : values)
       end
-
+      
+      # Handle microseconds for Time and DateTime values, as well as PostgreSQL
+      # specific boolean values and string escaping.
       def literal(v)
         case v
         when LiteralString
@@ -310,18 +343,19 @@ module Sequel
       end
       
       # Locks the table with the specified mode.
-      def lock(mode, &block)
+      def lock(mode, server=nil)
         sql = LOCK % [source_list(@opts[:from]), mode]
-        @db.synchronize do
-          if block # perform locking inside a transaction and yield to block
-            @db.transaction {@db.execute(sql); yield}
+        @db.synchronize(server) do
+          if block_given? # perform locking inside a transaction and yield to block
+            @db.transaction(server){@db.execute(sql, :server=>server); yield}
           else
-            @db.execute(sql) # lock without a transaction
+            @db.execute(sql, :server=>server) # lock without a transaction
             self
           end
         end
       end
       
+      # For PostgreSQL version > 8.2, allow inserting multiple rows at once.
       def multi_insert_sql(columns, values)
         return super if @db.server_version < 80200
         
@@ -331,10 +365,13 @@ module Sequel
         ["INSERT INTO #{source_list(@opts[:from])} (#{columns}) VALUES #{values}"]
       end
       
+      # PostgreSQL assumes unquoted identifiers are lower case by default,
+      # so do not upcase the identifier when quoting it.
       def quoted_identifier(c)
         "\"#{c}\""
       end
-    
+      
+      # Support lock mode, allowing FOR SHARE and FOR UPDATE queries.
       def select_sql(opts = nil)
         row_lock_mode = opts ? opts[:lock] : @opts[:lock]
         sql = super
@@ -346,6 +383,13 @@ module Sequel
         end
         sql
       end
+      
+      private
+      
+      # Call execute_insert on the database object with the given values.
+      def execute_insert(sql, opts={})
+        @db.execute_insert(sql, {:server=>@opts[:server] || :default}.merge(opts))
+      end
     end
   end
 end