activerecord-postgres-earthdistance: A Ruby repository from cluesque

#ActiveRecord + PostgreSQL Earthdistance

Check distances with latitude and longitude using PostgreSQL special indexes. This gem enables your model to query the database using the earthdistance extension. This should be much faster than using trigonometry functions over standart indexs.

##Requirements

Postgresql 9.1+ with contrib and Rails 3.1+ On Ubuntu, this is easy: sudo apt-get install postgresql-contrib-9.1

On Mac you have a couple of options:

the binary package kindly provided by EnterpriseDB
Homebrew’s Postgres installation also includes the contrib packages: brew install postgres
Postgres.app

##Install

Earthdistance is a PostgreSQL contrib module, check it out first.

Then, just add this to your Gemfile:

gem 'activerecord-postgres-earthdistance'

And run your bundler:

bundle install

Now you need to create a migration that adds earthdistance support for your PostgreSQL database:

rails g earth_distance:setup

Run it:

rake db:migrate

Now let's add some gist indexes to make queries ultra-fast. For the model Place we could create an index over the lat and lng fields:

rails g migration add_index_to_places

Edit the created migration:

class AddIndexToPlaces < ActiveRecord::Migration
  def change
    add_earthdistance_index :places
  end
end

This will create the index with a SQL like this:

CREATE INDEX places_earthdistance_ix ON places USING GIST (ll_to_earth(lat, lng));

##Usage

This gem only provides a custom serialization coder. If you want to use it just put in your Gemfile:

gem 'activerecord-postgres-earthdistance'

Now add a line (for each earthdistance column) on the model you have your earthdistance columns. Assuming a model called Person, with a data field on it, the code should look like:

class Place < ActiveRecord::Base
  acts_as_geolocated
end

This way, you will automatically look for columns with names such as lat/latitude and lng/longitude. But you can use alternative names passing them as:

class Place < ActiveRecord::Base
  acts_as_geolocated lat: 'latitude_column_name', lng: 'longitude_column_name'
end

###Querying the database

To query for all places within a given radius of 100 meters from the origin -22.951916,-43.210487 just use:

Place.within_radius(100, -22.951916, -43.210487).all

You can also order the records based on the distance from a point

Place.within_radius(100, -22.951916,-43.210487).order_by_distance(-22.951916,-43.210487)

##Test Database

To have earthdistance enabled when you load your database schema (as happens in rake db:test:prepare), you have two options.

The first option is creating a template database with earthdistance installed and set the template option in database.yml to that database.

The second option is to uncomment or add the following line in config/application.rb

config.active_record.schema_format = :sql

This will change your schema dumps from Ruby to SQL. If you're unsure about the implications of this change, we suggest reading this Rails Guide.

##Help

You can use issues in github for that. Or else you can reach us at twitter: @dbiazus

##Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don’t break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.

cluesque/activerecord-postgres-earthdistance