activerecord-postgis 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d2022a537c5f4ac8fcdff4b7e9fb5a8801167da139a23df3095c66c5da4cad86
+  data.tar.gz: 174ed2a80856954bc39fae2bd479c47d3508f50ae5ed5ba2dfea458b2741a955
+SHA512:
+  metadata.gz: a5c66a366cf6e101c9adb412abc8f5714299f9d38c005125a9fff1ba54d0621190acdd391b7fcdf99f16bbf36a59b45a6504d99ef6fffa4d0165f6acff5db8e4
+  data.tar.gz: 2ba4c06a28dbef90a5aff91db38732e6df62cb9d19f65d363b883d5b49e8895aba4622c9b6f81f21892812b201c88a8c8310e6f2c027404d339ab00a29c237e3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Abdelkader Boudih
+
+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.md

@@ -0,0 +1,194 @@
+# ActiveRecord::PostGIS
+
+**The next-generation PostGIS adapter for Rails** - clean, modern, and built for the future.
+
+## Why This Gem?
+
+This is the **next-generation PostGIS adapter** that brings PostGIS support to Rails the right way:
+
+✅ **Use standard `postgres://` URLs** - No custom adapter names, no special configuration  
+✅ **No monkey patching** - Clean extensions using Rails 8 patterns  
+✅ **No obscure hacks** - Transparent, well-documented implementation  
+✅ **Latest APIs** - Built for Rails 8+ and Ruby 3.3+  
+✅ **Zero configuration** - Just add the gem and it works  
+
+Unlike legacy PostGIS adapters that require custom database URLs, special configurations, and complex setup, this gem **extends the existing PostgreSQL adapter** seamlessly. Your database configuration stays clean and standard.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'activerecord-postgis'
+```
+
+And then execute:
+
+```
+$ bundle install
+```
+
+Or install it yourself as:
+
+```
+$ gem install activerecord-postgis
+```
+
+## Configuration
+
+**Zero configuration required!** Just use your standard PostgreSQL database configuration:
+
+```yaml
+# config/database.yml
+development:
+  adapter: postgresql
+  url: postgres://user:password@localhost/myapp_development
+  # That's it! No special adapter, no custom configuration
+```
+
+## Usage
+
+### Migrations
+
+Create spatial columns using PostGIS types:
+
+```ruby
+class CreateLocations < ActiveRecord::Migration[8.0]
+  def change
+    create_table :locations do |t|
+      t.st_point :coordinates, srid: 4326
+      t.st_polygon :boundary, geographic: true
+      t.st_line_string :route, has_z: true
+      t.timestamps
+    end
+  end
+end
+```
+
+### Spatial Queries
+
+**With RGeo Objects** (Recommended):
+
+```ruby
+# Create RGeo geometries
+factory = RGeo::Geographic.spherical_factory(srid: 4326)
+point = factory.point(-5.923647, 35.790897)  # Cap Spartel, Tangier, Morocco
+polygon = factory.polygon(...)
+
+# Direct queries with RGeo objects
+Location.where(coordinates: point)
+Location.where("ST_Distance(coordinates, ?) < ?", point, 1000)
+
+# Using parameterized queries (automatically quoted)
+locations_nearby = Location.where(
+  "ST_DWithin(coordinates, ?, ?)", 
+  point, 
+  1000  # meters
+)
+
+# Complex spatial queries
+parks_in_city = Park.where(
+  "ST_Within(boundary, ?)", 
+  city_polygon
+)
+```
+
+**With Arel Spatial Methods**:
+
+```ruby
+# Find locations within distance
+Location.where(
+  Location.arel_table[:coordinates].st_distance(point).lt(1000)
+)
+
+# Find polygons that contain a point
+Boundary.where(
+  Boundary.arel_table[:area].st_contains(Arel.spatial(point))
+)
+
+# Calculate lengths and areas
+Route.select(
+  Route.arel_table[:path].st_length.as('distance')
+)
+```
+
+**With WKT Strings**:
+
+```ruby
+# Using Well-Known Text format
+Location.where(
+  "ST_Distance(coordinates, ST_GeomFromText(?)) < ?",
+  "POINT(-5.923647 35.790897)",
+  1000
+)
+```
+
+### Model Integration
+
+```ruby
+class Location < ApplicationRecord
+  # Works automatically - no configuration needed
+  # Spatial attributes are automatically parsed and serialized
+end
+
+location = Location.create!(
+  coordinates: "POINT(-5.923647 35.790897)"  # Tangier, Morocco
+)
+
+puts location.coordinates.x  # -5.923647
+puts location.coordinates.y  # 35.790897
+```
+
+## Features
+
+🌍 **Complete PostGIS Type Support**
+- `st_point`, `st_line_string`, `st_polygon` 
+- `st_multi_point`, `st_multi_line_string`, `st_multi_polygon`
+- `st_geometry_collection`, `st_geography`
+- Support for SRID, Z/M dimensions
+
+🔍 **Spatial Query Methods**
+- `st_distance`, `st_contains`, `st_within`, `st_length`
+- Custom Arel visitor for PostGIS SQL generation
+- Seamless integration with ActiveRecord queries
+
+⚡ **Modern Architecture**
+- Built on Rails 8 patterns
+- Clean module extensions (no inheritance)
+- Proper type registration and schema dumping
+- Compatible with multi-database setups
+
+🛠️ **Developer Experience**
+- Standard `postgres://` URLs
+- Works with existing PostgreSQL tools
+- Clear error messages and debugging
+- Full RGeo integration
+
+## Acknowledgments
+
+This gem builds upon the incredible work of many contributors to the Ruby geospatial ecosystem:
+
+🙏 **RGeo Ecosystem** - The foundation that makes Ruby geospatial possible:
+- [RGeo](https://github.com/rgeo/rgeo) originally by Daniel Azuma, currently maintained by Keith Doggett (@keithdoggett) and Ulysse Buonomo (@BuonOmo)
+- [RGeo::ActiveRecord](https://github.com/rgeo/rgeo-activerecord) for ActiveRecord integration
+- [RGeo::Proj4](https://github.com/rgeo/rgeo-proj4) for coordinate system transformations
+- Former maintainer Tee Parham and all contributors who built this ecosystem
+
+🗺️ **PostGIS Pioneers** - Previous PostGIS adapters that paved the way:
+- [activerecord-postgis-adapter](https://github.com/rgeo/activerecord-postgis-adapter) by Daniel Azuma and the RGeo team
+- All the maintainers and contributors who solved spatial data challenges in Rails
+
+🌍 **PostGIS & GEOS** - The underlying spatial powerhouses:
+- PostGIS developers for the amazing spatial database extension
+- GEOS contributors for computational geometry
+- PostgreSQL team for the solid foundation
+
+This gem exists because of their pioneering work. I'm simply bringing it into the modern Rails era with cleaner patterns and zero configuration.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/seuros/activerecord-postgis.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/activerecord-postgis.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'lib/active_record/connection_adapters/postgis/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'activerecord-postgis'
+  spec.version = ActiveRecord::ConnectionAdapters::PostGIS::VERSION
+  spec.authors = [ 'Abdelkader Boudih' ]
+  spec.email = [ 'terminale@gmail.com' ]
+
+  spec.summary = 'PostGIS Type support for ActiveRecord'
+  spec.description = spec.summary
+  spec.homepage = 'https://github.com/seuros/activerecord-postgis'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.3.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/master/CHANGELOG.md"
+
+  gemspec = File.basename(__FILE__)
+  spec.files = Dir.glob('{lib}/**/*') + [ gemspec, 'LICENSE.txt', 'README.md' ]
+  spec.require_paths = [ 'lib' ]
+
+  spec.add_dependency 'activerecord', '>= 8.0', '< 8.1'
+  spec.add_dependency 'pg'
+  spec.add_dependency 'rgeo-activerecord', '>= 8.0'
+end

data/lib/active_record/connection_adapters/postgis/adapter_extensions.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module PostGIS
+      module AdapterExtensions
+        # Override type_to_sql to handle PostGIS spatial types
+        def type_to_sql(type, limit: nil, precision: nil, scale: nil, geographic: false, srid: nil, has_z: false, has_m: false, **options)
+          if type.to_s =~ /^st_/ || type.to_s == "geography"
+            geometric_type = type.to_s.sub(/^st_/, "")
+
+            # If limit contains our custom format, parse it
+            if limit.is_a?(String) && limit.include?(",")
+              geo_part, srid_part = limit.split(",", 2)
+              # Extract geometry type from the limit if provided
+              if geo_part && !geo_part.empty? && geo_part != geometric_type.upcase
+                geometric_type = geo_part.downcase
+              end
+              # Extract SRID from limit
+              if srid_part && !srid_part.empty?
+                srid = srid_part.to_i
+              end
+              # Extract Z/M modifiers
+              if geo_part && geo_part.include?("Z")
+                has_z = true
+                geometric_type = geo_part.gsub(/[ZM]/, "").downcase
+              end
+              if geo_part && geo_part.include?("M")
+                has_m = true
+                geometric_type = geo_part.gsub(/[ZM]/, "").downcase
+              end
+            end
+
+            PostGIS::SpatialColumnType.new(
+              geometric_type,
+              srid,
+              has_z: has_z,
+              has_m: has_m,
+              geography: geographic
+            ).to_sql
+          else
+            super
+          end
+        end
+
+        # Override to handle PostGIS types
+        def lookup_cast_type(sql_type)
+          # Handle PostGIS types
+          if sql_type.to_s =~ /^(geometry|geography)/i
+            type_name = case sql_type.to_s
+            when /geography\(Point/i, /geometry\(Point/i then :st_point
+            when /geography\(LineString/i, /geometry\(LineString/i then :st_line_string
+            when /geography\(Polygon/i, /geometry\(Polygon/i then :st_polygon
+            when /geography\(MultiPoint/i, /geometry\(MultiPoint/i then :st_multi_point
+            when /geography\(MultiLineString/i, /geometry\(MultiLineString/i then :st_multi_line_string
+            when /geography\(MultiPolygon/i, /geometry\(MultiPolygon/i then :st_multi_polygon
+            when /geography\(GeometryCollection/i, /geometry\(GeometryCollection/i then :st_geometry_collection
+            when /geography/i then :st_geography
+            when /geometry/i then :st_geometry
+            else
+                          :st_geometry
+            end
+
+            ActiveRecord::Type.lookup(type_name, adapter: adapter_name.downcase.to_sym)
+          else
+            super
+          end
+        end
+
+        # Override create_table_definition to use our custom table definition
+        def create_table_definition(*args, **kwargs)
+          table_def = super(*args, **kwargs)
+          table_def.extend(PostGIS::TableDefinition)
+          table_def
+        end
+
+        # Use PostGIS Arel visitor for spatial queries
+        def arel_visitor
+          require_relative "../../../arel/visitors/postgis"
+          @arel_visitor ||= Arel::Visitors::PostGIS.new(self)
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/postgis/column_extensions.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module PostGIS
+      module ColumnExtensions
+        def spatial?
+          type.to_s.start_with?("st_") ||
+          [ :geography, :geometry, :geometry_collection, :line_string,
+           :multi_line_string, :multi_point, :multi_polygon, :polygon ].include?(type.to_sym)
+        end
+
+        def geographic?
+          sql_type.start_with?("geography") || (spatial? && limit.is_a?(Hash) && limit[:geographic])
+        end
+
+        def srid
+          if spatial?
+            if limit.is_a?(Hash) && limit[:srid]
+              limit[:srid]
+            elsif sql_type =~ /,(\d+)\)/
+              $1.to_i
+            else
+              geographic? ? 4326 : 0
+            end
+          else
+            nil
+          end
+        end
+
+
+        def geometric_type
+          if spatial?
+            case type.to_sym
+            when :st_point then RGeo::Feature::Point
+            when :st_line_string then RGeo::Feature::LineString
+            when :st_polygon then RGeo::Feature::Polygon
+            when :st_multi_point then RGeo::Feature::MultiPoint
+            when :st_multi_line_string then RGeo::Feature::MultiLineString
+            when :st_multi_polygon then RGeo::Feature::MultiPolygon
+            when :st_geometry_collection then RGeo::Feature::GeometryCollection
+            when :st_geometry then RGeo::Feature::Geometry
+            when :st_geography then RGeo::Feature::Geometry
+            # Legacy types
+            when :geometry then RGeo::Feature::Geometry
+            when :geography then RGeo::Feature::Geometry
+            when :line_string then RGeo::Feature::LineString
+            when :polygon then RGeo::Feature::Polygon
+            when :multi_point then RGeo::Feature::MultiPoint
+            when :multi_line_string then RGeo::Feature::MultiLineString
+            when :multi_polygon then RGeo::Feature::MultiPolygon
+            when :geometry_collection then RGeo::Feature::GeometryCollection
+            else RGeo::Feature::Geometry
+            end
+          else
+            nil
+          end
+        end
+
+        def has_z?
+          if spatial?
+            if limit.is_a?(Hash) && limit.key?(:has_z)
+              limit[:has_z]
+            elsif sql_type =~ /\b\w+Z\b|\b\w+ZM\b/
+              true
+            else
+              false
+            end
+          else
+            nil
+          end
+        end
+
+        def has_m?
+          if spatial?
+            if limit.is_a?(Hash) && limit.key?(:has_m)
+              limit[:has_m]
+            elsif sql_type =~ /\b\w+M\b|\b\w+ZM\b/
+              true
+            else
+              false
+            end
+          else
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/postgis/column_methods.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module PostGIS
+      module ColumnMethods
+        # Override to handle PostGIS types in column definitions
+        def new_column_from_field(table_name, field, _definitions)
+          column_name = field["column_name"]
+          type_metadata = fetch_type_metadata(column_name, field["data_type"], field["sql_type"], field)
+
+          # Handle PostGIS types
+          if field["sql_type"] =~ /geometry|geography/i
+            type_metadata = handle_spatial_type_metadata(field["sql_type"], type_metadata)
+          end
+
+          default_value = extract_value_from_default(field["column_default"])
+          default_function = extract_default_function(field["column_default"], default_value)
+
+          PostgreSQL::Column.new(
+            column_name,
+            default_value,
+            type_metadata,
+            field["is_nullable"] == "YES",
+            default_function,
+            comment: field["comment"].presence
+          )
+        end
+
+        private
+
+        def handle_spatial_type_metadata(sql_type, original_metadata)
+          # Parse spatial type info
+          type_name = case sql_type
+          when /geography\(Point/i, /geometry\(Point/i then "point"
+          when /geography\(LineString/i, /geometry\(LineString/i then "line_string"
+          when /geography\(Polygon/i, /geometry\(Polygon/i then "polygon"
+          when /geography\(MultiPoint/i, /geometry\(MultiPoint/i then "multi_point"
+          when /geography\(MultiLineString/i, /geometry\(MultiLineString/i then "multi_line_string"
+          when /geography\(MultiPolygon/i, /geometry\(MultiPolygon/i then "multi_polygon"
+          when /geography\(GeometryCollection/i, /geometry\(GeometryCollection/i then "geometry_collection"
+          when /geography/i then "geography"
+          when /geometry/i then "geometry"
+          else
+                        return original_metadata
+          end
+
+          # Create new type metadata with spatial type
+          type = ActiveRecord::Type.lookup(type_name.to_sym, adapter: adapter_name.downcase.to_sym)
+          ActiveRecord::ConnectionAdapters::SqlTypeMetadata.new(
+            sql_type: sql_type,
+            type: type,
+            limit: original_metadata.limit,
+            precision: original_metadata.precision,
+            scale: original_metadata.scale
+          )
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/postgis/constants.rb

@@ -0,0 +1,36 @@
+# lib/active_record/connection_adapters/postgis/constants.rb
+
+module ActiveRecord
+  module ConnectionAdapters
+    module PostGIS
+      SPATIAL_TYPES = %i[
+        geometry
+        geography
+        point
+        line_string
+        polygon
+        multi_point
+        multi_line_string
+        multi_polygon
+        geometry_collection
+      ].freeze
+
+      GEOMETRIC_TYPES = %i[
+        st_geography
+        st_geometry
+        st_geometry_collection
+        st_line_string
+        st_multi_line_string
+        st_multi_point
+        st_multi_polygon
+        st_point
+        st_polygon
+      ].freeze
+
+      VALID_TYPES = %w[
+        point line_string polygon multi_point
+        multi_line_string multi_polygon geometry_collection geography
+      ].freeze
+    end
+  end
+end

data/lib/active_record/connection_adapters/postgis/oid/spatial.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module PostGIS
+      module OID
+        # OID used to represent geometry/geography database types and attributes.
+        #
+        # Accepts `geo_type`, `srid`, `has_z`, `has_m`, and `geographic` as parameters.
+        # Responsible for parsing sql_types returned from the database and WKT features.
+        class Spatial < Type::Value
+          def initialize(geo_type: "geometry", srid: 0, has_z: false, has_m: false, geographic: false)
+            @geo_type = geo_type
+            @srid = srid
+            @has_z = has_z
+            @has_m = has_m
+            @geographic = geographic
+          end
+
+          # sql_type: geometry, geometry(Point), geometry(Point,4326), ...
+          #
+          # returns [geo_type, srid, has_z, has_m]
+          #   geo_type: geography, geometry, point, line_string, polygon, ...
+          #   srid:     1234
+          #   has_z:    false
+          #   has_m:    false
+          def self.parse_sql_type(sql_type)
+            geo_type = nil
+            srid = 0
+            has_z = false
+            has_m = false
+
+            if sql_type =~ /(geography|geometry)\((.*)\)$/i
+              # geometry(Point)
+              # geometry(Point,4326)
+              params = Regexp.last_match(2).split(",")
+              if params.first =~ /([a-z]+[^zm])(z?)(m?)/i
+                has_z = Regexp.last_match(2).length.positive?
+                has_m = Regexp.last_match(3).length.positive?
+                geo_type = Regexp.last_match(1)
+              end
+              srid = Regexp.last_match(1).to_i if params.last =~ /(\d+)/
+            else
+              # geometry
+              # otherType(a,b)
+              geo_type = sql_type
+            end
+            geographic = sql_type.match?(/geography/)
+
+            [ geo_type, srid, has_z, has_m, geographic ]
+          end
+
+          def spatial_factory
+            @spatial_factory ||=
+              RGeo::ActiveRecord::SpatialFactoryStore.instance.factory(
+                factory_attrs
+              )
+          end
+
+          def spatial?
+            true
+          end
+
+          def type
+            @geographic ? :geography : :geometry
+          end
+
+          # support setting an RGeo object or a WKT string
+          def serialize(value)
+            return if value.nil?
+
+            geo_value = cast_value(value)
+
+            # TODO: - only valid types should be allowed
+            # e.g. linestring is not valid for point column
+            # raise "maybe should raise" unless RGeo::Feature::Geometry.check_type(geo_value)
+
+            RGeo::WKRep::WKBGenerator.new(hex_format: true, type_format: :ewkb, emit_ewkb_srid: true)
+                                     .generate(geo_value)
+          end
+
+          private
+
+          def cast_value(value)
+            return if value.nil?
+
+            value.is_a?(String) ? parse_wkt(value) : value
+          end
+
+          # convert WKT string into RGeo object
+          def parse_wkt(string)
+            wkt_parser(string).parse(string)
+          rescue RGeo::Error::ParseError
+            nil
+          end
+
+          def binary_string?(string)
+            string[0] == "\x00" || string[0] == "\x01" || string[0, 4] =~ /[0-9a-fA-F]{4}/
+          end
+
+          def wkt_parser(string)
+            if binary_string?(string)
+              RGeo::WKRep::WKBParser.new(spatial_factory, support_ewkb: true, default_srid: @srid)
+            else
+              RGeo::WKRep::WKTParser.new(spatial_factory, support_ewkt: true, default_srid: @srid)
+            end
+          end
+
+          def factory_attrs
+            {
+              geo_type: @geo_type.underscore,
+              has_m: @has_m,
+              has_z: @has_z,
+              srid: @srid,
+              sql_type: type.to_s
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/postgis/oid/spatial_types.rb

@@ -0,0 +1,26 @@
+module ActiveRecord
+  module ConnectionAdapters
+    module PostGIS
+      module OID
+        SPATIAL_TYPES = %i[
+          geometry
+          geography
+          point
+          line_string
+          polygon
+          multi_point
+          multi_line_string
+          multi_polygon
+          geometry_collection
+        ]
+
+        SPATIAL_TYPES.each do |type|
+          class_name = "St#{type.to_s.camelize}"
+          const_set(class_name, Class.new(Spatial) do
+            define_method(:type) { :"st_#{type}" }
+          end)
+        end
+      end
+    end
+  end
+end