activerecord-postgis-adapter 0.5.1 → 0.6.0

data/Documentation.rdoc

@@ -0,0 +1,322 @@
+== \Documentation for the PostGIS \ActiveRecord Adapter
+
+This document provides basic how-to information that should help get you started with integrating your Rails application with a PostGIS database. We cover three parts:
+
+* How to install the adapter, and how to configure your database.yml.
+* How to set up and configure spatial columns and tables.
+* How to read, write, and query spatial data.
+
+This document is part of the distribution for the activerecord-postgis-adapter gem. For more information, please visit http://dazuma.github.com/activerecord-postgis-adapter.
+
+== Installation and Configuration
+
+=== General Installation Considerations
+
+Generally, we recommend starting with the latest versions of Ruby, Rails, PostgreSQL, and PostGIS. As of this writing, those are Ruby 1.9.3, Rails 3.2, PostgreSQL 9.2, and PostGIS 2.0. If you cannot upgrade, the minimum supported configuration is the following:
+
+* Ruby 1.8.7
+* Rails 3.0.3
+* PostgreSQL 9.0
+* PostGIS 1.5
+
+However, older software versions can make for a more involved setup process, so we recommend using the latest available if possible.
+
+As of this writing, Rails 4.0.0 beta 1 has just been released. This version of activerecord-postgis-adapter does support Rails 4, but because the software is still beta, the usual caveats apply.
+
+JRuby and the JDBC Postgres Adapter is supported. (But, as of this writing, the JDBC adapters themselves are not yet compatible with Rails 4.)
+  
+=== Creating a Spatial Rails App
+
+This section covers starting a new Rails application from scratch. If you need to add geospatial capabilities to an existing Rails application (i.e. you need to convert a non-spatial database to a spatial database), see the section on "Upgrading a Database With Spatial Features" below.
+
+To create a new Rails application using activerecord-postgis-adapter, start by using the postgresql adapter.
+
+  rails new my_app --database=postgresql
+
+Next, add the activerecord-postgis-adapter gem to the Gemfile as follows:
+
+  gem 'activerecord-postgis-adapter'
+
+We also recommend including the "squeel" gem, which comes in very useful for writing spatial queries. Then run <code>bundle install</code> to complete your bundle.
+
+The adapter includes a railtie that provides specialized rake tasks for managing spatial databases. Earlier versions of this adapter required you to load that railtie explicitly by adding a certain require statement to your <code>config/application.rb</code>. As of version 0.6, that explicit require statement is no longer necessary. If your code already has that require statement, it will not harm anything in this version, but it is considered deprecated.
+
+Next, you need to modify your <code>config/database.yml</code> file to invoke the postgis adapter, and to provide additional information it may need to set up a new database with spatial features. For example, at minimum, you will need to change the <code>adapter</code> field from "postgresql" to "postgis". Please see the Configuration sections below to see how to set up your database configs properly before proceeding.
+
+Once you have set up your database configs, you should be able to run:
+
+  rake db:create
+
+to create your development database. The adapter will automatically add the PostGIS spatial definitions to your database.
+
+When you create your production database, you'll also need to add PostGIS to that database. The adapter does not provide rake tasks for setting up your production database; you will have to do that yourself. Generally, that means logging into your newly created production database and running, as a superuser:
+
+  CREATE EXTENSION postgis;
+
+For more information, see the PostGIS documentation, or any relevant documentation provided by your hosting service.
+
+=== Upgrading an Existing Database With Spatial Features
+
+If you have an existing Rails app and an existing database that uses Postgres, and you want to add geospatial features, you should follow these steps.
+
+First, add the activerecord-postgis-adapter gem to the Gemfile, and update your bundle by running <code>bundle install</code>.
+
+Next, modify your <code>config/database.yml</code> file to invoke the postgis adapter, as described above. At minimum, you will need to change the <code>adapter</code> field from "postgresql" to "postgis".
+
+Once you have set up your database configs, run:
+
+  rake db:gis:setup
+
+This rake task adds the PostGIS extension to your existing development database.
+
+Prior to deployment, you will also need to add the PostGIS extension to your production database. Generally, that means logging into your production database and running, as a superuser:
+
+  CREATE EXTENSION postgis;
+
+For more information, see the PostGIS documentation, or any relevant documentation provided by your hosting service.
+
+=== Recommended Configuration
+
+Setting up the database.yml is a bit of an art. In this section, we'll cover a recommended configuration to get you started. This should be sufficient for most cases. We'll cover some of the alternate configuration options in more detail in the next section.
+
+Assuming you have at least PostgreSQL 9.2 and PostGIS 2.0, the following is the recommended configuration:
+
+  development:
+    adapter: postgis
+    encoding: unicode
+    postgis_extension: true
+    schema_search_path: public,postgis
+    pool: 5
+    database: my_app_development    # substitute your dev database name
+    username: my_app_user           # substitute the username your app will use to connect
+    password: my_app_password       # substitute the user's password
+    su_username: my_global_user     # substitute a superuser for the database
+    su_password: my_global_pasword  # substitute the superuser's password
+
+The adapter name _must_ be set to "postgis" to invoke the adapter.
+
+The <code>postgis_extension</code> tells the adapter to add the PostGIS extension to the database when the database is created (i.e. <code>rake db:create</code>). If it is missing, you will need to add PostGIS to your database through some other mechanism.
+
+The <code>schema_search_path</code> is an important value. If you include a schema called "postgis" in the search path, the adapter will isolate all the PostGIS-specific definitions, including data types, functions, views, and so forth, into that schema instead of including them in the default "public" schema. Then, when Rails needs to dump the schema (for example, to replicate it for the test database), it can use that isolation to omit the PostGIS definitions from cluttering the schema dump.
+
+The credentials that your app will use to connect to the database should be given in the <code>username</code> and <code>password</code> fields. Generally, for security reasons, it is not a good idea for this user to have "superuser" privileges. However, the adapter _does_ need superuser privileges for one function: installing PostGIS into the database when the database is first created. Therefore, you should provide a _second_ set of credentials, <code>su_username</code> and <code>su_password</code>, which identify a superuser account. This account will be used once, when you create the database (i.e. rake db:create), and not afterward.
+
+=== Alternate Configuration Schemes
+
+Here are some configuration options for other cases.
+
+*If you have an older PostgreSQL or an older PostGIS* you will not be able to use the Postgres extension mechanism to install PostGIS into your database. In this case, instead of including <code>postgis_extension</code>, you should include <code>script_dir</code> in the configuration. This should be set to a directory containing two files that contain all the PostGIS-provided spatial definitions: <code>postgis.sql</code> and <code>spatial_ref_sys.sql</code>.
+
+This directory is usually in the share/contrib directory of your PostgreSQL installation. To find it, run
+
+  pg_config --sharedir
+
+Then, append <code>contrib</code>, and look for a subdirectory named "postgis-(version)". For example, if you installed PostgreSQL in /usr/local, and you are running PostGIS 1.5, you should probably set <code>script_dir</code> to <code>/usr/local/share/contrib/postgis-1.5</code>.
+
+*If you are using a template to install PostGIS into your database* then set the <code>template</code> configuration as appropriate, and _omit_ both the <code>postgis_extension</code> and <code>script_dir</code> configurations. In this case, you also do not need to include <code>su_username</code> or <code>su_password</code>, since those configurations apply only to adding the extension or using the script dir.
+
+*If you do not want the spatial declarations to live in a separate schema* then do _not_ include "postgis" on the <code>schema_search_path</code>. Note that we recommend separating PostGIS into a separate schema, because that is the best way to ensure <code>rake test</code> works properly and is able to create the test database.
+
+== Spatial Database Structure
+
+A spatial database is one that includes a set of data types, functions, tables, and other objects related to geospatial data. When these objects are present in your database, you can use them to store and query spatial objects such as points, lines, and polygons.
+
+PostGIS is a plugin for PostgreSQL that provides definitions for the objects you need to add to a database to enable geospatial capabilities.
+
+When you create your Rails database as described above in the section on installation and configuration, activerecord-postgis-adapter automatically invokes PostGIS to add the appropriate definitions to your database. You can determine whether your database includes the correct definitions by attempting to invoke the POSTGIS_VERSION function:
+
+  SELECT POSTGIS_VERSION();   # succeeds if PostGIS objects are present.
+
+Standard spatial databases also include a table called <code>spatial_ref_sys</code>. This table includes a set of "spatial reference systems", or coordinate systems--- for example, WGS84 latitude and longitude, or Mercator Projection. Spatial databases also usually include a table called <code>geometry_columns</code>, which includes information on each database column that includes geometric data. In recent versions of PostGIS, <code>geometry_columns</code> is actually not a table but a view into the system catalogs.
+
+=== Creating Spatial Tables
+
+To store spatial data, you must create a column with a spatial type. PostGIS provides a variety of spatial types, including point, linestring, polygon, and different kinds of collections. These types are defined in a standard produced by the Open Geospatial Consortium. Furthermore, you can specify options indicating the coordinate system and number of coordinates for the values you are storing.
+
+The activerecord-postgis-adapter extends \ActiveRecord's migration syntax to support these spatial types. The following example creates four spatial columns in a table:
+
+  create_table :my_spatial_table do |t|
+    t.column :shape1, :geometry
+    t.geometry :shape2
+    t.line_string :path, :srid => 3785
+    t.point :lonlat, :geographic => true
+    t.point :lonlatheight, :geographic => true, :has_z => true
+  end
+
+The first column, "shape1", is created with type "geometry". This is a general "base class" for spatial types; the column declares that it can contain values of _any_ spatial type. The second column, "shape2", uses a shorthand syntax for the same type. Like "normal" types, you can create a column either by invoking <code>column</code> or invoking the name of the type directly.
+
+The third column, "path", has a specific geometric type, <code>line_string</code>. It also specifies an SRID (spatial reference ID) that indicates which coordinate system it expects the data to be in. The column now has a "constraint" on it; it will accept only LineString data, and only data whose SRID is 3785.
+
+The fourth column, "lonlat", has the <code>point</code> type, and accepts only Point data. Furthermore, it declares the column as "geographic", which means it accepts longitude/latitude data, and performs calculations such as distances using a spheroidal domain.
+
+The fifth column, "lonlatheight", is a geographic (longitude/latitude) point that also includes a third "z" coordinate that can be used to store height information.
+
+The following are the data types understood by PostGIS and exposed by activerecord-postgis-adapter:
+
+* <tt>:geometry</tt> -- Any geometric type
+* <tt>:point</tt> -- Point data
+* <tt>:line_string</tt> -- LineString data
+* <tt>:polygon</tt> -- Polygon data
+* <tt>:geometry_collection</tt> -- Any collection type
+* <tt>:multi_point</tt> -- A collection of Points
+* <tt>:multi_line_string</tt> -- A collection of LineStrings
+* <tt>:multi_polygon</tt> -- A collection of Polygons
+
+Following are the options understood by the adapter:
+
+* <tt>:geographic</tt> -- If set to true, create a PostGIS geography column for longitude/latitude data over a spheroidal domain; otherwise create a geometry column in a flat coordinate system. Default is false. Also implies :srid set to 4326.
+* <tt>:srid</tt> -- Set a SRID constraint for the column. Default is 4326 for a geography column, or -1 for a geometry column. Note that PostGIS currently (as of version 2.0) requires geography columns to have SRID 4326, so this constraint is of limited use for geography columns.
+* <tt>:has_z</tt> -- Specify that objects in this column include a Z coordinate. Default is false.
+* <tt>:has_m</tt> -- Specify that objects in this column include an M coordinate. Default is false.
+
+The adapter also extends the \ActiveRecord migration syntax for creating spatial indexes. To create a PostGIS spatial index, simply set the :spatial option to true, as follows:
+
+  change_table :my_spatial_table do |t|
+    t.index :lonlat, :spatial => true
+  end
+
+=== Configuring the \ActiveRecord class
+
+\ActiveRecord's usefulness stems from the way it automatically configures classes based on the database structure and schema. If a column in the database has an integer type, \ActiveRecord automatically casts the data to a Ruby Integer. In the same way, the activerecord-postgis-adapter automatically casts spatial data to a corresponding RGeo data type.
+
+However, RGeo offers more "flexibility" in its type system than can be interpreted solely from analyzing the database column. For example, you can configure RGeo objects to exhibit certain behaviors related to their serialization, validation, coordinate system, or computation. These settings are embodied in the RGeo "factory" associated with the object.
+
+Therefore, you can configure the adapter to use a particular factory (i.e. a particular combination of settings) for data associated with each column in the database. This is done by calling class methods on the \ActiveRecord class associated with that database table. Specifically, you can call <code>set_rgeo_factory_for_column</code> to set the factory that \ActiveRecord uses for a particular column.
+
+You can also provide a "factory generator" function which takes information from the database column and returns a suitable factory. Set the factory generator by setting the <code>rgeo_factory_generator</code> class attribute of your \ActiveRecord class. The generator should be a callable object that takes a hash that could include the following keys:
+
+* <tt>:srid</tt> -- the SRID of the database column
+* <tt>:has_z_coordinate</tt> -- true if the database column has a Z coordinate
+* <tt>:has_m_coordinate</tt> -- true if the database column has a M coordinate
+* <tt>:geographic</tt> -- true if the database column is geographic instead of geometric
+
+Here are some examples, given the spatial table defined above:
+
+  class MySpatialTable < ActiveRecord::Base
+    
+    # By default, use the GEOS implementation for spatial columns.
+    self.rgeo_factory_generator = RGeo::Geos.factory_generator
+    
+    # But use a geographic implementation for the :lonlat column.
+    set_rgeo_factory_for_column(:lonlat, RGeo::Geographic.spherical_factory(:srid => 4326))
+    
+  end
+
+The <code>rgeo_factory_generator</code> attribute and <code>set_rgeo_factory_for_column</code> method are actually implemented (and documented) in the "rgeo-activerecord" gem, which is a dependency of the activerecord-postgis-adapter.
+
+=== Schema Dump and Reload
+
+The presence of geospatial data in a database causes some issues with \ActiveRecord's schema dump and restore functions. This is because (1) installing PostGIS into your database injects a lot of objects in your database that can clutter up schema dumps, and (2) to define a spatial column correctly, you generally must call a SQL function such as AddGeometryColumn(), and Rails's schema dumper isn't smart enough to reproduce those function calls.
+
+Because of this, we recommend the following.
+
+* Install the PostGIS definitions in a separate schema called "postgis" (as described in the recommended installation procedure above). The activerecord-postgis-adapter will ignore a schema called "postgis" when dumping the schema, thus omitting the clutter.
+
+* Set the \ActiveRecord schema format to <code>:ruby</code>, _not_ <code>:sql</code>. The former emits higher level commands that can be interpreted correctly to reproduce the schema. The latter, however, emits low level SQL, which loses information such as the fact that AddGeometryColumn() was originally used to generate a column. Executing a <code>:sql</code> format schema dump will _not_ correctly reproduce the schema.
+
+Of course, the above discussion is really relevant only if you are using the \ActiveRecord rake tasks that create and restore databases, either directly such as <code>rake db:create</code> or indirectly such as <code>rake test</code>. It does not have any effect on running migrations or normal website execution.
+
+== Working With Spatial Data
+
+Of course, you're using this adapter because you want to work with geospatial data in your \ActiveRecord models. Once you've installed the adapter, set up your database, and run your migrations, you can interact directly with spatial data in your models as RGeo objects.
+
+RGeo is a Ruby implementation of the industry standard OGC Simple Features specification. It's a set of data types that can represent a variety of geospatial objects such as points, lines, polygons, and collections. It also provides the standard set of spatial analysis operations such as computing intersections or bounding boxes, calculating length or area, and so forth. We recommend browsing the RGeo documentation for a clearer understanding of its capabilities. For now, just note that the data values you will be working with are all RGeo geometry objects.
+
+=== Reading and Writing Spatial Columns
+
+When you access a spatial attribute on your \ActiveRecord model, it is given to you as an RGeo geometry object (or nil, for attributes that allow null values). You can then call the RGeo api on the object. For example, consider the MySpatialTable class we worked with above:
+
+  record = MySpatialTable.find(1)
+  p = record.lonlat                  # Returns an RGeo::Feature::Point
+  puts p.x                           # displays the x coordinate
+  puts p.geometry_type.type_name     # displays "Point"
+
+The RGeo factory for the value is determined by how you configured the \ActiveRecord class, as described above. In this case, we explicitly set a spherical factory for the <code>:lonlat</code> column:
+
+  factory = p.factory                # returns a spherical factory
+
+You can set a spatial attribute by providing an RGeo geometry object, or by providing the WKT string representation of the geometry. If a string is provided, the activerecord-postgis-adapter will attempt to parse it as WKT and set the value accordingly.
+
+  record.lonlat = 'POINT(-122, 47)'  # sets the value to the given point
+
+If the WKT parsing fails, the value currently will be silently set to nil. In the future, however, this will raise an exception.
+
+  record.lonlat = 'POINT(x)'         # sets the value to nil
+
+If you set the value to an RGeo object, the factory needs to match the factory for the attribute. If the factories do not match, activerecord-postgis-adapter will attempt to cast the value to the correct factory.
+
+  p2 = factory.point(-122, 47)       # p2 is a point in a spherical factory
+  record.lonlat = p2                 # sets the value to the given point
+  record.shape1 = p2                 # shape1 uses a flat geos factory, so it
+                                     # will cast p2 into that coordinate system
+                                     # before setting the value
+  record.save
+
+If, however, you attempt to set the value to the wrong type-- for example, setting a linestring attribute to a point value, you will get an exception from Postgres when you attempt to save the record.
+
+  record.path = p2      # This will appear to work, but...
+  record.save           # This will raise an exception from the database
+
+=== Spatial Queries
+
+You can create simple queries based on representational equality in the same way you would on a scalar column:
+
+  record2 = MySpatialTable.where(:lonlat => factory.point(-122, 47)).first
+
+You can also use WKT:
+
+  record3 = MySpatialTable.where(:lonlat => 'POINT(-122 47)').first
+
+Note that these queries use representational equality, meaning they return records where the lonlat value matches the given value exactly. A 0.00001 degree difference would not match, nor would a different representation of the same geometry (like a multipoint with a single element). Equality queries aren't generally all that useful in real world applications. Typically, if you want to perform a spatial query, you'll look for, say, all the points within a given area. For those queries, you'll need to use the standard spatial SQL functions provided by PostGIS.
+
+Unfortunately, Rails by itself doesn't provide good support for embedding arbitrary function calls in your where clause. You could get around this by writing raw SQL. But the solution we recommend is to use the "squeel" gem. This gem extends the \ActiveRecord syntax to support more complex queries.
+
+Let's say you wanted to find all records whose lonlat fell within a particular polygon. In the query, you can accomplish this by calling the ST_Intersects() SQL function on the lonlat and the polygon. That is, you'd want to generate SQL that looks something like this:
+
+  SELECT * FROM my_spatial_table WHERE ST_Intersects(lonlat, <i>my-polygon</i>);
+
+Using squeel, you can write this as follows:
+
+  my_polygon = get_my_polygon()       # Obtain the polygon as an RGeo geometry
+  MySpatialTable.where{st_intersects(lonlat, my_polygon)}.first
+
+Notice the curly brackets instead of parentheses in the where clause. This is how to write squeel queries: squeel is actually a DSL, and you're passing a block to the where method instead of an argument list. Also note that Squeel requires \ActiveRecord 3.1 or later to handle SQL function calls such as ST_Intersects.
+
+As another example, one common query is to find all objects displaying in a window. This can be done using the overlap (&&) operator with a bounding box. Here's an example that finds linestrings in the "path" column that intersect a bounding box:
+
+  sw = get_sw_corner_in_projected_coordinates()
+  ne = get_ne_corner_in_projected_coordinates()
+  window = RGeo::Cartesian::BoundingBox.create_from_points(sw, ne)
+  MySpatialTable.where{path.op('&&', window)}.all
+
+Note that bounding box queries make sense only in a projected coordinate system; you shouldn't try to run such a query against a lat/long (geographic) column.
+
+== License
+
+Copyright 2010-2013 Daniel Azuma
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+* Neither the name of the copyright holder, nor the names of any other
+  contributors to this software, may be used to endorse or promote products
+  derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/History.rdoc

@@ -1,3 +1,8 @@
+=== 0.6.0 / 2013-02-28
+
+* Experimental support for the recently released Rails 4.0 beta.
+* Documentation improvements.
+
 === 0.5.1 / 2013-02-04
 
 * Database creation properly treats geometry_columns as a view when setting owner. (Pull request by hendrikstier)

data/README.rdoc

@@ -1,300 +1,52 @@
 == PostGIS \ActiveRecord Adapter
 
-The PostGIS \ActiveRecord Adapter is an \ActiveRecord connection adapter
-based on the standard postgresql adapter. It extends the standard adapter
-to provide support for the spatial extensions provided by PostGIS, using
-the {RGeo}[http://github.com/dazuma/rgeo] library to represent spatial
-data in Ruby. Like the standard postgresql adapter, this adapter requires
-the pg gem.
-
-== What This Adapter Provides
-
-=== Spatial Migrations
-
-First, this adapter extends the migration syntax to support creating 
-spatial columns and indexes. To create a spatial column, use the
-<tt>:geometry</tt> type, or any of the OGC spatial types such as
-<tt>:point</tt> or <tt>:line_string</tt> to set a geometry type
-constraint. You may also provide any of the following options:
-
-* <tt>:geographic</tt> -- If set to true, create a PostGIS geography
-  column; otherwise create a geometry column. Default is false.
-* <tt>:srid</tt> -- Set a SRID constraint for the column. Default is 4326
-  for a geography column, or -1 for a geometry column. Note that PostGIS
-  currently (as of version 1.5.2) requires geography columns to have SRID
-  4326, so this constraint is of limited use for geography columns.
-* <tt>:has_z</tt> -- Specify that objects in this column include a Z
-  coordinate. Default is false.
-* <tt>:has_m</tt> -- Specify that objects in this column include an M
-  coordinate. Default is false.
-
-To create a spatial index, set the <tt>:spatial</tt> option to true when
-creating the index.
-
-Examples:
-
-  create_table :my_spatial_table do |t|
-    t.column :shape, :geometry  # or t.geometry :shape
-    t.line_string :path, :srid => 3785
-    t.point :lonlat, :geographic => true
-  end
-  change_table :my_spatial_table do |t|
-    t.index :lonlat, :spatial => true
-  end
-
-=== Spatial Attributes
-
-When this adapter is in use, spatial attributes in your \ActiveRecord
-objects will have RGeo geometry values. You can set spatial attributes
-either to RGeo geometry objects, or to strings in WKT (well-known text)
-format, which the adapter will automatically convert to geometry objects.
-
-Spatial objects in RGeo are tied to a factory that specifies the
-coordinate system as well as other behaviors of the object. You must
-therefore specify a factory for each spatial column (attribute) in your
-\ActiveRecord class. You can either set an explicit factory for a specific
-column, or provide a factory generator that will yield the appropriate
-factory for the table's spatial columns based on their types. For the
-former, call the <tt>set_rgeo_factory_for_column</tt> class method on your
-\ActiveRecord class. For the latter, set the rgeo_factory_generator class
-attribute. This generator should understand the usual <tt>:srid</tt>,
-<tt>:has_z_coordinate</tt>, and <tt>:has_m_coordinate</tt> options. It
-will also be passed a <tt>:geographic</tt> option indicating whether the
-column is a geography column. The set_rgeo_factory_for_column and 
-rgeo_factory_generator methods are actually implemented and documented in
-the "rgeo-activerecord" gem.
-
-Examples, given the spatial table defined above:
-
-  class MySpatialTable < ActiveRecord::Base
-    
-    # By default, use the GEOS implementation for spatial columns.
-    self.rgeo_factory_generator = RGeo::Geos.factory_generator
-    
-    # But use a geographic implementation for the :lonlat column.
-    set_rgeo_factory_for_column(:lonlat, RGeo::Geographic.spherical_factory(:srid => 4326))
-    
-  end
-
-Now you can interact with the data using the RGeo types:
-
-  rec = MySpatialTable.new
-  rec.lonlat = 'POINT(-122 47)'   # You can set by feature object or WKT.
-  loc = rec.lonlat                # Accessing always returns a feature object, in
-                                  # this case, a geographic that understands latitude.
-  loc.latitude                    # => 47
-  rec.shape = loc                 # the factory for the :shape column is GEOS, so the
-                                  # value will be cast from geographic to GEOS.
-  RGeo::Geos.is_geos?(rec.shape)  # => true
-
-=== Spatial Queries
-
-You can create simple queries based on objective equality in the same way
-you would on a scalar column:
-
-  rec = MySpatialTable.where(:lonlat => RGeo::Geos.factory.point(-122, 47)).first
-
-You can also use WKT:
-
-  rec = MySpatialTable.where(:lonlat => 'POINT(-122 47)').first
-
-Most more complex spatial queries require the use of SQL functions. You
-can write such queries in raw SQL, but you may find the "squeel" gem
-very helpful in this regard. Using squeel, you can write queries like
-the following:
-
-  my_polygon = get_my_polygon()
-  MySpatialTable.where{st_intersects(lonlat, my_polygon)}.first
-
-Note that using squeel to create SQL functions requires Rails 3.1 or later.
-
-One common query is to find all objects displaying in a window. This can
-be done using the overlap (&&) operator with a bounding box. Here's an
-example that finds linestrings in the "path" column that intersect a
-bounding box:
-
-  sw = get_sw_corner_in_projected_coordinates()
-  ne = get_ne_corner_in_projected_coordinates()
-  window = RGeo::Cartesian::BoundingBox.create_from_points(sw, ne)
-  MySpatialTable.where{path.op('&&', window)}.all
-
-Note that bounding box queries make sense only in a projected coordinate
-system; you shouldn't try to run such a query against a lat/long
-(geographic) column.
-
-== Installation And Configuration
-
-=== Installing The Adapter Gem
-
-This adapter has the following requirements:
+The activerecord-postgis-adapter is a plugin that provides access to features of the PostGIS geospatial database from \ActiveRecord. Technically, it extends the standard postgresql adapter to provide support for the spatial data types and features added by the PostGIS extension. It uses the {RGeo}[http://github.com/dazuma/rgeo] library to represent spatial data in Ruby.
 
-* Ruby 1.8.7 or later. Ruby 1.9.2 or later preferred. JRuby 1.6.3 or
-  later also supported.
+== About the PostGIS Adapter
+
+This is a brief summary covering how to use activerecord-postgis-adapter. For full documentation, see Documentation.rdoc.
+
+=== Features
+
+The adapter provides three basic capabilities.
+
+First, it provides *spatial migrations*. It extends the \ActiveRecord migration syntax to support creating spatially-typed columns and spatial indexes. You can control the various PostGIS-provided attributes such as srid, dimension, and geographic vs geometric math.
+
+Second, it recognizes spatial types and casts them properly to RGeo geometry objects. The adapter can configure these objects automatically based on the srid and dimension in the database table, or you can tell it to convert the data to a different form. You can also set attribute data using WKT format.
+
+Third, it lets you include simple spatial data in queries. WKT format data and RGeo objects can be embedded in where clauses. If you include the Squeel gem, the adapter also supports advanced queries utilizing the standard SQL spatial function set.
+
+=== Requirements
+
+The adapter has the following requirements.
+
+* Ruby 1.8.7 or later. Ruby 1.9.2 or later preferred. JRuby 1.6.3 or later also supported.
 * PostgreSQL 9.0 or later.
 * PostGIS 1.5, PostGIS 2.0, or later.
-* \ActiveRecord 3.0.3 or later. Earlier versions will not work.
-  Should be compatible with Rails versions through 3.2.x.
-* rgeo gem 0.3.20 or later.
-* rgeo-activerecord gem 0.4.6 or later.
+* \ActiveRecord 3.0.3 or later. Earlier versions will not work. Rails 4.0 is supported on an experimental basis.
+* The rgeo and rgeo-activerecord gems are also required.
+
+As of this writing, the JDBC Postgres driver is not yet compatible with Rails 4, so the combination of JRuby/JDBC/Rails 4 is not yet supported. Similarly, Rubinius receives limited testing and support.
+
+=== Installation and Configuration
+
+To install this adapter in a Rails application, add it to your Gemfile:
 
-Please note that this version of the adapter is targeted towards Rails
-3.x only. The upcoming version 0.6 will target Rails 4.0.
+  gem 'activerecord-postgis-adapter'
 
-Install this adapter as a gem:
+and run bundle install to update your bundle.
+
+Alternately, if you are not using bundler, install it separately as a gem:
 
   gem install activerecord-postgis-adapter
 
-See the README for the "rgeo" gem, a required dependency, for further
-installation information.
-
-=== Basic Setup
-
-To use this adapter, add this gem, "activerecord-postgis-adapter", to
-your Gemfile, and then request the adapter name "postgis" in your
-database connection configuration (which, for a Rails application, is in
-the config/database.yml file). Most of the rest of the configuration
-parameters are identical to those used by the stock "postgresql" adapter,
-so you can create a new Rails application using:
-
-  rails new my_app --database=postgresql
-
-...and then just change the adapter name to "postgis".
-
-Next, the PostGIS adapter includes a special railtie that provides
-support for PostGIS databases in ActiveRecord's rake tasks. This railtie
-is required in order to run, e.g., rake test. To install this railtie,
-you should add this line to your config/application.rb:
-
-  require 'active_record/connection_adapters/postgis_adapter/railtie'
-
-Note that this railtie must load after the ActiveRecord railtie. That is,
-the above require command should appear after <tt>require 'rails/all'</tt>.
-
-Besides the adapter name "postgis", most of the other database connection
-configuration parameters are the same as for the stock postgresql adapter.
-However, there are several important differences:
-
-The <i>postgis_extension</i> parameter is specific to the PostGIS adapter,
-and directs the adapter to use PostgreSQL's CREATE EXTENSION mechanism to
-install the PostGIS types, functions, and tables to a newly created
-database. Generally, the value should be set to true, although you can
-also set it to a comma-delimited list of extension names (which should
-include the base "postgis" extension) if you want to customize which
-extensions are installed. This is the easiest and cleanest way to create
-a PostGIS-enabled database, but it requires PostgreSQL 9.1 or later AND
-PostGIS 2.0 or later.
-
-The <i>script_dir</i> parameter is specific to the PostGIS adapter, and
-provides an alternative mechanism for installing the PostGIS definitions
-into a new database if either PostgreSQL 9.1 or PostGIS 2.0 is not
-available. Its value should be set to the path to the directory containing
-the SQL scripts for PostGIS installation. This is the directory containing
-the files <tt>postgis.sql</tt> and <tt>spatial_ref_sys.sql</tt>. (A common
-setting might be <tt>/usr/local/share/contrib/postgis-1.5</tt>.)
-
-If you do not provide <i>postgis_extension</i> or <i>script_dir</i>, you
-will need to add the PostGIS definitions to the database manually.
-Generally, therefore, one of them is required at least for the test
-database, which is usually automatically created by the rake tasks.
-
-The <i>su_username</i> and <i>su_password</i> parameters are provided as
-optional parameters. If present, they specify an auxiliary PostgreSQL role
-that must have superuser privileges, and will be used for two functions:
-
-* Creation of the database. This is so the main database user that you
-  specify doesn't need superuser or createdb privileges.
-* Installation of the PostGIS definitions, if requested by the presence
-  of <i>script_dir</i>. This process normally requires a PostgreSQL role
-  with superuser privileges, so again if you don't want your main database
-  user to have superuser, you can perform this one-time procedure using
-  this alternate user.
-
-Any schemas listed in the <i>schema_search_path</i> parameter are
-automatically created by <tt>rake db:create</tt>. This is arguably what
-the stock PostgreSQL adapter should be doing anyway.
-
-If the schema name "postgis" is included in the <i>schema_search_path</i>
-parameter, the PostGIS adapter omits it from a SQL structure dump. This
-can be useful to prevent PostGIS definitions from appearing in the dump
-as described below.
-
-=== Dealing With PostGIS Definitions
-
-PostGIS adds many objects (types, functions, triggers, meta-information
-tables, and other elements) to a PostgreSQL database. These objects are
-required for PostGIS to do its magic, but they can be a hassle when you
-are managing a database using Rails and \ActiveRecord. For example:
-
-* Dumping the structure as sql (rake db:structure:dump) may include all
-  the PostGIS definitions as well, cluttering your SQL dump.
-* Rake tasks that automatically create the test database (e.g. rake test)
-  may fail or emit a number of errors, because PostGIS definitions are
-  either missing from or being added twice to the test database.
-
-To deal with these issues, we recommend the following technique:
-
-* Set either <i>postgis_extension</i> or <i>script_dir</i> in both your
-  development and test database configurations. This will cause the
-  PostGIS Adapter to automatically add the PostGIS definitions and
-  spatial references to your databases when rake db:create is run.
-* Include "postgis" in your <i>schema_search_path</i> for both your
-  development and test databases. It is recommended that you include it
-  as the <i>last</i> element, so that your application's tables don't get
-  added to it by default. For example:
-    schema_search_path: public,postgis
-  The PostGIS Adapter responds to this special name by sandboxing the
-  PostGIS definitions into it when rake db:create is run, and it omits
-  this schema when running SQL structure dumps.
-* Provide a separate <i>su_username</i> and <i>su_password</i> role for
-  your database, and make sure that separate role has the SUPERUSER
-  privilege. This will cause the PostGIS Adapter to log in as that role
-  when creating the database, since the PostGIS definition installation
-  requires SUPERUSER. Alternately, you can give the normal database role
-  SUPERUSER privilege, which may be okay for a private development
-  database. These are used only by <tt>rake db:create</tt> so you can
-  remove them from your database.yml for your staging or production
-  databases once you've performed the initial creation.
-
-Finally, you generally should _not_ set the \ActiveRecord schema format
-to <tt>:sql</tt>. You should leave it set to <tt>:ruby</tt>. The reason
-is that SQL structure dumps do not currently properly emit the correct
-<tt>AddGeometryColumn</tt> calls to create geometry columns. As a result,
-the <tt>geometry_columns</tt> table will not be populated properly, among
-other issues. Instead, the schema.rb output by the Ruby schema format
-should properly replicate the schema. This is a known issue that we are
-investigating.
-
-Of course, the above steps are only really necessary if you are using the
-\ActiveRecord rake tasks that create databases, either directly such as
-<tt>rake db:create</tt>, or indirectly such as <tt>rake test</tt>. They
-should not be necessary for running migrations or normal website execution.
-
-== Additional Information
-
-=== Known bugs and limitations
-
-The PostGIS Adapter has not yet been tested in a large variety of
-environments, and we are still fixing bugs. Here is a partial list of
-current known issues.
-
-* Dumping as SQL (i.e. rake db:structure:dump) does not properly emit
-  <tt>AddGeometryColumn</tt> calls, and so does not completely create the
-  spatial schema (e.g. it fails to add the proper row to the
-  <tt>geometry_columns</tt> table.) Because of this, you should not depend
-  on a SQL dump to be an accurate representation of the schema. (That is,
-  you should not set <tt>config.active_record.schema_format</tt> to
-  <tt>:sql</tt>.)
-* Other rake tasks may not be supported. Unfortunately, Rails makes it
-  difficult for custom \ActiveRecord adapters to support the standard
-  rake tasks.
-* Rails 4 is not yet supported. The good news is that the base PostgreSQL
-  adapter has been refactored in Rails 4 to make it easier to extend, so
-  once we get it ported to Rails 4, activerecord-postgis-adapter should
-  be cleaner and more stable.
-
-=== Development and support
-
-Documentation is available at http://dazuma.github.com/activerecord-postgis-adapter/rdoc
+Please note that this adapter uses the rgeo gem, which may have additional dependencies. Please see the \README documentation for rgeo for more information.
+
+Once you have installed the adapter, you'll need to edit your config/database.yml to call for it. At minimum, this means changing the adapter name from "postgresql" to "postgis". It may also require other settings to ensure that other functions (such as rake test) continue to work as expected. We recommend reading the Configuration section in the Documentation.rdoc file carefully before starting to use this adapter.
+
+== Development and Support
+
+\Documentation is available at http://dazuma.github.com/activerecord-postgis-adapter/rdoc
 
 Source code is hosted on Github at http://github.com/dazuma/activerecord-postgis-adapter
 
@@ -306,7 +58,7 @@ Support available on the rgeo-users google group at http://groups.google.com/gro
 
 Contact the author at dazuma at gmail dot com.
 
-=== Acknowledgments
+== Acknowledgments
 
 The PostGIS Adapter and its supporting libraries (including RGeo) are
 written by Daniel Azuma (http://www.daniel-azuma.com).
@@ -318,9 +70,9 @@ This adapter implementation owes some debt to the spatial_adapter plugin
 different design decisions for this adapter, studying the spatial_adapter
 source gave us a head start on the implementation.
 
-=== License
+== License
 
-Copyright 2010-2012 Daniel Azuma
+Copyright 2010-2013 Daniel Azuma
 
 All rights reserved.