sequel 4.26.0 → 5.37.0

data/doc/schema_modification.rdoc

@@ -22,30 +22,30 @@ Columns are generally created by specifying the column type as the method
 name, followed by the column name symbol to use, and after that any options that should be used.
 If the method is a ruby class name that Sequel recognizes, Sequel will transform it into the appropriate
 type for the given database.  So while you specified +String+, Sequel will actually use +varchar+ or
-+text+ depending on the underlying database.  Here's a list of all of ruby classes that Sequel will
++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
@@ -74,6 +74,11 @@ as the second argument, either as ruby classes, symbols, or strings:
     column :a6, 'timestamp(6)'     # timestamp(6)
   end
 
+If you use a ruby class as the type, Sequel will try to guess the appropriate type name for the
+database you are using.  If a symbol or string is used as the type, it is used verbatim as the type
+name in SQL, with the exception of :Bignum.  Using the symbol :Bignum as a type will use the
+appropriate 64-bit integer type for the database you are using.
+
 === Column options
 
 When using the type name as method, the third argument is an options hash, and when using the +column+
@@ -84,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.
@@ -93,11 +98,11 @@ 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
 
-In addition to the +column+ method and other methods that create columns, there are a other methods that can be used:
+In addition to the +column+ method and other methods that create columns, there are other methods that can be used:
 
 ==== +primary_key+
 
@@ -107,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
@@ -123,8 +128,8 @@ via the :name option:
   create_table(:items) do
     Integer :group_id
     Integer :position
-    primary_key [:group_id, :position], :name=>:items_pk
-  end 
+    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.
 
@@ -132,7 +137,7 @@ If provided with an array, +primary_key+ does not create a column, it just sets
 
 +foreign_key+ is used to create a foreign key column that references a column in another table (or the same table).
 It takes the column name as the first argument, the table it references as the second argument, and an options hash
-as it's third argument.  A simple example is:
+as its third argument.  A simple example is:
 
   create_table(:albums) do
     primary_key :id
@@ -142,7 +147,7 @@ as it's 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:
 
@@ -154,7 +159,7 @@ as it's third argument.  A simple example is:
         references the primary key of the associated table, at least
         on most databases.
 :on_delete :: Specify the behavior of this foreign key column when the row with the primary key
-              it references is deleted , can be :restrict, :cascade, :set_null, or :set_default.
+              it references is deleted, can be :restrict, :cascade, :set_null, or :set_default.
               You can also use a string, which is used literally.
 :on_update :: Specify the behavior of this foreign key column when the row with the primary key
               it references modifies the value of the primary key.  Takes the same options as
@@ -181,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
@@ -191,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+
@@ -199,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
@@ -236,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
@@ -271,7 +276,7 @@ both take the same options as +index+.
     String :name
     constraint(:name_min_length){char_length(name) > 2}
   end
-  
+
 Instead of using a block, you can use arguments that will be handled similarly
 to <tt>Dataset#where</tt>:
 
@@ -280,7 +285,7 @@ to <tt>Dataset#where</tt>:
     String :name
     constraint(:name_length_range, Sequel.function(:char_length, :name)=>3..50)
   end
-  
+
 ==== +check+
 
 +check+ operates just like +constraint+, except that it doesn't take a name
@@ -291,7 +296,7 @@ and it creates an unnamed constraint:
     String :name
     check{char_length(name) > 2}
   end
-  
+
 It's recommended that you use the +constraint+ method and provide a name for the
 constraint, as that makes it easier to drop the constraint later if necessary.
 
@@ -299,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+
 
@@ -331,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+
@@ -369,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:
 
@@ -387,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, :name=>:albums_artist_id_fkey
+    add_foreign_key :artist_id, :artists, foreign_key_constraint_name: :albums_artist_id_fkey
   end
 
-To set up a multiple column foreign key constraint, use an array with multiple column
-symbols:
+or via the :name option if just adding the constraint:
 
   alter_table(:albums) do
-    add_foreign_key [:artist_name, :artist_location], :artists, :name=>:albums_artist_name_location_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:
+
+  alter_table(:albums) do
+    add_foreign_key [:artist_name, :artist_location], :artists, name: :albums_artist_name_location_fkey
   end
 
 === +drop_foreign_key+
@@ -415,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
@@ -440,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+
@@ -456,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+
@@ -473,9 +495,9 @@ method:
     add_constraint(:name_min_length){char_length(name) > 2}
   end
 
-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 recommend to do that
-as it is difficult to drop such a constraint.
+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 more difficult to drop such a constraint.
 
 === +add_unique_constraint+
 
@@ -486,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:
@@ -501,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+
@@ -514,17 +542,23 @@ This modifies the default value of a column:
     set_column_default :copies_sold, 0
   end
 
+To remove a default value for a column, use +nil+ as the value:
+
+  alter_table(:albums) do
+    set_column_default :copies_sold, nil
+  end
+
 === +set_column_type+
 
 This modifies a column's type.  Most databases will attempt to convert existing values in
 the columns to the new type:
 
   alter_table(:albums) do
-    set_column_type :copies_sold, Bignum
+    set_column_type :copies_sold, :Bignum
   end
 
 You can specify the type as a string or symbol, in which case it is used verbatim, or as a supported
-ruby class, in which case it gets converted to an appropriate database type.
+ruby class or the :Bignum symbol, in which case it gets converted to an appropriate database type.
 
 === +set_column_allow_null+
 
@@ -586,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+,
@@ -612,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
@@ -629,11 +657,9 @@ is the same as:
   unless table_exists?(:artists)
     create_table(:artists) do
       primary_key :id
-    end 
+    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
@@ -651,4 +677,3 @@ second argument:
 arguments:
 
   drop_view(:gold_albums, :platinum_albums)
-

data/doc/security.rdoc

@@ -16,13 +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::JDBC.load_driver
+* Sequel::Plugins.def_dataset_methods
+* Sequel::Dataset.prepared_statements_module (private)
 * Sequel::SQL::Expression.to_s_method (private)
-* Sequel::Plugins::HookClassMethods::ClassMethods#add_hook_type
 
 As long as you don't call those with user input, you should not be
 vulnerable to code execution.
@@ -44,34 +42,62 @@ There are basically two kinds of possible SQL injections in Sequel:
 
 ==== Full SQL Strings
 
-Some Sequel methods are designed to execute raw SQL, including:
+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::Database#[]
-* Sequel::Database#fetch
-* Sequel::Dataset#with_sql
+* Sequel::Dataset#fetch_rows
+* Sequel::Dataset#with_sql_all
+* Sequel::Dataset#with_sql_delete
+* Sequel::Dataset#with_sql_each
+* Sequel::Dataset#with_sql_first
+* Sequel::Dataset#with_sql_insert
+* Sequel::Dataset#with_sql_single_value
+* Sequel::Dataset#with_sql_update
 
 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['SQL'].all
-  DB.fetch('SQL').all
-  DB.dataset.with_sql('SQL').all
+  DB.fetch_rows('SQL'){|row| }
+  DB.dataset.with_sql_all('SQL')
+  DB.dataset.with_sql_delete('SQL')
+  DB.dataset.with_sql_each('SQL'){|row| }
+  DB.dataset.with_sql_first('SQL')
+  DB.dataset.with_sql_insert('SQL')
+  DB.dataset.with_sql_single_value('SQL')
+  DB.dataset.with_sql_update('SQL')
 
 If you pass a string to these methods that is derived from user input, you open
-yourself up to SQL injection.  The Sequel::Database#run, Sequel::Database#<<, and
-Sequel::Database#execute methods are not designed to work at all with user input.
-If you must use them with user input, you should escape the user input manually
-via Sequel::Database#literal. Example:
+yourself up to SQL injection.  These methods are not designed to work at all
+with user input.  If you must call them with user input, you should escape the
+user input manually via Sequel::Database#literal. Example:
 
   DB.run "SOME SQL #{DB.literal(params[:user].to_s)}"
 
-With Sequel::Database#[], Sequel::Database#fetch and Sequel::Dataset#with_sql, you should use placeholders,
-in which case Sequel automatically literalizes the input:
+==== Full SQL Strings, With Possible Placeholders
+
+Other Sequel methods are designed to support execution of raw SQL strings that may contain placeholders:
+
+* Sequel::Database#[]
+* Sequel::Database#fetch
+* Sequel::Dataset#with_sql
+
+Here are some examples of use:
+
+  DB['SQL'].all
+  DB.fetch('SQL').all
+  DB.dataset.with_sql('SQL').all
+
+With these methods you should use placeholders, in which case Sequel automatically escapes the input:
 
   DB['SELECT * FROM foo WHERE bar = ?', params[:user].to_s]
 
@@ -79,19 +105,16 @@ in which case Sequel automatically literalizes the input:
 
 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
@@ -109,78 +132,117 @@ 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
 
-  DB[:table].where{|o| o.name > params[:id].to_s} # Safe
+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.
 
-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].select(Sequel.cast(:a, params[:id])) # SQL injection!
 
-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:
+==== 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!
+
+==== SQL Window Frames
+
+For backwards compatibility, Sequel supports regular strings in the
+window function :frame option, which will be treated as a literal string:
+
+  DB[:table].select{fun(arg).over(:frame=>'SQL Here')}
+
+You should make sure the frame argument is not derived from user input,
+or switch to using a hash as the :frame option value.
+
+==== auto_literal_strings extension
+
+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:
+
+  DB[:table].where("name > #{params[:id].to_s}")
+  # SQL injection when using auto_literal_strings extension
+
+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#[]
-* 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.
-
-==== SQL Fragment passed to Dataset#update
 
-Similar to the filter methods, Sequel::Dataset#update also treats a
-string argument as raw SQL:
+Even stuff that looks like it may be safe isn't:
 
-  DB[:table].update("column = 1")
+  DB[:table].first(params[:num_rows])
+  # SQL injection when using auto_literal_strings extension
 
-So you should not do:
+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:
 
-  DB[:table].update("column = #{params[:value].to_s}") # SQL Injection!
+  Album.find(params[:id])
+  # SQL injection when using auto_literal_strings extension
 
-Instead, you should do:
+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 => params[:value].to_s) # Safe
+  DB[:table].update("column = 1")
 
-==== SQL Fragment passed to Dataset#lock_style
+So you should not do:
 
-The Sequel::Dataset#lock_style method also treats an input string 
-as SQL code. This method should not be called with user input.
+  DB[:table].update(params[:changes])
+  # SQL injection when using auto_literal_strings extension
 
-==== SQL Type Names
+or:
 
-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].update("column = #{params[:value].to_s}")
+  # SQL injection when using auto_literal_strings extension
 
-==== 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
@@ -200,7 +262,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.
@@ -215,19 +277,24 @@ derived from user input unless absolutely necessary.
 
 Sequel also allows you to create identifiers using
 Sequel.identifier[rdoc-ref:Sequel::SQL::Builders#identifier] for plain identifiers,
-Sequel.qualify[rdoc-ref:Sequel::SQL::Builders#qualify] for qualified identifiers, and
+Sequel.qualify[rdoc-ref:Sequel::SQL::Builders#qualify] and
+Sequel::SQL::Indentifier#[][rdoc-ref:Sequel::SQL::QualifyingMethods#[]] for qualified identifiers, and
 Sequel.as[rdoc-ref:Sequel::SQL::Builders#as] for aliased expressions.  So if you
 pass any of those values derived from user input, you are dealing with the same scenario.
 
 Note that the issues with SQL identifiers do not just apply to places where
 strings are used as identifiers, they also apply to all places where Sequel
 uses symbols as identifiers.  However, if you are creating symbols from user input,
-you at least have a denial of service vulnerability, and possibly a more serious
-vulnerability.
+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 are not
+Sequel converts some strings to symbols.  Because symbols in ruby <2.2 are not
 garbage collected, if the strings that are converted to symbols are
 derived from user input, you have a denial of service vulnerability due to
 memory exhaustion.
@@ -256,7 +323,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.
 
@@ -302,25 +369,31 @@ they also allow mass assignment:
   Album.new(params[:album]) # Mass Assignment
   Album.create(params[:album]) # Mass Assignment
 
-Instead of these methods, it is encouraged to either use the
-Model#set_only[rdoc-ref:Sequel::Model::InstanceMethods#set_only],
-Model#update_only[rdoc-ref:Sequel::Model::InstanceMethods#update_only],
-Model#set_fields[rdoc-ref:Sequel::Model::InstanceMethods#set_fields], or
-Model#update_fields[rdoc-ref:Sequel::Model::InstanceMethods#update_fields]
-methods, which allow you to specify which fields
-to allow on a per-call basis.  This pretty much eliminates the chance that the
-user will be able to set a column you did not intend to allow:
+When the argument is derived from user input, instead of these methods, it is encouraged to either use 
+Model#set_fields[rdoc-ref:Sequel::Model::InstanceMethods#set_fields] or
+Model#update_fields[rdoc-ref:Sequel::Model::InstanceMethods#update_fields],
+which allow you to specify which fields to allow on a per-call basis.  This
+pretty much eliminates the chance that the user will be able to set a column
+you did not intend to allow:
 
-  album.set_only(params[:album], [:name, :copies_sold])
   album.set_fields(params[:album], [:name, :copies_sold])
+  album.update_fields(params[:album], [:name, :copies_sold])
 
-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:
+These two methods iterate over the second argument (+:name+ and +:copies_sold+ in
+this example) instead of iterating over the entries in the first argument
+(<tt>params[:album]</tt> in this example).
 
+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
@@ -331,8 +404,8 @@ their type.  For example:
 
   Album.where(:id=>params[:id])
 
-is probably a bad idea.  Assuming you are using a web framework, params\[:id\] could
-be a string, an array, a hash, or nil.
+is probably a bad idea.  Assuming you are using a web framework, <tt>params[:id]</tt> could
+be a string, an array, a hash, nil, or potentially something else.
 
 Assuming that +id+ is an integer field, you probably want to do:
 
@@ -346,7 +419,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: