colincasey-sequel 2.10.0 → 2.10.1

data/doc/cheat_sheet.rdoc

@@ -0,0 +1,223 @@
+= 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.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 WHERE name = ?", name]
+  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(0){|sum, r| sum + r[:value]}
+
+== 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])
+
+  # 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
+
+  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
+
+== 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.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, :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___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(:items) => [[:id, {:type=>:integer, ...}], [:name, {:type=>:string, ...}], ...]
+                       # Works on PostgreSQL, MySQL, SQLite, and JDBC

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 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'"
+
+=== 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, without using a block:
+
+  items.filter(:price * 2 < 50).sql
+  #=> "SELECT * FROM items WHERE ((price * 2) < 50) 
+
+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{|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 => 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/doc/prepared_statements.rdoc

@@ -0,0 +1,104 @@
+= Prepared Statements and Bound Variables
+
+Starting with version 2.4.0, Sequel has support for prepared statements and
+bound variables.  No matter which database you are using, the Sequel prepared
+statement/bound variable API remains exactly the same.  There is native support
+for prepared statements/bound variables on the following databases:
+
+* PostgreSQL (using the pg driver, requires type specifiers)
+* MySQL (prepared statements only, as the ruby mysql driver doesn't support
+  bound variables)
+* SQLite (a new native prepared statement is used for each call, though)
+* JDBC (using the postgresql, mysql, or sqlite databases, and possibly others)
+
+Support on other databases is emulated via the usual string interpolation.
+
+== Placeholders
+
+Generally, when using prepared statements (and certainly when using bound
+variables), you need to put placeholders in your SQL to indicate where you
+want your bound arguments to appear.  Database support and syntax vary
+significantly for placeholders (e.g. :name, $1, ?).  Sequel abstracts all of
+that and allows you to specify placeholders by using the :$name format for
+placeholders, e.g.:
+
+  ds = DB[:items].filter(:name=>:$name)
+
+== Bound Variables
+
+Using bound variables for this query is simple:
+
+  ds.call(:select, :name=>'Jim')
+
+This will do the equivalent of selecting records that have the name 'Jim'. It
+returns all records, and can take a block that is passed to Dataset#all.
+
+Deleting or returning the first record works similarly:
+
+  ds.call(:first, :name=>'Jim') # First record with name 'Jim'
+  ds.call(:delete, :name=>'Jim') # Delete records with name 'Jim'
+
+For inserting/updating records, you should also specify a value hash, which
+may itself contain placeholders:
+
+  # Insert record with 'Jim', note that the previous filter is ignored
+  ds.call(:insert, {:name=>'Jim'}, :name=>:$name)
+  # Change name to 'Bob' for all records with name of 'Jim'
+  ds.call(:update, {:name=>'Jim', :new_name=>'Bob'}, :name=>$:new_name)
+
+== Prepared Statements
+
+Prepared statement support is similar to bound variable support, but you
+use Dataset#prepare with a name, and Dataset#call later with the values:
+
+  ds = DB[:items].filter(:name=>:$name)
+  ps = ds.prepare(:select, :select_by_name)
+  ps.call(:name=>'Jim')
+  DB.call(:select_by_name, :name=>'Jim') # same as above
+
+The Dataset#prepare method returns a prepared statement, and also stores a
+copy of the prepared statement in the database for later use.  For insert
+and update queries, the hash to insert/update is passed to prepare:
+
+  ps1 = DB[:items].prepare(:insert, :insert_with_name, :name=>:$name)
+  ps1.call(:name=>'Jim')
+  DB.call(:insert_with_name, :name=>'Jim') # same as above
+  ds = DB[:items].filter(:name=>:$name)
+  ps2 = ds.prepare(:update, :update_name, :name=>:$new_name)
+  ps2.call(:name=>'Jim', :new_name=>'Bob')
+  DB.call(:update_name, :name=>'Jim', :new_name=>'Bob') # same as above
+
+== Database support
+
+=== PostgreSQL
+
+If you are using the ruby-postgres or postgres-pr driver, PostgreSQL uses the
+default emulated support.  If you are using ruby-pg, there is native support,
+but it requires type specifiers most of the time.  This is easy if you have
+direct control over the SQL string, but since Sequel abstracts that, the types
+have to be specified another way.  This is done by adding a __* suffix to the
+placeholder symbol (e.g. :$name__text, which will be compiled to "$1::text"
+in the SQL).  Prepared statements are always server side.
+
+=== SQLite
+
+SQLite supports bound variables and prepared statements exactly the same, since
+a new native prepared statement is created and executed for each call.
+
+=== MySQL
+
+The MySQL ruby driver does not support bound variables, so the the bound
+variable methods fall back to string interpolation.  It uses server side
+prepared statements.
+
+=== JDBC
+
+JDBC supports both prepared statements and bound variables.  Whether these
+are server side or client side depends on the JDBC driver.  For PostgreSQL
+over JDBC, you can add the prepareThreshold=N parameter to the connection
+string, which will use a server side prepared statement after N calls to
+the prepared statement.
+
+=== All Others
+
+Support is emulated using interpolation.

data/doc/release_notes/1.0.txt

@@ -0,0 +1,38 @@
+=== New code organization
+
+Sequel is now divided into two parts: sequel_core and sequel_model.
+These two parts are distributed as two separate gems. The sequel gem
+bundles sequel_core and sequel_model together. If you don't use
+Sequel::Model in your code, you can just install and use sequel_core.
+
+=== New model hooks implementation
+
+The hooks implementation have been rewritten from scratch, is much
+more robust and offers a few new features:
+
+* More ways to define hooks: hooks can now be defined by supplying a
+block or a method name, or by overriding the hook instance method.
+
+* Inheritable hooks: Hooks can now be inherited, which means that you
+can define general hooks in a model superclass, and use them in
+subclasses. You can also define global hooks on Sequel::Model that
+will be invoked for all model classes.
+
+* Hook chains can be broken by returning false from within the hook.
+
+* New after_initialize hook, invoked after instance initialization.
+
+* The hook invocation order can no longer be changed. Hooks are
+invoked in order of definition, from the top of the class hierarchy
+(that is, from Sequel::Model) down to the specific class.
+
+=== Miscellanea
+
+* Removed deprecated adapter stubs, and all other deprecations in both
+sequel_core and sequel_model.
+
+* Fixed String#to_time to raise error correctly for invalid time
+stamps.
+
+* Fixed error behavior when parse_tree or ruby2ruby are not available.
+

data/doc/release_notes/1.1.txt

@@ -0,0 +1,143 @@
+=== DRY Sequel models
+
+With the new Sequel release you no longer need to explicitly specify
+the table
+name for each model class, assuming your model name is the singular of
+the
+table name (just like in ActiveRecord or DataMapper):
+
+  class UglyBug < Sequel::Model
+  end
+
+  UglyBug.table_name #=> :ugly_bugs
+
+=== New model validations and support for virtual attributes
+
+Sequel model now include validation functionality which largly follows
+the
+validations offered in ActiveRecord. Validations can be checked
+anytime by
+calling Model#valid?, with validation errors accessible through
+Model#errors:
+
+  class Item < Sequel::Model
+    validates_presence_of :name
+  end
+
+  my_item = Item.new
+  my_item.valid? #=> false
+  my_item.errors.full_messages #=> ["name is not present"]
+
+The Model#save method has been changed to check for validity before
+saving. If
+the model instance is not valid, the #save method returns false
+without saving
+the instance. You can also bypass the validity test by calling
+Model#save!
+instead.
+
+Model classes also now support virtual attributes, letting you assign
+values to
+any attribute (virtual or persistent) at initialization time:
+
+  class User < Sequel::Model
+    attr_accessor :password
+  end
+
+  u = User.new(:password => 'blah', ...)
+  u.password #=> 'blah'
+
+Also, virtual attributes can be validated just like persistent
+attributes.
+
+=== Other changes (long list!)
+
+* Added Model#reload as alias to Model#refresh.
+
+* Changed Model.create to accept a block (#126).
+
+* Fixed Model#initialize to accept nil values (#115).
+
+* Added Model#update_with_params method with support for virtual
+attributes and auto-filtering of unrelated parameters, and changed
+Model.create_with_params to support virtual attributes (#128).
+
+* Fixed Model.dataset to correctly set the dataset if using implicit
+naming or inheriting the superclass dataset (thanks celldee).
+
+* Finalized support for virtual attributes.
+
+* Fixed Model#set to work with string keys (#143).
+
+* Fixed Model.create to correctly initialize instances marked as new
+(#135).
+
+* Fixed Model#initialize to convert string keys into symbol keys. This
+also fixes problem with validating objects initialized with string
+keys (#136).
+
+* Added Dataset#table_exists? convenience method.
+
+* Changed Dataset#group_and_count to accept multiple columns (#134).
+
+* Added Dataset#select_all method.
+
+* Added Dataset#select_more, Dataset#order_more methods (#129).
+
+* Fixed Dataset#count to work correctly for grouped datasets (#144).
+
+* Fixed joining datasets using aliased tables (#140).
+
+* Added support for UNSIGNED constraint, used in MySQL? (#127).
+
+* Implemented constraint definitions inside Database#create_table.
+
+* Enhanced Database.connect to accept options with string keys, so it
+can now accept options loaded from YAML files. Database.connect also
+automatically converts :username option into :user for compatibility
+with existing YAML configuration files for AR and DataMapper.
+
+* Changed ODBC::Database to support connection using driver and
+database name, also added support for untitled columns in
+ODBC::Dataset (thanks Leonid Borisenko).
+
+* Changed MySQL adapter to support specifying socket option.
+
+* Fixed MySQL adapter to correctly format foreign key definitions
+(#123).
+
+* Changed MySQL::Dataset to allow HAVING clause on ungrouped datasets,
+and put HAVING clause before ORDER BY clause (#133).
+
+* Changed mysql adapter to default to localhost if :host option is not
+specified (#114).
+
+* Added String#to_date. Updated mysql adapter to use String#to_date
+for mysql date types (thanks drfreeze).
+
+* Fixed postgres adapter to define PGconn#async_exec as alias to #exec
+if not defined (for pure-ruby postgres driver).
+
+* Changed postgres adapter to quote column references using double
+quotes.
+
+* Applied patch for oracle adapter: fix behavior of limit and offset,
+transactions, #table_exists?, #tables and additional specs (thanks
+Liming Lian #122).
+
+* Added support additional field types in postgresql adapter (#146).
+
+* Added support for date field types in postgresql adapter (#145).
+
+* Added support for limiting and paginating datasets with fixed SQL,
+e.g. using Database#fetch.
+
+* Added new Dataset#from_self method that returns a dataset selecting
+from the original dataset.
+
+* Allow for additional filters on a grouped dataset (#119 and #120)
+
+* Refactored Sequelizer to use Proc#to_sexp (method provided by r2r).
+
+* Fixed bin/sequel to require sequel_model if available.
+