sequel 0.0.1

data/CHANGELOG

@@ -0,0 +1,13 @@
+*0.0.1*
+
+* More documentation for Dataset.
+
+* Renamed Database#query to Database#dataset.
+
+* Added Dataset#insert_multiple for inserting multiple records.
+
+* Added Dataset#<< as shorthand for inserting records.
+
+* Added Database#<< method for executing arbitrary SQL.
+
+* Imported Sequel code.

data/COPYING

@@ -0,0 +1,18 @@
+Copyright (c) 2006 Sharon Rosner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+  
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+   
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,151 @@
+== about Sequel
+
+Sequel is an ORM framework for Ruby. Sequel provides thread safety, connection pooling, and a DSL for constructing queries and table schemas.
+
+== Sequel vs. ActiveRecord
+
+Sequel offers the following advantages over ActiveRecord:
+
+* Better performance with large tables: unlike ActiveRecord, Sequel does not load the entire resultset into memory, but fetches each record separately and implements an Enumerable interface.
+* Easy construction of queries using a DSL.
+* Using model classes is possible, but not mandatory.
+
+== Resources
+
+* {Project page}[http://code.google.com/p/ruby-sequel/]
+* {Source code}[http://ruby-sequel.googlecode.com/svn/]
+* {Bug tracking}[http://code.google.com/p/ruby-sequel/issues/list]
+* {RubyForge page}[http://rubyforge.org/projects/sequel/]
+
+To check out the source code:
+  
+  svn co http://ruby-sequel.googlecode.com/svn/trunk
+
+== Installation
+
+  sudo gem install sequel
+
+== A Short Tutorial
+
+=== Connecting to a database
+
+There are two ways to create a connection to a database. The easier way is to provide a connection URL:
+
+  DB = Sequel.connect("postgres://postgres:postgres@localhost:5432/my_db")
+
+You can also specify optional parameters, such as the connection pool size:
+
+  DB = Sequel.connect("postgres://postgres:postgres@localhost:5432/my_db",
+    :max_connections => 10)
+
+The second, more verbose, way is to create an instance of a database class:
+
+  DB = Sequel::Postgres::Database.new(:database => 'my_db', :host => 'localhost',
+    :port => 5432)
+
+== Arbitrary SQL queries
+
+  DB.execute("create table t (a text, b text)")
+  DB.execute("insert into t values ('a', 'b')")
+
+Or more succintly:
+
+  DB << "create table t (a text, b text)"
+  DB << "insert into t values ('a', 'b')"
+
+=== Creating Datasets
+
+Dataset is the primary means through which records are retrieved and manipulated. You can create an blank dataset by using the query method:
+
+  dataset = DB.query
+
+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
+  
+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)
+  
+Some adapters 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)
+  
+=== Counting Records
+
+  posts.count
+  
+=== 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')
+  
+=== 

data/Rakefile

@@ -0,0 +1,96 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'fileutils'
+include FileUtils
+
+NAME = "sequel"
+VERS = "0.0.1"
+CLEAN.include ['**/.*.sw?', 'pkg/*', '.config', 'doc/*', 'coverage/*']
+RDOC_OPTS = ['--quiet', '--title', "Sequel Documentation",
+  "--opname", "index.html",
+  "--line-numbers", 
+  "--main", "README",
+  "--inline-source"]
+
+desc "Packages up Sequel."
+task :default => [:package]
+task :package => [:clean]
+
+task :doc => [:rdoc]
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'doc/rdoc'
+  rdoc.options += RDOC_OPTS
+  rdoc.main = "README"
+  rdoc.title = "Sequel Documentation"
+  rdoc.rdoc_files.add ['README', 'COPYING', 'lib/sequel.rb', 'lib/sequel/**/*.rb']
+end
+
+spec = Gem::Specification.new do |s|
+  s.name = NAME
+  s.version = VERS
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "CHANGELOG", "COPYING"]
+  s.rdoc_options += RDOC_OPTS + 
+    ['--exclude', '^(examples|extras)\/', '--exclude', 'lib/sequel.rb']
+  s.summary = "ORM framework for Ruby."
+  s.description = s.summary
+  s.author = "Sharon Rosner"
+  s.email = 'ciconia@gmail.com'
+  s.homepage = 'http://code.google.com/p/ruby-sequel/'
+
+  s.add_dependency('metaid')
+  s.required_ruby_version = '>= 1.8.2'
+
+  s.files = %w(COPYING README Rakefile) + Dir.glob("{doc,spec,lib}/**/*")
+      
+  s.require_path = "lib"
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.need_tar = true
+  p.gem_spec = spec
+end
+
+task :install do
+  sh %{rake package}
+  sh %{sudo gem install pkg/#{NAME}-#{VERS}}
+end
+
+task :uninstall => [:clean] do
+  sh %{sudo gem uninstall #{NAME}}
+end
+
+desc 'Update docs and upload to rubyforge.org'
+task :doc_rforge do
+  sh %{rake doc}
+  sh %{scp -r doc/rdoc/* ciconia@rubyforge.org:/var/www/gforge-projects/sequel}
+end
+
+require 'spec/rake/spectask'
+
+desc "Run specs with coverage"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/*_spec.rb']
+  t.rcov = true
+end
+
+##############################################################################
+# Statistics
+##############################################################################
+
+STATS_DIRECTORIES = [
+  %w(Code   lib/),
+  %w(Spec   spec/)
+].collect { |name, dir| [ name, "./#{dir}" ] }.select { |name, dir| File.directory?(dir) }
+
+desc "Report code statistics (KLOCs, etc) from the application"
+task :stats do
+  require 'extra/stats'
+  verbose = true
+  CodeStatistics.new(*STATS_DIRECTORIES).to_s
+end
+

data/lib/sequel.rb

@@ -0,0 +1,13 @@
+dir = File.join(File.dirname(__FILE__), 'sequel')
+require File.join(dir, 'core_ext')
+require File.join(dir, 'database')
+require File.join(dir, 'connection_pool')
+require File.join(dir, 'schema')
+require File.join(dir, 'dataset')
+require File.join(dir, 'model')
+
+module Sequel #:nodoc:
+  def self.connect(url)
+    Database.connect(url)
+  end
+end

data/lib/sequel/connection_pool.rb

@@ -0,0 +1,65 @@
+require 'thread'
+
+module Sequel
+  class ConnectionPool
+    attr_reader :max_size, :mutex, :conn_maker
+    attr_reader :available_connections, :allocated, :created_count
+  
+    def initialize(max_size = 4, &block)
+      @max_size = max_size
+      @mutex = Mutex.new
+      @conn_maker = block
+
+      @available_connections = []
+      @allocated = {}
+      @created_count = 0
+    end
+    
+    def size
+      @created_count
+    end
+    
+    def hold
+      t = Thread.current
+      if (conn = owned_connection(t))
+        return yield(conn)
+      end
+      while !(conn = acquire(t))
+        sleep 0.001
+      end
+      begin
+        yield conn
+      ensure
+        release(t)
+      end
+    end
+    
+    def owned_connection(thread)
+      @mutex.synchronize {@allocated[thread]}
+    end
+    
+    def acquire(thread)
+      @mutex.synchronize do
+        @allocated[thread] ||= available
+      end
+    end
+    
+    def available
+      @available_connections.pop || make_new
+    end
+    
+    def make_new
+      if @created_count < @max_size
+        @created_count += 1
+        @conn_maker.call
+      end
+    end
+    
+    def release(thread)
+      @mutex.synchronize do
+        @available_connections << @allocated[thread]
+        @allocated.delete(thread)
+      end
+    end
+  end
+end

data/lib/sequel/core_ext.rb

@@ -0,0 +1,9 @@
+# Time extensions.
+class Time
+  SQL_FORMAT = "TIMESTAMP '%Y-%m-%d %H:%M:%S'".freeze
+  
+  # Formats the Time object as an SQL TIMESTAMP.
+  def to_sql_timestamp
+    strftime(SQL_FORMAT)
+  end
+end

data/lib/sequel/database.rb

@@ -0,0 +1,119 @@
+require 'uri'
+
+require File.join(File.dirname(__FILE__), 'schema')
+
+module Sequel
+  # A Database object represents a virtual connection to a database.
+  # The Database class is meant to be subclassed by database adapters in order
+  # to provide the functionality needed for executing queries.
+  class Database
+    # Constructs a new instance of a database connection with the specified
+    # options hash.
+    #
+    # Sequel::Database is an abstract class that is not useful by itself.
+    def initialize(opts = {})
+      @opts = opts
+    end
+
+    # Returns a new dataset with the from method invoked.
+    def from(*args); dataset.from(*args); end
+    
+    # Returns a new dataset with the select method invoked.
+    def select(*args); dataset.select(*args); end
+
+    # Returns a new dataset with the from parameter set. For example,
+    #   db[:posts].each {|p| puts p[:title]}
+    def [](table)
+      dataset.from(table)
+    end
+    
+    # call-seq:
+    #   db.execute(sql)
+    #   db << sql
+    #
+    # Executes an sql query.
+    def <<(sql)
+      execute(sql)
+    end
+
+    # Returns a literal SQL representation of a value. This method is usually
+    # overriden in database adapters.
+    def literal(v)
+      case v
+      when String: "'%s'" % v
+      else v.to_s
+      end
+    end
+    
+    # Creates a table. The easiest way to use this method is to provide a
+    # block:
+    #   DB.create_table :posts do
+    #     primary_key :id, :serial
+    #     column :title, :text
+    #     column :content, :text
+    #     index :title
+    #   end
+    def create_table(name, columns = nil, indexes = nil, &block)
+      if block
+        schema = Schema.new
+        schema.create_table(name, &block)
+        schema.create(self)
+      else
+        execute Schema.create_table_sql(name, columns, indexes)
+      end
+    end
+    
+    # Drops a table.
+    def drop_table(name)
+      execute Schema.drop_table_sql(name)
+    end
+    
+    # Performs a brute-force check for the existance of a table. This method is
+    # usually overriden in descendants.
+    def table_exists?(name)
+      from(name).first && true
+    rescue
+      false
+    end
+    
+    @@adapters = Hash.new
+    
+    # Sets the adapter scheme for the database class. Call this method in
+    # descendnants of Database to allow connection using a URL. For example:
+    #   class DB2::Database < Sequel::Database
+    #     set_adapter_scheme :db2
+    #     ...
+    #   end
+    def self.set_adapter_scheme(scheme)
+      @@adapters[scheme.to_sym] = self
+    end
+    
+    # Converts a uri to an options hash. These options are then passed
+    # to a newly created database object.
+    def self.uri_to_options(uri)
+      {
+        :user => uri.user,
+        :password => uri.password,
+        :host => uri.host,
+        :port => uri.port,
+        :database => (uri.path =~ /\/(.*)/) && ($1)
+      }
+    end
+    
+    # call-seq:
+    #   Sequel::Database.connect(conn_string)
+    #   Sequel.connect(conn_string)
+    #
+    # Creates a new database object based on the supplied connection string.
+    # The specified scheme determines the database class used, and the rest
+    # of the string specifies the connection options. For example:
+    #   DB = Sequel.connect('sqlite:///blog.db')
+    def self.connect(conn_string)
+      uri = URI.parse(conn_string)
+      c = @@adapters[uri.scheme.to_sym]
+      raise "Invalid database scheme" unless c
+      c.new(c.uri_to_options(uri))
+    end
+  end
+end
+