activerecord 1.0.0 → 3.0.0

data/README.rdoc

@@ -0,0 +1,222 @@
+= Active Record -- Object-relational mapping put on rails
+
+Active Record connects classes to relational database tables to establish an
+almost zero-configuration persistence layer for applications. The library
+provides a base class that, when subclassed, sets up a mapping between the new
+class and an existing table in the database. In context of an application,
+these classes are commonly referred to as *models*. Models can also be
+connected to other models; this is done by defining *associations*.
+
+Active Record relies heavily on naming in that it uses class and association
+names to establish mappings between respective database tables and foreign key
+columns. Although these mappings can be defined explicitly, it's recommended
+to follow naming conventions, especially when getting started with the
+library.
+
+A short rundown of some of the major features:
+
+* Automated mapping between classes and tables, attributes and columns.
+
+   class Product < ActiveRecord::Base
+   end
+
+   The Product class is automatically mapped to the table named "products",
+   which might look like this:
+
+   CREATE TABLE products (
+     id int(11) NOT NULL auto_increment,
+     name varchar(255),
+     PRIMARY KEY  (id)
+   );
+
+   This would also define the following accessors: `Product#name` and
+   `Product#name=(new_name)`
+
+  {Learn more}[link:classes/ActiveRecord/Base.html]
+
+
+* Associations between objects defined by simple class methods.
+
+   class Firm < ActiveRecord::Base
+     has_many   :clients
+     has_one    :account
+     belongs_to :conglomerate
+   end
+
+  {Learn more}[link:classes/ActiveRecord/Associations/ClassMethods.html]
+
+
+* Aggregations of value objects.
+
+   class Account < ActiveRecord::Base
+     composed_of :balance, :class_name => "Money",
+                 :mapping => %w(balance amount)
+     composed_of :address,
+                 :mapping => [%w(address_street street), %w(address_city city)]
+   end
+
+  {Learn more}[link:classes/ActiveRecord/Aggregations/ClassMethods.html]
+
+
+* Validation rules that can differ for new or existing objects.
+
+    class Account < ActiveRecord::Base
+      validates_presence_of     :subdomain, :name, :email_address, :password
+      validates_uniqueness_of   :subdomain
+      validates_acceptance_of   :terms_of_service, :on => :create
+      validates_confirmation_of :password, :email_address, :on => :create
+    end
+
+  {Learn more}[link:classes/ActiveRecord/Validations.html]
+
+
+* Callbacks available for the entire life cycle (instantiation, saving, destroying, validating, etc.)
+
+   class Person < ActiveRecord::Base
+     before_destroy :invalidate_payment_plan
+     # the `invalidate_payment_plan` method gets called just before Person#destroy
+   end
+
+  {Learn more}[link:classes/ActiveRecord/Callbacks.html]
+
+
+* Observers that react to changes in a model
+
+   class CommentObserver < ActiveRecord::Observer
+     def after_create(comment) # is called just after Comment#save
+       Notifications.deliver_new_comment("david@loudthinking.com", comment)
+     end
+   end
+
+  {Learn more}[link:classes/ActiveRecord/Observer.html]
+
+
+* Inheritance hierarchies
+
+   class Company < ActiveRecord::Base; end
+   class Firm < Company; end
+   class Client < Company; end
+   class PriorityClient < Client; end
+
+  {Learn more}[link:classes/ActiveRecord/Base.html]
+
+
+* Transactions
+
+    # Database transaction
+    Account.transaction do
+      david.withdrawal(100)
+      mary.deposit(100)
+    end
+
+  {Learn more}[link:classes/ActiveRecord/Transactions/ClassMethods.html]
+
+
+* Reflections on columns, associations, and aggregations
+
+    reflection = Firm.reflect_on_association(:clients)
+    reflection.klass # => Client (class)
+    Firm.columns # Returns an array of column descriptors for the firms table
+
+  {Learn more}[link:classes/ActiveRecord/Reflection/ClassMethods.html]
+
+
+* Database abstraction through simple adapters
+
+    # connect to SQLite3
+    ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => "dbfile.sqlite3")
+
+    # connect to MySQL with authentication
+    ActiveRecord::Base.establish_connection(
+      :adapter  => "mysql",
+      :host     => "localhost",
+      :username => "me",
+      :password => "secret",
+      :database => "activerecord"
+    )
+
+  {Learn more}[link:classes/ActiveRecord/Base.html] and read about the built-in support for
+  MySQL[link:classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html],
+  PostgreSQL[link:classes/ActiveRecord/ConnectionAdapters/PostgreSQLAdapter.html], and
+  SQLite3[link:classes/ActiveRecord/ConnectionAdapters/SQLite3Adapter.html].
+
+
+* Logging support for Log4r[http://log4r.sourceforge.net] and Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc]
+
+    ActiveRecord::Base.logger = Logger.new(STDOUT)
+    ActiveRecord::Base.logger = Log4r::Logger.new("Application Log")
+
+
+* Database agnostic schema management with Migrations
+
+    class AddSystemSettings < ActiveRecord::Migration
+      def self.up
+        create_table :system_settings do |t|
+          t.string  :name
+          t.string  :label
+          t.text    :value
+          t.string  :type
+          t.integer :position
+        end
+
+        SystemSetting.create :name => "notice", :label => "Use notice?", :value => 1
+      end
+
+      def self.down
+        drop_table :system_settings
+      end
+    end
+
+  {Learn more}[link:classes/ActiveRecord/Migration.html]
+
+
+== Philosophy
+
+Active Record is an implementation of the object-relational mapping (ORM)
+pattern[http://www.martinfowler.com/eaaCatalog/activeRecord.html] by the same
+name described by Martin Fowler:
+
+  "An object that wraps a row in a database table or view,
+  encapsulates the database access, and adds domain logic on that data."
+
+Active Record attempts to provide a coherent wrapper as a solution for the inconvenience that is
+object-relational mapping. The prime directive for this mapping has been to minimize
+the amount of code needed to build a real-world domain model. This is made possible
+by relying on a number of conventions that make it easy for Active Record to infer
+complex relations and structures from a minimal amount of explicit direction.
+
+Convention over Configuration:
+* No XML-files!
+* Lots of reflection and run-time extension
+* Magic is not inherently a bad word
+
+Admit the Database:
+* Lets you drop down to SQL for odd cases and performance
+* Doesn't attempt to duplicate or replace data definitions
+
+
+== Download and installation
+
+The latest version of Active Record can be installed with Rubygems:
+
+  % [sudo] gem install activerecord
+
+Source code can be downloaded as part of the Rails project on GitHub
+
+* http://github.com/rails/rails/tree/master/activerecord/
+
+
+== License
+
+Active Record is released under the MIT license.
+
+
+== Support
+
+API documentation is at
+
+* http://api.rubyonrails.com
+
+Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
+
+* https://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets

data/examples/performance.rb

@@ -0,0 +1,162 @@
+#!/usr/bin/env ruby -KU
+
+TIMES = (ENV['N'] || 10000).to_i
+require 'rubygems'
+
+gem 'addressable',  '~>2.0'
+gem 'faker',        '~>0.3.1'
+gem 'rbench',       '~>0.2.3'
+
+require 'addressable/uri'
+require 'faker'
+require 'rbench'
+
+require File.expand_path("../../../load_paths", __FILE__)
+require "active_record"
+
+conn = { :adapter => 'mysql',
+  :database => 'activerecord_unittest',
+  :username => 'rails', :password => '',
+  :encoding => 'utf8' }
+
+conn[:socket] = Pathname.glob(%w[
+  /opt/local/var/run/mysql5/mysqld.sock
+  /tmp/mysqld.sock
+  /tmp/mysql.sock
+  /var/mysql/mysql.sock
+  /var/run/mysqld/mysqld.sock
+]).find { |path| path.socket? }
+
+ActiveRecord::Base.establish_connection(conn)
+
+class User < ActiveRecord::Base
+  connection.create_table :users, :force => true do |t|
+    t.string :name, :email
+    t.timestamps
+  end
+
+  has_many :exhibits
+end
+
+class Exhibit < ActiveRecord::Base
+  connection.create_table :exhibits, :force => true do |t|
+    t.belongs_to :user
+    t.string :name
+    t.text :notes
+    t.timestamps
+  end
+
+  belongs_to :user
+
+  def look; attributes end
+  def feel; look; user.name end
+
+  def self.look(exhibits) exhibits.each { |e| e.look } end
+  def self.feel(exhibits) exhibits.each { |e| e.feel } end
+end
+
+sqlfile = File.expand_path("../performance.sql", __FILE__)
+
+if File.exists?(sqlfile)
+  mysql_bin = %w[mysql mysql5].detect { |bin| `which #{bin}`.length > 0 }
+  `#{mysql_bin} -u #{conn[:username]} #{"-p#{conn[:password]}" unless conn[:password].blank?} #{conn[:database]} < #{sqlfile}`
+else
+  puts 'Generating data...'
+
+  # pre-compute the insert statements and fake data compilation,
+  # so the benchmarks below show the actual runtime for the execute
+  # method, minus the setup steps
+
+  # Using the same paragraph for all exhibits because it is very slow
+  # to generate unique paragraphs for all exhibits.
+  notes = Faker::Lorem.paragraphs.join($/)
+  today = Date.today
+
+  puts 'Inserting 10,000 users and exhibits...'
+  10_000.times do
+    user = User.create(
+      :created_at => today,
+      :name       => Faker::Name.name,
+      :email      => Faker::Internet.email
+    )
+
+    Exhibit.create(
+      :created_at => today,
+      :name       => Faker::Company.name,
+      :user       => user,
+      :notes      => notes
+    )
+  end
+
+  mysqldump_bin = %w[mysqldump mysqldump5].select { |bin| `which #{bin}`.length > 0 }
+  `#{mysqldump_bin} -u #{conn[:username]} #{"-p#{conn[:password]}" unless conn[:password].blank?} #{conn[:database]} exhibits users > #{sqlfile}`
+end
+
+RBench.run(TIMES) do
+  column :times
+  column :ar
+
+  report 'Model#id', (TIMES * 100).ceil do
+    ar_obj = Exhibit.find(1)
+
+    ar { ar_obj.id }
+  end
+
+  report 'Model.new (instantiation)' do
+    ar { Exhibit.new }
+  end
+
+  report 'Model.new (setting attributes)' do
+    attrs = { :name => 'sam' }
+    ar { Exhibit.new(attrs) }
+  end
+
+  report 'Model.first' do
+    ar { Exhibit.first.look }
+  end
+
+  report 'Model.all limit(100)', (TIMES / 10).ceil do
+    ar { Exhibit.look Exhibit.limit(100) }
+  end
+
+  report 'Model.all limit(100) with relationship', (TIMES / 10).ceil do
+    ar { Exhibit.feel Exhibit.limit(100).includes(:user) }
+  end
+
+  report 'Model.all limit(10,000)', (TIMES / 1000).ceil do
+    ar { Exhibit.look Exhibit.limit(10000) }
+  end
+
+  exhibit = {
+    :name       => Faker::Company.name,
+    :notes      => Faker::Lorem.paragraphs.join($/),
+    :created_at => Date.today
+  }
+
+  report 'Model.create' do
+    ar { Exhibit.create(exhibit) }
+  end
+
+  report 'Resource#attributes=' do
+    attrs_first  = { :name => 'sam' }
+    attrs_second = { :name => 'tom' }
+    ar { exhibit = Exhibit.new(attrs_first); exhibit.attributes = attrs_second }
+  end
+
+  report 'Resource#update' do
+    ar { Exhibit.first.update_attributes(:name => 'bob') }
+  end
+
+  report 'Resource#destroy' do
+    ar { Exhibit.first.destroy }
+  end
+
+  report 'Model.transaction' do
+    ar { Exhibit.transaction { Exhibit.new } }
+  end
+
+  summary 'Total'
+end
+
+ActiveRecord::Migration.drop_table "exhibits"
+ActiveRecord::Migration.drop_table "users"

data/examples/simple.rb

@@ -0,0 +1,14 @@
+$LOAD_PATH.unshift "#{File.dirname(__FILE__)}/../lib"
+require 'active_record'
+
+class Person < ActiveRecord::Base
+  establish_connection :adapter => 'sqlite3', :database => 'foobar.db'
+  connection.create_table table_name, :force => true do |t|
+    t.string :name
+  end
+end
+
+bob = Person.create!(:name => 'bob')
+puts Person.all.inspect
+bob.destroy
+puts Person.all.inspect