sequel 2.2.0 → 2.3.0

data/bin/sequel

@@ -0,0 +1,106 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'optparse'
+require 'sequel'
+
+db_opts = {}
+echo = nil
+env = nil
+logfile = nil
+migrate_dir = nil
+migrate_ver = nil
+
+opts = OptionParser.new do |opts|
+  opts.banner = "Sequel: The Database Toolkit for Ruby"
+  opts.define_head "Usage: sequel <uri|path> [options]"
+  opts.separator ""
+  opts.separator "Examples:"
+  opts.separator "  sequel sqlite://blog.db"
+  opts.separator "  sequel postgres://localhost/my_blog"
+  opts.separator "  sequel config/database.yml"
+  opts.separator ""
+  opts.separator "For more information see http://sequel.rubyforge.org"
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on_tail("-?", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+
+  opts.on("-l", "--log logfile", "log SQL statements to log file") do |v|
+    logfile = v
+  end
+  
+  opts.on("-e", "--env ENV", "use environment config for database") do |v|
+    env = v
+  end
+  
+  opts.on("-E", "--echo", "echo SQL statements") do
+    echo = true
+  end
+  
+  opts.on("-m", "--migrate-directory DIR", "run the migrations in directory") do |v|
+    migrate_dir = v
+  end
+  
+  opts.on("-M", "--migrate-version VER", "migrate the database to version given") do |v|
+    migrate_ver = Integer(v)
+  end
+  
+  opts.on_tail("-v", "--version", "Show version") do
+    class << Gem; attr_accessor :loaded_specs; end
+    begin
+      specs = Gem.loaded_specs['sequel']
+      puts "sequel #{specs.version} (#{specs.date.strftime '%Y-%m-%d'})"
+    rescue
+      puts "No gem version found"
+    end
+    exit
+  end
+end
+opts.parse!
+
+db = ARGV.shift
+
+if db.blank?
+  puts opts
+  exit 1
+end
+
+if logfile || echo
+  require 'logger'
+  db_opts[:loggers] = []
+  db_opts[:loggers] << Logger.new(logfile) if logfile
+  db_opts[:loggers] << Logger.new($stdout) if echo
+end
+
+if File.exist?(db)
+  require 'yaml'
+  db_config = YAML.load_file(db)[env || "development"]
+  db_config.each {|(k,v)| db_config[k.to_sym] = db_config.delete(k)}
+  db_config.merge!(db_opts)
+end
+
+begin
+  if db_config
+    opts = [db_config]
+  else
+    opts = [db, db_opts]
+  end
+  DB = Sequel.connect(*opts)
+  DB.test_connection
+  if migrate_dir
+    Sequel::Migrator.apply(DB, migrate_dir, migrate_ver)
+    exit
+  end
+rescue => e
+  puts e.message
+  puts e.backtrace.first
+  exit 1
+end
+
+require 'irb'
+puts "Your database is stored in DB..."
+IRB.start

data/doc/cheat_sheet.rdoc

@@ -0,0 +1,225 @@
+= Cheat Sheet   
+
+== Open a database
+
+  require 'rubygems'
+  require 'sequel'
+
+  DB = Sequel.sqlite 'my_blog.db'
+  DB = Sequel('postgres://user:password@localhost/my_db')
+  DB = Sequel.mysql '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 RAM.
+
+  DB = Sequel.sqlite
+
+== Logging SQL statements
+
+  require 'logger'
+  DB = Sequel.sqlite '', :loggers => [Logger.new($stdout)]
+  # or
+  DB.loggers << Logger.new(...)
+
+== Using raw SQL
+
+  DB << "CREATE TABLE users (name VARCHAR(255) NOT NULL, age INT(3) NOT NULL)"
+  DB.fetch("SELECT name FROM users") do |row|
+    p r[:name]
+  end
+  dataset = DB["SELECT age FROM users"]
+  dataset.print
+  dataset.map(:age)
+
+== Create a dataset
+
+  dataset = DB[:items]
+  dataset = DB.dataset.from(:items)
+
+== Most dataset methods are chainable
+
+  dataset = DB[:managers].where(:salary => 5000..10000).order(:name, :department)
+  # or
+  dataset = DB.query do
+    from :managers
+    where :salary => 5000..10000
+    order :name, :department
+  end
+
+== Insert rows
+
+  dataset.insert(:name => 'Sharon', :grade => 50)
+  dataset << {:name => 'Sharon', :grade => 50} # same effect as above
+
+== Retrieve rows
+
+  dataset.each {|r| p r}
+  dataset.all #=> [{...}, {...}, ...]
+  dataset.first
+  dataset.order(:name).last # works only for ordered datasets
+
+== Update/Delete rows
+
+  dataset.filter(:active => false).delete
+  dataset.filter('price < ?', 100).update(:active => true)
+
+== Datasets are Enumerable
+
+  dataset.map {|r| r[:name]}
+  dataset.map(:name) # same effect as above
+
+  dataset.inject {|sum, r| sum + r[:value]}
+
+== Filtering (see also doc/dataset_filtering.rdoc)
+
+  dataset.filter(:name => 'abc')
+  dataset.filter('name = ?', 'abc')
+  dataset.filter(:value > 100)
+  dataset.exclude(:value <= 100)
+
+  dataset.filter(:value => 50..100)
+  dataset.where((:value >= 50) & (:value <= 100))
+
+  dataset.where('value IN ?', [50,75,100])
+
+  # Get the first record that matches a condition
+  dataset[:name => 'abc'] # Same as:
+  dataset.filter(:name => 'abc').first
+
+  # Filter using a subquery
+  dataset.filter('price > ?', dataset.select('AVG(price) + 100'))
+
+=== Advanced filtering using ruby expressions without blocks
+
+Available as of Sequel 2.0:
+
+  DB[:items].filter(: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((:x > 5) & (: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(:price < :AVG[:price] + 100).sql 
+  #=> "SELECT * FROM items WHERE (price < (AVG(price) + 100))" 
+
+== 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
+
+== Pagination
+
+  paginated = dataset.paginate(1, 10) # first page, 10 rows per page
+  paginated.page_count #=> number of pages in dataset
+  paginated.current_page #=> 1
+  paginated.next_page #=> next page number or nil
+  paginated.prev_page #=> previous page number or nil
+  paginated.first_page? #=> true if page number = 1
+  paginated.last_page? #=> true if page number = page_count
+
+== Joins
+
+  DB[:items].left_outer_join(:categories, :id => :category_id).sql #=>
+    "SELECT * FROM items LEFT OUTER JOIN categories ON categories.id = items.category_id"
+
+== Summarizing
+
+  dataset.count #=> record count
+  dataset.max(:price)
+  dataset.min(:price)
+  dataset.avg(:price)
+  dataset.sum(:stock)
+
+  dataset.group(:category).select(:category, :AVG[:price])
+
+== SQL Functions / Literals
+
+  dataset.update(:updated_at => :NOW[])
+  dataset.update(:updated_at => 'NOW()'.lit)
+
+  dataset.update(:updated_at => "DateValue('1/1/2001')".lit)
+  dataset.update(:updated_at => :DateValue['1/1/2001'])
+
+== Schema Manipulation
+
+  DB.create_table :items do
+    primary_key :id
+    text :name, :unique => true, :null => false
+    boolean :active, :default => true
+    foreign_key :category_id, :categories
+    
+    index :grade
+  end
+
+  DB.drop_table :items
+
+  DB.create_table :test do
+    varchar :zipcode, :size => 10
+    enum :system, :elements => ['mac', 'linux', 'windows']
+  end
+
+== Aliasing
+
+  DB[:items].select(:name.as(:item_name))
+  DB[:items].select(:name => :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 << {:first_name => 'Inigo', :last_name => 'Montoya'}
+    dataset << {: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::Error::Rollback:
+
+  DB.transaction do
+    raise(Sequel::Error::Rollback) if something_bad_happened
+  end # ROLLBACK issued and no error raised
+
+Miscellaneous:
+
+  dataset.sql #=> "SELECT * FROM items"
+  dataset.delete_sql #=> "DELETE FROM items"
+  dataset.where(:name => 'sequel').exists #=> "EXISTS ( SELECT 1 FROM items WHERE name = 'sequel' )"
+  dataset.print #=> pretty table print to $stdout
+  dataset.columns #=> array of columns in the result set, does a SELECT
+  DB.schema_for_table(:items) => [[:id, {:type=>:integer, ...}], [:name, {:type=>:string, ...}], ...]
+                                 # Works on PostgreSQL, MySQL, SQLite, and possibly elsewhere

data/doc/dataset_filtering.rdoc

@@ -0,0 +1,182 @@
+= 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 do not wish to lose control over your SQL WHERE clauses, 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'"
+
+== An aside: column references in Sequel
+
+Sequel expects column names to be specified using symbols. In addition, tuples always use symbols as their keys. This allows you to freely mix literal values and column references. For example, the two following lines produce equivalent SQL:
+
+  items.filter(:x => 1) #=> "SELECT * FROM items WHERE (x = 1)"
+  items.filter(1 => :x) #=> "SELECT * FROM items WHERE (1 = x)"
+
+=== Qualifying column names
+
+Column references can be qualified by using the double underscore special notation :table__column:
+
+  items.literal(:items__price) #=> "items.price"
+
+=== Column aliases
+
+You can also alias columns by using the triple undersecore special notation :column___alias or :table__column___alias:
+
+  items.literal(:price___p) #=> "price AS p"
+  items.literal(:items__price___p) #=> "items.price AS p"
+
+Another way to alias columns is to use the #AS method:
+
+  items.literal(:price.as(:p)) #=> "price AS p"
+
+=== Specifying SQL functions
+
+Sequel also allows you to specify functions by using the Symbol#[] method:
+
+  items.literal(:avg[: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
+
+New in Sequel 2.0 is the ability to use ruby expressions directly in the call to filter, without using a block:
+
+  items.filter(:price < 100).sql
+  #=> "SELECT * FROM items WHERE (price < 100) 
+
+This works for the standard inequality and arithmetic operators:
+
+  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(:credit > :debit).sql
+  #=> "SELECT * FROM items WHERE (credit > debit)
+
+Or against SQL functions:
+
+  items.filter(:price < :max[:price] + 100).sql
+  #=> "SELECT * FROM items WHERE (price < (max(price) + 100))"
+
+== 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 => true).select(:consumer_id)
+  consumers.filter(:id => refs).sql
+  #=> "SELECT * FROM consumers WHERE (id IN (SELECT consumer_id FROM consumer_refs WHERE (logged_in = 't')))"
+
+Note that if you compare against a sub-query, you must select a single column in the sub-query.