= Spatial Adapter for ActiveRecord
This is the Spatial Adapter for ActiveRecord. It enhances ActiveRecord to handle spatial datatypes in the following databases:
== Dependencies
The following gems are required:
For PostgreSQL:
== 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 a Rails 2.x app, you can add a gem dependency in environment.rb:
config.gem 'spatial_adapter'
In a Rails 3 app, add a gem dependency to Gemfile:
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.
== Configuration
Choose the database type for which you would like to use spatial_adapter, and load each with
require 'spatial_adapter/[database]'
where [database] should be replaced with one of the following:
For example to use the PostgreSQL spatial adapter:
require 'spatial_adapter/postgresql'
In a Rails app, spatial_adapter will automatically load the adapter for the database specified in your database.yml configuration.
== 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 => trueend
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 => trueend
=== 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 :options => "ENGINE=MyISAM" 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 findby* 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 Point.from_x_y 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
These will hopefully be added back in the near future.
== Support
Any questions, enhancement proposals, bug notifications or corrections can be made via the project page at http://github.com/fragility/spatial_adapter
== Running Tests
The gem depdencencies can be installed with bundle install.
You will need to set up an empty database named spatial_adapter for each
adapter you want to test.
Tests are partitioned by adapter and can be run using separate rake task.
bundle exec rake spec:[adapter]