sequel 4.36.0 → 5.61.0

data/doc/core_extensions.rdoc

@@ -10,12 +10,18 @@ Historically, Sequel added methods to many of the core classes, and usage of tho
 
 While Sequel never overrode any methods defined by ruby, it is possible that other libraries could define the same methods that Sequel defines, which could cause problems.  Also, some rubyists do not like using libraries that add methods to the core classes.
 
-Alternatives for the core extension methods where added to Sequel, so the query above could be written as:
+Alternatives for the core extension methods were added to Sequel, so the query above could be written as:
 
   DB[:table].select(Sequel.cast(:column, Integer)).
     where(Sequel.like(:column, 'A%')).
     order(Sequel.case({1=>2}, 0, :a))
 
+or with virtual rows:
+
+  DB[:table].select{column.as(Integer)}.
+    where{column.like('A%')}.
+    order(Sequel.case({1=>2}, 0, :a))
+
 Almost all of the core extension methods have a replacement on the Sequel module.  So it is now up to the user which style to use.  Using the methods on the Sequel module results in slightly more verbose code, but allows the code to work without modifications to the core classes.
 
 == Issues
@@ -40,6 +46,16 @@ All of Sequel's extensions to the core classes are stored in Sequel's core_exten
 
 Sequel has no internal dependency on the core extensions.  This includes Sequel's core, Sequel::Model, and all plugins and extensions that ship with Sequel.  However, it is possible that external plugins and extensions will depend on the core extensions.  Such plugins and extensions should be updated so that they no longer depend on the core extensions.
 
+== Refinements
+
+Most of the these extensions can be added on a per-file basis using refinements (if you are using Ruby 2.0+).  To use refinements, first load them:
+
+  Sequel.extension :core_refinements
+
+Then for each file where you want to use the refinements:
+
+  using Sequel::CoreRefinements
+
 == Core Extension Methods
 
 This section will briefly describe all of the methods added to the core classes, and what the alternative method is that doesn't require the core extensions.
@@ -53,8 +69,9 @@ Symbol#as and String#as return Sequel aliased expressions using the provided ali
   :a.as(:b)  # SQL: a AS b
   'a'.as(:b) # SQL: 'a' AS b
 
-Alternative: Sequel.as:
+Alternatives:
 
+  Sequel[:a].as(:b)
   Sequel.as(:a, :b)
 
 ==== cast
@@ -64,8 +81,9 @@ Symbol#cast and String#cast return Sequel cast expressions for typecasting in th
   :a.cast(Integer)  # SQL: CAST(a AS integer)
   'a'.cast(Integer) # SQL: CAST('a' AS integer)
 
-Alternative: Sequel.cast:
+Alternatives:
 
+  Sequel[:a].cast(Integer)
   Sequel.cast(:a, Integer)
 
 ==== cast_numeric
@@ -75,8 +93,9 @@ Symbol#cast_numeric and String#cast_numeric return Sequel cast expressions for t
   :a.cast_numeric         # SQL: CAST(a AS integer)
   'a'.cast_numeric(Float) # SQL: CAST('a' AS double precision)
 
-Alternative: Sequel.cast_numeric:
+Alternative:
 
+  Sequel[:a].cast_numeric
   Sequel.cast_numeric(:a)
 
 ==== cast_string
@@ -86,21 +105,23 @@ Symbol#cast_string and String#cast_string return Sequel cast expressions for typ
   :a.cast_string         # SQL: CAST(a AS varchar(255))
   'a'.cast_string(:text) # SQL: CAST('a' AS text)
 
-Alternative: Sequel.cast_string:
+Alternatives:
 
+  Sequel[:a].cast_string
   Sequel.cast_string(:a)
 
 === Symbol
 
 ==== identifier
 
-Symbol#identifier wraps the symbol in a single identifier that will not be split.  By default, Sequel will split symbols with double or triple underscores to do qualifying and aliasing.
+Symbol#identifier wraps the symbol in an Sequel identifier object.  If symbol splitting is enabled (no longer the default), it also makes sure the symbol will not be split.  If symbol splitting is disabled (the default), there is little reason to use this).
 
-  :table__column.identifier # SQL: table__column
+  :column.identifier # SQL: column
 
-Alternative: Sequel.identifier:
+Alternatives:
 
-  Sequel.identifier(:table__column)
+  Sequel[:column]
+  Sequel.identifier(:column)
 
 ==== asc
 
@@ -108,8 +129,9 @@ Symbol#asc is used to define an ascending order on a column.  It exists mostly f
 
   :a.asc # SQL: a ASC
 
-Alternative: Sequel.asc:
+Alternatives:
 
+  Sequel[:a].asc
   Sequel.asc(:a)
 
 ==== desc
@@ -118,8 +140,9 @@ Symbol#desc is used to defined a descending order on a column.  The returned val
 
   :a.desc # SQL: a DESC
 
-Alternative: Sequel.desc:
+Alternatives:
 
+  Sequel[:a].desc
   Sequel.desc(:a)
 
 ==== +, -, *, /
@@ -130,13 +153,25 @@ The standard mathematical operators are defined on Symbol, and return a Sequel n
     :a - :b # SQL: a - b
     :a * :b # SQL: a * b
     :a / :b # SQL: a / b 
+    :a ** :b # SQL: power(a, b)
+
+Sequel also supports ruby's coercion protocols on symbols (note that this does not work when using refinements):
+
+    1 + :b # SQL: 1 + b
 
 Alternatives:
 
+    Sequel[:a] + :b
+    Sequel[:a] - :b
+    Sequel[:a] * :b
+    Sequel[:a] / :b
+    Sequel[:a] ** :b
+
     Sequel.+(:a, :b)
     Sequel.-(:a, :b)
     Sequel.*(:a, :b)
     Sequel./(:a, :b)
+    Sequel.**(:a, :b)
 
 ==== *
 
@@ -144,9 +179,9 @@ The * operator is overloaded on Symbol such that if it is called with no argumen
 
   :a.* # SQL: a.*
 
-Alternative: Sequel.expr.*:
+Alternative:
 
-  Sequel.expr(:a).*
+  Sequel[:a].*
 
 ==== qualify
 
@@ -154,11 +189,11 @@ Symbol#qualify qualifies the identifier (e.g. a column) with a another identifie
 
   :column.qualify(:table) # SQL: table.column
 
-Alternative: Sequel.qualify:
+Alternative:
 
-  Sequel.qualify(:table, :column)
+  Sequel[:table][:column]
 
-Note the reversed order of the arguments.  For the Symbol#qualify method, the argument is the qualifier, while for Sequel.qualify, the qualifier is the first argument.
+Note the reversed order of the arguments.  For the Symbol#qualify method, the argument is the qualifier, while for Sequel[][], the first [] is the qualifier, and the second [] is the identifier.
 
 ==== like
 
@@ -166,8 +201,9 @@ Symbol#like returns a case sensitive LIKE expression between the identifier and
 
   :a.like('b%') # SQL: a LIKE 'b%' ESCAPE '\'
 
-Alternative: Sequel.like:
+Alternatives:
 
+  Sequel[:a].like('b%')
   Sequel.like(:a, 'b%')
 
 ==== ilike
@@ -176,8 +212,9 @@ Symbol#ilike returns a case insensitive LIKE expression between the identifier a
 
   :a.ilike('b%') # SQL: a ILIKE 'b%' ESCAPE '\'
 
-Alternative: Sequel.ilike:
+Alternatives:
 
+  Sequel[:a].ilike('b%')
   Sequel.ilike(:a, 'b%')
 
 ==== sql_subscript
@@ -186,8 +223,9 @@ Symbol#sql_subscript returns a Sequel expression representing an SQL array acces
 
   :a.sql_subscript(1) # SQL: a[1]
 
-Alternative: Sequel.subscript:
+Alternatives:
 
+  Sequel[:a].sql_subscript(1)
   Sequel.subscript(:a, 1)
 
 ==== extract
@@ -196,12 +234,11 @@ Symbol#extract does a datetime part extraction from the receiver:
 
   :a.extract(:year) # SQL: extract(year FROM a)
 
-Alternative: Sequel.extract:
+Alternatives:
 
+  Sequel[:a].extract(:year)
   Sequel.extract(:year, :a)
 
-Note the reversed order of the arguments.  In Symbol#extract, the datetime part is the argument, while in Sequel.extract, the datetime part is the first argument.
-
 ==== sql_boolean, sql_number, sql_string
 
 These Symbol methods are used to force the treating of the object as a specific SQL type, instead of as a general SQL type.  For example:
@@ -210,11 +247,11 @@ These Symbol methods are used to force the treating of the object as a specific
   :a.sql_number << 1  # SQL: a << 1
   :a.sql_string + 'a' # SQL: a || 'a'
 
-Alternative: Sequel.expr:
+Alternatives:
 
-  Sequel.expr(:a).sql_boolean
-  Sequel.expr(:a).sql_number
-  Sequel.expr(:a).sql_string
+  Sequel[:a].sql_boolean
+  Sequel[:a].sql_number
+  Sequel[:a].sql_string
 
 ==== sql_function
 
@@ -224,8 +261,9 @@ Symbol#sql_function returns an SQL function call expression object:
   :sum.sql_function(:a) # SQL: sum(a)
   :concat.sql_function(:a, :b) # SQL: concat(a, b)
 
-Alternative: Sequel.function:
+Alternatives:
 
+  Sequel[:sum].function(:a)
   Sequel.function(:sum, :a)
 
 === String
@@ -237,9 +275,10 @@ String#lit creates a literal string, using placeholders if any arguments are giv
   'a'.lit          # SQL: a
   '"a" = ?'.lit(1) # SQL: "a" = 1
 
-Alternative: Sequel.lit:
+Alternatives:
 
   Sequel.lit('a')
+  Sequel.lit('a = ?', 1)
 
 ==== to_sequel_blob
 
@@ -247,7 +286,7 @@ String#to_sequel_blob returns the string wrapper in Sequel blob object.  Often b
 
   "a\0".to_sequel_blob # SQL: X'6100'
 
-Alternative: Sequel.blob:
+Alternative:
 
   Sequel.blob("a\0")
 
@@ -257,12 +296,13 @@ Alternative: Sequel.blob:
 
 Array#~, Hash#~, and Symbol#~ treat the receiver as a conditions specifier, not matching all of the conditions:
 
-  ~{:a=>1, :b=>[2, 3]}     # SQL: a != 1 OR b NOT IN (2, 3)
+  ~{a: 1, b: [2, 3]}       # SQL: a != 1 OR b NOT IN (2, 3)
   ~[[:a, 1], [:b, [1, 2]]] # SQL: a != 1 OR b NOT IN (1, 2)
 
-Alternative: Sequel.~:
+Alternatives:
 
-   Sequel.~(:a=>1, :b=>[2, 3])
+   ~Sequel[a: 1, b: [2, 3]]
+   Sequel.~(a: 1, b: [2, 3])
 
 === Hash & Array
 
@@ -270,45 +310,45 @@ Alternative: Sequel.~:
 
 Array#case and Hash#case return an SQL CASE expression, where the keys are conditions and the values are results:
 
-  {{:a=>[2,3]}=>1}.case(0)   # SQL: CASE WHEN a IN (2, 3) THEN 1 ELSE 0 END
-  [[{:a=>[2,3]}, 1]].case(0) # SQL: CASE WHEN a IN (2, 3) THEN 1 ELSE 0 END
+  {{a: [2,3]} => 1}.case(0) # SQL: CASE WHEN a IN (2, 3) THEN 1 ELSE 0 END
+  [[{a: [2,3]}, 1]].case(0) # SQL: CASE WHEN a IN (2, 3) THEN 1 ELSE 0 END
 
-Alternative: Sequel.case:
+Alternative:
 
-  Sequel.case({{:a=>[2,3]}=>1}, 0)
+  Sequel.case({{a: [2,3]}=>1}, 0)
 
 ==== sql_expr
 
 Array#sql_expr and Hash#sql_expr treat the receiver as a conditions specifier, matching all of the conditions in the array.
 
-  {:a=>1, :b=>[2, 3]}.sql_expr     # SQL: a = 1 AND b IN (2, 3)
+  {a: 1, b: [2, 3]}.sql_expr     # SQL: a = 1 AND b IN (2, 3)
   [[:a, 1], [:b, [2, 3]]].sql_expr # SQL: a = 1 AND b IN (2, 3)
 
-Alternative: Sequel.expr:
+Alternative:
 
-  Sequel.expr(:a=>1, :b=>[2, 3])
+  Sequel[a: 1, b: [2, 3]]
 
 ==== sql_negate
 
 Array#sql_negate and Hash#sql_negate treat the receiver as a conditions specifier, matching none of the conditions in the array:
 
-  {:a=>1, :b=>[2, 3]}.sql_negate     # SQL: a != 1 AND b NOT IN (2, 3)
+  {a: 1, b: [2, 3]}.sql_negate       # SQL: a != 1 AND b NOT IN (2, 3)
   [[:a, 1], [:b, [2, 3]]].sql_negate # SQL: a != 1 AND b NOT IN (2, 3)
 
-Alternative: Sequel.negate:
+Alternative:
 
-  Sequel.negate(:a=>1, :b=>[2, 3])
+  Sequel.negate(a: 1, b: [2, 3])
 
 ==== sql_or
 
 Array#sql_or nd Hash#sql_or treat the receiver as a conditions specifier, matching any of the conditions in the array:
 
-  {:a=>1, :b=>[2, 3]}.sql_or     # SQL: a = 1 OR b IN (2, 3)
+  {a: 1, b: [2, 3]}.sql_or       # SQL: a = 1 OR b IN (2, 3)
   [[:a, 1], [:b, [2, 3]]].sql_or # SQL: a = 1 OR b IN (2, 3)
 
-Alternative: Sequel.or:
+Alternative:
 
-  Sequel.or(:a=>1, :b=>[2, 3])
+  Sequel.or(a: 1, b: [2, 3])
 
 === Array
 
@@ -316,10 +356,10 @@ Alternative: Sequel.or:
 
 Array#sql_value_list wraps the array in an array subclass, which Sequel will always treat as a value list and not a conditions specifier.  By default, Sequel treats arrays of two element arrays as a conditions specifier.
 
-  DB[:a].filter('(a, b) IN ?', [[1, 2], [3, 4]]) # SQL: (a, b) IN ((1 = 2) AND (3 = 4))
-  DB[:a].filter('(a, b) IN ?', [[1, 2], [3, 4]].sql_value_list) # SQL: (a, b) IN ((1, 2), (3, 4))
+  DB[:a].where('(a, b) IN ?', [[1, 2], [3, 4]])                # SQL: (a, b) IN ((1 = 2) AND (3 = 4))
+  DB[:a].where('(a, b) IN ?', [[1, 2], [3, 4]].sql_value_list) # SQL: (a, b) IN ((1, 2), (3, 4))
 
-Alternative: Sequel.value_list:
+Alternative:
 
   Sequel.value_list([[1, 2], [3, 4]])
 
@@ -327,12 +367,12 @@ Alternative: Sequel.value_list:
 
 Array#sql_string_join joins all of the elements in the array in an SQL string concatentation expression:
 
-  [:a].sql_string_join # SQL: a
-  [:a, :b].sql_string_join # SQL: a || b
-  [:a, 'b'].sql_string_join # SQL: a || 'b'
+  [:a].sql_string_join           # SQL: a
+  [:a, :b].sql_string_join       # SQL: a || b
+  [:a, 'b'].sql_string_join      # SQL: a || 'b'
   ['a', :b].sql_string_join(' ') # SQL: 'a' || ' ' || b
 
-Alternative: Sequel.join:
+Alternative:
 
   Sequel.join(['a', :b], ' ')
 
@@ -342,23 +382,24 @@ Alternative: Sequel.join:
 
 Hash#& and Symbol#& return a Sequel boolean expression, matching the condition specified by the receiver and the condition specified by the given argument:
 
-  :a & :b         # SQL: a AND b
-  {:a=>1} & :b    # SQL: a = 1 AND b
-  {:a=>true} & :b # SQL: a IS TRUE AND b
+  :a & :b        # SQL: a AND b
+  {a: 1} & :b    # SQL: a = 1 AND b
+  {a: true} & :b # SQL: a IS TRUE AND b
 
-Alternative: Sequel.&:
+Alternatives:
 
-  Sequel.&({:a=>1}, :b)
+  Sequel[a: 1] & :b
+  Sequel.&({a: 1}, :b)
 
 ==== |
 
 Hash#| returns a Sequel boolean expression, matching the condition specified by the receiver or the condition specified by the given argument:
 
-  :a | :b         # SQL: a OR b
-  {:a=>1} | :b    # SQL: a = 1 OR b
-  {:a=>true} | :b # SQL: a IS TRUE OR b
-
-Alternative: Sequel.|:
+  :a | :b        # SQL: a OR b
+  {a: 1} | :b    # SQL: a = 1 OR b
+  {a: true} | :b # SQL: a IS TRUE OR b
 
-  Sequel.|({:a=>1}, :b)
+Alternative:
 
+  Sequel[a: 1] | :b
+  Sequel.|({a: 1}, :b)

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