og 0.31.0 → 0.40.0

data/lib/og/store/sql.rb

@@ -1,280 +1,31 @@
-require 'yaml'
-require 'time'
-
-require 'facet/kernel/constant'
-require 'facet/string/capitalized'
-require 'facet/ormsupport'
+require 'facets/core/module/ancestor'
+require 'facets/core/class/subclasses'
 
+require 'og/store'
+require 'og/store/sql/utils'
+require 'og/store/sql/join'
+require 'og/store/sql/evolution'
 
 module Og
 
-# A collection of useful SQL utilities.
-
-module SqlUtils
-
-  # Escape an SQL string
-
-  def escape(str)
-    return nil unless str
-    return str.gsub(/'/, "''")
-  end
-
-  # Convert a ruby time to an sql timestamp.
-  #--
-  # TODO: Optimize this.
-  #++
-
-  def timestamp(time = Time.now)
-    return nil unless time
-    return time.strftime("%Y-%m-%d %H:%M:%S")
-  end
-
-  # Output YYY-mm-dd
-  #--
-  # TODO: Optimize this.
-  #++
-
-  def date(date)
-    return nil unless date
-    return "#{date.year}-#{date.month}-#{date.mday}" 
-  end
-
-  #--
-  # TODO: implement me!
-  #++
-
-  def blob(val)
-    val
-  end
-
-  # Parse an integer.
-
-  def parse_int(int)
-    int = int.to_i if int
-    int
-  end
-
-  # Parse a float.
-
-  def parse_float(fl)
-    fl = fl.to_f if fl
-    fl
-  end
-
-  # Parse sql datetime
-  #--
-  # TODO: Optimize this.
-  #++
-
-  def parse_timestamp(str)
-    return nil unless str
-    return Time.parse(str)    
-  end
-
-  # Input YYYY-mm-dd
-  #--
-  # TODO: Optimize this.
-  #++
-
-  def parse_date(str)
-    return nil unless str
-    return Date.strptime(str)
-  end
-
-  # Parse a boolean
-  # true, 1, t  => true
-  # other       => false
-
-  def parse_boolean(str)
-    return true if (str=='true' || str=='t' || str=='1')
-    return false
-  end
-
-  #--
-  # TODO: implement me!!
-  #++
-
-  def parse_blob(val)
-    val
-  end
-
-  # Escape the various Ruby types.
-
-  def quote(vals)
-    vals = [vals] unless vals.is_a?(Array)
-    quoted = vals.inject("") do |s,val|
-      s += case val
-        when Fixnum, Integer, Float
-          val ? val.to_s : 'NULL'
-        when String
-          val ? "'#{escape(val)}'" : 'NULL'
-        when Time
-          val ? "'#{timestamp(val)}'" : 'NULL'
-        when Date
-          val ? "'#{date(val)}'" : 'NULL'
-        when TrueClass
-          val ? "'t'" : 'NULL'
-        else
-          # gmosx: keep the '' for nil symbols.
-          val ? escape(val.to_yaml) : ''
-      end + ','
-    end
-    quoted.chop!
-    vals.size > 1 ? "(#{quoted})" : quoted
-  end
-
-  # Escape the Array Ruby type.
-
-  def quote_array(val)
-    case val
-      when Array
-        val.collect{ |v| quotea(v) }.join(',')
-      else
-        quote(val)
-    end
-  end
-  alias_method :quotea, :quote_array
-
-  # Apply table name conventions to a class name.
-
-  def tableize(klass)
-    "#{klass.to_s.gsub(/::/, "_").downcase}"
-  end
-
-  def table(klass)
-    klass.ann.self[:sql_table] || klass.ann.self[:table] || "#{Og.table_prefix}#{tableize(klass)}"
-  end
-
-  def join_object_ordering(obj1, obj2)
-    if obj1.class.to_s <= obj2.class.to_s
-      return obj1, obj2
-    else
-      return obj2, obj1, true
-    end
-  end
-
-  def join_class_ordering(class1, class2)
-    if class1.to_s <= class2.to_s
-      return class1, class2
-    else
-      return class2, class1, true
-    end
-  end
-
-  def build_join_name(class1, class2, postfix = nil)
-    # Don't reorder arguments, as this is used in places that
-    # have already determined the order they want.
-    "#{Og.table_prefix}j_#{tableize(class1)}_#{tableize(class2)}#{postfix}"
-  end
-
-  def join_table(class1, class2, postfix = nil)
-    first, second = join_class_ordering(class1, class2)
-    build_join_name(first, second, postfix)
-  end
-
-  def join_table_index(key)
-    "#{key}_idx"
-  end
-
-  def join_table_key(klass)
-    klass = klass.schema_inheritance_root_class if klass.schema_inheritance_child?
-    "#{klass.to_s.demodulize.underscore.downcase}_oid"
-  end
-
-  def join_table_keys(class1, class2)
-    if class1 == class2
-      # Fix for the self-join case.
-      return join_table_key(class1), "#{join_table_key(class2)}2"
-    else
-      return join_table_key(class1), join_table_key(class2)
-    end
-  end
-
-  def ordered_join_table_keys(class1, class2)
-    first, second = join_class_ordering(class1, class2)
-    return join_table_keys(first, second)
-  end
-
-  def join_table_info(relation, postfix = nil)
-
-    # some fixes for schema inheritance.
-
-    owner_class, target_class = relation.owner_class, relation.target_class
-    
-    raise "Undefined owner_class in #{target_class}" unless owner_class
-    raise "Undefined target_class in #{owner_class}" unless target_class
-    
-    owner_class = owner_class.schema_inheritance_root_class if owner_class.schema_inheritance_child?
-    target_class = target_class.schema_inheritance_root_class if target_class.schema_inheritance_child?
-
-    owner_key, target_key = join_table_keys(owner_class, target_class)
-    first, second, changed = join_class_ordering(owner_class, target_class)
-
-    if changed
-      first_key, second_key = target_key, owner_key
-    else
-      first_key, second_key = owner_key, target_key
-    end
-
-    table = (relation.table ?
-      relation.table :
-      join_table(owner_class, target_class, postfix)
-    )
-    
-    return {
-      :table => table,
-      :owner_key => owner_key,
-      :owner_table => table(owner_class),
-      :target_key => target_key,
-      :target_table => table(target_class),
-      :first_table => table(first),
-      :first_key => first_key,
-      :first_index => join_table_index(first_key),
-      :second_table => table(second),
-      :second_key => second_key,
-      :second_index => join_table_index(second_key)
-    }
-  end
-
-  # Subclasses can override this if they need a different 
-  # syntax.
-
-  def create_join_table_sql(join_table_info, suffix = 'NOT NULL', key_type = 'integer')
-    join_table = join_table_info[:table]
-    first_index = join_table_info[:first_index]
-    first_key = join_table_info[:first_key]
-    second_key = join_table_info[:second_key]
-    second_index = join_table_info[:second_index]
-
-    sql = []
-
-    sql << %{      
-      CREATE TABLE #{join_table} (
-        #{first_key} integer NOT NULL,
-        #{second_key} integer NOT NULL,
-        PRIMARY KEY(#{first_key}, #{second_key})
-      )
-    }
-
-    # gmosx: not that useful?
-    # sql << "CREATE INDEX #{first_index} ON #{join_table} (#{first_key})"
-    # sql << "CREATE INDEX #{second_index} ON #{join_table} (#{second_key})"
-
-    return sql
-  end
-
-end
-
-# An abstract SQL powered store.
+# The base implementation for all SQL stores. Reused by all
+# SQL adapters.
 
 class SqlStore < Store
-  extend SqlUtils
-  include SqlUtils
-
-  # The connection to the backend SQL RDBMS.
 
+  # The connection to the SQL backend.
+  
   attr_accessor :conn
+  
+  # Ruby type <-> SQL type mappings.
+  
+  attr_accessor :typemap
 
+  # Initialize the store.
+  #--
+  # Override in the adapter.
+  #++
+   
   def initialize(options)
     super
 
@@ -297,42 +48,61 @@ class SqlStore < Store
   end
 
   #--
-  # FIXME: not working.
+  # Override in the adapter.
   #++
 
-  def enable_logging
-    require 'facets/more/aspects'
-    klass = self.class
-    klass.send :include, ::Aspects
-    klass.pre "Logger.info sql", :on => [:exec, :query]
-    ::Aspects.wrap(klass, [:exec, :query])
+  def close
+    @conn.close
+    super
   end
 
-  # Returns a list of tables that exist within the database but are 
-  # not managed by the supplied manager.
+  # Creates the database where Og managed objects are
+  # serialized.
+  #--
+  # Override in the adapter.
+  #++
   
-  def unmanaged_tables(manager)
-    ret = Array.new
-    mt = managed_tables(manager)
-    @conn.list_tables.each do |table|
-      ret << table unless mt.include?(table)
-    end
-    ret
+  def create_db(options)
+    Logger.info "Created database '#{options[:name]}'"
+  end
+
+  # Destroys the database where Og managed objects are
+  # serialized.
+  #--
+  # Override in the adapter.
+  #++
+  
+  def destroy_db(options)
+    Logger.info "Dropped database '#{options[:name]}'"
+  end
+  alias drop_db destroy_db  
+
+  # The type used for default primary keys.
+  
+  def primary_key_type
+    'integer PRIMARY KEY'
   end
 
-  # Returns a list of tables within the database that are there to 
-  # support a class managed by the supplied manager.
+  # Force the creation of a primary key class.
   
-  def managed_tables(manager)
-    ret = Array.new
-    manager.managed_classes.each do |klass|
-      ret << klass::OGTABLE
-      ret.concat(klass.relations.reject{|rel| not rel.options[:join_table]}.map{|rel| rel.options[:join_table]})
+  def force_primary_key(klass)
+    # Automatically add an :oid serializable field if none is 
+    # defined and no other primary key is defined.
+    
+    if klass.primary_key == :oid and !klass.attributes.include?(:oid)
+      klass.attr_accessor :oid, Fixnum, :sql => primary_key_type
     end
-    ret
   end
 
-  # Enchants a class.
+  # Performs SQL related enchanting to the class. This method
+  # is further extended in more specialized adapters to add
+  # backend specific enchanting.
+  # 
+  # Defines:
+  #
+  # * the OGTABLE constant, and .table / .schema aliases.
+  # * the index method for defing sql indices.
+  # * precompiles the object lifecycle callbacks.
 
   def enchant(klass, manager)
     # setup the table where this class is mapped.
@@ -344,15 +114,17 @@ class SqlStore < Store
       klass.const_set 'OGTABLE', table(klass)
     end
 
-    #--
-    # FIXME: use an SQL agnostic name like schema instead
-    # of table.
-    #++
+    # Define table and schema aliases for OGTABLE.
     
-    klass.module_eval 'def self.table; OGTABLE; end'
+    klass.module_eval %{
+      def self.table; OGTABLE; end
+      def self.schema; OGTABLE; end
+    }
 
     eval_og_allocate(klass)
 
+    # Perform base store enchantment.
+    
     super
 
     unless klass.polymorphic_parent?
@@ -381,10 +153,12 @@ class SqlStore < Store
   # :section: Lifecycle methods.
 
   # Loads an object from the store using the primary key.
-
+  # Returns nil if the passes pk is nil.
+  
   def load(pk, klass)
-    pk_field = klass.primary_key.field || klass.primary_key.symbol
-    sql = "SELECT * FROM #{klass::OGTABLE} WHERE #{pk_field}=#{pk.to_i}"
+    return nil unless pk
+    
+    sql = "SELECT * FROM #{klass.table} WHERE #{pk_field klass}=#{quote(pk)}"
     sql << " AND ogtype='#{klass}'" if klass.schema_inheritance_child?
     res = query sql
     read_one(res, klass)
@@ -392,36 +166,40 @@ class SqlStore < Store
   alias_method :exist?, :load
 
   # Reloads an object from the store.
+  # Returns nil if the passes pk is nil.
 
   def reload(obj, pk)
+    return nil unless pk
+
+    klass = obj.class
     raise 'Cannot reload unmanaged object' unless obj.saved?
-    sql = "SELECT * FROM #{obj.class.table} WHERE #{obj.class.pk_symbol}=#{pk.to_i}"
-    sql << " AND ogtype='#{obj.class}'" if obj.class.schema_inheritance_child?
+    sql = "SELECT * FROM #{klass.table} WHERE #{pk_field klass}=#{quote(pk)}"
+    sql << " AND ogtype='#{klass}'" if klass.schema_inheritance_child?
     res = query sql
     obj.og_read(res.next, 0)
   ensure
     res.close if res
   end
 
-  # If a properties collection is provided, only updates the 
-  # selected properties. Pass the required properties as symbols
+  # If an attributes collection is provided, only updates the 
+  # selected attributes. Pass the required attributes as symbols
   # or strings.
   #--
   # gmosx, THINK: condition is not really useful here :(
   #++
 
   def update(obj, options = nil)
-    if options and properties = options[:only]
-      if properties.is_a?(Array)
+    if options and attrs = options[:only]
+      if attrs.is_a?(Array)
         set = []
-        for p in properties
-          set << "#{p}=#{quote(obj.send(p))}"
+        for a in attrs
+          set << "#{a}=#{quote(obj.send(a))}"
         end
         set = set.join(',')
       else
-        set = "#{properties}=#{quote(obj.send(properties))}"
+        set = "#{attrs}=#{quote(obj.send(attrs))}"
       end
-      sql = "UPDATE #{obj.class.table} SET #{set} WHERE #{obj.class.pk_symbol}=#{obj.pk}"
+      sql = "UPDATE #{obj.class.table} SET #{set} WHERE #{pk_field obj.class}=#{quote(obj.pk)}"
       sql << " AND #{options[:condition]}" if options[:condition]
       sql_update(sql)
     else
@@ -429,26 +207,17 @@ class SqlStore < Store
     end
   end
 
-  # Update selected properties of an object or class of
-  # objects.
-
-  def update_properties(target, *properties)
-    update(target, :only => properties)
-  end
-  alias_method :pupdate, :update_properties
-  alias_method :update_property, :update_properties
-
   # More generalized method, also allows for batch updates.
 
   def update_by_sql(target, set, options = nil)
     set = set.gsub(/@/, '')
 
-    if target.is_a?(Class)
+    if target.is_a? Class
       sql = "UPDATE #{target.table} SET #{set} "
       sql << " WHERE #{options[:condition]}" if options and options[:condition]
       sql_update(sql)
     else
-      sql = "UPDATE #{target.class.table} SET #{set} WHERE #{target.class.pk_symbol}=#{target.pk}"
+      sql = "UPDATE #{target.class.table} SET #{set} WHERE #{pk_field target.class}=#{quote(target.pk)}"
       sql << " AND #{options[:condition]}" if options and options[:condition]
       sql_update(sql)
     end      
@@ -498,6 +267,10 @@ class SqlStore < Store
   # This low level method is used by the Entity 
   # calculation / aggregation methods.
   # 
+  # === Options
+  #
+  # :field = the return type.
+  #
   # === Example
   #
   # calculate 'COUNT(*)'
@@ -505,152 +278,128 @@ class SqlStore < Store
   # calculate 'SUM(age)', :group => :name
 
   def aggregate(term = 'COUNT(*)', options = {})
+    # Leave this .dup here, causes problems because options are changed
+    options = options.dup
+    
     klass = options[:class]
     field = options[:field]
-
-    if field_properties = klass.properties[field]
-      return_type = field_properties[:klass]
+    
+    # Rename search term, SQL92 but _not_ SQL89 compatible
+    options.update(:select => "#{term} AS #{term[/^\w+/]}")
+    
+    unless options[:group] || options[:group_by]
+      options.delete(:order)
+      options.delete(:order_by)
     end
-
-    if options.is_a?(String)
-      sql = options
-    else
-      sql = "SELECT #{term} FROM #{options[:class].table}"
-      if condition = options[:condition]
-        sql << " WHERE #{condition}"
-        sql << " AND " if options[:class].schema_inheritance_child?
-      else
-        sql << " WHERE " if options[:class].schema_inheritance_child?
-      end
-      sql << "ogtype='#{options[:class]}'" if options[:class].schema_inheritance_child?
-      if group = options[:group]
-        sql << " GROUP BY #{group}"
-      end
-      if extra = options[:extra_sql]
-        sql << " {extra}"
-      end        
+    
+    sql = resolve_options(klass, options)
+    
+    if anno = klass.ann[field]
+      return_type = anno.class
     end
-   
-    if group
+    return_type ||= Integer
+    
+    if options[:group] || options[:group_by]
       # This is an aggregation, so return the calculated values
       # as an array.
       values = []
       res = query(sql)
       res.each_row do |row, idx|
-        value = [ row[idx] ].flatten[0]
-        values << type_cast(return_type, value)
+        values << type_cast(return_type, row[0])
       end
       return values
     else
-      #--
-      # gmosx, TODO: don't convert to float by default, perhaps
-      # should consult an option.
-      #++ 
       return type_cast(return_type, query(sql).first_value)
     end
+    
   end
   alias_method :calculate, :aggregate
 
-  def type_cast(klass, val)
-    typemap = {
-      Time => :parse_timestamp,
-      Date => :parse_date,
-    }
-
-    if method = typemap[klass]
-      send(method, val)
-    else
-      val.to_f
-    end
-  end
-
   # Perform a count query.
   
   def count(options = {})
     calculate('COUNT(*)', options).to_i
   end
 
-  # Relate two objects through an intermediate join table.
-  # Typically used in joins_many and many_to_many relations.
-
-  def join(obj1, obj2, table, options = nil)
-    first, second = join_object_ordering(obj1, obj2)
-    first_key, second_key = ordered_join_table_keys(obj1.class, obj2.class)
-    if options
-      exec "INSERT INTO #{table} (#{first_key},#{second_key}, #{options.keys.join(',')}) VALUES (#{first.pk},#{second.pk}, #{options.values.map { |v| quote(v) }.join(',')})"
-    else
-      exec "INSERT INTO #{table} (#{first_key},#{second_key}) VALUES (#{first.pk}, #{second.pk})"
-    end
-  end
-
-  # Unrelate two objects be removing their relation from the
-  # join table.
-
-  def unjoin(obj1, obj2, table)
-    first, second = join_object_ordering(obj1, obj2)
-    first_key, second_key = ordered_join_table_keys(obj1.class, obj2.class)
-    exec "DELETE FROM #{table} WHERE #{first_key}=#{first.pk} AND #{second_key}=#{second.pk}"    
-  end
-
+  # Delete all instances of the given class from the backend.
+  
   def delete_all(klass)
     sql = "DELETE FROM #{klass.table}"
     sql << " WHERE ogtype='#{klass}'" if klass.schema_inheritance? and not klass.schema_inheritance_root?
     exec sql
   end
+  
+  # :section: Misc methods.
+  
+  # Create the SQL table where instances of the given class
+  # will be serialized.
+  
+  def create_table(klass)
+    fields = fields_for_class(klass)
 
-  # :section: Transaction methods.
-
-  # Start a new transaction.
-
-  def start  
-    exec('START TRANSACTION') if @transaction_nesting < 1
-    @transaction_nesting += 1
-  end
-
-  # Commit a transaction.
+    sql = "CREATE TABLE #{klass.table} (#{fields.join(', ')}"
 
-  def commit
-    @transaction_nesting -= 1
-    exec('COMMIT') if @transaction_nesting < 1
-  end
+    # Create table constraints.
 
-  # Rollback a transaction.
+    if constraints = klass.ann.self[:sql_constraint]
+      sql << ", #{constraints.join(', ')}"
+    end
 
-  def rollback
-    @transaction_nesting -= 1
-    exec('ROLLBACK') if @transaction_nesting < 1
-  end
+    # Set the table type (Mysql default, InnoDB, Hash, etc)
+    
+    if table_type = @options[:table_type]
+      sql << ") TYPE = #{table_type};"  
+    else
+      sql << ");"
+    end
 
-  # :section: Low level methods.
+    # Create indices.
+    #
+    # An example index definition:
+    #
+    # classs MyClass
+    #   attr_accessor :age, Fixnum, :index => true, :pre_index => ..., :post_index => ...
+    # end
+
+    for idx in sql_indices_for_class(klass)
+      anno = klass.ann(idx)
+      idx = idx.to_s
+      pre_sql, post_sql = anno[:pre_index], options[:post_index]
+      idxname = idx.gsub(/ /, "").gsub(/,/, "_").gsub(/\(.*\)/, "")
+      sql << " CREATE #{pre_sql} INDEX #{klass.table}_#{idxname}_idx #{post_sql} ON #{klass.table} (#{idx});"  
+    end
 
-  # Encapsulates a low level update method.
+    begin
+      exec(sql, false)
+      Logger.info "Created table '#{klass.table}'."
+    rescue Object => ex
+      if table_already_exists_exception? ex
+        # Don't return yet. Fall trough to also check for the 
+        # join table.
+      else
+        handle_sql_exception(ex, sql)
+      end
+    end
 
-  def sql_update(sql)
-    exec(sql)
-    # return affected rows.
-  end
+    # Create join tables if needed. Join tables are used in
+    # 'many_to_many' relations.
 
-  #takes an array, the first parameter of which is a prepared statement
-  #style string; this handles parameter escaping.
-  def prepare_statement(condition)
-    if condition.is_a?(Array)
-      args = condition.dup
-      str = args.shift
-      # ? handles a single type.
-      # ?* handles an array.
-      args.each { |arg| str.sub!(/\?\*/, quotea(arg)); str.sub!(/\?/, quote(arg)) }
-      condition = str
+    if join_tables = klass.ann.self[:join_tables] 
+      for info in join_tables
+        begin
+          create_join_table_sql(info).each do |sql|
+            exec(sql, false)
+          end
+          Logger.debug "Created jointable '#{info[:table]}'." if $DBG
+        rescue Object => ex
+          if table_already_exists_exception? ex
+            Logger.debug 'Join table already exists' if $DBG
+          else
+            raise
+          end
+        end
+      end
     end
-    condition
-  end
-  
-private
-
-  # Create the sql table where objects of this class are 
-  # persisted.
-  
-  def create_table(klass)
-    raise 'Not implemented'
   end
 
   # Drop the sql table where objects of this class are 
@@ -669,290 +418,50 @@ private
   alias_method :destroy, :drop_table
   alias_method :drop_schema, :drop_schema
 
-  # Evolve (recreate) the sql table where objects of this class 
-  # are persisted.
-  
-  def evolve_table(klass)
-    drop_table(klass)
-    create_table(klass)
-  end
-  alias_method :update_table, :evolve_table
+  # Perform an sql query with results.
 
-  # Return the field for the given property.
-
-  def field_for_property(property)
-    if f = property.field
-      return f.to_s
-    else
-      return property.to_s
+  def query(sql, rescue_exception = true)
+    Logger.debug sql if $DBG
+    return query_statement(sql)
+  rescue Object => ex
+    if rescue_exception
+      handle_sql_exception(ex, sql)
+    else 
+      raise
     end
   end
+
+  #--
+  # Override.
+  #++
   
-  #utility function - return either the properties for the class
-  #or, in the case of schema inheritance, all of the properties
-  #of the class hierarchy, starting from the schema inheritance
-  #root class
-   
-  def get_properties_for_class(klass)
-    properties = klass.properties.dup
-    if(klass.schema_inheritance?)
-      for desc in klass.schema_inheritance_root_class.descendents
-        properties.update(desc.properties)
-      end  
-    end
-    properties
+  def query_statement(sql)
+    return @conn.query(sql)
   end
-    
-  # Create the fields that correspond to the klass properties.
-  # The generated fields array is used in create_table.
-  # If the property has an :sql annotation this overrides the 
-  # default mapping. If the property has an :extra_sql annotation
-  # the extra sql is appended after the default mapping.
   
-  def fields_for_class(klass)
-    fields = []
-    properties = get_properties_for_class(klass)
-
-    if klass.schema_inheritance?
-      # This class as a superclass in a single table inheritance
-      # chain. So inject a special class ogtype field that 
-      # holds the class name.
-
-      fields << "ogtype VARCHAR(50)"
-    end
-    
-    for p in properties.values
-      klass.index(p.symbol) if p.index
-        
-      field = field_for_property(p)
-      
-      if p.sql
-        field << " #{p.sql}"
-      else
-        field << " #{type_for_class(p.klass)}"
-        field << " UNIQUE" if p.unique  
-        field << " DEFAULT #{p.default.inspect} NOT NULL" if p.default
-        field << " #{p.extra_sql}" if p.extra_sql
-      end
-      
-      fields << field
-    end
-
-    return fields
-  end
+  # Perform an sql query with no results.
   
-  def type_for_class(klass)
-    @typemap[klass]    
+  def exec(sql, rescue_exception = true)
+    Logger.debug sql if $DBG
+    exec_statement(sql)
+  rescue Object => ex
+    if rescue_exception
+      handle_sql_exception(ex, sql)
+    else 
+      raise
+    end
   end
 
-  # Return an sql string evaluator for the property.
-  # No need to optimize this, used only to precalculate code.
-  # YAML is used to store general Ruby objects to be more 
-  # portable.
   #--
-  # FIXME: add extra handling for float.
+  # Override.
   #++
   
-  def write_prop(p)
-    if p.klass.ancestors.include?(Integer)
-      return "#\{@#{p} || 'NULL'\}"
-    elsif p.klass.ancestors.include?(Float)
-      return "#\{@#{p} || 'NULL'\}"    
-    elsif p.klass.ancestors.include?(String)
-      return %|#\{@#{p} ? "'#\{#{self.class}.escape(@#{p})\}'" : 'NULL'\}|
-    elsif p.klass.ancestors.include?(Time)
-      return %|#\{@#{p} ? "'#\{#{self.class}.timestamp(@#{p})\}'" : 'NULL'\}|
-    elsif p.klass.ancestors.include?(Date)
-      return %|#\{@#{p} ? "'#\{#{self.class}.date(@#{p})\}'" : 'NULL'\}|
-    elsif p.klass.ancestors.include?(TrueClass)
-      return "#\{@#{p} ? \"'t'\" : 'NULL' \}"
-    elsif p.klass.ancestors.include?(Og::Blob)
-      return %|#\{@#{p} ? "'#\{#{self.class}.escape(#{self.class}.blob(@#{p}))\}'" : 'NULL'\}|      
-    else 
-      # gmosx: keep the '' for nil symbols.
-      return %|#\{@#{p} ? "'#\{#{self.class}.escape(@#{p}.to_yaml)\}'" : "''"\}|
-    end
-  end    
+  def exec_statement(sql)
+    return @conn.exec(sql)
+  end
 
-  # Return an evaluator for reading the property.
-  # No need to optimize this, used only to precalculate code.
-  
-  def read_prop(p, col)
-    if p.klass.ancestors.include?(Integer)
-      return "#{self.class}.parse_int(res[#{col} + offset])"
-    elsif p.klass.ancestors.include?(Float)
-      return "#{self.class}.parse_float(res[#{col} + offset])"
-    elsif p.klass.ancestors.include?(String)
-      return "res[#{col} + offset]"
-    elsif p.klass.ancestors.include?(Time)
-      return "#{self.class}.parse_timestamp(res[#{col} + offset])"
-    elsif p.klass.ancestors.include?(Date)
-      return "#{self.class}.parse_date(res[#{col} + offset])"
-    elsif p.klass.ancestors.include?(TrueClass)
-      return "#{self.class}.parse_boolean(res[#{col} + offset])"
-    elsif p.klass.ancestors.include?(Og::Blob)
-      return "#{self.class}.parse_blob(res[#{col} + offset])"
-    else 
-      return "YAML::load(res[#{col} + offset])"
-    end        
-  end
-
-  # :section: Lifecycle method compilers.
-  
-  
-  # Get the fields from the database table. Also handles the
-  # change of ordering of the fields in the table.
-  #
-  # To ignore a database field use the ignore_fields annotation
-  # ie,
-  #
-  # class Article
-  #   ann self, :ignore_fields => [ :tsearch_idx, :ext_field ]
-  # end
-  #
-  # other aliases for ignore_fiels: ignore_field, ignore_column.
+  # Gracefully handle a backend exception.
   
-  def create_field_map(klass)
-  end
-    
-  # Compile the og_insert method for the class.
-
-  def eval_og_insert(klass)
-    pk = klass.pk_symbol
-    props = klass.properties.values.dup
-    values = props.collect { |p| write_prop(p) }.join(',') 
-
-    if klass.ann.self[:superclass] or klass.ann.self[:subclasses]
-      props << Property.new(:symbol => :ogtype, :klass => String)
-      values << ", '#{klass}'"
-    end
-    
-    sql = "INSERT INTO #{klass.table} (#{props.collect {|p| field_for_property(p)}.join(',')}) VALUES (#{values})"
-
-    klass.module_eval %{ 
-      def og_insert(store)
-        #{::Aspects.gen_advice_code(:og_insert, klass.advices, :pre) if klass.respond_to?(:advices)}
-        store.exec "#{sql}"
-        #{::Aspects.gen_advice_code(:og_insert, klass.advices, :post) if klass.respond_to?(:advices)}
-      end
-    }
-  end
-
-  # Compile the og_update method for the class.
-
-  def eval_og_update(klass)
-    pk = klass.pk_symbol
-    pk_field = klass.primary_key.field || klass.primary_key.symbol
-
-    props = klass.properties.values.reject { |p| pk == p.symbol }
-
-    updates = props.collect { |p|
-      "#{field_for_property(p)}=#{write_prop(p)}"
-    }
-
-    sql = "UPDATE #{klass::OGTABLE} SET #{updates.join(', ')} WHERE #{pk_field}=#\{@#{pk}\}"
-
-    klass.module_eval %{
-      def og_update(store, options = nil)
-        #{::Aspects.gen_advice_code(:og_update, klass.advices, :pre) if klass.respond_to?(:advices)}
-        sql = "#{sql}"
-        sql << " AND \#{options[:condition]}" if options and options[:condition]
-        changed = store.sql_update(sql)
-        #{::Aspects.gen_advice_code(:og_update, klass.advices, :post) if klass.respond_to?(:advices)}
-        return changed
-      end
-    }    
-  end
-
-  # Compile the og_read method for the class. This method is 
-  # used to read (deserialize) the  given class from the store. 
-  # In order to allow for changing field/attribute orders a 
-  # field mapping hash is used.
-  
-  def eval_og_read(klass)
-    code = []
-    props = klass.properties.values
-    field_map = create_field_map(klass)
-
-    for p in props
-      f = field_for_property(p).to_sym
-
-      if col = field_map[f]
-        code << "@#{p} = #{read_prop(p, col)}"
-      end
-    end
-
-    code = code.join('; ')
-
-    klass.module_eval %{
-       def og_read(res, row = 0, offset = 0)
-        #{::Aspects.gen_advice_code(:og_read, klass.advices, :pre) if klass.respond_to?(:advices)}
-        #{code}
-        #{::Aspects.gen_advice_code(:og_read, klass.advices, :post) if klass.respond_to?(:advices)}
-      end
-    }
-  end
-
-  #--
-  # FIXME: is pk needed as parameter?
-  #++
-
-  def eval_og_delete(klass)
-    klass.module_eval %{
-       def og_delete(store, pk, cascade = true)
-        #{::Aspects.gen_advice_code(:og_delete, klass.advices, :pre) if klass.respond_to?(:advices)}
-        pk ||= @#{klass.pk_symbol}
-        transaction do |tx|
-          tx.exec "DELETE FROM #{klass.table} WHERE #{klass.pk_symbol}=\#{pk}"
-          if cascade and #{klass}.ann.self[:descendants]
-            #{klass}.ann.self.descendants.each do |dclass, foreign_key|
-              tx.exec "DELETE FROM \#{dclass::OGTABLE} WHERE \#{foreign_key}=\#{pk}"
-            end
-          end
-        end
-        #{::Aspects.gen_advice_code(:og_delete, klass.advices, :post) if klass.respond_to?(:advices)}
-      end
-    }
-  end
-
-  # Creates the schema for this class. Can be intercepted with
-  # aspects to add special behaviours.
-
-  def eval_og_create_schema(klass)
-    klass.module_eval %{
-      def og_create_schema(store)
-        if Og.create_schema
-          #{::Aspects.gen_advice_code(:og_create_schema, klass.advices, :pre) if klass.respond_to?(:advices)}
-#          unless self.class.superclass.ancestors.include? SchemaInheritanceBase
-            store.send(:create_table, #{klass})
-#          end
-          #{::Aspects.gen_advice_code(:og_create_schema, klass.advices, :post) if klass.respond_to?(:advices)}
-        end
-      end
-    }
-  end
-
-  # Precompile a class specific allocate method. If this is an 
-  # STI parent classes it reads the class from the resultset.
-
-  def eval_og_allocate(klass)  
-    if klass.schema_inheritance? 
-      klass.module_eval %{
-        def self.og_allocate(res, row = 0)
-          Object.constant(res[0]).allocate
-        end
-      }
-    else
-      klass.module_eval %{
-        def self.og_allocate(res, row = 0)
-          self.allocate
-        end
-      }
-    end
-  end
-
-  # :section: Misc methods.
-
   def handle_sql_exception(ex, sql = nil)
     Logger.error "DB error #{ex}, [#{sql}]"
     Logger.error ex.backtrace.join("\n")
@@ -962,6 +471,25 @@ private
     return nil 
   end
 
+  # Perform an sql update, return the number of updated rows.
+  #--
+  # Override
+  #++
+    
+  def sql_update(sql)
+    exec(sql)
+    # return affected rows.
+  end
+
+  # Return the last inserted row id.
+  #--
+  # Override
+  #--
+  
+  def last_insert_id(klass = nil)
+    # return last insert id
+  end
+
   # Resolve the finder options. Also takes scope into account.
   # This method handles among other the following cases:
   #
@@ -1049,24 +577,42 @@ private
       # If an array is passed as a condition, use prepared 
       # statement style escaping. 
              
-      condition = prepare_statement(condition)
+      if condition.is_a?(Array)
+        condition = prepare_statement(condition)
+      end
 
       sql << " WHERE #{condition}"
     end
+    
+    if group = options[:group] || options[:group_by]
+      sql << " GROUP BY #{group}"
+    end
 
-    if order = options[:order]
+    if order = options[:order] || options[:order_by]
       sql << " ORDER BY #{order}"
     end
 
     resolve_limit_options(options, sql)
 
-    if extra = options[:extra]
+    if extra = options[:extra] || options[:extra_sql]
       sql << " #{extra}"
     end
 
     return sql
   end
   
+  #takes an array, the first parameter of which is a prepared statement
+  #style string; this handles parameter escaping.
+  
+  def prepare_statement(condition)
+    args = condition.dup
+    str = args.shift
+    # ? handles a single type.
+    # ?* handles an array.
+    args.each { |arg| str.sub!(/\?\*/, quotea(arg)); str.sub!(/\?/, quote(arg)) }
+    condition = str
+  end
+  
   # Subclasses can override this if they need some other order.
   # This is needed because different backends require different
   # order of the keywords.
@@ -1081,6 +627,414 @@ private
     end
   end
 
+  # :section: Utility methods for serialization/deserialization.
+
+  # Return either the serializable attributes for the class or, 
+  # in the case of schema inheritance, all of the serializable 
+  # attributes of the class hierarchy, starting from the schema 
+  # inheritance root class.
+   
+  def serializable_attributes_for_class(klass) 
+    attrs = klass.serializable_attributes
+    if klass.schema_inheritance?
+      for desc in klass.schema_inheritance_root_class.descendents
+        attrs.concat desc.serializable_attributes
+      end  
+    end
+    return attrs.uniq
+  end
+  
+  # Return the SQL table field for the given serializable 
+  # attribute. You can override the default field name by 
+  # annotating the attribute with a :field annotation.
+  
+  def field_for_attribute(a, anno)
+    (f = anno[:field]) ? f : a
+  end
+
+  def field_sql_for_attribute(a, anno)
+    field = field_for_attribute(a, anno).to_s
+
+    if anno.sql?
+      field << " #{anno.sql}"
+    else
+      field << " #{sql_type_for_class(anno.class)}"
+      field << " UNIQUE" if anno.unique?  
+      field << " DEFAULT #{quote(anno.default)} NOT NULL" if anno.default?
+      field << " #{anno.extra_sql}" if anno.extra_sql?
+    end
+
+    return field
+  end
+  
+  # Create the fields that correspond to the class serializable 
+  # attributes. The generated fields array is used in 
+  # create_table. 
+  #
+  # If the property has an :sql annotation this overrides the 
+  # default mapping. If the property has an :extra_sql annotation
+  # the extra sql is appended after the default mapping.
+  
+  def fields_for_class(klass)
+    fields = []
+    attrs = serializable_attributes_for_class(klass)
+
+    # FIXME: move to serializable attributes.
+    
+    if klass.schema_inheritance?
+      # This class is a superclass in a single table inheritance
+      # chain. So inject a special class ogtype field that 
+      # holds the class name.
+      fields << "ogtype VARCHAR(30)"
+    end
+    
+    for a in attrs
+      anno = klass.ann[a]
+      if anno.null?
+        klass.subclasses.each do |subklass|
+          anno = subklass.ann[a] if anno.null?
+        end
+      end
+      fields << field_sql_for_attribute(a, anno)
+    end
+
+    return fields
+  end
+  
+  # Returns the SQL indexed serializable attributes for the
+  # given class.
+  
+  def sql_indices_for_class klass
+    indices = []
+
+    for a in klass.serializable_attributes
+      indices << a if klass.ann(a).index?
+    end
+
+    return indices
+  end
+  
+  # Return the SQL type for the given Ruby class.
+  
+  def sql_type_for_class klass
+    @typemap[klass]    
+  end
+
+  # Generate code to serialize an attribute to an SQL table
+  # field.
+  # YAML is used (instead of Marshal) to store general Ruby 
+  # objects to be more 
+  # portable.
+  #
+  # === Input
+  #
+  # * s = attribute symbol
+  # * a = attribute annotations
+  #--
+  # No need to optimize this, used only to precalculate code.
+  # FIXME: add extra handling for float.
+  #++
+  
+  def write_attr(s, a)
+    store = self.class
+    
+    if a.class.ancestor? Integer
+      "#\{@#{s} || 'NULL'\}"
+    
+    elsif a.class.ancestor? Float
+      "#\{@#{s} || 'NULL'\}"    
+    
+    elsif a.class.ancestor? String
+      %|#\{@#{s} ? "'#\{#{store}.escape(@#{s})\}'" : 'NULL'\}|
+    
+    elsif a.class.ancestor? Time
+      %|#\{@#{s} ? "'#\{#{store}.timestamp(@#{s})\}'" : 'NULL'\}|
+    
+    elsif a.class.ancestor? Date 
+      %|#\{@#{s} ? "'#\{#{store}.date(@#{s})\}'" : 'NULL'\}|
+    
+    elsif a.class.ancestor? TrueClass
+      "#\{@#{s} ? \"'t'\" : 'NULL' \}"
+    
+    elsif a.class.ancestor? Og::Blob 
+      %|#\{@#{s} ? "'#\{#{store}.escape(#{store}.blob(@#{s}))\}'" : 'NULL'\}|      
+    
+    else 
+      # keep the '' for nil symbols.
+      %|#\{@#{s} ? "'#\{#{store}.escape(@#{s}.to_yaml)\}'" : "''"\}|
+    end
+  end    
+
+  # Generate code to deserialize an SQL table field into an
+  # attribute.
+  #--
+  # No need to optimize this, used only to precalculate code.
+  #++
+  
+  def read_attr(s, a, col)
+    store = self.class
+    
+    if a.class.ancestor? Integer
+      "#{store}.parse_int(res[#{col} + offset])"
+
+    elsif a.class.ancestor? Float
+      "#{store}.parse_float(res[#{col} + offset])"
+
+    elsif a.class.ancestor? String
+      "res[#{col} + offset]"
+
+    elsif a.class.ancestor? Time
+      "#{store}.parse_timestamp(res[#{col} + offset])"
+
+    elsif a.class.ancestor? Date
+      "#{store}.parse_date(res[#{col} + offset])"
+
+    elsif a.class.ancestor? TrueClass
+      "#{store}.parse_boolean(res[#{col} + offset])"
+
+    elsif a.class.ancestor? Og::Blob
+      "#{store}.parse_blob(res[#{col} + offset])"
+
+    else 
+      "YAML::load(res[#{col} + offset])"
+    end        
+  end
+
+  # Get the fields from the database table. Also handles the
+  # change of ordering of the fields in the table.
+  #
+  # To ignore a database field use the ignore_fields annotation
+  # ie,
+  #
+  # class Article
+  #   ann self, :ignore_fields => [ :tsearch_idx, :ext_field ]
+  # end
+  #
+  # other aliases for ignore_fiels: ignore_field, ignore_column.
+  #--
+  # Even though great care has been taken to make this
+  # method reusable, oveeride if needed in your adapter.
+  #++
+      
+  def create_field_map(klass)
+    res = query "SELECT * FROM #{klass.table} LIMIT 1"
+    map = {}
+
+    # Check if the field should be ignored.
+    
+    ignore = klass.ann.self[:ignore_field] || klass.ann.self[:ignore_fields] || klass.ann.self[:ignore_columns]   
+
+    res.fields.each_with_index do |f, i|
+      field_name = f.to_sym
+      unless (ignore and ignore.include?(field_name))
+        map[field_name] = i
+      end
+    end
+
+    return map
+  ensure
+    res.close if res
+  end
+    
+  # Generates the SQL field of the primary key for this class.
+  
+  def pk_field klass
+    pk = klass.primary_key
+    return klass.ann(pk)[:field] || pk
+  end
+  
+  # :section: Lifecycle method compilers.
+  
+  # Compile the og_insert method for the class. This method is
+  # used to create insert the object into a new Row in the
+  # database.
+  #--
+  # Override the og_insert_kernel method to customize for
+  # adapters.
+  #++
+  
+  def eval_og_insert(klass)
+    fields = []
+    values = []
+    
+    for a in klass.serializable_attributes
+      anno = klass.ann(a)
+      fields << field_for_attribute(a, anno)
+      values << write_attr(a, anno) 
+    end
+
+    # If the class participates in STI, automatically insert
+    # an ogtype serializable attribute.
+    
+    if klass.schema_inheritance?
+      fields << :ogtype
+      values << quote(klass.name)
+    end
+
+    fields = fields.join(', ')
+    values = values.join(', ')
+        
+    sql = "INSERT INTO #{klass.table} (#{fields}) VALUES (#{values})"
+
+    klass.module_eval %{ 
+      def og_insert(store)
+        #{insert_advices :pre, :og_insert, klass, :advices}
+        #{insert_sql sql, klass}
+        #{insert_advices :post, :og_insert, klass, :advices}
+      end
+    }
+  end
+
+  # The insert sql statements.
+  
+  def insert_sql(sql, klass)
+    %{
+    store.exec "#{sql}"
+    @#{klass.primary_key} = store.last_insert_id
+    }
+  end
+
+  # Compile the og_update method for the class.
+
+  def eval_og_update(klass)
+    pk = klass.primary_key
+
+    updates = []
+    
+    for a in klass.serializable_attributes.reject { |a| a == pk }
+      anno = klass.ann(a)
+      updates << "#{field_for_attribute a, anno}=#{write_attr a, anno}"
+    end
+
+    updates = updates.join(', ')
+    
+    sql = "UPDATE #{klass.table} SET #{updates} WHERE #{pk_field klass}=#\{@#{pk}\}"
+
+    klass.module_eval %{
+      def og_update(store, options = nil)
+        #{insert_advices :pre, :og_update, klass, :advices}
+        sql = "#{sql}"
+        sql << " AND \#{options[:condition]}" if options and options[:condition]
+        changed = store.sql_update(sql)
+        #{insert_advices :post, :og_update, klass, :advices}
+        return changed
+      end
+    }    
+  end
+
+  # Compile the og_read method for the class. This method is 
+  # used to read (deserialize) the  given class from the store. 
+  # In order to allow for changing field/attribute orders a 
+  # field mapping hash is used.
+  
+  def eval_og_read(klass)
+    code = []
+    
+    attrs = klass.attributes
+    field_map = create_field_map(klass)
+
+    for a in attrs
+      anno = klass.ann(a)
+      
+      f = field_for_attribute(a, anno)
+
+      if col = field_map[f]
+        code << "@#{a} = #{read_attr a, anno, col}"
+      end
+    end
+
+    code = code.join('; ')
+
+    klass.module_eval %{
+       def og_read(res, row = 0, offset = 0)
+        #{insert_advices :pre, :og_read, klass, :advices}
+        #{code}
+        #{insert_advices :post, :og_read, klass, :advices}
+      end
+    }
+  end
+
+  # Compiles the og_delete method for this class. This method
+  # is used to delete instances of this class.
+  
+  def eval_og_delete klass
+    klass.module_eval %{
+      def og_delete(store, cascade = true)
+        #{insert_advices :pre, :og_delete, klass, :advices}
+        
+        if cascade
+          
+          transaction do |tx|
+            tx.exec "DELETE FROM #{klass.table} WHERE #{pk_field klass}=\#{pk}"
+            if descendants = #{klass}.ann.self[:descendants]
+              descendants.each do |dclass, foreign_key|
+                tx.exec "DELETE FROM \#{dclass::OGTABLE} WHERE \#{foreign_key}=\#{pk}"
+              end
+            end
+          end
+          
+        else
+          tx.exec "DELETE FROM #{klass.table} WHERE #{pk_field klass}=\#{pk}"
+        end
+        
+        #{insert_advices :post, :og_delete, klass, :advices}
+      end
+    }
+  end
+
+  # Creates the schema for this class. Can be intercepted with
+  # aspects to add special behaviours.
+
+  def eval_og_create_schema(klass)
+    klass.module_eval %{
+      def og_create_schema(store)
+        if Og.create_schema
+          #{insert_advices :pre, :og_create_schema, klass, :advices}
+          unless self.class.schema_inheritance_child?
+            store.create_table #{klass}
+          end
+          store.evolve_schema(#{klass})
+          #{insert_advices :post, :og_create_schema, klass, :advices}
+        end
+      end
+    }
+  end
+
+  # Precompile a class specific allocate method. If this is an 
+  # STI parent classes it reads the class from the resultset.
+
+  def eval_og_allocate(klass)  
+    if klass.schema_inheritance? 
+      klass.module_eval %{
+        def self.og_allocate(res, row = 0)
+          Object.constant(res[0]).allocate
+        end
+      }
+    else
+      klass.module_eval %{
+        def self.og_allocate(res, row = 0)
+          self.allocate
+        end
+      }
+    end
+  end
+
+  # ...
+  
+  def type_cast(klass, val)
+    typemap = {
+      Time      => :parse_timestamp,
+      Date      => :parse_date,
+      TrueClass => :parse_boolean
+    }
+
+    if method = typemap[klass]
+      send(method, val)
+    else
+      Integer(val) rescue Float(val) rescue raise "No conversion for #{klass} (#{val.inspect})"
+    end
+  end
+
   # :section: Deserialization methods.
 
   # Read a field (column) from a result set row.
@@ -1102,16 +1056,48 @@ private
   # Deserialize the join relations.
 
   def read_join_relations(obj, res_row, row, join_relations)
-    offset = obj.class.properties.size 
+    offset = obj.class.serializable_attributes.size 
 
     for rel in join_relations 
       rel_obj = rel[:target_class].og_allocate(res_row, row)
       rel_obj.og_read(res_row, row, offset) 
-      offset += rel_obj.class.properties.size 
+      offset += rel_obj.class.serializable_attributes.size 
       obj.instance_variable_set("@#{rel[:name]}", rel_obj)
     end
   end
 
+  # Deserialize one object from the ResultSet.
+
+  def read_one(res, klass, options = nil)
+    return nil if res.blank?
+
+    if options and join_relations = options[:include]
+      join_relations = [join_relations].flatten.collect do |n| 
+        klass.relation(n) 
+      end
+    end
+
+    res_row = res.next
+    
+    # causes STI classes to come back as the correct child class 
+    # if accessed from the superclass.
+    
+    klass = Og::Entity::entity_from_string(res_row[0]) if klass.schema_inheritance?
+    obj = klass.og_allocate(res_row, 0)
+
+    if options and options[:select]
+      read_row(obj, res, res_row, 0)
+    else
+      obj.og_read(res_row)
+      read_join_relations(obj, res_row, 0, join_relations) if join_relations
+    end
+
+    return obj
+
+  ensure
+    res.close
+  end
+
   # Deserialize all objects from the ResultSet.
 
   def read_all(res, klass, options = nil)
@@ -1156,13 +1142,24 @@ private
     end
   end
 
-end
+  # Returns true if a table exists within the database, false
+  # otherwise.
+
+  def table_exists?(table)
+    table_info(table) ? true : false
+  end
+  alias_method :table_exist?, :table_exists?
+
+private
 
+  def database_does_not_exist_exception?(ex)
+    false
+  end
+  
+  def table_already_exists_exception?(ex)
+    false
+  end    
+  
 end
 
-# * George Moschovitis <gm@navel.gr>
-# * Michael Neumann <mneumann@ntecs.de>
-# * Ghislain Mary
-# * Ysabel <deb@ysabel.org>
-# * Guillaume Pierronnet <guillaume.pierronnet@laposte.net>
-# * Rob Pitt <rob@motionpath.com>
+end