activerecord-postgis-adapter, PostGIS spatial types inside ActiveRecord

An extension of the postgresql adapter, not a replacement

The activerecord-postgis-adapter gives ActiveRecord access to the features of the PostGIS geospatial database. It extends the standard postgresql adapter rather than replacing it, which is the key architectural decision. Everything ActiveRecord already knows about PostgreSQL keeps working, and the spatial types and features added by the PostGIS extension are layered on top of that behaviour.

Spatial data itself is represented through the RGeo library, which handles the geometry objects in Ruby. The split of responsibility is clean: PostGIS provides the column types, the spatial indexes and the server-side spatial functions, RGeo provides the in-memory object model, and the adapter is the translation layer between ActiveRecord, the two of them and PostgreSQL.

The adapter provides three basic capabilities, and it is worth separating them because they are used at different stages of a project's life. The first is spatial migrations, extending the migration syntax to create spatially typed columns and spatial indexes, with control over the PostGIS attributes such as SRID, dimension, and the choice between geographic and geometric math. The second is type recognition and casting, so spatial columns are cast properly to RGeo geometry objects, configured automatically from the SRID and dimension in the table or converted to a different form, with attribute data settable in WKT format. The third is query support, where WKT data and RGeo objects can be embedded in where clauses.

Spatial migrations that speak geometry, linestring and st_point

PostGIS provides a variety of spatial types, including point, linestring, polygon and different kinds of collections, and these types are defined in a standard produced by the Open Geospatial Consortium. The adapter extends ActiveRecord's migration syntax to support them, with options that indicate the coordinate system and the number of coordinates stored for the values.

A migration creates spatial columns through the usual table DSL:

create_table :my_spatial_table do |t|
  t.column :shape1, :geometry
  t.geometry :shape2
  t.line_string :path, srid: 3785
  t.st_point :lonlat, geographic: true
  t.st_point :lonlatheight, geographic: true, has_z: true
end

Two ways of declaring a column appear in that snippet. The generic t.column with the type :geometry creates the base type, which can hold values of any spatial type, while the specific helpers such as t.geometry, t.line_string and t.st_point produce the narrower column types. The options carry the PostGIS attributes: srid sets the coordinate reference system, geographic switches from planar geometric math to geographic, and has_z adds the third coordinate.

Those three options are the whole spatial contract of a column, and they are the decisions to get right. A column created with a wrong SRID stores the data fine and returns wrong answers later, because the value itself carries no record of what it was supposed to mean.

RGeo casting, SRID-aware configuration and WKT assignment

The second capability is recognition. When ActiveRecord reads a row, the adapter sees that the column is spatial and casts it to an RGeo geometry object rather than handing back a string. The configuration of that object can be automatic, based on the SRID and dimension found in the database table, or you can tell the adapter to convert the data into a different form.

Automatic configuration is the sensible default, because it means the Ruby object agrees with what the column actually stores. A forced conversion is the escape hatch for the cases where you want a specific RGeo factory or a different representation than the column implies, at the cost of the adapter doing work on every read.

Attribute data can also be set using WKT format, the well-known text representation. That matters for fixtures, seeds and tests, where writing a geometry as a readable string is far more maintainable than the binary or hex form a raw column would take. The third capability ties the two together: simple spatial data can be included in queries, so WKT data and RGeo objects can be embedded in where clauses. A predicate against a geometry column is then written in the same style as any other ActiveRecord condition, with the geometry expressed in the language you already use for the model.

The scope is worth being clear about. These are the spatial types, the casting and the query embedding. The adapter does not attempt to be a spatial query builder, and the server-side spatial functions are the ones PostGIS provides.

Setting up a Rails app around the adapter

The setup path assumes a Rails application. Create it with the PostgreSQL database option:

rails new my_app --database=postgresql

Then add the gem to the Gemfile:

gem 'activerecord-postgis-adapter'

And point ActiveRecord at the adapter by setting the adapter field in config/database.yml:

default: &default
  adapter: postgis

The database then has to exist, which is done with rake db:create. PostGIS itself is enabled through a migration, generated with rails generate migration AddPostgisExtensionToDatabase, and the generated file enables the extension:

class AddPostgisExtensionToDatabase < ActiveRecord::Migration[7.2]
  def change
    enable_extension 'postgis'
  end
end

Running rails db:migrate applies it. The order matters and the documentation makes it explicit: the extension has to be enabled in the database before any table with spatial columns can be created, so the extension migration comes first and the spatial table migrations follow.

One piece of configuration catches people out. If the PostGIS extension is installed in a schema other than the default public, that schema has to be added to schema_search_path, and the adapter also exposes options such as postgis_extension, postgis_schema, encoding, pool and the usual connection fields.

The version table is the upgrade cost

The adapter ships a version compatibility table, and it is the most useful page in the README for anyone planning an upgrade. The current line, 11.1.x, pairs with ActiveRecord 8.1, requires Ruby 3.2.0 or newer and PostGIS 2.0 or newer. The 11.0.x line pairs with ActiveRecord 8.0, 10.x with 7.2, 9.x with 7.1, 8.x with 7.0 and 7.x with 6.1.

Two things stand out. The lower end of the table goes back a long way, with older adapter versions supporting Ruby 1.9.3 and JRuby, but the newer lines no longer list JRuby, so a JRuby shop has to stay on an older adapter version or accept a rewrite. The other is that PostGIS 2.0+ is listed for the version table while the install requirements ask for PostgreSQL 9.0 or newer and PostGIS 2.4 or newer, so the table describes what the code tolerates and the install section describes what it recommends.

The upgrade notes are specific about two breaking changes. The PostgisDatabaseTasks module was removed in version 8.x, which means the rake tasks for installing PostGIS are no longer available and an existing Rails app has to follow the documented upgrade path instead. Upgrading from 6.x to a newer major version may also require changes to the SpatialFactoryStore configuration, with the detail living in the rgeo-activerecord README.

The last push to the repository was on 2026-04-16 and there are no GitHub releases for it, so version numbers are read from the compatibility table and the gem rather than from release notes.

Installing PostGIS and running the test database

PostGIS has to be installed before the adapter is useful, and the README lists the common methods. On macOS with Homebrew it is a single command:

brew install postgis

On Ubuntu and Debian:

sudo apt-get install postgis postgresql-16-postgis-3

On Windows it is likely available as an optional package through the PostgreSQL installer, and the installation guide is the fallback. More detailed methods are pointed to on the PostGIS site.

The repository also carries a docker-compose.yml for running the test database, which shows the shape of a PostGIS service the adapter is exercised against:

services:
  db:
    image: postgis/postgis:11-3.0
    ports:
      - 5432:5432
    environment:
      POSTGRES_HOST_AUTH_METHOD: trust
      POSTGRES_USER: postgres
      POSTGRES_DB: postgis_adapter_test
      POSTGRES_PASSWORD: postgres

Two details in that file are deliberate. The image is a specific PostGIS build, not a plain PostgreSQL image, since the extension has to exist in the server. And the authentication method is set to trust with a fixed database name, which is fine for a throwaway test container and would be a serious mistake anywhere else. The rest of the repository follows the usual Ruby gem layout, with lib/, test/, bin/, a Rakefile, a gemspec, a Gemfile, and rubocop configuration split between .rubocop.yml and .rubocop_todo.yml.

Where this adapter stops and a plain adapter will do

The adapter is deliberately narrow, and there are projects where it is the wrong choice. If your application stores a geometry and never queries it spatially, the standard postgresql adapter will store the column and the RGeo layer will be unnecessary weight. The spatial machinery pays for itself when you use spatial indexes, spatial predicates or geographic math.

The second limitation is the licence. The repository does not carry a standard open source licence identifier, and the licensing metadata points to a custom licence in the LICENSE file. The file itself is at the top level of the repository, named LICENSE.txt. For a gem that ends up inside a commercial product that matters, and it is the first thing to read before the version table.

The alternative approach is rgeo-activerecord, the companion project the README points to for SpatialFactoryStore configuration, which is documented as covering the older PostGIS 1 generation of the stack and lives in its own repository with its own README. That is the route for a system still on PostGIS 1, or one whose configuration predates the 6.x to 7.x change. For a current PostGIS 2.4 or later database on a supported ActiveRecord and Ruby version, this adapter is the direct path, and the RGeo casting and the spatial migration syntax are the two features that justify it.

Editorial conclusion

activerecord-postgis-adapter suits Rails teams that want PostGIS columns, spatial indexes and RGeo geometry objects through ordinary ActiveRecord migrations, and it does not suit projects that need spatial functions beyond what the adapter exposes or teams unwilling to depend on a custom licence file. Before adopting it, check the version compatibility table against your ActiveRecord and Ruby versions, confirm PostGIS 2.4 or higher is what you will run, and read LICENSE.txt, since the repository does not use a standard licence identifier.

Frequently asked questions

Official sources

1. Issues
2. README
3. rgeo/activerecord-postgis-adapter on GitHub