sequel 4.11.0 → 4.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ced6249de982434d96b02340853663f604357771
-  data.tar.gz: 2f34bc5dff2cb2e0ffa1c613252291a52a0b5876
+  metadata.gz: b15d571f0ccc175749541cfee443b953dcd145fd
+  data.tar.gz: 9dec9dd2f6816432f511c0153737646e44da31a1
 SHA512:
-  metadata.gz: 8df573b48f64deb1af7958cdf2d09e75a5f8adb2709519e04f51cabc2b18f7b08e3da857261b0faec876e476b1a3bd961517f82d79bfb33ee9a236dfc066d899
-  data.tar.gz: becb87b9aecc164e06e48a4b5f86eb983ad9e3d09851155f50c935f0e17bccd26d57987dfdcc4635c4531d1cc07a1e753a20998b55c6fa9921e89c58310bc3dd
+  metadata.gz: ec94d8b6fcd34fecdb4d4c3cc4f2b4fb0277c8d7289baebde098b8b84cc99ab0bfd0ab28effa316df0a0fbba1a7bf2cc3bc0fbbfc682e68f6d50326652719306
+  data.tar.gz: 919e8651ded7808d66e95788af7993c4b13136487bed14b6e12db2150bca22ab166eef6e0eeb5350b2e2aebdb6f72c36f47ef7dfaef4e3eea2170c396f15f02c

data/CHANGELOG

@@ -1,3 +1,35 @@
+=== 4.12.0 (2014-07-01)
+
+* Support :readonly Database option in sqlite adapter (ippeiukai, jeremyevans) (#832)
+
+* Automatically setup max_length validations for string columns in the auto_validations plugin (jeremyevans)
+
+* Add :max_length entry to column schema hashes for string types (jeremyevans)
+
+* Add :before_thread_exit option to Database#listen_for_static_cache_updates in pg_static_cache_updater extension (jeremyevans)
+
+* Add Database#values on PostgreSQL to create a dataset that uses VALUES instead of SELECT (jeremyevans)
+
+* Add Model#set_nested_attributes to nested_attributes, allowing setting nested attributes options per-call (jeremyevans)
+
+* Use explicit columns when using automatically prepared SELECT statements in the prepared statement plugins (jeremyevans)
+
+* Make Dataset#insert_select on PostgreSQL respect existing RETURNING clause (jeremyevans)
+
+* Fix eager loading limited associations via a UNION when an association block is used (jeremyevans)
+
+* Associate reciprocal object before saving associated object when creating new objects in nested_attributes (chanks, jeremyevans) (#831)
+
+* Handle intervals containing more than 100 hours in the pg_interval extension's parser (will) (#827)
+
+* Remove methods/class deprecated in 4.11.0 (jeremyevans)
+
+* Allow Dataset#natural_join/cross_join and related methods to take a options hash passed to join_table (jeremyevans)
+
+* Add :reset_implicit_qualifier option to Dataset#join_table, to set false to not reset the implicit qualifier (jeremyevans)
+
+* Support :notice_receiver Database option when postgres adapter is used with pg driver (jeltz, jeremyevans) (#825)
+
 === 4.11.0 (2014-06-03)
 
 * Add :model_map option to class_table_inheritance plugin so class names don't need to be stored in the database (jeremyevans)

data/Rakefile

@@ -33,10 +33,6 @@ RDOC_DEFAULT_OPTS = ["--line-numbers", "--inline-source", '--title', 'Sequel: Th
 
 begin
   # Sequel uses hanna-nouveau for the website RDoc.
-  # Due to bugs in older versions of RDoc, and the
-  # fact that hanna-nouveau does not support RDoc 4,
-  # a specific version of rdoc is required.
-  gem 'rdoc', '= 3.12.2'
   gem 'hanna-nouveau'
   RDOC_DEFAULT_OPTS.concat(['-f', 'hanna'])
 rescue Gem::LoadError
@@ -68,7 +64,7 @@ if rdoc_task_class
   rdoc_task_class.new(:website_rdoc_main) do |rdoc|
     rdoc.rdoc_dir = "www/public/rdoc"
     rdoc.options += RDOC_OPTS + %w'--no-ignore-invalid'
-    rdoc.rdoc_files.add %w"README.rdoc CHANGELOG MIT-LICENSE lib/*.rb lib/sequel/*.rb lib/sequel/{connection_pool,dataset,database,model}/*.rb doc/*.rdoc doc/release_notes/*.txt lib/sequel/extensions/migration.rb lib/sequel/extensions/core_extensions.rb"
+    rdoc.rdoc_files.add %w"README.rdoc CHANGELOG MIT-LICENSE lib/*.rb lib/sequel/*.rb lib/sequel/{connection_pool,dataset,database,model}/*.rb doc/*.rdoc doc/release_notes/*.txt lib/sequel/extensions/migration.rb"
   end
 
   rdoc_task_class.new(:website_rdoc_adapters) do |rdoc|

data/doc/opening_databases.rdoc

@@ -373,9 +373,12 @@ The following additional options are supported:
                                 conversion is done, so an error is raised if you attempt to retrieve an infinite
                                 timestamp/date.  You can set this to :nil to convert to nil, :string to leave
                                 as a string, or :float to convert to an infinite float.
-:encoding :: Set the client_encoding to the given string
 :connect_timeout :: Set the number of seconds to wait for a connection (default 20, only respected
                     if using the pg library).
+:encoding :: Set the client_encoding to the given string
+:notice_receiver :: A proc that be called with the PGresult objects that have notice or warning messages.
+                    The default notice receiver just prints the messages to stderr, but this can be used
+                    to handle notice/warning messages differently.  Only respected if using the pg library).
 :sslmode :: Set to 'disable', 'allow', 'prefer', 'require' to choose how to treat SSL (only
             respected if using the pg library)
 :use_iso_date_format :: This can be set to false to not force the ISO date format.  Sequel forces
@@ -417,6 +420,7 @@ Examples:
 
 The following additional options are supported:
 
+:readonly :: open database in read-only mode
 :timeout :: the busy timeout to use in milliseconds (default: 5000).
 
 === swift

data/doc/release_notes/4.12.0.txt

@@ -0,0 +1,105 @@
+= New Features
+
+* Database#schema now includes :max_length entries for string
+  columns, specifying the size of the string field.  The
+  auto_validations plugin now uses this information to
+  automatically set up max_length validations on those fields.
+
+* The Dataset join methods now support a :reset_implicit_qualifier
+  option.  If set to false, this makes the join not reset the
+  implicit qualifier, so that the next join will not consider this
+  table as the last table joined.  Example:
+
+    DB[:a].join(:b, :c=>:d).
+      join(:e, :f=>:g)
+    # SELECT * FROM a
+    # INNER JOIN b ON (b.c = a.d)
+    # INNER JOIN e ON (e.f = b.g)
+
+    DB[:a].join(:b, {:c=>:d}, :reset_implicit_qualifier=>false).
+      join(:e, :f=>:g)
+    # SELECT * FROM a
+    # INNER JOIN b ON (b.c = a.d)
+    # INNER JOIN e ON (e.f = a.g)
+
+* The Dataset cross and natural join methods now accept an options
+  hash. Example:
+
+    DB[:a].cross_join(:b, :table_alias=>:c)
+    # SELECT * FROM a CROSS JOIN b AS c
+
+* Model#set_nested_attributes has been added to the nested_attributes
+  plugin, which allows you to to set the nested_attributes options to
+  use per-call.  This is very helpful if you have multiple forms that
+  handle associated objects, but with different input fields used
+  for the associated objects depending on the form.  Example:
+
+    album.set_nested_attributes(:tracks,
+      params[:track_attributes],
+      :fields=>[:a, :b, :c])
+
+* Database#values has been added on PostgreSQL, which creates a
+  dataset that uses VALUES instead of SELECT.  Just as PostgreSQL
+  allows, you can also use orders, limits, and offsets with this
+  dataset.
+
+* A :notice_receiver option is now supported in the postgres adapter
+  if the pg driver is used.  This should be a proc, which will be
+  passed to the pg connection's set_notice_receiver method.
+
+* A Database :readonly option is now supported in the sqlite adapter,
+  which opens the database in a read-only mode, causing an error
+  if a query is issued that would modify the database.
+
+* A :before_thread_exit option has been added to
+  Database#listen_for_static_cache_updates in the
+  pg_static_cache_updater extension, allowing you to run code before
+  the created thread exits.
+
+= Other Improvements
+
+* Eager loading limited associations using a UNION now works
+  correctly when an association block is used.  This fixes a
+  regression that first occurred in 4.10.0, when the union
+  eager loader became the default eager loader.
+
+* When creating a new associated object in the nested_attributes
+  plugin, where the reciprocal association is a many_to_one
+  association, set the cached reciprocal object in the new
+  associated object before saving it.
+
+  This fixes issues when validations in the associated object
+  require access to the current object, which may not yet be
+  saved in the database.
+
+* The prepared_statements and prepared_statements_associations
+  plugins now automatically use explicit column references when
+  preparing statements.  This fixes issues on PostgreSQL when a
+  column is added to a table while a prepared statement exists
+  that selects * from the table.  Previously, all further attempts
+  to use the prepared statement will fail.
+
+  This allows you to run migrations that add columns to tables
+  while concurrently running an application that uses the
+  prepared statements plugins.  Note that many other schema
+  modifications can cause issues when running migrations
+  while concurrently running an application, but most of those
+  are not specific to usage of prepared statements.
+
+* Dataset#insert_select on PostgreSQL now respects an existing
+  RETURNING clause, and won't override it to use RETURNING *.
+
+  A similar fix was applied to the generalized prepared statements
+  support as well.
+
+* The interval parser in the pg_interval extension now supports
+  intervals with 2-10 digits for hours.  Previously, it only
+  supported using 2 digits for hours.
+
+= Backwards Compatibility
+
+* The methods and classes deprecated in 4.11.0 have been removed.
+
+* The nested_attributes internal API has changed significantly. If
+  you were calling any private nested_attributes methods, you'll
+  probably need to update your code.

data/lib/sequel/adapters/jdbc.rb

@@ -729,6 +729,7 @@ module Sequel
         metadata(:getColumns, nil, schema, table, nil) do |h|
           next if schema_parse_table_skip?(h, schema)
           s = {:type=>schema_column_type(h[:type_name]), :db_type=>h[:type_name], :default=>(h[:column_def] == '' ? nil : h[:column_def]), :allow_null=>(h[:nullable] != 0), :primary_key=>pks.include?(h[:column_name]), :column_size=>h[:column_size], :scale=>h[:decimal_digits]}
+          s[:max_length] = s[:column_size] if s[:type] == :string
           if s[:db_type] =~ DECIMAL_TYPE_RE && s[:scale] == 0
             s[:type] = :integer
           end

data/lib/sequel/adapters/oracle.rb

@@ -305,6 +305,7 @@ module Sequel
               :allow_null => column.nullable?
           }
           h[:type] = oracle_column_type(h)
+          h[:max_length] = h[:char_size] if h[:type] == :string
           table_schema << [m.call(column.name), h]
         end
         table_schema

data/lib/sequel/adapters/postgres.rb

@@ -198,12 +198,13 @@ module Sequel
       # Connects to the database.  In addition to the standard database
       # options, using the :encoding or :charset option changes the
       # client encoding for the connection, :connect_timeout is a
-      # connection timeout in seconds, and :sslmode sets whether postgres's
-      # sslmode.  :connect_timeout and :ssl_mode are only supported if the pg
-      # driver is used.
+      # connection timeout in seconds, :sslmode sets whether postgres's
+      # sslmode, and :notice_receiver handles server notices in a proc.
+      # :connect_timeout, :ssl_mode, and :notice_receiver are only supported
+      # if the pg driver is used.
       def connect(server)
         opts = server_opts(server)
-        conn = if SEQUEL_POSTGRES_USES_PG
+        if SEQUEL_POSTGRES_USES_PG
           connection_params = {
             :host => opts[:host],
             :port => opts[:port] || 5432,
@@ -213,9 +214,15 @@ module Sequel
             :connect_timeout => opts[:connect_timeout] || 20,
             :sslmode => opts[:sslmode]
           }.delete_if { |key, value| blank_object?(value) }
-          Adapter.connect(connection_params)
+          conn = Adapter.connect(connection_params)
+
+          conn.instance_variable_set(:@prepared_statements, {})
+
+          if receiver = opts[:notice_receiver]
+            conn.set_notice_receiver(&receiver)
+          end
         else
-          Adapter.connect(
+          conn = Adapter.connect(
             (opts[:host] unless blank_object?(opts[:host])),
             opts[:port] || 5432,
             nil, '',
@@ -224,6 +231,9 @@ module Sequel
             opts[:password]
           )
         end
+
+        conn.instance_variable_set(:@db, self)
+
         if encoding = opts[:encoding] || opts[:charset]
           if conn.respond_to?(:set_client_encoding)
             conn.set_client_encoding(encoding)
@@ -231,8 +241,7 @@ module Sequel
             conn.async_exec("set client_encoding to '#{encoding}'")
           end
         end
-        conn.instance_variable_set(:@db, self)
-        conn.instance_variable_set(:@prepared_statements, {}) if SEQUEL_POSTGRES_USES_PG
+
         connection_configuration_sqls.each{|sql| conn.execute(sql)}
         conn
       end

data/lib/sequel/adapters/shared/cubrid.rb

@@ -51,12 +51,13 @@ module Sequel
           from(:db_attribute).
           where(:class_name=>m2.call(table_name)).
           order(:def_order).
-          select(:attr_name, :data_type___db_type, :default_value___default, :is_nullable___allow_null).
+          select(:attr_name, :data_type___db_type, :default_value___default, :is_nullable___allow_null, :prec).
           map do |row|
             name = m.call(row.delete(:attr_name))
             row[:allow_null] = row[:allow_null] == 'YES'
             row[:primary_key] = pks.include?(name)
             row[:type] = schema_column_type(row[:db_type])
+            row[:max_length] = row[:prec] if row[:type] == :string
             [name, row]
           end
       end

data/lib/sequel/adapters/shared/db2.rb

@@ -42,6 +42,7 @@ module Sequel
             column[:allow_null]  = column.delete(:nulls) == 'Y'
             column[:primary_key] = column.delete(:identity) == 'Y' || !column[:keyseq].nil?
             column[:type]        = schema_column_type(column[:db_type])
+            column[:max_length]  = column[:longlength] if column[:type] == :string
             [ m.call(column.delete(:name)), column]
           end
       end

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

@@ -457,6 +457,7 @@ module Sequel
           else
             schema_column_type(row[:db_type])
           end
+          row[:max_length] = row[:max_chars] if row[:type] == :string
           [m.call(row.delete(:column)), row]
         end
       end

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

@@ -524,6 +524,17 @@ module Sequel
         @supported_types.fetch(type){@supported_types[type] = (from(:pg_type).filter(:typtype=>'b', :typname=>type.to_s).count > 0)}
       end
 
+      # Creates a dataset that uses the VALUES clause:
+      #
+      #   DB.values([[1, 2], [3, 4]])
+      #   VALUES ((1, 2), (3, 4))
+      #
+      #   DB.values([[1, 2], [3, 4]]).order(:column2).limit(1, 1)
+      #   VALUES ((1, 2), (3, 4)) ORDER BY column2 LIMIT 1 OFFSET 1
+      def values(v)
+        @default_dataset.clone(:values=>v)
+      end
+
       # Array of symbols specifying view names in the current database.
       #
       # Options:
@@ -1147,12 +1158,13 @@ module Sequel
       CRLF = "\r\n".freeze
       BLOB_RE = /[\000-\037\047\134\177-\377]/n.freeze
       WINDOW = " WINDOW ".freeze
+      SELECT_VALUES = "VALUES ".freeze
       EMPTY_STRING = ''.freeze
       LOCK_MODES = ['ACCESS SHARE', 'ROW SHARE', 'ROW EXCLUSIVE', 'SHARE UPDATE EXCLUSIVE', 'SHARE', 'SHARE ROW EXCLUSIVE', 'EXCLUSIVE', 'ACCESS EXCLUSIVE'].each{|s| s.freeze}
 
       Dataset.def_sql_method(self, :delete, [['if server_version >= 90100', %w'with delete from using where returning'], ['else', %w'delete from using where returning']])
       Dataset.def_sql_method(self, :insert, [['if server_version >= 90100', %w'with insert into columns values returning'], ['else', %w'insert into columns values returning']])
-      Dataset.def_sql_method(self, :select, [['if server_version >= 80400', %w'with select distinct columns from join where group having window compounds order limit lock'], ['else', %w'select distinct columns from join where group having compounds order limit lock']])
+      Dataset.def_sql_method(self, :select, [['if opts[:values]', %w'values order limit'], ['elsif server_version >= 80400', %w'with select distinct columns from join where group having window compounds order limit lock'], ['else', %w'select distinct columns from join where group having compounds order limit lock']])
       Dataset.def_sql_method(self, :update, [['if server_version >= 90100', %w'with update table set from where returning'], ['else', %w'update table set from where returning']])
 
       # Shared methods for prepared statements when used with PostgreSQL databases.
@@ -1285,7 +1297,10 @@ module Sequel
       # Insert a record returning the record inserted.  Always returns nil without
       # inserting a query if disable_insert_returning is used.
       def insert_select(*values)
-        returning.insert(*values){|r| return r} unless @opts[:disable_insert_returning]
+        unless @opts[:disable_insert_returning]
+          ds = opts[:returning] ? self : returning
+          ds.insert(*values){|r| return r}
+        end
       end
 
       # Locks all tables in the dataset's FROM clause (but not in JOINs) with
@@ -1510,6 +1525,12 @@ module Sequel
         @opts[:lock] == :share ? (sql << FOR_SHARE) : super
       end
 
+      # Support VALUES clause instead of the SELECT clause to return rows.
+      def select_values_sql(sql)
+        sql << SELECT_VALUES
+        expression_list_append(sql, opts[:values])
+      end
+
       # SQL fragment for named window specifications
       def select_window_sql(sql)
         if ws = @opts[:window]

data/lib/sequel/adapters/shared/sqlanywhere.rb

@@ -66,6 +66,7 @@ module Sequel
           else
             schema_column_type(row[:db_type])
           end
+          row[:max_length] = row[:width] if row[:type] == :string
           [m.call(row.delete(:name)), row]
         end
       end

data/lib/sequel/adapters/sqlite.rb

@@ -91,14 +91,20 @@ module Sequel
       # The conversion procs to use for this database
       attr_reader :conversion_procs
 
-      # 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).
+      # Connect to the database. Since SQLite is a file based database,
+      # available options are limited:
+      #
+      # :database :: database name (filename or ':memory:' or file: URI)
+      # :readonly :: open database in read-only mode; useful for reading
+      #              static data that you do not want to modify
+      # :timeout :: 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 = ::SQLite3::Database.new(opts[:database])
+        sqlite3_opts = {}
+        sqlite3_opts[:readonly] = typecast_value_boolean(opts[:readonly]) if opts.has_key?(:readonly)
+        db = ::SQLite3::Database.new(opts[:database].to_s, sqlite3_opts)
         db.busy_timeout(opts.fetch(:timeout, 5000))
         
         connection_pragmas.each{|s| log_yield(s){db.execute_batch(s)}}

data/lib/sequel/database/query.rb

@@ -157,7 +157,12 @@ module Sequel
 
       cols = schema_parse_table(table_name, opts)
       raise(Error, 'schema parsing returned no columns, table probably doesn\'t exist') if cols.nil? || cols.empty?
-      cols.each{|_,c| c[:ruby_default] = column_schema_to_ruby_default(c[:default], c[:type])}
+      cols.each do |_,c|
+        c[:ruby_default] = column_schema_to_ruby_default(c[:default], c[:type])
+        if !c[:max_length] && c[:type] == :string && (max_length = column_schema_max_length(c[:db_type]))
+          c[:max_length] = max_length
+        end
+      end
       Sequel.synchronize{@schemas[quoted_name] = cols} if cache_schema
       cols
     end
@@ -251,6 +256,14 @@ module Sequel
       column_schema_default_to_ruby_value(default, type) rescue nil
     end
 
+    # Look at the db_type and guess the maximum length of the column.
+    # This assumes types such as varchar(255).
+    def column_schema_max_length(db_type)
+      if db_type =~ /\((\d+)\)/
+        $1.to_i
+      end
+    end
+
     # Return a Method object for the dataset's output_identifier_method.
     # Used in metadata parsing to make sure the returned information is in the
     # correct format.

data/lib/sequel/dataset/prepared_statements.rb

@@ -86,7 +86,8 @@ module Sequel
         when :first
           clone(:limit=>1).select_sql
         when :insert_select
-          returning.insert_sql(*@prepared_modify_values)
+          ds = opts[:returning] ? self : returning
+          ds.insert_sql(*@prepared_modify_values)
         when :insert
           insert_sql(*@prepared_modify_values)
         when :update

data/lib/sequel/dataset/query.rb

@@ -23,10 +23,9 @@ module Sequel
     # block from the method call.
     CONDITIONED_JOIN_TYPES = [:inner, :full_outer, :right_outer, :left_outer, :full, :right, :left]
 
-    # These symbols have _join methods created (e.g. natural_join) that
-    # call join_table with the symbol.  They only accept a single table
-    # argument which is passed to join_table, and they raise an error
-    # if called with a block.
+    # These symbols have _join methods created (e.g. natural_join).
+    # They accept a table argument and options hash which is passed to join_table,
+    # and they raise an error if called with a block.
     UNCONDITIONED_JOIN_TYPES = [:natural, :natural_left, :natural_right, :natural_full, :cross]
     
     # All methods that return modified datasets with a joined table added.
@@ -387,37 +386,42 @@ module Sequel
     #
     # Takes the following arguments:
     #
-    # * type - The type of join to do (e.g. :inner)
-    # * table - Depends on type:
-    #   * Dataset - a subselect is performed with an alias of tN for some value of N
-    #   * String, Symbol: table
-    # * expr - specifies conditions, depends on type:
-    #   * Hash, Array of two element arrays - Assumes key (1st arg) is column of joined table (unless already
-    #     qualified), and value (2nd arg) is column of the last joined or primary table (or the
-    #     :implicit_qualifier option).
-    #     To specify multiple conditions on a single joined table column, you must use an array.
-    #     Uses a JOIN with an ON clause.
-    #   * Array - If all members of the array are symbols, considers them as columns and 
-    #     uses a JOIN with a USING clause.  Most databases will remove duplicate columns from
-    #     the result set if this is used.
-    #   * nil - If a block is not given, doesn't use ON or USING, so the JOIN should be a NATURAL
-    #     or CROSS join. If a block is given, uses an ON clause based on the block, see below.
-    #   * Everything else - pretty much the same as a using the argument in a call to where,
-    #     so strings are considered literal, symbols specify boolean columns, and Sequel
-    #     expressions can be used. Uses a JOIN with an ON clause.
-    # * options - a hash of options, with any of the following keys:
-    #   * :table_alias - the name of the table's alias when joining, necessary for joining
-    #     to the same table more than once.  No alias is used by default.
-    #   * :implicit_qualifier - The name to use for qualifying implicit conditions.  By default,
-    #     the last joined or primary table is used.
-    #   * :qualify - Can be set to false to not do any implicit qualification.  Can be set
-    #     to :deep to use the Qualifier AST Transformer, which will attempt to qualify
-    #     subexpressions of the expression tree.  Can be set to :symbol to only qualify
-    #     symbols. Defaults to the value of default_join_table_qualification.
-    # * block - The block argument should only be given if a JOIN with an ON clause is used,
-    #   in which case it yields the table alias/name for the table currently being joined,
-    #   the table alias/name for the last joined (or first table), and an array of previous
-    #   SQL::JoinClause. Unlike +where+, this block is not treated as a virtual row block.
+    # type :: The type of join to do (e.g. :inner)
+    # table :: table to join into the current dataset.  Generally one of the following types:
+    #          String, Symbol :: identifier used as table or view name
+    #          Dataset :: a subselect is performed with an alias of tN for some value of N
+    #          SQL::Function :: set returning function
+    #          SQL::AliasedExpression :: already aliased expression.  Uses given alias unless
+    #                                    overridden by the :table_alias option.
+    # expr :: conditions used when joining, depends on type:
+    #         Hash, Array of pairs :: Assumes key (1st arg) is column of joined table (unless already
+    #                                 qualified), and value (2nd arg) is column of the last joined or
+    #                                 primary table (or the :implicit_qualifier option).
+    #                                 To specify multiple conditions on a single joined table column,
+    #                                 you must use an array.  Uses a JOIN with an ON clause.
+    #         Array :: If all members of the array are symbols, considers them as columns and 
+    #                  uses a JOIN with a USING clause.  Most databases will remove duplicate columns from
+    #                  the result set if this is used.
+    #         nil :: If a block is not given, doesn't use ON or USING, so the JOIN should be a NATURAL
+    #                or CROSS join. If a block is given, uses an ON clause based on the block, see below.
+    #         otherwise :: Treats the argument as a filter expression, so strings are considered literal, symbols
+    #                      specify boolean columns, and Sequel expressions can be used. Uses a JOIN with an ON clause.
+    # options :: a hash of options, with the following keys supported:
+    #            :table_alias :: Override the table alias used when joining.  In general you shouldn't use this
+    #                            option, you should provide the appropriate SQL::AliasedExpression as the table
+    #                            argument.
+    #            :implicit_qualifier :: The name to use for qualifying implicit conditions.  By default,
+    #                                   the last joined or primary table is used.
+    #            :reset_implicit_qualifier :: Can set to false to ignore this join when future joins determine qualifier
+    #                                         for implicit conditions.
+    #            :qualify :: Can be set to false to not do any implicit qualification.  Can be set
+    #                        to :deep to use the Qualifier AST Transformer, which will attempt to qualify
+    #                        subexpressions of the expression tree.  Can be set to :symbol to only qualify
+    #                        symbols. Defaults to the value of default_join_table_qualification.
+    # block :: The block argument should only be given if a JOIN with an ON clause is used,
+    #          in which case it yields the table alias/name for the table currently being joined,
+    #          the table alias/name for the last joined (or first table), and an array of previous
+    #          SQL::JoinClause. Unlike +where+, this block is not treated as a virtual row block.
     #
     # Examples:
     #
@@ -505,7 +509,8 @@ module Sequel
         SQL::JoinOnClause.new(expr, type, table_expr)
       end
 
-      opts = {:join => (@opts[:join] || []) + [join], :last_joined_table => table_name}
+      opts = {:join => (@opts[:join] || []) + [join]}
+      opts[:last_joined_table] = table_name unless options[:reset_implicit_qualifier] == false
       opts[:num_dataset_sources] = table_alias_num if table_alias_num
       clone(opts)
     end
@@ -514,7 +519,13 @@ module Sequel
       class_eval("def #{jtype}_join(*args, &block); join_table(:#{jtype}, *args, &block) end", __FILE__, __LINE__)
     end
     UNCONDITIONED_JOIN_TYPES.each do |jtype|
-      class_eval("def #{jtype}_join(table); raise(Sequel::Error, '#{jtype}_join does not accept join table blocks') if block_given?; join_table(:#{jtype}, table) end", __FILE__, __LINE__)
+      class_eval(<<-END, __FILE__, __LINE__+1)
+        def #{jtype}_join(table, opts=Sequel::OPTS)
+          raise(Sequel::Error, '#{jtype}_join does not accept join table blocks') if block_given?
+          raise(Sequel::Error, '#{jtype}_join 2nd argument should be an options hash, not conditions') unless opts.is_a?(Hash)
+          join_table(:#{jtype}, table, nil, opts)
+        end
+      END
     end
 
     # Marks this dataset as a lateral dataset.  If used in another dataset's FROM