sequel 5.83.1 → 5.84.0

data/doc/dataset_filtering.rdoc

@@ -1,222 +0,0 @@
-= Dataset Filtering
-
-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')"
-
-Sequel can check for null values:
-
-  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)"
-
-And also compare against multiple values:
-
-  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)"
-
-== Filtering using an array
-
-If you need to select multiple items from a dataset, you can supply an array:
-
-  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 (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)
-
-This works for the standard inequality and arithmetic operators:
-
-  items.where{price + 100 < 200}.sql
-  # "SELECT * FROM items WHERE ((price + 100) < 200)
-
-  items.where{price - 100 > 200}.sql
-  # "SELECT * FROM items WHERE ((price - 100) > 200)
-
-  items.where{price * 100 <= 200}.sql
-  # "SELECT * FROM items WHERE ((price * 100) <= 200)
-
-  items.where{price / 100 >= 200}.sql
-  # "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))
-
-  items.where{(price - 100 > 200) | (price / 100 >= 200)}.sql
-  # "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))"
-
-You can also use the =~ operator:
-
-  items.where{(category =~ 'ruby') & (price + 100 < 200)}.sql
-  # "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{(price =~ (100..200)) & :active}.sql
-  # "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(:active).sql
-  # "SELECT * FROM items WHERE NOT active"
-
-  items.exclude{price / 100 >= 200}.sql
-  # "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{~(category =~ 'ruby') & (price + 100 < 200)}.sql
-  # "SELECT * FROM items WHERE ((category != 'ruby') AND ((price + 100) < 200))"
-
-You can also use the !~ method:
-
-  items.where{(category !~ 'ruby') & (price + 100 < 200)}.sql
-  # "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)
-
-Or against SQL functions:
-
-  items.where{price - 100 < max(price)}.sql
-  # "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 '\')"
-
-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 '\')"
-
-You can specify a Regexp as a hash value (or like argument), but this will probably only work
-on PostgreSQL and MySQL:
-
-  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.*'))"
-
-== 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 '\')"
-
-Sequel.join also takes a join argument:
-
-  items.where(Sequel.join([:name, :comment], ':').like('John:%nice%')).sql
-  # "SELECT * FROM items WHERE ((name || ':' || comment) LIKE 'John:%nice%' ESCAPE '\')"
-
-== Filtering using sub-queries
-
-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))"
-
-Note that if you are checking for the inclusion of a single column in a subselect, the subselect should only select a single column.
-
-== Using OR instead of AND
-
-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))"

data/doc/extensions.rdoc

@@ -1,77 +0,0 @@
-= Sequel Extensions
-
-Sequel has an official extension system, for adding global, Database, and Dataset extensions.
-
-== Global Extensions
-
-Global extensions can add or modify the behavior of any part of Sequel.  Technically, they are not limited to affecting Sequel, as they can also modify code outside of Sequel (e.g. the blank extension).  However, extensions that modify things outside of Sequel generally do so only for backwards compatibility.
-
-Global extensions are loaded via <tt>Sequel.extension</tt>:
-
-  Sequel.extension :named_timezones
-
-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
-
-Database extensions should add or modify the behavior of a single <tt>Sequel::Database</tt> instance.  They are loaded via <tt>Sequel::Database#extension</tt>:
-
-  DB.extension :server_block
-
-The first thing that this does is load the relevent extension globally.  However, Database extensions should be structured in a way that loading the relevent extension globally just adds a module with the related behavior, it doesn't modify any other state.  After loading the extension globally, it modifies the related <tt>Sequel::Database</tt> object to modify it's behavior, usually by extending it with a module.
-
-If you want a Database extension loaded into all future Database instances, you can use <tt>Sequel::Database.extension</tt>:
-
-  Sequel::Database.extension :server_block
-
-All future <tt>Sequel::Database</tt> instances created afterward will then automatically have the server_block extension loaded.
-
-== 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>.  <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)
-
-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:
-
-  DB.extension :columns_introspection
-
-Likewise, if you want to load an extension into all future datasets for all future databases, you can load it via <tt>Sequel::Database.extension</tt>:
-
-  Sequel::Database.extension :columns_introspection
-  
-== Creating Global Extensions
-
-If you want to create a global extension, you just need to store your code so that you can require it via <tt>sequel/extensions/extension_name</tt>.  Then users can load it via:
-
-  Sequel.extension :extension_name
-
-It is recommended you only create a global extension if what you want to do would not work as a Database or Dataset extension.
-
-== Creating Database Extensions
-
-Creating Database extensions is similar to global extensions in terms of creating the file.  However, somewhere in the file, you need to call <tt>Sequel::Database.register_extension</tt>.  Usually you would call this with the module that will be added to the related <tt>Sequel::Database</tt> instance when the extension is loaded.  For example, the server_block extension uses something like:
-
-  Sequel::Database.register_extension(:server_block, Sequel::ServerBlock)
-
-The first argument is the name of the extension as a symbol, and the second is the module.
-
-In some cases, just extending the <tt>Sequel::Database</tt> instance with a module is not sufficient.  So <tt>Sequel::Database.register_extension</tt> also accepts a proc instead of a second argument.  This proc is called with the <tt>Sequel::Database</tt> instance, and can then run any related code:
-
-  Sequel::Database.register_extension(:arbitrary_servers){|db| db.pool.extend(Sequel::ArbitraryServers)}
-
-== Creating Dataset Extensions
-
-Creating Dataset extensions is very similar to creating Database extensions, but instead of calling <tt>Sequel::Database.register_extension</tt>, you call <tt>Sequel::Dataset.register_extension</tt>.  In general, you would call this with the module that will be added to the related <tt>Sequel::Dataset</tt> instance when the extension is loaded.  For example, the columns_introspection extension uses something like:
-
-  Sequel::Dataset.register_extension(:columns_introspection, Sequel::ColumnsIntrospection)
-
-The first argument is the name of the extension as a symbol, and the second is the module.  When you call the <tt>Sequel::Dataset.register_extension</tt> method with a module, it in turn calls <tt>Sequel::Database.register_extension</tt> and adds a Database extension that loads this Dataset extension into all future Datasets created from the Database.
-
-You can also call <tt>Sequel::Dataset.register_extension</tt> with a proc:
-
-  Sequel::Dataset.register_extension(:extension_name){|ds| }
-
-Note that if you use a proc, a corresponding Database extension will not be created automatically (you can still call <tt>Sequel::Database.register_extension</tt> manually in this case).

data/doc/fork_safety.rdoc

@@ -1,84 +0,0 @@
-= Fork Safety
-
-If you are forking or using a library that forks after you have created a
-Sequel::Database instance, then you must disconnect database connections before forking. If you
-don't do this, you can end up with child processes sharing database connections
-and all sorts of weird behavior, including crashes.  Sequel will automatically create new
-connections on an as needed basis in the child processes, so you only need to do the following in
-the parent process:
-
-  DB.disconnect
-
-Or if you have connections to multiple databases:
-
-  Sequel::DATABASES.each(&:disconnect)
-
-== Puma
-
-When using the Puma web server in clustered mode (which is the default behavior in Puma 5+ when
-using multiple processes), you should disconnect inside the +before_fork+ hook in your
-Puma config:
-
-  before_fork do
-    Sequel::DATABASES.each(&:disconnect)
-  end
-
-== Unicorn
-
-When using the Unicorn web server and preloading the application (+preload_app true+ in the Unicorn
-config), you should disconnect inside the +before_fork+ hook in the Unicorn config:
-
-  before_fork do
-    Sequel::DATABASES.each(&:disconnect)
-  end
-
-== Passenger
-
-In Passenger web server, you should disconnect inside the
-+starting_worker_process+ event hook:
-
-  if defined?(PhusionPassenger)
-    PhusionPassenger.on_event(:starting_worker_process) do |forked|
-      Sequel::DATABASES.each(&:disconnect) if forked
-    end
-  end
-
-Note that this disconnects after forking instead of before forking.  Passenger does not
-offer a before fork hook.
-
-== Spring
-
-In Spring application preloader, you should disconnect inside the +after_fork+ hook:
-
-  if defined?(Spring)
-    Spring.after_fork do
-      Sequel::DATABASES.each(&:disconnect)
-    end
-  end
-
-As the method indicates, this disconnects after forking instead of before forking.
-Spring does not offer a before fork hook.
-
-== Resque
-
-In Resque, you should disconnect inside the +before_fork+ hook:
-
-  Resque.before_fork do |job|
-    Sequel::DATABASES.each(&:disconnect)
-  end
-
-== Parallel
-
-If you're using the Parallel gem with processes, you should disconnect before
-calling it:
-
-  Sequel::DATABASES.each(&:disconnect)
-  Parallel.map(['a','b','c'], in_processes: 3) { |one_letter| }
-
-== Other Libraries Calling fork
-
-For any other library that calls fork, you should disconnect before calling
-a method that forks:
-
-  Sequel::DATABASES.each(&:disconnect)
-  SomeLibrary.method_that_forks

data/doc/mass_assignment.rdoc

@@ -1,98 +0,0 @@
-= 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.
-
-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.
-
-So if you do:
-
-  post = Post.new(id: 1)
-
-Sequel will raise a Sequel::MassAssignmentRestriction exception, since by default setting the primary key is not allowed.
-
-To enable use of primary key setters, you need to call +unrestrict_primary_key+ for that model:
-
-  Post.unrestrict_primary_key
-
-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
-  # Class level
-  Post.strict_param_setting = false
-  # Instance level
-  post.strict_param_setting = false
-
-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 untrusted 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])
-
-+set_fields+ will set the value to nil (the default hash value) by default, with behavior equivalent to:
-
-  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
-
-Here's a table describing Sequel's default mass assignment methods:
-
-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
-
-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.