sequel_core 1.5.1 → 2.0.0

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,257 @@
+= 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 expressions with blocks
+
+Most SQL expressions that you can can create with expressions you can also express inside blocks.  This was previously the only way to specify expressions using ruby code.  Filtering with blocks requires that you install ParseTree, ruby2ruby, and their dependencies.  It's slower than using the equivalent expression without a block, and the syntax inside the block is different in some cases. Because it requires ParseTree, it can only be used with MRI (Matz's Ruby Interpreter) 1.8.*, as ParseTree doesn't run on any other ruby implementation (blockless filters should work on other ruby implementations).
+
+In general, filtering with a block should only be used with legacy code.  While it is not officially deprecated, usage of blocks when filtering is discouraged.
+
+To filter with a block, supply a block to filter with the appropriate ruby code:
+
+  items.filter{:price < 100}.sql
+  #=> "SELECT * FROM items WHERE (price < 100) 
+
+Sequel is smart enough to literalize values correctly, even if you compare against arrays or ranges:
+
+  items.filter{:category == 'ruby'}.sql
+  #=> "SELECT * FROM items WHERE (category = 'ruby')"
+
+  items.filter{:category == ['ruby', 'other']}.sql
+  #=> "SELECT * FROM items WHERE (category IN ('ruby', 'other'))"
+
+  items.filter{:price == (100..200)}.sql
+  #=> "SELECT * FROM items WHERE (price >= 100 AND price <= 200)"
+
+=== Negating conditions
+
+You can use the negation operator (!) anywhere:
+
+  items.filter{:category != 'ruby'}.sql
+  #=> "SELECT * FROM items WHERE NOT (category = 'ruby')"
+
+  items.filter{!:active}.sql
+  #=> "SELECT * FROM items WHERE (active = 'f')"
+
+=== 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))"
+
+=== Concatenating conditions with logical operators
+
+Expressions can be nested and combined using logical operators:
+
+  items.filter{(:price < 100 && :age < 27) || :category == 'ruby'}.sql
+  #=> "SELECT * FROM items WHERE (((price < 100) AND (age < 27)) OR (category = 'ruby'))"
+
+Another way to concatenate conditions is to specify each condition as a separate statement:
+
+  items.filter do
+    :price < 100
+    :category == 'ruby'
+  end.sql
+  #=> "SELECT * FROM items WHERE ((price < 100) AND (category = 'ruby'))"
+
+=== Special methods
+
+Inside blocks, Sequel recognizes the special methods nil/nil?, in/in? and like/like?:
+
+  items.filter{:price.nil?}.sql
+  #=> "SELECT * FROM items WHERE (price IS NULL)"
+
+  items.filter{:category.in ['ruby', 'other']}.sql
+  #=> "SELECT * FROM items WHERE (category IN ('ruby', 'other'))"
+
+  items.filter{:price.in 100..200}.sql
+  #=> "SELECT * FROM items WHERE (price >= 100 AND price <= 200)"
+
+  items.filter{:category.like 'ruby%'}.sql
+  #=> "SELECT * FROM items WHERE (category LIKE 'ruby%')"
+
+== 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.

data/lib/sequel_core/adapters/adapter_skeleton.rb

@@ -18,7 +18,7 @@ module Sequel
       end
       
       def execute(sql)
-        @logger.info(sql) if @logger
+        log_info(sql)
         @pool.hold {|conn| conn.exec(sql)}
       end
       
@@ -30,6 +30,8 @@ module Sequel
         case v
         when Time
           literal(v.iso8601)
+        when Date, DateTime
+          literal(v.to_s)
         else
           super
         end
@@ -65,4 +67,4 @@ module Sequel
       end
     end
   end
-end
+end

data/lib/sequel_core/adapters/ado.rb

@@ -36,7 +36,7 @@ module Sequel
       end
     
       def execute(sql)
-        @logger.info(sql) if @logger
+        log_info(sql)
         @pool.hold {|conn| conn.Execute(sql)}
       end
       
@@ -48,6 +48,8 @@ module Sequel
         case v
         when Time
           literal(v.iso8601)
+        when Date, DateTime
+          literal(v.to_s)
         else
           super
         end

data/lib/sequel_core/adapters/db2.rb

@@ -54,7 +54,7 @@ module Sequel
       end
       
       def execute(sql, &block)
-        @logger.info(sql) if @logger
+        log_info(sql)
         @pool.hold do |conn|
           rc, sth = SQLAllocHandle(SQL_HANDLE_STMT, @handle) 
           check_error(rc, "Could not allocate statement")
@@ -82,6 +82,8 @@ module Sequel
         case v
         when Time
           literal(v.iso8601)
+        when Date, DateTime
+          literal(v.to_s)
         else
           super
         end
@@ -155,4 +157,4 @@ module Sequel
       end
     end
   end
-end
+end