sequel 4.49.0 → 5.3.0

data/doc/schema_modification.rdoc

@@ -25,27 +25,27 @@ type for the given database.  So while you specified +String+, Sequel will actua
 +text+ depending on the underlying database.  Here's a list of all ruby classes that Sequel will
 convert to database types:
 
-  create_table(:columns_types) do       # common database type used
-    Integer :a0                         # integer
-    String :a1                          # varchar(255)
-    String :a2, :size=>50               # varchar(50)
-    String :a3, :fixed=>true            # char(255)
-    String :a4, :fixed=>true, :size=>50 # char(50)
-    String :a5, :text=>true             # text
-    File :b                             # blob
-    Fixnum :c                           # integer
-    Bignum :d                           # bigint
-    Float :e                            # double precision
-    BigDecimal :f                       # numeric
-    BigDecimal :f2, :size=>10           # numeric(10)
-    BigDecimal :f3, :size=>[10, 2]      # numeric(10, 2)
-    Date :g                             # date
-    DateTime :h                         # timestamp
-    Time :i                             # timestamp
-    Time :i2, :only_time=>true          # time
-    Numeric :j                          # numeric
-    TrueClass :k                        # boolean
-    FalseClass :l                       # boolean
+  create_table(:columns_types) do     # common database type used
+    Integer :a0                       # integer
+    String :a1                        # varchar(255)
+    String :a2, size: 50              # varchar(50)
+    String :a3, fixed: true           # char(255)
+    String :a4, fixed: true, size: 50 # char(50)
+    String :a5, text: true            # text
+    File :b                           # blob
+    Fixnum :c                         # integer
+    Bignum :d                         # bigint
+    Float :e                          # double precision
+    BigDecimal :f                     # numeric
+    BigDecimal :f2, size: 10          # numeric(10)
+    BigDecimal :f3, size: [10, 2]     # numeric(10, 2)
+    Date :g                           # date
+    DateTime :h                       # timestamp
+    Time :i                           # timestamp
+    Time :i2, only_time: true         # time
+    Numeric :j                        # numeric
+    TrueClass :k                      # boolean
+    FalseClass :l                     # boolean
   end
 
 Note that in addition to the ruby class name, Sequel also pays attention to the column options when
@@ -89,7 +89,7 @@ method, the fourth argument is the options hash.  The following options are supp
           options for the index.
 :null :: Mark the column as allowing NULL values (if true),
          or not allowing NULL values (if false).  If unspecified, will default
-         to whatever the database default is.
+         to whatever the database default is (usually true).
 :primary_key :: Mark this column as the primary key.  This is used instead of the
                 primary key method if you want a non-autoincrementing primary key.
 :primary_key_constraint_name :: The name to give the primary key constraint.
@@ -98,7 +98,7 @@ method, the fourth argument is the options hash.  The following options are supp
          as +primary_key+ or +foreign_key+.
 :unique :: Mark the column as unique, generally has the same effect as
            creating a unique index on the column.
-:unique_constraint_name :: The name to give the unique key constraint.
+:unique_constraint_name :: The name to give the unique constraint.
 
 === Other methods
 
@@ -112,14 +112,14 @@ You've seen this one used already.  It's used to create an autoincrementing inte
 
 If you want an autoincrementing 64-bit integer:
 
-  create_table(:a0){primary_key :id, :type=>:Bignum}
+  create_table(:a0){primary_key :id, type: :Bignum}
 
 If you want to create a primary key column that doesn't use an autoincrementing integer, you should
 not use this method.  Instead, you should use the :primary_key option to the +column+ method or type
 method:
 
-  create_table(:a1){Integer :id, :primary_key=>true} # Non autoincrementing integer primary key
-  create_table(:a2){String :name, :primary_key=>true} # varchar(255) primary key
+  create_table(:a1){Integer :id, primary_key: true} # Non autoincrementing integer primary key
+  create_table(:a2){String :name, primary_key: true} # varchar(255) primary key
 
 If you want to create a composite primary key, you should call the +primary_key+ method with an
 array of column symbols.  You can provide a specific name to use for the primary key constraint
@@ -128,7 +128,7 @@ via the :name option:
   create_table(:items) do
     Integer :group_id
     Integer :position
-    primary_key [:group_id, :position], :name=>:items_pk
+    primary_key [:group_id, :position], name: :items_pk
   end
 
 If provided with an array, +primary_key+ does not create a column, it just sets up the primary key constraint.
@@ -147,7 +147,7 @@ as its third argument.  A simple example is:
 
 +foreign_key+ accepts the same options as +column+.  For example, to have a unique foreign key with varchar(16) type:
 
-  foreign_key :column_name, :table, :unique=>true, :type=>'varchar(16)'
+  foreign_key :column_name, :table, unique: true, type: 'varchar(16)'
 
 +foreign_key+ also accepts some specific options:
 
@@ -186,7 +186,7 @@ When using an array of symbols, you can also provide a :name option to name the
     String :artist_name
     String :artist_location
     String :name
-    foreign_key [:artist_name, :artist_location], :artists, :name=>'albums_artist_name_location_fkey'
+    foreign_key [:artist_name, :artist_location], :artists, name: 'albums_artist_name_location_fkey'
   end
 
 If you want to add a foreign key for a single column with a named constraint, you must use
@@ -196,7 +196,7 @@ the array form with a single symbol:
     primary_key :id
     Integer :artist_id
     String :name
-    foreign_key [:artist_id], :artists, :name=>'albums_artist_id_fkey'
+    foreign_key [:artist_id], :artists, name: 'albums_artist_id_fkey'
   end
 
 ==== +index+
@@ -204,18 +204,18 @@ the array form with a single symbol:
 +index+ creates indexes on the table.  For single columns, calling index is the same as using the
 <tt>:index</tt> option when creating the column:
 
-  create_table(:a){Integer :id, :index=>true}
+  create_table(:a){Integer :id, index: true}
   # Same as:
   create_table(:a) do
     Integer :id
     index :id
   end
 
-  create_table(:a){Integer :id, :index=>{:unique=>true}}
+  create_table(:a){Integer :id, index: {unique: true}}
   # Same as:
   create_table(:a) do
     Integer :id
-    index :id, :unique=>true
+    index :id, unique: true
   end
 
 Similar to the +primary_key+ and +foreign_key+ methods, calling +index+ with an array of symbols
@@ -241,11 +241,11 @@ The +unique+ method creates a unique constraint on the table.  A unique constrai
 operates identically to a unique index, so the following three +create_table+ blocks are
 pretty much identical:
 
-  create_table(:a){Integer :a, :unique=>true}
+  create_table(:a){Integer :a, unique: true}
 
   create_table(:a) do
     Integer :a
-    index :a, :unique=>true
+    index :a, unique: true
   end
 
   create_table(:a) do
@@ -304,23 +304,23 @@ constraint, as that makes it easier to drop the constraint later if necessary.
 
 +create_join_table+ is a shortcut that you can use to create simple many-to-many join tables:
 
-  create_join_table(:artist_id=>:artists, :album_id=>:albums)
+  create_join_table(artist_id: :artists, album_id: :albums)
 
 which expands to:
 
   create_table(:albums_artists) do
-    foreign_key :album_id, :albums, :null=>false
-    foreign_key :artist_id, :artists, :null=>false
+    foreign_key :album_id, :albums
+    foreign_key :artist_id, :artists
     primary_key [:album_id, :artist_id]
     index [:artist_id, :album_id]
   end
 
-== <tt>create_table :as=></tt>
+== <tt>create_table :as</tt>
 
 To create a table from the result of a SELECT query, instead of passing a block
 to +create_table+, provide a dataset to the :as option:
 
-  create_table(:older_items, :as=>DB[:items].where{updated_at < Date.today << 6})
+  create_table(:older_items, as: DB[:items].where{updated_at < Date.today << 6})
 
 == +alter_table+
 
@@ -336,7 +336,7 @@ argument is the column name, the second is the type, and the third is an options
 hash:
 
   alter_table(:albums) do
-    add_column :copies_sold, Integer, :default=>0
+    add_column :copies_sold, Integer, default: 0
   end
 
 === +drop_column+
@@ -374,6 +374,12 @@ Sequel will not add a column, but will add a composite primary key constraint:
     add_primary_key [:album_id, :artist_id]
   end
 
+It is possible to specify a name for the primary key constraint: via the :name option:
+
+  alter_table(:albums_artists) do
+    add_primary_key [:album_id, :artist_id], :name=>:albums_artists_pkey
+  end
+
 If you just want to take an existing single column and make it a primary key, call
 +add_primary_key+ with an array with a single symbol:
 
@@ -392,18 +398,29 @@ creates a new column:
   end
 
 If you want to add a new foreign key constraint to an existing column, you provide an
-array with a single element.  It's encouraged to provide a name when adding the constraint,
-via the :name option:
+array with a single element:
+
+  alter_table(:albums) do
+    add_foreign_key [:artist_id], :artists
+  end
+
+It's encouraged to provide a name when adding the constraint, via the :foreign_key_constraint_name
+option if adding the column and the constraint:
+
+  alter_table(:albums) do
+    add_foreign_key :artist_id, :artists, foreign_key_constraint_name: :albums_artist_id_fkey
+  end
+
+or via the :name option if just adding the constraint:
 
   alter_table(:albums) do
-    add_foreign_key [:artist_id], :artists, :name=>:albums_artist_id_fkey
+    add_foreign_key [:artist_id], :artists, name: :albums_artist_id_fkey
   end
 
-To set up a multiple column foreign key constraint, use an array with multiple column
-symbols:
+To set up a multiple column foreign key constraint, use an array with multiple column symbols:
 
   alter_table(:albums) do
-    add_foreign_key [:artist_name, :artist_location], :artists, :name=>:albums_artist_name_location_fkey
+    add_foreign_key [:artist_name, :artist_location], :artists, name: :albums_artist_name_location_fkey
   end
 
 === +drop_foreign_key+
@@ -420,13 +437,13 @@ an array.  It's encouraged to use the :name option to provide the constraint nam
 drop, though on some databases Sequel may be able to find the name through introspection:
 
   alter_table(:albums) do
-    drop_foreign_key [:artist_id], :name=>:albums_artist_id_fkey
+    drop_foreign_key [:artist_id], name: :albums_artist_id_fkey
   end
 
 An array is also used to drop a composite foreign key constraint:
 
   alter_table(:albums) do
-    drop_foreign_key [:artist_name, :artist_location], :name=>:albums_artist_name_location_fkey
+    drop_foreign_key [:artist_name, :artist_location], name: :albums_artist_name_location_fkey
   end
 
 If you do not provide a :name option and Sequel is not able to determine the name
@@ -445,7 +462,7 @@ It accepts the same options as +create_table+'s +index+ method, and you can set
 a multiple column index using an array:
 
   alter_table(:albums_artists) do
-    add_index [:album_id, :artist_id], :unique=>true
+    add_index [:album_id, :artist_id], unique: true
   end
 
 === +drop_index+
@@ -461,7 +478,7 @@ Just like +drop_column+, it is often used in the +down+ block of a migration.
 To drop an index with a specific name, use the <tt>:name</tt> option:
 
   alter_table(:albums) do
-    drop_index :artist_id, :name=>:artists_id_index
+    drop_index :artist_id, name: :artists_id_index
   end
 
 === +add_full_text_index+, +add_spatial_index+
@@ -480,7 +497,7 @@ method:
 
 There is no method to add an unnamed constraint, but you can pass +nil+ as the first
 argument of +add_constraint+ to do so.  However, it's not recommended to do that
-as it is difficult to drop such a constraint.
+as it is more difficult to drop such a constraint.
 
 === +add_unique_constraint+
 
@@ -491,6 +508,12 @@ method.  This usually has the same effect as adding a unique index.
     add_unique_constraint [:artist_id, :name]
   end
 
+You can also specify a name via the :name option when adding the constraint:
+
+  alter_table(:albums) do
+    add_unique_constraint [:artist_id, :name], name: :albums_artist_id_name_ukey
+  end
+
 === +drop_constraint+
 
 This method drops an existing named constraint:
@@ -506,9 +529,9 @@ For that reason, you should not add unnamed constraints that you ever might need
 On some databases, you must specify the type of constraint via a <tt>:type</tt> option:
 
   alter_table(:albums) do
-    drop_constraint(:albums_pk, :type=>:primary_key)
-    drop_constraint(:albums_fk, :type=>:foreign_key)
-    drop_constraint(:albums_uk, :type=>:unique)
+    drop_constraint(:albums_pk, type: :primary_key)
+    drop_constraint(:albums_fk, type: :foreign_key)
+    drop_constraint(:albums_uk, type: :unique)
   end
 
 === +set_column_default+
@@ -597,9 +620,6 @@ the table if the table already exists.  On some databases, it uses
 <tt>IF NOT EXISTS</tt>, on others it does a separate query to check for
 existence.
 
-This should not be used inside migrations, as if the table does not
-exist, it may mess up the migration.
-
 === +rename_table+
 
 You can rename an existing table using +rename_table+.  Like +rename_column+,
@@ -623,9 +643,6 @@ is the same as:
     primary_key :id
   end
 
-It should not be used inside migrations, as if the table does not exist, it may
-mess up the migration.
-
 === <tt>create_table?</tt>
 
 <tt>create_table?</tt> only creates the table if it does
@@ -643,8 +660,6 @@ is the same as:
     end
   end
 
-Like <tt>create_table!</tt>, it should not be used inside migrations.
-
 === +create_view+ and +create_or_replace_view+
 
 These can be used to create views.  The difference between them is that
@@ -662,4 +677,3 @@ second argument:
 arguments:
 
   drop_view(:gold_albums, :platinum_albums)
-

data/doc/security.rdoc

@@ -16,14 +16,11 @@ as it never calls eval on a string that is derived from user input.
 However, some Sequel methods used for creating methods via metaprogramming
 could conceivably be abused to do so:
 
-* Sequel::Schema::CreateTableGenerator.add_type_method
-* Sequel::Dataset.def_mutation_method
 * Sequel::Dataset.def_sql_method
-* Sequel::Model::Plugins.def_dataset_methods
-* Sequel.def_adapter_method (private)
-* Sequel::SQL::Expression.to_s_method (private)
-* Sequel::Plugins::HookClassMethods::ClassMethods#add_hook_type
+* Sequel::JDBC.load_driver
 * Sequel::Plugins.def_dataset_methods
+* Sequel::Dataset.prepared_statements_module (private)
+* Sequel::SQL::Expression.to_s_method (private)
 
 As long as you don't call those with user input, you should not be
 vulnerable to code execution.
@@ -48,6 +45,9 @@ There are basically two kinds of possible SQL injections in Sequel:
 Some Sequel methods are designed to execute raw SQL strings, including:
 
 * Sequel::Database#execute
+* Sequel::Database#execute_ddl
+* Sequel::Database#execute_dui
+* Sequel::Database#execute_insert
 * Sequel::Database#run
 * Sequel::Database#<<
 * Sequel::Dataset#fetch_rows
@@ -61,9 +61,12 @@ Some Sequel methods are designed to execute raw SQL strings, including:
 
 Here are some examples of use:
 
+  DB.execute 'SQL'
+  DB.execute_ddl 'SQL'
+  DB.execute_dui 'SQL'
+  DB.execute_insert 'SQL'
   DB.run 'SQL'
   DB << 'SQL'
-  DB.execute 'SQL'
   DB.fetch_rows('SQL'){|row| }
   DB.dataset.with_sql_all('SQL')
   DB.dataset.with_sql_delete('SQL')
@@ -102,19 +105,16 @@ With these methods you should use placeholders, in which case Sequel automatical
 
 Sequel generally treats ruby strings as SQL strings (escaping them correctly), and
 not as raw SQL.  However, you can convert a ruby string to a literal string, and
-Sequel will then treat it as raw SQL.  This is typically done through String#lit
-if the {core_extensions}[rdoc-ref:doc/core_extensions.rdoc] are in use,
-or Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit] if they are not in use.
+Sequel will then treat it as raw SQL.  This is typically done through
+Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit].
 
-  'a'.lit
   Sequel.lit('a')
 
-Using String#lit or Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit] to turn a ruby string into a literal string results
+Using Sequel.lit[rdoc-ref:Sequel::SQL::Builders#lit] to turn a ruby string into a literal string results
 in SQL injection if the string is derived from user input.  With both of these
 methods, the strings can contain placeholders, which you can use to safely include
 user input inside a literal string:
 
-  'a = ?'.lit(params[:user_id].to_s)
   Sequel.lit('a = ?', params[:user_id].to_s)
 
 Even though they have similar names, note that Sequel::Database#literal operates very differently from
@@ -132,91 +132,107 @@ a ruby string as raw SQL.  For example:
 
 ==== SQL Filter Fragments
 
-The most common way to use raw SQL with Sequel is in filters:
+Starting in Sequel 5, Sequel does not automatically convert plain strings to
+literal strings in typical code.  Instead, you can use Sequel.lit to
+create literal strings:
 
-  DB[:table].where("name > 'M'")
+  Sequel.lit("name > 'A'")
 
-If a filter method is passed a string as the first argument, it treats the rest of
-the arguments (if any) as placeholders to the string.  So you should never do:
+To safely include user input as part of an SQL filter fragment, use Sequel.lit
+with placeholders:
 
-  DB[:table].where("name > #{params[:id].to_s}") # SQL Injection!
+  DB[:table].where(Sequel.lit("name > ?", params[:id].to_s)) # Safe
 
-Instead, you should use a placeholder:
+Be careful to never call Sequel.lit where the first argument is derived from
+user input.
 
-  DB[:table].where("name > ?", params[:id].to_s) # Safe
- 
-Note that for that type of query, Sequel generally encourages the following form:
+There are a few uncommon cases where Sequel will still convert
+plain strings to literal strings.
+
+==== SQL Fragment passed to Dataset#lock_style and Model#lock!
+
+The Sequel::Dataset#lock_style and Sequel::Model#lock! methods also treat
+an input string as SQL code. These methods should not be called with user input.
+
+  DB[:table].lock_style(params[:id]) # SQL injection!
+  Album.first.lock!(params[:id]) # SQL injection!
+
+==== SQL Type Names
+
+In general, most places where Sequel needs to use an SQL type that should
+be specified by the user, it allows you to use a ruby string, and that
+string is used verbatim as the SQL type.  You should not use user input
+for type strings.
+
+  DB[:table].select(Sequel.cast(:a, params[:id])) # SQL injection!
+
+==== SQL Function Names
+
+In most cases, Sequel does not quote SQL function names.  You should not use
+user input for function names.
+
+  DB[:table].select(Sequel.function(params[:id])) # SQL injection!
+
+==== auto_literal_strings extension
 
-  DB[:table].where{|o| o.name > params[:id].to_s} # Safe
+If the auto_literal_strings extension is used for backwards compatibility,
+then Sequel will treat plain strings as literal strings if they are used
+as the first argument to a filtering method.  This can lead to SQL
+injection:
 
-Sequel's DSL supports a wide variety of SQL concepts, so it's possible to
-code most applications without ever using raw SQL.
+  DB[:table].where("name > #{params[:id].to_s}")
+  # SQL injection when using auto_literal_strings extension
 
-A large number of dataset methods ultimately pass down their arguments to a filter
-method, even some you may not expect, so you should be careful.  At least the
-following methods pass their arguments to a filter method:
+If you are using the auto_literal_strings extension, you need to be very careful,
+as the following methods will treat a plain string given as the first argument
+as a literal string:
 
 * Sequel::Dataset#where
 * Sequel::Dataset#having
 * Sequel::Dataset#filter
 * Sequel::Dataset#exclude
-* Sequel::Dataset#exclude_where
 * Sequel::Dataset#exclude_having
-* Sequel::Dataset#and
 * Sequel::Dataset#or
 * Sequel::Dataset#first
 * Sequel::Dataset#last
 * Sequel::Dataset#[]
 
-The Model.find[rdoc-ref:Sequel::Model::ClassMethods#find] and Model.find_or_create[rdoc-ref:Sequel::Model::ClassMethods#find_or_create]
-class methods also call down to the filter methods.
+Even stuff that looks like it may be safe isn't:
 
-The no_auto_string_literals extension can be used to remove the default support 
-for plain strings as literal strings in filter methods.
+  DB[:table].first(params[:num_rows])
+  # SQL injection when using auto_literal_strings extension
 
-==== SQL Fragment passed to Dataset#update
+The Model.find[rdoc-ref:Sequel::Model::ClassMethods#find] and
+Model.find_or_create[rdoc-ref:Sequel::Model::ClassMethods#find_or_create]
+class methods will also treat string arguments as literal strings if the
+auto_literal_strings extension is used:
 
-Similar to the filter methods, Sequel::Dataset#update also treats a
-string argument as raw SQL:
+  Album.find(params[:id])
+  # SQL injection when using auto_literal_strings extension
+
+Similar to the filter methods, the auto_literal_strings extension
+also makes Sequel::Dataset#update treats a string argument as raw SQL:
 
   DB[:table].update("column = 1")
 
 So you should not do:
 
-  DB[:table].update("column = #{params[:value].to_s}") # SQL Injection!
+  DB[:table].update(params[:changes])
+  # SQL injection when using auto_literal_strings extension
 
-Instead, you should do:
+or:
 
-  DB[:table].update(:column => params[:value].to_s) # Safe
+  DB[:table].update("column = #{params[:value].to_s}")
+  # SQL injection when using auto_literal_strings extension
 
-The no_auto_string_literals extension can also be used to remove the default support
-for plain strings as literal strings in update methods.
-
-==== SQL Fragment passed to Dataset#lock_style and Model#lock!
-
-The Sequel::Dataset#lock_style and Sequel::Model#lock! methods also treat
-an input string as SQL code. This method should not be called with user input.
-
-==== SQL Fragment passed to Virtual Row #` method
-
-Virtual row blocks currently support a #` method for using literal SQL:
-
-  DB[:table].where{a > `some SQL`}
-
-This method should not be called with user input.
-
-==== SQL Type Names
-
-In general, most places where Sequel needs to use an SQL type that should
-be specified by the user, it allows you to use a ruby string, and that
-string is used verbatim as the SQL type.  You should not use user input
-for type strings.
-
-==== SQL Function Names
+Instead, you should do:
 
-In most cases, Sequel does not quote SQL function names.  You should not use
-user input for function names.
+  DB[:table].update(:column => params[:value].to_s) # Safe
 
+Because using the auto_literal_strings extension makes SQL injection
+so much eaiser, it is recommended to not use it, and instead
+use Sequel.lit with placeholders.
+ 
 === SQL Identifier Injections
 
 Usually, Sequel treats ruby symbols as SQL identifiers, and ruby
@@ -236,7 +252,7 @@ the Sequel::Dataset#insert and Sequel::Dataset#update methods:
   DB[:t].insert('b'=>1) # INSERT INTO "t" ("b") VALUES (1)
 
 Note how the identifier is still quoted in these cases.  Sequel quotes identifiers by default
-on most databases.  However, it does not quote identifiers by default on DB2 and Informix.
+on most databases.  However, it does not quote identifiers by default on DB2.
 On those databases using an identifier derived from user input can lead to SQL injection.
 Similarly, if you turn off identifier quoting manually on other databases, you open yourself
 up to SQL injection if you use identifiers derived from user input.
@@ -262,6 +278,10 @@ uses symbols as identifiers.  However, if you are creating symbols from user inp
 you at least have a denial of service vulnerability in ruby <2.2, and possibly a
 more serious vulnerability.
 
+Note that many Database schema modification methods (e.g. create_table, add_column)
+also allow for SQL identifier injections, and possibly also SQL code injections.
+These methods should never be called with user input.
+
 == Denial of Service
 
 Sequel converts some strings to symbols.  Because symbols in ruby <2.2 are not
@@ -293,7 +313,7 @@ if you allow the user to control the alias name:
 
   DB[:table].select(:column.as(params[:alias]))
 
-Then you have a denial of service vulnerability.  In general, such a vulnerability
+Then you can have a denial of service vulnerability.  In general, such a vulnerability
 is unlikely, because you are probably indexing into the returned hash(es) by name,
 and if an alias was used and you didn't expect it, your application wouldn't work.
 
@@ -353,28 +373,17 @@ These two methods iterate over the second argument (+:name+ and +:copies_sold+ i
 this example) instead of iterating over the entries in the first argument
 (<tt>params[:album]</tt> in this example).
 
-In addition to these two methods, you can also use 
-Model#set_only[rdoc-ref:Sequel::Model::InstanceMethods#set_only] or
-Model#update_only[rdoc-ref:Sequel::Model::InstanceMethods#update_only],
-which are similar but iterate over the entries in the first argument, checking
-the second argument to see if setting the entries is allowed.
-
-  album.set_only(params[:album], [:name, :copies_sold])
-  album.update_only(params[:album], [:name, :copies_sold])
-
-If you expect all entries in the second argument to be present in the first
-argument, use +set_fields+ or +update_fields+.  If you are not sure if all
-arguments in the second argument will be present in the first argument, but
-do not want to allow setting any column other than the ones listed in the
-second argument, use +set_only+ or +update_only+.
-
-You can override the columns to allow by default during mass assignment via
-the Model.set_allowed_columns[rdoc-ref:Sequel::Model::ClassMethods#set_allowed_columns] class method.  This is a good
-practice, though being explicit on a per-call basis is still recommended:
+If you want to override the columns that Model#set[rdoc-ref:Sequel::Model::InstanceMethods#set]
+allows by default during mass assignment, you can use the whitelist_security plugin, then call
+the set_allowed_columns class method.
 
+  Album.plugin :whitelist_security
   Album.set_allowed_columns(:name, :copies_sold)
   Album.create(params[:album]) # Only name and copies_sold set
 
+Being explicit on a per-call basis using the set_fields and update_fields methods is recommended
+instead of using the whitelist_security plugin and setting a global whitelist.
+
 For more details on the mass assignment methods, see the {Mass Assignment Guide}[rdoc-ref:doc/mass_assignment.rdoc].
 
 == General Parameter Handling
@@ -386,7 +395,7 @@ their type.  For example:
   Album.where(:id=>params[:id])
 
 is probably a bad idea.  Assuming you are using a web framework, <tt>params[:id]</tt> could
-be a string, an array, a hash, or nil.
+be a string, an array, a hash, nil, or potentially something else.
 
 Assuming that +id+ is an integer field, you probably want to do:
 
@@ -400,7 +409,7 @@ a string:
 If you are trying to use an IN clause with a list of id values based on input provided
 on a web form:
 
-  Album.where(:id=>params[:ids].to_a.map{|i| i.to_i})
+  Album.where(:id=>params[:ids].to_a.map(&:to_i))
 
 Basically, be as explicit as possible. While there aren't any known security issues
 in Sequel when you do: