sequel 4.26.0 → 5.37.0

data/doc/dataset_basics.rdoc

@@ -2,16 +2,7 @@
 
 == Introduction
 
-Datasets are the primary way Sequel uses to access the database. While most database libraries have specific support for updating all records or only a single record, Sequel's ability to represent SQL queries themselves as objects is what gives Sequel most of its power.  However, if you haven't been exposed to the dataset concept before, it can be a little disorienting.  This document aims to give a basic introduction to datasets and how to use them.
-
-== What a Dataset Represents
-
-A Dataset can be thought of representing one of two concepts:
-
-* An SQL query
-* An abstract set of rows and some related behavior
-
-The first concept is more easily understood, so you should probably start with that assumption.
+Datasets are the primary way Sequel uses to access the database. While most database libraries have specific support for updating all records or only a single record, Sequel's ability to represent SQL queries themselves as datasets is what gives Sequel most of its power.  This document aims to give a basic introduction to datasets and how to use them.
 
 == Basics
 
@@ -22,9 +13,9 @@ The most basic dataset is the simple selection of all columns in a table:
   
 Here, DB represents your Sequel::Database object, and ds is your dataset, with the SQL query it represents below it.
 
-One of the core dataset ideas that should be understood is that datasets use a functional style of modification, in which methods called on the dataset return modified copies of the dataset, they don't modify the dataset themselves:
+One of the core dataset ideas that should be understood is that datasets are frozen and use a functional style of modification, in which methods called on the dataset return modified copies of the dataset, they don't modify the dataset themselves:
 
-  ds2 = ds.where(:id=>1)
+  ds2 = ds.where(id: 1)
   ds2
   # SELECT * FROM posts WHERE id = 1
   ds
@@ -35,7 +26,7 @@ Note how ds itself is not modified.  This is because ds.where returns a modified
   # Thread safe:
   100.times do |i|
     Thread.new do
-      ds.where(:id=>i).first
+      ds.where(id: i).first
     end
   end
   
@@ -48,7 +39,7 @@ Thread safety you don't really need to worry about, but chainability is core to
 Another important thing to realize is that dataset methods that return modified datasets do not execute the dataset's code on the database.  Only dataset methods that return or yield results will execute the code on the database:
 
   # No SQL queries sent:
-  ds3 = ds.select(:id, :name).order(:name).filter{id < 100}
+  ds3 = ds.select(:id, :name).order(:name).where{id < 100}
   
   # Until you call a method that returns results
   results = ds3.all
@@ -56,12 +47,12 @@ Another important thing to realize is that dataset methods that return modified
 One important consequence of this API style is that if you use a method chain that includes both methods that return modified copies and a method that executes the SQL, the method that executes the SQL should generally be the last method in the chain:
 
   # Good
-  ds.select(:id, :name).order(:name).filter{id < 100}.all
+  ds.select(:id, :name).order(:name).where{id < 100}.all
   
   # Bad
-  ds.all.select(:id, :name).order(:name).filter{id < 100}
+  ds.all.select(:id, :name).order(:name).where{id < 100}
   
-This is because all will return an array of hashes, and select, order, and filter are dataset methods, not array methods.
+This is because all will return an array of hashes, and +select+, +order+, and +where+ are dataset methods, not array methods.
 
 == Methods
 
@@ -77,7 +68,7 @@ Most dataset methods fall into this category, which can be further broken down b
 SELECT:: select, select_all, select_append, select_group, select_more
 FROM:: from, from_self
 JOIN:: join, left_join, right_join, full_join, natural_join, natural_left_join, natural_right_join, natural_full_join, cross_join, inner_join, left_outer_join, right_outer_join, full_outer_join, join_table
-WHERE:: where, filter, exclude, exclude_where, and, or, grep, invert, unfiltered
+WHERE:: where, filter, exclude, or, grep, invert, unfiltered
 GROUP:: group, group_by, group_and_count, group_append, select_group, ungrouped
 HAVING:: having, exclude_having, invert, unfiltered
 ORDER:: order, order_by, order_append, order_prepend, order_more, reverse, reverse_order, unordered
@@ -85,16 +76,16 @@ LIMIT/OFFSET:: limit, offset, unlimited
 compounds:: union, intersect, except
 locking:: for_update, lock_style
 common table expressions:: with, with_recursive
-other:: clone, distinct, naked, qualify, server, with_sql
+other:: distinct, naked, qualify, server, with_sql
 
 === Methods that execute code on the database
 
 Most other dataset methods commonly used will execute the dataset's SQL on the database:
 
-SELECT (All Records):: all, each, map, to_hash, to_hash_groups, select_map, select_order_map, select_hash, select_hash_groups
+SELECT (All Records):: all, each, map, as_hash, to_hash_groups, select_map, select_order_map, select_hash, select_hash_groups
 SELECT (First Record):: first, last, [], single_record
 SELECT (Single Value):: get, single_value
-SELECT (Aggregates):: count, avg, max, min, sum, range, interval
+SELECT (Aggregates):: count, avg, max, min, sum
 INSERT:: insert, <<, import, multi_insert
 UPDATE:: update
 DELETE:: delete

data/doc/dataset_filtering.rdoc

@@ -1,203 +1,216 @@
 = Dataset Filtering
 
-Sequel is very flexibile when it comes to filtering records. You can specify your conditions as a custom string, as a string with parameters, as a hash of values to compare against, or as ruby code that Sequel translates into SQL expressions.
-
-== Filtering using a custom filter string
-
-If you wish to write your SQL by hand, you can just supply it to the dataset's #where method:
-
-  items.where('x < 10').sql
-  #=> "SELECT * FROM items WHERE x < 10"
-
-In order to prevent SQL injection, you can replace literal values with question marks and supply the values as additional arguments:
-
-  items.where('category = ?', 'ruby').sql
-  #=> "SELECT * FROM items WHERE category = 'ruby'"
-
-You can also use placeholders with :placeholder and a hash of placeholder values:
-
-  items.where('category = :category', :category=>'ruby').sql
-  #=> "SELECT * FROM items WHERE category = 'ruby'"
-
-=== Specifying SQL functions
-
-Sequel also allows you to specify functions by using the Sequel.function method:
-
-  items.literal(Sequel.function(:avg, :price)) #=> "avg(price)"
-
-If you are specifying a filter/selection/order, you can use a virtual row block:
-
-  items.select{avg(price)}
-
-You can also use the {core_extensions extension}[rdoc-ref:doc/core_extensions.rdoc] and the +sql_function+ method:
-
-  :avg.sql_function(:price)
+Sequel is very flexible when it comes to filtering records. You can specify your conditions as a hash of values to compare against, or as ruby code that Sequel translates into SQL expressions, or as an SQL code fragment (with optional parameters), .
 
 == Filtering using a hash
 
 If you just need to compare records against values, you can supply a hash:
 
-  items.where(:category => 'ruby').sql
-  #=> "SELECT * FROM items WHERE (category = 'ruby')"
+  items.where(category: 'ruby').sql
+  # "SELECT * FROM items WHERE (category = 'ruby')"
 
 Sequel can check for null values:
 
-  items.where(:category => nil).sql
-  #=> "SELECT * FROM items WHERE (category IS NULL)"
+  items.where(category: nil).sql
+  # "SELECT * FROM items WHERE (category IS NULL)"
 
 Or compare two columns:
 
-  items.where(:x => :some_table__y).sql
-  #=> "SELECT * FROM items WHERE (x = some_table.y)"
+  items.where{{x: some_table[:y]}}.sql
+  # "SELECT * FROM items WHERE (x = some_table.y)"
 
 And also compare against multiple values:
 
-  items.where(:category => ['ruby', 'perl']).sql
-  #=> "SELECT * FROM items WHERE (category IN ('ruby', 'perl'))"
+  items.where(category: ['ruby', 'perl']).sql
+  # "SELECT * FROM items WHERE (category IN ('ruby', 'perl'))"
 
 Ranges (both inclusive and exclusive) can also be used:
 
-  items.where(:price => 100..200).sql
-  #=> "SELECT * FROM items WHERE (price >= 100 AND price <= 200)"
+  items.where(price: 100..200).sql
+  # "SELECT * FROM items WHERE (price >= 100 AND price <= 200)"
 
-  items.where(:price => 100...200).sql
-  #=> "SELECT * FROM items WHERE (price >= 100 AND price < 200)"
+  items.where(price: 100...200).sql
+  # "SELECT * FROM items WHERE (price >= 100 AND price < 200)"
 
 == Filtering using an array
 
 If you need to select multiple items from a dataset, you can supply an array:
 
-	item_array = [1, 38, 47, 99]
-	items.where(:id => item_array).sql
-	#=> "SELECT * FROM items WHERE (id IN (1, 38, 47, 99))"
+  items.where(id: [1, 38, 47, 99]).sql
+  # "SELECT * FROM items WHERE (id IN (1, 38, 47, 99))"
 
 == Filtering using expressions
 
-You can pass a block to where, which is evaluated in a special context:
+You can pass a block to where (referred to as a virtual row block), which is evaluated in a special context:
 
   items.where{price * 2 < 50}.sql
-  #=> "SELECT * FROM items WHERE ((price * 2) < 50)
+  # "SELECT * FROM items WHERE ((price * 2) < 50)
 
 This works for the standard inequality and arithmetic operators:
 
   items.where{price + 100 < 200}.sql
-  #=> "SELECT * FROM items WHERE ((price + 100) < 200)
+  # "SELECT * FROM items WHERE ((price + 100) < 200)
 
   items.where{price - 100 > 200}.sql
-  #=> "SELECT * FROM items WHERE ((price - 100) > 200)
+  # "SELECT * FROM items WHERE ((price - 100) > 200)
 
   items.where{price * 100 <= 200}.sql
-  #=> "SELECT * FROM items WHERE ((price * 100) <= 200)
+  # "SELECT * FROM items WHERE ((price * 100) <= 200)
 
   items.where{price / 100 >= 200}.sql
-  #=> "SELECT * FROM items WHERE ((price / 100) >= 200)
+  # "SELECT * FROM items WHERE ((price / 100) >= 200)
+
+  items.where{price ** 2 >= 200}.sql
+  # "SELECT * FROM items WHERE (power(price, 2) >= 200)
 
 You use the overloaded bitwise and (&) and or (|) operators to combine expressions:
 
   items.where{(price + 100 < 200) & (price * 100 <= 200)}.sql
-  #=> "SELECT * FROM items WHERE (((price + 100) < 200) AND ((price * 100) <= 200))
+  # "SELECT * FROM items WHERE (((price + 100) < 200) AND ((price * 100) <= 200))
 
   items.where{(price - 100 > 200) | (price / 100 >= 200)}.sql
-  #=> "SELECT * FROM items WHERE (((price - 100) > 200) OR ((price / 100) >= 200))
+  # "SELECT * FROM items WHERE (((price - 100) > 200) OR ((price / 100) >= 200))
 
 To filter by equality, you use the standard hash, which can be combined with other expressions using Sequel.& and Sequel.|:
 
-  items.where{Sequel.&({:category => 'ruby'}, (price + 100 < 200))}.sql
-  #=> "SELECT * FROM items WHERE ((category = 'ruby') AND ((price + 100) < 200))"
+  items.where{Sequel.&({category: 'ruby'}, (price + 100 < 200))}.sql
+  # "SELECT * FROM items WHERE ((category = 'ruby') AND ((price + 100) < 200))"
 
 You can also use the =~ operator:
 
   items.where{(category =~ 'ruby') & (price + 100 < 200)}.sql
-  #=> "SELECT * FROM items WHERE ((category = 'ruby') AND ((price + 100) < 200))"
+  # "SELECT * FROM items WHERE ((category = 'ruby') AND ((price + 100) < 200))"
 
 This works with other hash values, such as arrays and ranges:
 
-  items.where{Sequel.|({:category => ['ruby', 'other']}, (price - 100 > 200))}.sql
-  #=> "SELECT * FROM items WHERE ((category IN ('ruby', 'other')) OR ((price - 100) <= 200))"
+  items.where{Sequel.|({category: ['ruby', 'other']}, (price - 100 > 200))}.sql
+  # "SELECT * FROM items WHERE ((category IN ('ruby', 'other')) OR ((price - 100) > 200))"
 
   items.where{(price =~ (100..200)) & :active}.sql
-  #=> "SELECT * FROM items WHERE ((price >= 100 AND price <= 200) AND active)"
+  # "SELECT * FROM items WHERE ((price >= 100 AND price <= 200) AND active)"
+
+== Filtering using a custom filter string
+
+If you wish to include an SQL fragment as part of a filter, you need to wrap it with +Sequel.lit+ to mark that it is literal SQL code, and pass it to the #where method:
+
+  items.where(Sequel.lit('x < 10')).sql
+  # "SELECT * FROM items WHERE x < 10"
+
+In order to prevent SQL injection, you can replace literal values with question marks and supply the values as additional arguments to +Sequel.lit+:
+
+  items.where(Sequel.lit('category = ?', 'ruby')).sql
+  # "SELECT * FROM items WHERE category = 'ruby'"
+
+You can also use placeholders with :placeholder and a hash of placeholder values:
+
+  items.where(Sequel.lit('category = :category', category: "ruby")).sql
+  # "SELECT * FROM items WHERE category = 'ruby'"
+
+In order to combine AND and OR together, you have a few options:
+
+  items.where(category: nil).or(category: "ruby")
+  # SELECT * FROM items WHERE (category IS NULL) OR (category = 'ruby')
+
+This won't work if you add other conditions:
+
+  items.where(name: "Programming in Ruby").where(category: nil).or(category: 'ruby')
+  # SELECT * FROM items WHERE ((name = 'Programming in Ruby') AND (category IS NULL)) OR (category = 'ruby')
+
+The OR applies globally and not locally. To fix this, use & and |:
+
+  items.where(Sequel[name: "Programming in Ruby"] & (Sequel[category: nil] | Sequel[category: "ruby"]))
+  # SELECT * FROM items WHERE ((name = 'Programming in Ruby') AND ((category IS NULL) OR (category = 'ruby')))
+
+=== Specifying SQL functions
+
+Sequel also allows you to specify functions by using the Sequel.function method:
+
+  items.literal(Sequel.function(:avg, :price)) # "avg(price)"
+
+If you are specifying a filter/selection/order, you can use a virtual row block:
+
+  items.select{avg(price)}
 
 === Negating conditions
 
 You can use the exclude method to exclude whole conditions:
 
-  items.exclude(:category => 'ruby').sql
-  #=> "SELECT * FROM items WHERE (category != 'ruby')"
+  items.exclude(category: 'ruby').sql
+  # "SELECT * FROM items WHERE (category != 'ruby')"
 
   items.exclude(:active).sql
-  #=> "SELECT * FROM items WHERE NOT active"
+  # "SELECT * FROM items WHERE NOT active"
 
   items.exclude{price / 100 >= 200}.sql
-  #=> "SELECT * FROM items WHERE ((price / 100) < 200)
+  # "SELECT * FROM items WHERE ((price / 100) < 200)
 
 To exclude only parts of conditions, you can use when in combination with Sequel.~ or the ~ method on Sequel expressions:
 
-  items.where{Sequel.&(Sequel.~(:category => 'ruby'), (price + 100 < 200))}.sql
-  #=> "SELECT * FROM items WHERE ((category != 'ruby') AND ((price + 100) < 200))"
+  items.where{Sequel.&(Sequel.~(category: 'ruby'), (price + 100 < 200))}.sql
+  # "SELECT * FROM items WHERE ((category != 'ruby') AND ((price + 100) < 200))"
 
   items.where{~(category =~ 'ruby') & (price + 100 < 200)}.sql
-  #=> "SELECT * FROM items WHERE ((category != 'ruby') AND ((price + 100) < 200))"
+  # "SELECT * FROM items WHERE ((category != 'ruby') AND ((price + 100) < 200))"
 
-On Ruby 1.9+, you can also use the !~ method:
+You can also use the !~ method:
 
   items.where{(category !~ 'ruby') & (price + 100 < 200)}.sql
-  #=> "SELECT * FROM items WHERE ((category != 'ruby') AND ((price + 100) < 200))"
+  # "SELECT * FROM items WHERE ((category != 'ruby') AND ((price + 100) < 200))"
 
 === Comparing against column references
 
 You can also compare against other columns:
 
   items.where{credit > debit}.sql
-  #=> "SELECT * FROM items WHERE (credit > debit)
+  # "SELECT * FROM items WHERE (credit > debit)
 
 Or against SQL functions:
 
   items.where{price - 100 < max(price)}.sql
-  #=> "SELECT * FROM items WHERE ((price - 100) < max(price))"
+  # "SELECT * FROM items WHERE ((price - 100) < max(price))"
 
 == String search functions
 
 You can search SQL strings in a case sensitive manner using the Sequel.like method:
 
   items.where(Sequel.like(:name, 'Acme%')).sql
-  #=> "SELECT * FROM items WHERE (name LIKE 'Acme%' ESCAPE '\')"
+  # "SELECT * FROM items WHERE (name LIKE 'Acme%' ESCAPE '\')"
 
 You can search SQL strings in a case insensitive manner using the Sequel.ilike method:
 
   items.where(Sequel.ilike(:name, 'Acme%')).sql
-  #=> "SELECT * FROM items WHERE (name ILIKE 'Acme%' ESCAPE '\')"
+  # "SELECT * FROM items WHERE (name ILIKE 'Acme%' ESCAPE '\')"
 
-You can specify a Regexp as a like argument, but this will probably only work
+You can specify a Regexp as a hash value (or like argument), but this will probably only work
 on PostgreSQL and MySQL:
 
-  items.where(Sequel.like(:name, /Acme.*/)).sql
-  #=> "SELECT * FROM items WHERE (name ~ 'Acme.*')"
+  items.where(name: /Acme.*/).sql
+  # "SELECT * FROM items WHERE (name ~ 'Acme.*')"
 
 Like can also take more than one argument:
 
   items.where(Sequel.like(:name, 'Acme%', /Beta.*/)).sql
-  #=> "SELECT * FROM items WHERE ((name LIKE 'Acme%' ESCAPE '\') OR (name ~ 'Beta.*'))"
+  # "SELECT * FROM items WHERE ((name LIKE 'Acme%' ESCAPE '\') OR (name ~ 'Beta.*'))"
 
 == String concatenation
 
 You can concatenate SQL strings using Sequel.join:
 
   items.where(Sequel.join([:name, :comment]).like('Jo%nice%')).sql
-  #=> "SELECT * FROM items WHERE ((name || comment) LIKE 'Jo%nice%' ESCAPE '\')"
+  # "SELECT * FROM items WHERE ((name || comment) LIKE 'Jo%nice%' ESCAPE '\')"
 
 Sequel.join also takes a join argument:
 
-  items.filter(Sequel.join([:name, :comment], ':').like('John:%nice%')).sql
-  #=> "SELECT * FROM items WHERE ((name || ':' || comment) LIKE 'John:%nice%' ESCAPE '\')"
+  items.where(Sequel.join([:name, :comment], ':').like('John:%nice%')).sql
+  # "SELECT * FROM items WHERE ((name || ':' || comment) LIKE 'John:%nice%' ESCAPE '\')"
 
 == Filtering using sub-queries
 
-One of the best features of Sequel is the ability to use datasets as sub-queries. Sub-queries can be very useful for filtering records, and many times provide a simpler alternative to table joins. Sub-queries can be used in all forms of filters:
+Datasets can be used as subqueries. Subqueries can be very useful for filtering records, and many times provide a simpler alternative to table joins. Subqueries can be used in all forms of filters:
 
   refs = consumer_refs.where(:logged_in).select(:consumer_id)
-  consumers.where(:id => refs).sql
-  #=> "SELECT * FROM consumers WHERE (id IN (SELECT consumer_id FROM consumer_refs WHERE logged_in))"
+  consumers.where(id: refs).sql
+  # "SELECT * FROM consumers WHERE (id IN (SELECT consumer_id FROM consumer_refs WHERE logged_in))"
 
 Note that if you are checking for the inclusion of a single column in a subselect, the subselect should only select a single column.
 
@@ -205,5 +218,5 @@ Note that if you are checking for the inclusion of a single column in a subselec
 
 By default, if you chain calls to +where+, the conditions get ANDed together.  If you want to use an OR for a condition, you can use the +or+ method:
 
-  items.where(:name=>'Food').or(:vendor=>1).sql
-  #=> "SELECT * FROM items WHERE ((name = 'Food') OR (vendor = 1))"
+  items.where(name: 'Food').or(vendor: 1).sql
+  # "SELECT * FROM items WHERE ((name = 'Food') OR (vendor = 1))"

data/doc/extensions.rdoc

@@ -10,7 +10,7 @@ Global extensions are loaded via <tt>Sequel.extension</tt>:
 
   Sequel.extension :named_timezones
 
-What this does is require the relevent extension from <tt>sequel/extensions/named_timezones</tt> somewhere in the ruby path.  Actually, that is all that does.  Global extensions are just a simpler, consistent way to require code that modifies Sequel.
+All this does is require the relevent extension from <tt>sequel/extensions/named_timezones</tt> somewhere in the ruby path.  Global extensions are just a simpler, consistent way to require code that modifies Sequel.
 
 == Database Extensions
 
@@ -28,18 +28,11 @@ All future <tt>Sequel::Database</tt> instances created afterward will then autom
 
 == Dataset Extensions
 
-Dataset extensions should add or modify the behavior of a single <tt>Sequel::Dataset</tt> instance.  They are loaded via <tt>Sequel::Dataset#extension</tt> or <tt>Sequel::Dataset#extension!</tt>.  <tt>Sequel::Dataset#extension</tt> returns a modifies copy of the dataset that includes the extension (similar to how most dataset query methods work):
+Dataset extensions should add or modify the behavior of a single <tt>Sequel::Dataset</tt> instance.  They are loaded via <tt>Sequel::Dataset#extension</tt>.  <tt>Sequel::Dataset#extension</tt> returns a modifies copy of the dataset that includes the extension (similar to how most dataset query methods work):
 
   ds = DB[:a].extension(:columns_introspection)
 
-<tt>Sequel::Dataset#extension!</tt> modifies a dataset to include the extension (similar to how dataset mutation methods work):
-  
-  ds = DB[:a]
-  ds.extension!(:columns_introspection)
-
-It is recommended you only use <tt>Sequel::Dataset#extension!</tt> if you have good reasons to.
-
-The first thing loading a Dataset extension does is load the relevent extension globally.  Similar to Database extensions, loading a Dataset extension globally should not affect state other than maybe adding a module.  After loading the extension globally, it modifies the related <tt>Sequel::Dataset</tt> instance to modify its behavior.
+The first thing loading a Dataset extension does is load the relevent extension globally.  Similar to Database extensions, loading a Dataset extension globally should not affect state other than maybe adding a module.  After loading the extension globally, it returned a modified copy of the <tt>Sequel::Dataset</tt> with the extension loaded into it.
 
 If you want to load an extension into all future datasets for a given <tt>Sequel::Database</tt> instance, you can also load it as a Database extension:
 

data/doc/mass_assignment.rdoc

@@ -1,33 +1,42 @@
 = Sequel::Model Mass Assignment
 
-Most Model methods that take a hash of attribute keys and values, including <tt>Model.new</tt>, <tt>Model.create</tt>, <tt>Model#set</tt> and <tt>Model#update</tt> are subject to Sequel's mass assignment rules.
-When you pass a hash to these methods, each key has an <tt>=</tt> appended to it (the setter method), and if the setter method exists and access to it is not restricted, Sequel will call the setter method with the hash value.
-By default, there are two types of setter methods that are restricted.  
+Most Model methods that take a hash of attribute keys and values, including <tt>Model.new</tt>,
+<tt>Model.create</tt>, <tt>Model#set</tt> and <tt>Model#update</tt> are subject to Sequel's mass assignment rules.
+
+If you have an instance of a plain Sequel::Model class:
+
+  class Post < Sequel::Model
+  end
+  post = Post.new
+
+and you call a mass assignment method with a hash:
+
+  post.set(title: 'T', body: 'B')
+
+the mass assignment method will go through each key in the hash, append <tt>=</tt> to it to determine the
+setter method, and if the setter method is defined and access to it is not restricted, Sequel will call the
+setter method with the hash value.  So if we assume that the posts table has title and body columns, what
+the above mass assignment call actually does is:
+
+  post.title=('T')
+  post.body=('B')
+
+By default, there are two types of setter methods that are restricted.
 The first is methods like <tt>typecast_on_assignment=</tt> and <tt>==</tt>, which don't affect columns.
 These methods cannot be enabled for mass assignment.
 The second is primary key setters.
-To enable use of primary key setters, you need to call +unrestrict_primary_key+ for that model:
-
-  Post.unrestrict_primary_key
 
-Since mass assignment by default allows modification of all column values except for primary key columns, it can be a security risk in some cases.
-Sequel has multiple ways of securing mass assignment.
-The first way is using +set_allowed_columns+:
+So if you do:
 
-  Post.set_allowed_columns :title, :body, :category
+  post = Post.new(id: 1)
 
-This explicitly sets which methods are allowed (<tt>title=</tt>, <tt>body=</tt>, and <tt>category=</tt>), all other methods will not be allowed.
-This method is useful in simple applications where the same columns are allowed in all cases, but not appropriate when different columns are allowed in different scenarios (e.g. admin access vs. user access).
-To handle cases where different columns are allowed in different cases, you can use +set_only+ or +update_only+:
+Sequel will raise a Sequel::MassAssignmentRestriction exception, since by default setting the primary key is not allowed.
 
-  # user case
-  post.set_only(params[:post], :title, :body)
-  # admin case
-  post.set_only(params[:post], :title, :body, :deleted)
+To enable use of primary key setters, you need to call +unrestrict_primary_key+ for that model:
 
-In this case, only the <tt>title=</tt> and <tt>body=</tt> methods will be allowed in the mass assignment in the user case, and only <tt>title=</tt>, <tt>body=</tt>, and <tt>deleted=</tt> will be allowed for mass assignment in the admin case.
+  Post.unrestrict_primary_key
 
-By default, if an invalid setter method call is attempted, Sequel raises a <tt>Sequel::Error</tt> exception.  You can have Sequel silently ignore invalid calls by doing:
+If you want to change mass assignment so it ignores attempts to access restricted setter methods, you can do:
 
   # Global default
   Sequel::Model.strict_param_setting = false
@@ -36,20 +45,54 @@ By default, if an invalid setter method call is attempted, Sequel raises a <tt>S
   # Instance level
   post.strict_param_setting = false
 
-In addition to +set_only+ and +update_only+, Sequel also has +set_fields+ and +update_fields+ methods, and these may be a better mass assignment choice for most users.
-These methods take two arguments, the attributes hash as the first argument, and a single array of valid field names as the second argument:
+Since mass assignment by default allows modification of all column values except for primary key columns, it can be a security risk in some cases.
+If you are dealing with untrusted input, you are generally going to want to restrict what should be updated.
+
+Sequel has <tt>Model#set_fields</tt> and <tt>Model#update_fields</tt> methods, which are designed to be used with untrused input.
+These methods take two arguments, the untrusted hash as the first argument, and a trusted array of field names as the second argument:
+
+  post.set_fields({title: 'T', body: 'B'}, [:title, :body])
+
+Instead of looking at every key in the untrusted hash, +set_fields+ will iterate over the trusted field names, looking each up in the hash, and
+calling the setter method appropriately with the result.  +set_fields+ basically translates the above method call to:
+
+  post.title=('T')
+  post.body=('B')
+
+By using this method, you can be sure that the mass assignment method only sets the fields you expect it to set.
+
+Note that if one of the fields does not exist in the hash:
+
+  post.set_fields({title: 'T'}, [:title, :body])
 
-  post.set_fields(params[:post], [:title, :body])
++set_fields+ will set the value to nil (the default hash value) by default, with behavior equivalent to:
 
-+set_fields+ and +update_fields+ differ in implementation from +set_only+ and +update_only+.
-With +set_only+ and +update_only+, the hash is iterated over and it checks each method call attempt to see if it is valid.
-With +set_fields+ and +update_fields+, the array is iterated over, and it just looks up the value in the hash and calls the appropriate setter method.
+  post.title=('T')
+  post.body=(nil)
+
+You can use the :missing option to +set_fields+ to change the behavior:
+
+  post.set_fields({title: 'T'}, [:title, :body], missing: :skip)
+  # post.title=('T') # only
+
+  post.set_fields({title: 'T'}, [:title, :body], missing: :raise)
+  # raises Sequel::Error
+
+If you want to set a model level default for the +set_fields+ options, you can use the +default_set_fields_options+ class accessor:
+
+  # Global default
+  Sequel::Model.default_set_fields_options[:missing] = :skip
+  # Class level
+  Post.default_set_fields_options[:missing] = :skip
 
-+set_fields+ and +update_fields+ are designed for the case where you are expecting specific fields in the input, and want to ignore the other fields.
-They work great for things like HTML forms where the form fields are static.
-+set_only+ and +update_only+ are designed for cases where you are not sure what fields are going to be present in the input, but still want to make sure only certain setter methods can be called.
-They work great for flexible APIs.
+Here's a table describing Sequel's default mass assignment methods:
 
-+set_fields+ and +update_fields+ take an optional argument hash, and currently handles the :missing option.  With <tt>:missing=>:skip</tt>, +set_fields+ and +update_fields+ will just skip missing entries in the hash, allowing them to be used in flexible APIs.  With <tt>:missing=>:raise</tt>, +set_fields+ and +update_fields+ will raise an error if one of the entries in the hash is missing, instead of just assigning the value to nil or whatever the hash's default value is.  That allows stricter checks, similar to the :strict_param_checking setting for the default mass assignment methods.  You can use the <tt>Model.default_set_fields_options=</tt> method to set the default options to use for +set_fields+ and +update_fields+ on a global or per-model basis.
+Model.new(hash) :: Creates a new model instance, then calls Model#set(hash)
+Model.create(hash) :: Calls Model.new(hash).save
+Model#set(hash) :: Calls related setter method (unless access is restricted) for each key in the hash, then returns self
+Model#update(hash) :: Calls set(hash).save_changes
+Model#set_fields(hash, columns, options) :: For each column in columns, looks up related entry in hash, and calls the related setter method
+Model#update_fields(hash, columns, options) :: Calls set_fields(hash, columns, options).save_changes
 
-In all of the mass assignment cases, methods starting with +set+ will set the attributes without saving the object, while methods starting with +update+ will set the attributes and then save the changes to the object.
+For backwards compatibility, Sequel also ships with a whitelist_security and blacklist_security plugins that offer additional mass assignment
+methods, but it is recommended to use +set_fields+ or +update_fields+ for untrusted input, and the other methods for trusted input.