spatial_adapter 0.2.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006 Guilhem Vellut <guilhem.vellut+georuby@gmail.com>
+Copyright (c) 2010 Pete Deffendol <pete@fragility.us>
+
+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 OR COPYRIGHT HOLDERS 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.rdoc

@@ -0,0 +1,178 @@
+= Spatial Adapter for ActiveRecord
+
+This is the Spatial Adapter for ActiveRecord.  It enhances ActiveRecord to
+handle spatial datatypes in the following databases:
+
+- PostgreSQL (using PostGIS)
+- MySQL (using Spatial Extensions)
+
+== Dependencies
+
+The following gems are required:
+
+- GeoRuby
+- ActiveRecord (version 2.2.2 and up)
+
+For PostgreSQL:
+
+- PostGIS version 1.4.0 or higher should be installed in your database
+ 
+== Installation
+
+Choose ONE of the following installation methods.  You shouldn't have to do both.
+
+=== From RubyGems
+
+This is the preferred method of installation, and will pull in the required
+dependencies as well.
+
+  gem install spatial_adapter
+  
+In your Rails app, you can add a gem dependency in environment.rb:
+
+  config.gem "spatial_adapter"
+  
+=== As a Rails Plugin
+
+In your Rails project, run the following:
+
+script/plugin install git://github.com/fragility/spatial_adapter.git
+
+You need to have Git installed first.
+
+== Operations
+
+Geometric columns in your ActiveRecord models now appear just like any other
+column of other basic data types. They can also be dumped in ruby schema mode
+and loaded in migrations the same way as columns of basic types.
+
+=== Migrations
+
+Here is an example of code for the creation of a table with a geometric column
+in PostGIS, along with the addition of a spatial index on the column:
+ 
+  ActiveRecord::Schema.define do
+    create_table :table_points, :force => true do |t|
+      t.string :data
+      t.point :geom, :null => false, :srid => 123, :with_z => true
+    end
+  
+    add_index :table_points, :geom, :spatial => true
+  end
+
+Here is a related statement valid for MySql version <= 5.0.16:
+
+  ActiveRecord::Schema.define do
+    create_table "table_points", ;options=>"ENGINE=MyISAM", :force => true do |t|
+      t.string :data
+      t.point :geom, :null => false
+    end
+  
+    add_index :table_points, :geom, :spatial => true
+  end
+  
+=== Differences Between Databases
+
+- On all versions of MySQL, the :srid, :with_z, and :with_m options are ignored, since
+  they are not supported. 
+  
+- On MySQL versions <= 5.0.16, you have to add <tt>:options =>
+  "ENGINE=MyISAM"</tt> to the create_table statement, since only MyISAM tables
+  can have spatial columns.  In addition, only MyISAM tables may have spatial
+  indexes.
+
+=== Models
+
+Create your ActiveRecord models normally.  Spatial Adapter will automatically
+handle spatial columns, converting them to the appropriate GeoRuby type.
+
+  class TablePoint < ActiveRecord::Base
+  end
+
+=== Access
+
+Here is an example of row creation and access, using the model and the table
+defined above:
+
+  pt = TablePoint.new(
+    :data => "Hello!", 
+    :geom => Point.from_x_y_z(-1.6, 2.8, -3.4, 123))
+  pt.save
+  pt = TablePoint.find_first
+  puts pt.geom.x #access the geom column like any other
+
+=== Fixtures
+
+If you use fixtures for your unit tests, at some point, you will want to input
+a geometry. You could transform your geometries to a form suitable for YAML
+yourself every time but Spatial Adapter provides a method to do it for you:
++to_fixture_format+. You would use it like this, if the geometric column is a
+point:
+
+  fixture:
+    id: 1
+    data: HELLO
+    geom: <%= Point.from_x_y(123.5,321.9).to_fixture_format %>
+
+=== Finder Enhancements
+
+Enhancements to find_by_* and friends has been removed from this version of
+Spatial Adapter until a cleaner implementation can be made.  (The previous
+implementation made adapter-specific modifications to ActiveRecord::Base,
+which prevented multiple adapters from being loaded at once.)
+
+=== Geometric data types
+
+Ruby geometric datatypes are currently made available only through the GeoRuby
+library (http://georuby.rubyforge.org/): This is where the
+<tt>Point.from_x_y</tt> in the example above comes from.
+
+== Warning
+
+- Since ActiveRecord seems to keep only the string values directly returned
+  from the database, it translates from these to the correct types everytime
+  an attribute is read, which is probably ok for simple types, but might be
+  less than efficient for geometries, since the EWKB string has to be parsed
+  everytime. Also it means you cannot modify the geometry object returned from
+  an attribute directly:
+
+    place = Place.find_first
+    place.the_geom.y=123456.7 # this doesn't work
+ 
+  Since the translation to a geometry is performed every time the_geom is read,
+  the change to y will not be saved! You would have to do something like this:
+
+    place = Place.find_first
+    the_geom = place.the_geom
+    the_geom.y=123456.7
+    place.the_geom = the_geom
+
+== License
+
+The Spatial Adapter for ActiveRecord is released under the MIT license.
+
+== Latest Changes
+
+Spatial Adapter has been refactored and is now available as a Ruby gem. The
+dependency on Rails has been removed. Unfortunately, the current version is
+without some of the previous functionality, until a cleaner implementation is
+made.
+
+The previous release is available on the "legacy" branch.
+
+=== Removed Features in 0.2.0
+
+- Compatibility with ActiveRecord/Rails older than version 2.2.2
+- enhancements to find_by_* for spatial columns
+- to_fixture_format extension to the GeoRuby types
+
+These will hopefully be added back in the near future.
+
+== TODO
+
+- Add support for PostGIS geography types (in PostGIS 1.5.0+)
+
+== Support
+
+Any questions, enhancement proposals, bug notifications or corrections can be
+made via the project page at http://github.com/fragility/spatial_adapter

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/spatial_adapter.rb

@@ -0,0 +1,26 @@
+require 'geo_ruby'
+require 'active_record'
+
+module SpatialAdapter
+  #Translation of geometric data types
+  def geometry_data_types
+    {
+      :point => { :name => "POINT" },
+      :line_string => { :name => "LINESTRING" },
+      :polygon => { :name => "POLYGON" },
+      :geometry_collection => { :name => "GEOMETRYCOLLECTION" },
+      :multi_point => { :name => "MULTIPOINT" },
+      :multi_line_string => { :name => "MULTILINESTRING" },
+      :multi_polygon => { :name => "MULTIPOLYGON" },
+      :geometry => { :name => "GEOMETRY"}
+    }
+  end
+end
+
+require 'spatial_adapter/raw_geom_info'
+require 'spatial_adapter/spatial_column'
+require 'spatial_adapter/schema_definitions'
+require 'spatial_adapter/schema_dumper'
+require 'spatial_adapter/table_definition'
+require 'spatial_adapter/adapters/postgis'
+require 'spatial_adapter/adapters/mysql'

data/lib/spatial_adapter/adapters/mysql.rb

@@ -0,0 +1,101 @@
+require 'active_record/connection_adapters/mysql_adapter'
+
+ActiveRecord::ConnectionAdapters::MysqlAdapter.class_eval do
+  include SpatialAdapter
+
+  def supports_geography?
+    false
+  end
+  
+  alias :original_native_database_types :native_database_types
+  def native_database_types
+    original_native_database_types.merge!(geometry_data_types)
+  end
+ 
+  alias :original_quote :quote
+  #Redefines the quote method to add behaviour for when a Geometry is encountered ; used when binding variables in find_by methods
+  def quote(value, column = nil)
+    if value.kind_of?(GeoRuby::SimpleFeatures::Geometry)
+      "GeomFromWKB(0x#{value.as_hex_wkb},#{value.srid})"
+    else
+      original_quote(value,column)
+    end
+  end
+  
+  #Redefinition of columns to add the information that a column is geometric
+  def columns(table_name, name = nil)#:nodoc:
+    sql = "SHOW FIELDS FROM #{quote_table_name(table_name)}"
+    columns = []
+    result = execute(sql, name)
+    result.each do |field|
+      if field[1] =~ /geometry|point|linestring|polygon|multipoint|multilinestring|multipolygon|geometrycollection/i
+        #to note that the column is spatial
+        columns << ActiveRecord::ConnectionAdapters::SpatialMysqlColumn.new(field[0], field[4], field[1], field[2] == "YES")
+      else
+        columns << ActiveRecord::ConnectionAdapters::MysqlColumn.new(field[0], field[4], field[1], field[2] == "YES")
+      end
+    end
+    result.free
+    columns
+  end
+
+
+  #operations relative to migrations
+
+  #Redefines add_index to support the case where the index is spatial
+  #If the :spatial key in the options table is true, then the sql string for a spatial index is created
+  def add_index(table_name,column_name,options = {})
+    index_name = options[:name] || index_name(table_name,:column => Array(column_name))
+    
+    if options[:spatial]
+      execute "CREATE SPATIAL INDEX #{index_name} ON #{table_name} (#{Array(column_name).join(", ")})"
+    else
+      super
+    end
+  end
+
+  #Check the nature of the index : If it is SPATIAL, it is indicated in the IndexDefinition object (redefined to add the spatial flag in spatial_adapter_common.rb)
+  def indexes(table_name, name = nil)#:nodoc:
+    indexes = []
+    current_index = nil
+    execute("SHOW KEYS FROM #{table_name}", name).each do |row|
+      if current_index != row[2]
+        next if row[2] == "PRIMARY" # skip the primary key
+        current_index = row[2]
+        indexes << ActiveRecord::ConnectionAdapters::IndexDefinition.new(row[0], row[2], row[1] == "0", [], row[10] == "SPATIAL")
+      end
+      indexes.last.columns << row[4]
+    end
+    indexes
+  end
+        
+  #Get the table creation options : Only the engine for now. The text encoding could also be parsed and returned here.
+  def options_for(table)
+    result = execute("show table status like '#{table}'")
+    engine = result.fetch_row[1]
+    if engine !~ /inno/i #inno is default so do nothing for it in order not to clutter the migration
+      "ENGINE=#{engine}" 
+    else
+      nil
+    end
+  end
+end
+
+
+module ActiveRecord
+  module ConnectionAdapters
+    class SpatialMysqlColumn < MysqlColumn
+      include SpatialAdapter::SpatialColumn
+      
+      #MySql-specific geometry string parsing. By default, MySql returns geometries in strict wkb format with "0" characters in the first 4 positions.
+      def self.string_to_geometry(string)
+        return string unless string.is_a?(String)
+        begin
+          GeoRuby::SimpleFeatures::Geometry.from_ewkb(string[4..-1])
+        rescue Exception => exception
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/spatial_adapter/adapters/postgis.rb

@@ -0,0 +1,302 @@
+require 'active_record/connection_adapters/postgresql_adapter'
+
+ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.class_eval do
+  include SpatialAdapter
+  
+  def postgis_version
+    begin
+      select_value("SELECT postgis_full_version()").scan(/POSTGIS="([\d\.]*)"/)[0][0]
+    rescue ActiveRecord::StatementInvalid
+      nil
+    end
+  end
+  
+  def postgis_major_version
+    version = postgis_version
+    version ? version.scan(/^(\d)\.\d\.\d$/)[0][0].to_i : nil
+  end
+  
+  def postgis_minor_version
+    version = postgis_version
+    version ? version.scan(/^\d\.(\d)\.\d$/)[0][0].to_i : nil
+  end
+  
+  def spatial?
+    !postgis_version.nil?
+  end
+  
+  def supports_geography?
+    postgis_major_version > 1 || (postgis_major_version == 1 && postgis_minor_version >= 5)
+  end
+  
+  alias :original_native_database_types :native_database_types
+  def native_database_types
+    original_native_database_types.merge!(geometry_data_types)
+  end
+
+  alias :original_quote :quote
+  #Redefines the quote method to add behaviour for when a Geometry is encountered
+  def quote(value, column = nil)
+    if value.kind_of?(GeoRuby::SimpleFeatures::Geometry)
+      "'#{value.as_hex_ewkb}'"
+    else
+      original_quote(value,column)
+    end
+  end
+
+  def columns(table_name, name = nil) #:nodoc:
+    raw_geom_infos = column_spatial_info(table_name)
+    
+    column_definitions(table_name).collect do |name, type, default, notnull|
+      case type
+      when /geometry/i
+        raw_geom_info = raw_geom_infos[name]
+        if raw_geom_info.nil?
+          ActiveRecord::ConnectionAdapters::SpatialPostgreSQLColumn.create_simplified(name, default, notnull == "f")
+        else
+          ActiveRecord::ConnectionAdapters::SpatialPostgreSQLColumn.new(name, default, raw_geom_info.type, notnull == "f", raw_geom_info.srid, raw_geom_info.with_z, raw_geom_info.with_m)
+        end
+      else
+        ActiveRecord::ConnectionAdapters::PostgreSQLColumn.new(name, default, type, notnull == "f")
+      end
+    end
+  end
+
+  def create_table(table_name, options = {})
+    # Using the subclassed table definition
+    table_definition = ActiveRecord::ConnectionAdapters::PostgreSQLTableDefinition.new(self)
+    table_definition.primary_key(options[:primary_key] || ActiveRecord::Base.get_primary_key(table_name.to_s.singularize)) unless options[:id] == false
+
+    yield table_definition if block_given?
+
+    if options[:force] && table_exists?(table_name)
+      drop_table(table_name, options)
+    end
+
+    create_sql = "CREATE#{' TEMPORARY' if options[:temporary]} TABLE "
+    create_sql << "#{quote_table_name(table_name)} ("
+    create_sql << table_definition.to_sql
+    create_sql << ") #{options[:options]}"
+    execute create_sql
+
+    # This is the additional portion for PostGIS
+    unless table_definition.geom_columns.nil?
+      table_definition.geom_columns.each do |geom_column|
+        execute geom_column.to_sql(table_name)
+      end
+    end
+  end
+
+  alias :original_remove_column :remove_column
+  def remove_column(table_name, column_name, options = {})
+    columns(table_name).each do |col|
+      if col.name == column_name.to_s 
+        #check if the column is geometric
+        unless geometry_data_types[col.type].nil? or
+               (options[:remove_using_dropgeometrycolumn] == false)
+          execute "SELECT DropGeometryColumn('#{table_name}','#{column_name}')"
+        else
+          original_remove_column(table_name, column_name)
+        end
+      end
+    end
+  end
+  
+  alias :original_add_column :add_column
+  def add_column(table_name, column_name, type, options = {})
+    unless geometry_data_types[type].nil? or (options[:create_using_addgeometrycolumn] == false)
+      geom_column = ActiveRecord::ConnectionAdapters::PostgreSQLColumnDefinition.new(self, column_name, type, nil, nil, options[:null], options[:srid] || -1 , options[:with_z] || false , options[:with_m] || false)
+      execute geom_column.to_sql(table_name)
+    else
+      original_add_column(table_name, column_name, type, options)
+    end
+  end
+
+  # Adds an index to a column.
+  def add_index(table_name, column_name, options = {})
+    column_names = Array(column_name)
+    index_name   = index_name(table_name, :column => column_names)
+
+    if Hash === options # legacy support, since this param was a string
+      index_type = options[:unique] ? "UNIQUE" : ""
+      index_name = options[:name] || index_name
+      index_method = options[:spatial] ? 'USING GIST' : ""
+    else
+      index_type = options
+    end
+    quoted_column_names = column_names.map { |e| quote_column_name(e) }.join(", ")
+    execute "CREATE #{index_type} INDEX #{quote_column_name(index_name)} ON #{quote_table_name(table_name)} #{index_method} (#{quoted_column_names})"
+  end
+
+  # Returns the list of all indexes for a table.
+  # This is a full replacement for the ActiveRecord method and as a result
+  # has a higher probability of breaking in future releases
+  def indexes(table_name, name = nil)
+    schemas = schema_search_path.split(/,/).map { |p| quote(p) }.join(',')
+    result = query(<<-SQL, name)
+    SELECT i.relname, d.indisunique, d.indkey, t.oid, am.amname
+      FROM pg_class t, pg_class i, pg_index d, pg_attribute a, pg_am am
+    WHERE i.relkind = 'i'
+      AND d.indexrelid = i.oid
+      AND d.indisprimary = 'f'
+      AND t.oid = d.indrelid
+      AND i.relam = am.oid
+      AND t.relname = '#{table_name}'
+      AND a.attrelid = t.oid
+      AND ( d.indkey[0]=a.attnum OR d.indkey[1]=a.attnum
+        OR d.indkey[2]=a.attnum OR d.indkey[3]=a.attnum
+        OR d.indkey[4]=a.attnum OR d.indkey[5]=a.attnum
+        OR d.indkey[6]=a.attnum OR d.indkey[7]=a.attnum
+        OR d.indkey[8]=a.attnum OR d.indkey[9]=a.attnum )
+    ORDER BY i.relname
+    SQL
+
+    indexes = []
+
+    indexes = result.map do |row|
+      index_name = row[0]
+      unique = row[1] == 't'
+      indkey = row[2].split(" ")
+      oid = row[3]
+      spatial = row[4] == "gist"
+
+      columns = query(<<-SQL, "Columns for index #{row[0]} on #{table_name}").inject({}) {|attlist, r| attlist[r[1]] = r[0]; attlist}
+      SELECT a.attname, a.attnum
+      FROM pg_attribute a
+      WHERE a.attrelid = #{oid}
+      AND a.attnum IN (#{indkey.join(",")})
+      SQL
+
+      column_names = indkey.map {|attnum| columns[attnum] }
+      ActiveRecord::ConnectionAdapters::IndexDefinition.new(table_name, index_name, unique, column_names, spatial)
+    end
+
+    indexes
+  end
+
+  def disable_referential_integrity(&block) #:nodoc:
+    if supports_disable_referential_integrity?() then
+      execute(tables_without_postgis.collect { |name| "ALTER TABLE #{quote_table_name(name)} DISABLE TRIGGER ALL" }.join(";"))
+    end
+    yield
+  ensure
+    if supports_disable_referential_integrity?() then
+      execute(tables_without_postgis.collect { |name| "ALTER TABLE #{quote_table_name(name)} ENABLE TRIGGER ALL" }.join(";"))
+    end
+  end
+
+  private
+  
+  def tables_without_postgis
+    tables - %w{ geometry_columns spatial_ref_sys }
+  end
+  
+  def column_spatial_info(table_name)
+    constr = query("SELECT * FROM geometry_columns WHERE f_table_name = '#{table_name}'")
+
+    raw_geom_infos = {}
+    constr.each do |constr_def_a|
+      raw_geom_infos[constr_def_a[3]] ||= SpatialAdapter::RawGeomInfo.new
+      raw_geom_infos[constr_def_a[3]].type = constr_def_a[6]
+      raw_geom_infos[constr_def_a[3]].dimension = constr_def_a[4].to_i
+      raw_geom_infos[constr_def_a[3]].srid = constr_def_a[5].to_i
+
+      if raw_geom_infos[constr_def_a[3]].type[-1] == ?M
+        raw_geom_infos[constr_def_a[3]].with_m = true
+        raw_geom_infos[constr_def_a[3]].type.chop!
+      else
+        raw_geom_infos[constr_def_a[3]].with_m = false
+      end
+    end
+
+    raw_geom_infos.each_value do |raw_geom_info|
+      #check the presence of z and m
+      raw_geom_info.convert!
+    end
+
+    raw_geom_infos
+
+  end
+end
+
+module ActiveRecord
+  module ConnectionAdapters
+    class PostgreSQLTableDefinition < TableDefinition
+      attr_reader :geom_columns
+      
+      def column(name, type, options = {})
+        unless (@base.geometry_data_types[type.to_sym].nil? or
+                (options[:create_using_addgeometrycolumn] == false))
+
+          geom_column = PostgreSQLColumnDefinition.new(@base, name, type)
+          geom_column.null = options[:null]
+          geom_column.srid = options[:srid] || -1
+          geom_column.with_z = options[:with_z] || false 
+          geom_column.with_m = options[:with_m] || false
+         
+          @geom_columns ||= []
+          @geom_columns << geom_column          
+        else
+          super(name, type, options)
+        end
+      end    
+    end
+
+    class PostgreSQLColumnDefinition < ColumnDefinition
+      attr_accessor :srid, :with_z, :with_m
+      attr_reader :spatial
+
+      def initialize(base = nil, name = nil, type=nil, limit=nil, default=nil, null=nil, srid=-1, with_z=false, with_m=false)
+        super(base, name, type, limit, default,null)
+        @spatial = true
+        @srid = srid
+        @with_z = with_z
+        @with_m = with_m
+      end
+      
+      def to_sql(table_name)
+        if @spatial
+          type_sql = type_to_sql(type.to_sym)
+          type_sql += "M" if with_m and !with_z
+          if with_m and with_z
+            dimension = 4 
+          elsif with_m or with_z
+            dimension = 3
+          else
+            dimension = 2
+          end
+          
+          column_sql = "SELECT AddGeometryColumn('#{table_name}','#{name}',#{srid},'#{type_sql}',#{dimension})"
+          column_sql += ";ALTER TABLE #{table_name} ALTER #{name} SET NOT NULL" if null == false
+          column_sql
+        else
+          super
+        end
+      end
+  
+      private
+      
+      def type_to_sql(name, limit=nil)
+        base.type_to_sql(name, limit) rescue name
+      end   
+    end
+  end
+end
+
+module ActiveRecord
+  module ConnectionAdapters
+    class SpatialPostgreSQLColumn < PostgreSQLColumn
+      include SpatialAdapter::SpatialColumn
+
+      #Transforms a string to a geometry. PostGIS returns a HewEWKB string.
+      def self.string_to_geometry(string)
+        return string unless string.is_a?(String)
+        GeoRuby::SimpleFeatures::Geometry.from_hex_ewkb(string) rescue nil
+      end
+
+      def self.create_simplified(name,default,null = true)
+        new(name,default,"geometry",null,nil,nil,nil)
+      end
+    end
+  end
+end