sequel 1.2 → 1.3

data/README

@@ -1,6 +1,6 @@
-== Sequel: Concise ORM for Ruby
+== Sequel: The Database Toolkit for Ruby
 
-Sequel is an ORM framework for Ruby. Sequel provides thread safety, connection pooling, and a concise DSL for constructing queries and table schemas.
+Sequel is a database access toolkit for Ruby. Sequel provides thread safety, connection pooling, and a concise DSL for constructing queries and table schemas.
 
 Sequel makes it easy to deal with multiple records without having to break your teeth on SQL.
 
@@ -23,11 +23,7 @@ If you have any comments or suggestions please send an email to ciconia at gmail
 == Installation
 
   sudo gem install sequel
-
-If you don't need to use Sequel models you can just install the sequel_core gem, which includes all database adapters and dataset functionality:
-
-  sudo gem install sequel_core
-
+  
 == Supported Databases
 
 Sequel currently supports:
@@ -53,7 +49,7 @@ You get an IRB session with the database object stored in DB.
 
 == An Introduction
 
-Sequel was designed to take the hassle away from connecting to databases and manipulating them. Sequel deals with all the boring stuff like maintaining connections, formatting SQL correctly and fetching records so you can concentrate on your application.
+Sequel is designed to take the hassle away from connecting to databases and manipulating them. Sequel deals with all the boring stuff like maintaining connections, formatting SQL correctly and fetching records so you can concentrate on your application.
 
 Sequel uses the concept of datasets to retrieve data. A Dataset object encapsulates an SQL query and supports chainability, letting you fetch data using a convenient Ruby DSL that is both concise and infinitely flexible.
 
@@ -78,4 +74,178 @@ Or getting results as a transposed hash, with one column as key and another as v
 
   middle_east.to_hash(:name, :area) #=> {'Israel' => 20000, 'Greece' => 120000, ...}
 
-You can find more information on getting started with Sequel {here}[http://code.google.com/p/ruby-sequel/wiki/GettingStarted]
+Much of Sequel is still undocumented (especially the part relating to model classes). The following section provides examples of common usage. Feel free to explore...
+
+== Getting Started
+
+=== Connecting to a database
+
+To connect to a database you simply provide Sequel with a URL:
+
+  require 'sequel'
+  DB = Sequel.open 'sqlite:///blog.db'
+  
+The connection URL can also include such stuff as the user name and password:
+
+  DB = Sequel.open 'postgres://cico:12345@localhost:5432/mydb'
+
+You can also specify optional parameters, such as the connection pool size, or a logger for logging SQL queries:
+
+  DB = Sequel.open("postgres://postgres:postgres@localhost/my_db",
+    :max_connections => 10, :logger => Logger.new('log/db.log'))
+
+=== Arbitrary SQL queries
+
+  DB.execute("create table t (a text, b text)")
+  DB.execute("insert into t values ('a', 'b')")
+
+Or more succinctly:
+
+  DB << "create table t (a text, b text)"
+  DB << "insert into t values ('a', 'b')"
+
+=== Getting Dataset Instances
+
+Dataset is the primary means through which records are retrieved and manipulated. You can create an blank dataset by using the dataset method:
+
+  dataset = DB.dataset
+
+Or by using the from methods:
+
+  posts = DB.from(:posts)
+
+You can also use the equivalent shorthand:
+
+  posts = DB[:posts]
+
+Note: the dataset will only fetch records when you explicitly ask for them, as will be shown below. Datasets can be manipulated to filter through records, change record order and even join tables, as will also be shown below.
+
+=== Retrieving Records
+
+You can retrieve records by using the all method:
+
+  posts.all
+
+The all method returns an array of hashes, where each hash corresponds to a record.
+
+You can also iterate through records one at a time:
+
+  posts.each {|row| p row}
+
+Or perform more advanced stuff:
+
+  posts.map(:id)
+  posts.inject({}) {|h, r| h[r[:id]] = r[:name]}
+  
+You can also retrieve the first record in a dataset:
+
+  posts.first
+  
+Or retrieve a single record with a specific value:
+
+  posts[:id => 1]
+  
+If the dataset is ordered, you can also ask for the last record:
+
+  posts.order(:stamp).last
+  
+=== Filtering Records
+
+The simplest way to filter records is to provide a hash of values to match:
+
+  my_posts = posts.filter(:category => 'ruby', :author => 'david')
+  
+You can also specify ranges:
+
+  my_posts = posts.filter(:stamp => (2.weeks.ago)..(1.week.ago))
+  
+Or lists of values:
+
+  my_posts = posts.filter(:category => ['ruby', 'postgres', 'linux'])
+  
+Sequel now also accepts expressions as closures, AKA block filters:
+
+  my_posts = posts.filter {:category == ['ruby', 'postgres', 'linux']}
+  
+Which also lets you do stuff like:
+
+  my_posts = posts.filter {:stamp > 1.month.ago}
+  
+Some adapters (like postgresql) will also let you specify Regexps:
+
+  my_posts = posts.filter(:category => /ruby/i)
+  
+You can also use an inverse filter:
+
+  my_posts = posts.exclude(:category => /ruby/i)
+
+You can then retrieve the records by using any of the retrieval methods:
+
+  my_posts.each {|row| p row}
+  
+You can also specify a custom WHERE clause:
+
+  posts.filter('(stamp < ?) AND (author <> ?)', 3.days.ago, author_name)
+
+Datasets can also be used as subqueries:
+
+  DB[:items].filter('price > ?', DB[:items].select('AVG(price) + 100'))
+
+=== Summarizing Records
+
+Counting records is easy:
+  posts.filter(:category => /ruby/i).count
+
+And you can also query maximum/minimum values:
+  max_value = DB[:history].max(:value)
+  
+Or calculate a sum:
+  total = DB[:items].sum(:price)
+  
+=== Ordering Records
+
+  posts.order(:stamp)
+  
+You can also specify descending order
+
+  posts.order(:stamp.DESC)
+
+=== Deleting Records
+
+  posts.filter('stamp < ?', 3.days.ago).delete
+  
+=== Inserting Records
+
+  posts.insert(:category => 'ruby', :author => 'david')
+  
+Or alternatively:
+
+  posts << {:category => 'ruby', :author => 'david'}
+  
+=== Updating Records
+
+  posts.filter('stamp < ?', 3.days.ago).update(:state => 'archived')
+
+=== Joining Tables
+
+Joining is very useful in a variety of scenarios, for example many-to-many relationships. With Sequel it's really easy:
+
+  order_items = DB[:items].join(:order_items, :item_id => :id).
+    filter(:order_items__order_id => 1234)
+  
+This is equivalent to the SQL:
+
+  SELECT * FROM items LEFT OUTER JOIN order_items
+  ON order_items.item_id = items.id 
+  WHERE order_items.order_id = 1234
+
+You can then do anything you like with the dataset:
+
+  order_total = order_items.sum(:price)
+  
+Which is equivalent to the SQL:
+
+  SELECT sum(price) FROM items LEFT OUTER JOIN order_items
+  ON order_items.item_id = items.id
+  WHERE order_items.order_id = 1234
+  

data/Rakefile

@@ -9,7 +9,7 @@ include FileUtils
 # Configuration
 ##############################################################################
 NAME = "sequel"
-VERS = "1.2"
+VERS = "1.3"
 CLEAN.include ["**/.*.sw?", "pkg/*", ".config", "doc/*", "coverage/*"]
 RDOC_OPTS = [
   "--quiet", 
@@ -29,7 +29,7 @@ task :package => [:clean]
 
 RDOC_OPTS = [
   "--quiet", 
-  "--title", "Sequel Model: Lightweight ORM for Ruby",
+  "--title", "Sequel Model: The Database Toolkit for Ruby",
   "--opname", "index.html",
   "--line-numbers", 
   "--main", "README",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: sequel
 version: !ruby/object:Gem::Version 
-  version: "1.2"
+  version: "1.3"
 platform: ruby
 authors: 
 - Sharon Rosner
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-02-29 00:00:00 +02:00
+date: 2008-03-08 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency