viking-sequel 3.10.0

data/doc/cheat_sheet.rdoc

@@ -0,0 +1,218 @@
+= Cheat Sheet   
+
+== Open a database
+
+  require 'rubygems'
+  require 'sequel'
+
+  DB = Sequel.sqlite('my_blog.db')
+  DB = Sequel.connect('postgres://user:password@localhost/my_db')
+  DB = Sequel.postgres('my_db', :user => 'user', :password => 'password', :host => 'localhost')
+  DB = Sequel.ado('mydb')
+
+== Open an SQLite memory database
+
+Without a filename argument, the sqlite adapter will setup a new sqlite database in memory.
+
+  DB = Sequel.sqlite
+
+== Logging SQL statements
+
+  require 'logger'
+  DB = Sequel.sqlite '', :loggers => [Logger.new($stdout)]
+  # or
+  DB.loggers << Logger.new(...)
+
+== Using raw SQL
+
+  DB.run "CREATE TABLE users (name VARCHAR(255) NOT NULL, age INT(3) NOT NULL)"
+  dataset = DB["SELECT age FROM users WHERE name = ?", name]
+  dataset.map(:age)
+  DB.fetch("SELECT name FROM users") do |row|
+    p r[:name]
+  end
+
+== Create a dataset
+
+  dataset = DB[:items]
+  dataset = DB.from(:items)
+
+== Most dataset methods are chainable
+
+  dataset = DB[:managers].where(:salary => 5000..10000).order(:name, :department)
+
+== Insert rows
+
+  dataset.insert(:name => 'Sharon', :grade => 50)
+
+== Retrieve rows
+
+  dataset.each{|r| p r}
+  dataset.all #=> [{...}, {...}, ...]
+  dataset.first
+
+== Update/Delete rows
+
+  dataset.filter(~:active).delete
+  dataset.filter('price < ?', 100).update(:active => true)
+
+== Datasets are Enumerable
+
+  dataset.map{|r| r[:name]}
+  dataset.map(:name) # same as above
+
+  dataset.inject(0){|sum, r| sum + r[:value]}
+  dataset.sum(:value) # same as above
+
+== Filtering (see also doc/dataset_filtering.rdoc)
+
+  dataset.filter(:name => 'abc')
+  dataset.filter('name = ?', 'abc')
+
+  dataset.filter{|o| o.value > 100}
+  dataset.exclude{|o| o.value <= 100}
+
+  dataset.filter(:value => 50..100)
+  dataset.where{|o| (o.value >= 50) & (o.value <= 100)}
+
+  dataset.where('value IN ?', [50,75,100])
+  dataset.where(:value=>[50,75,100])
+
+  dataset.filter(:name => 'abc').first
+  dataset[:name => 'abc']
+
+  dataset.where('price > (SELECT avg(price) + 100 FROM table)')
+  dataset.filter{|o| o.price > dataset.select(o.avg(price) + 100)}
+
+=== Advanced filtering using ruby expressions
+
+  DB[:items].filter{|o| o.price < 100}.sql 
+  #=> "SELECT * FROM items WHERE (price < 100)" 
+
+  DB[:items].filter(:name.like('AL%')).sql 
+  #=> "SELECT * FROM items WHERE (name LIKE 'AL%')" 
+
+There's support for nested expressions with AND, OR and NOT:
+
+  DB[:items].filter{|o| (o.x > 5) & (o.y > 10)}.sql 
+  #=> "SELECT * FROM items WHERE ((x > 5) AND (y > 10))" 
+
+  DB[:items].filter({:x => 1, :y => 2}.sql_or & ~{:z => 3}).sql 
+  #=> "SELECT * FROM items WHERE (((x = 1) OR (y = 2)) AND (z != 3))"
+
+You can use arithmetic operators and specify SQL functions:
+
+  DB[:items].filter((:x + :y) > :z).sql 
+  #=> "SELECT * FROM items WHERE ((x + y) > z)" 
+
+  DB[:items].filter{|o| :price - 100 < o.avg(:price)}.sql 
+  #=> "SELECT * FROM items WHERE ((price - 100) < avg(price))" 
+
+== Ordering
+
+  dataset.order(:kind)
+  dataset.reverse_order(:kind)
+  dataset.order(:kind.desc, :name)
+
+== Row ranges
+
+  dataset.limit(30) # LIMIT 30
+  dataset.limit(30, 10) # LIMIT 30 OFFSET 10
+
+== Joins
+
+  DB[:items].left_outer_join(:categories, :id => :category_id).sql 
+  #=> "SELECT * FROM items LEFT OUTER JOIN categories ON categories.id = items.category_id"
+
+  DB[:items].join(:categories, :id => :category_id).join(:groups, :id => :items__group_id) 
+  #=> "SELECT * FROM items INNER JOIN categories ON categories.id = items.category_id INNER JOIN groups ON groups.id = items.group_id"
+	
+== Summarizing
+
+  dataset.count #=> record count
+  dataset.max(:price)
+  dataset.min(:price)
+  dataset.avg(:price)
+  dataset.sum(:stock)
+
+  dataset.group(:category).select(:category, :AVG.sql_function(:price))
+
+== SQL Functions / Literals
+
+  dataset.update(:updated_at => :NOW.sql_function)
+  dataset.update(:updated_at => 'NOW()'.lit)
+
+  dataset.update(:updated_at => "DateValue('1/1/2001')".lit)
+  dataset.update(:updated_at => :DateValue.sql_function('1/1/2001'))
+
+== Schema Manipulation
+
+  DB.create_table :items do
+    primary_key :id
+    String :name, :unique => true, :null => false
+    boolean :active, :default => true
+    foreign_key :category_id, :categories
+    Time :created_at
+    
+    index :grade
+  end
+
+  DB.drop_table :items
+
+  DB.create_table :test do
+    String :zipcode
+    enum :system, :elements => ['mac', 'linux', 'windows']
+  end
+
+== Aliasing
+
+  DB[:items].select(:name.as(:item_name))
+  DB[:items].select(:name___item_name)
+  DB[:items___items_table].select(:items_table__name___item_name)
+  # => "SELECT items_table.name AS item_name FROM items AS items_table"
+
+== Transactions
+
+  DB.transaction do
+    dataset.insert(:first_name => 'Inigo', :last_name => 'Montoya')
+    dataset.insert(:first_name => 'Farm', :last_name => 'Boy')
+  end # Either both are inserted or neither are inserted
+
+Database#transaction is re-entrant:
+
+  DB.transaction do # BEGIN issued only here
+    DB.transaction
+      dataset << {:first_name => 'Inigo', :last_name => 'Montoya'}
+    end
+  end # COMMIT issued only here
+
+Transactions are aborted if an error is raised:
+
+  DB.transaction do
+    raise "some error occurred"
+  end # ROLLBACK issued and the error is re-raised
+
+Transactions can also be aborted by raising Sequel::Rollback:
+
+  DB.transaction do
+    raise(Sequel::Rollback) if something_bad_happened
+  end # ROLLBACK issued and no error raised
+
+Savepoints can be used if the database supports it:
+
+  DB.transaction do
+    dataset << {:first_name => 'Farm', :last_name => 'Boy'} # Inserted
+    DB.transaction(:savepoint=>true) # This savepoint is rolled back
+      dataset << {:first_name => 'Inigo', :last_name => 'Montoya'} # Not inserted
+      raise(Sequel::Rollback) if something_bad_happened
+    end
+    dataset << {:first_name => 'Prince', :last_name => 'Humperdink'} # Inserted
+  end
+
+== Miscellaneous:
+
+  dataset.sql #=> "SELECT * FROM items"
+  dataset.delete_sql #=> "DELETE FROM items"
+  dataset.where(:name => 'sequel').exists #=> "EXISTS ( SELECT * FROM items WHERE name = 'sequel' )"
+  dataset.columns #=> array of columns in the result set, does a SELECT
+  DB.schema(:items) => [[:id, {:type=>:integer, ...}], [:name, {:type=>:string, ...}], ...]

data/doc/dataset_basics.rdoc

@@ -0,0 +1,106 @@
+= Dataset Basics 
+
+== Introduction
+
+Datasets are probably the thing that separate Sequel from other database libraries.  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.
+
+== Basics
+
+The most basic dataset is the simple selection of all columns in a table:
+
+  ds = DB[:posts]
+  # SELECT * FROM posts
+  
+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:
+
+  ds2 = ds.filter(:id=>1)
+  ds2
+  # SELECT * FROM posts WHERE id = 1
+  ds
+  # SELECT * FROM posts
+  
+Note how ds itself is not modified.  This is because ds.filter returns a modified copy of ds, instead of modifying ds itself.  This makes using datasets both thread safe and easy to chain:
+
+  # Thread safe:
+  100.times do |i|
+    Thread.new do
+      ds.filter(:id=>i).first
+    end
+  end
+  
+  # Easy to chain:
+  ds3 = ds.select(:id, :name).order(:name).filter{id < 100}
+  # SELECT id, name FROM posts WHERE id < 100 ORDER BY name
+
+Thread safety you don't really need to worry about, but chainability is core to how Sequel is generally used.  Almost all dataset methods that affect the SQL produced return modified copies of the receiving dataset.
+
+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}
+  
+  # Until you call a method that returns results
+  results = ds3.all
+  
+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
+  
+  # Bad
+  ds.all.select(:id, :name).order(:name).filter{id < 100}
+  
+This is because all will return an array of hashes, and select, order, and filter are dataset methods, not array methods.
+
+== Methods
+
+Most Dataset methods that users will use can be broken down into two types:
+
+* Methods that return modified datasets
+* Methods that execute code on the database
+
+=== Methods that return modified datasets
+
+Most dataset methods fall into this category, which can be further broken down by the clause they affect:
+
+SELECT:: select, select_all, select_append, select_more
+FROM:: from, from_self
+JOIN:: join, join_table, 
+WHERE:: where, filter, exclude, and, or, grep, invert, unfiltered
+GROUP:: group, group_by, group_and_count, ungrouped
+HAVING:: having, filter, exclude, and, or, grep, invert, unfiltered
+ORDER:: order, order_by, order_more, reverse, reverse_order, unordered
+LIMIT:: limit
+compounds:: union, intersect, except
+locking:: for_update, lock_style
+common table expressions:: with, with_recursive
+qualification:: qualify, qualify_to, qualify_to_first_source
+inserting:: set_defaults, set_overrides
+other:: clone, distinct, naked, 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, select_map, select_order_map, select_hash, to_csv
+SELECT (First Record):: first, last, get, [], empty?
+SELECT (Aggregates):: count, avg, max, min, sum, range, interval
+INSERT:: insert, <<, import, multi_insert, insert_multiple
+UPDATE:: update, set, []=
+DELETE:: delete
+other:: columns, columns!, truncate
+
+=== Other methods
+
+See the Sequel::Dataset RDoc for other methods that are less commonly used.

data/doc/dataset_filtering.rdoc

@@ -0,0 +1,158 @@
+= Dataset Filtering 
+
+Sequel offers unparalleled flexibility 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 #filter method:
+
+  items.filter('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.filter('category = ?', 'ruby').sql
+  #=> "SELECT * FROM items WHERE category = 'ruby'"
+
+=== Specifying SQL functions
+
+Sequel also allows you to specify functions by using the Symbol#sql_function method (and the Symbol#[] method on ruby 1.8):
+
+  items.literal(:avg.sql_function(:price)) #=> "avg(price)"
+
+== Filtering using a hash
+
+If you just need to compare records against values, you can supply a hash:
+
+  items.filter(:category => 'ruby').sql
+  #=> "SELECT * FROM items WHERE (category = 'ruby')"
+
+Sequel can check for null values:
+
+  items.filter(:category => nil).sql
+  #=> "SELECT * FROM items WHERE (category IS NULL)"
+
+Or compare two columns:
+
+  items.filter(:x => :some_table__y).sql
+  #=> "SELECT * FROM items WHERE (x = some_table.y)"
+
+And also compare against multiple values:
+
+  items.filter(:category => ['ruby', 'perl']).sql
+  #=> "SELECT * FROM items WHERE (category IN ('ruby', 'perl'))"
+
+Ranges (both inclusive and exclusive) can also be used:
+
+  items.filter(:price => 100..200).sql
+  #=> "SELECT * FROM items WHERE (price >= 100 AND price <= 200)"
+
+  items.filter(:price => 100...200).sql
+  #=> "SELECT * FROM items WHERE (price >= 100 AND price < 200)"
+
+== Filtering using expressions
+
+Sequel allows you to use ruby expressions directly in the call to filter:
+
+  items.filter(:price * 2 < 50).sql
+  #=> "SELECT * FROM items WHERE ((price * 2) < 50) 
+
+This works for the standard inequality and arithmetic operators (though you can't use the inequality operators directly on a symbol in ruby 1.9):
+
+  items.filter(:price + 100 < 200).sql
+  #=> "SELECT * FROM items WHERE ((price + 100) < 200) 
+
+  items.filter(:price - 100 > 200).sql
+  #=> "SELECT * FROM items WHERE ((price - 100) > 200) 
+
+  items.filter(:price * 100 <= 200).sql
+  #=> "SELECT * FROM items WHERE ((price * 100) <= 200) 
+
+  items.filter(:price / 100 >= 200).sql
+  #=> "SELECT * FROM items WHERE ((price / 100) >= 200) 
+
+You use the overloaded bitwise and (&) and or (|) operators to combine expressions:
+
+  items.filter((:price + 100 < 200) & (:price * 100 <= 200)).sql
+  #=> "SELECT * FROM items WHERE (((price + 100) < 200) AND ((price * 100) <= 200)) 
+
+  items.filter((: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 operators:
+
+  items.filter({: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.filter({:category => ['ruby', 'other']} | (:price - 100 > 200)).sql
+  #=> "SELECT * FROM items WHERE ((category IN ('ruby', 'other')) OR ((price - 100) <= 200))"
+
+  items.filter({:price => (100..200)} & :active).sql
+  #=> "SELECT * FROM items WHERE ((price >= 100 AND price <= 200) AND active)"
+
+=== Negating conditions
+
+You can use the negation operator (~) in most cases:
+
+  items.filter(~{:category => 'ruby'}).sql
+  #=> "SELECT * FROM items WHERE (category != 'ruby')"
+
+  items.filter{~:active}.sql
+  #=> "SELECT * FROM items WHERE NOT active"
+
+  items.filter(~(:price / 100 >= 200)).sql
+  #=> "SELECT * FROM items WHERE ((price / 100) < 200) 
+
+=== Comparing against column references
+
+You can also compare against other columns:
+
+  items.filter{|o| o.credit > :debit}.sql
+  #=> "SELECT * FROM items WHERE (credit > debit)
+
+Or against SQL functions:
+
+  items.filter{|o| :price - 100 < o.max(:price)}.sql
+  #=> "SELECT * FROM items WHERE ((price - 100) < max(price))"
+
+== String search functions
+
+You can search SQL strings using the #like method:
+
+  items.filter(:name.like('Acme%')).sql
+  #=> "SELECT * FROM items WHERE (name LIKE 'Acme%')"
+
+You can specify a Regexp as a like argument, but this will probably only work
+on PostgreSQL and MySQL:
+
+  items.filter(:name.like(/Acme.*/)).sql
+  #=> "SELECT * FROM items WHERE (name ~ 'Acme.*')"
+
+Like can also take more than one argument:
+
+  items.filter(:name.like('Acme%', /Beta.*/)).sql
+  #=> "SELECT * FROM items WHERE ((name LIKE 'Acme%') OR (name ~ 'Beta.*'))"
+
+== String concatenation
+
+You can concatenate SQL strings using Array#sql_string_join: 
+
+  items.filter([:name, :comment].sql_string_join.like('%acme%')).sql
+  #=> "SELECT * FROM items WHERE ((name || comment) LIKE 'Acme%')"
+
+Array#sql_string_join also takes a join argument:
+
+  items.filter([:name, :comment].sql_string_join(' ').like('%acme%')).sql
+  #=> "SELECT * FROM items WHERE ((name || ' ' || comment) LIKE 'Acme%')"
+
+== 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:
+
+  refs = consumer_refs.filter(:logged_in).select(:consumer_id)
+  consumers.filter(:id => refs).sql
+  #=> "SELECT * FROM consumers WHERE (id IN (SELECT consumer_id FROM consumer_refs WHERE logged_in))"
+
+Note that if you compare against a sub-query, you must select a single column in the sub-query.