NAME

DBIO::PostgreSQL::PostGIS - PostGIS spatial extension support for DBIO::PostgreSQL

VERSION

version 0.900000

SYNOPSIS

package MyApp::Schema::Result::Place;
use base 'DBIO::Core';
__PACKAGE__->load_components('PostgreSQL::PostGIS');
__PACKAGE__->table('place');
__PACKAGE__->add_columns(
  id   => { data_type => 'integer', is_auto_increment => 1 },
  name => { data_type => 'text' },
  geom => {
    data_type     => 'geometry',
    geometry_type => 'POINT',
    srid          => 4326,
  },
);

# Inflated reads
my $place = $schema->resultset('Place')->find(1);
$place->geom->isa('DBIO::PostgreSQL::PostGIS::Geometry');
$place->geom->x;        # longitude
$place->geom->y;        # latitude

# Deflated writes — pass a Geometry object, the helper builds EWKT
$place->geom(
  DBIO::PostgreSQL::PostGIS::Geometry->point(13.4, 52.5, srid => 4326),
);
$place->update;

# Spatial query — raw SQL via -bool literal
my $rs = $schema->resultset('Place')->search({
  -bool => \['ST_DWithin(geom, ST_MakePoint(?, ?)::geography, ?)',
             $lon, $lat, $meters],
});

DESCRIPTION

DBIO::PostgreSQL::PostGIS is a result-class component that adds PostGIS spatial type handling to DBIO result classes:

• Columns with data_type => 'geometry' or 'geography' are automatically inflated to DBIO::PostgreSQL::PostGIS::Geometry objects on read and deflated back to EWKT on write.

• Spatial-query helpers are mixed into the resultset class via DBIO::PostgreSQL::PostGIS::ResultSet.

For the schema-level storage extensions (ensure_postgis, postgis_version), set storage_type on the schema:

package MyApp::Schema;
use base 'DBIO::Schema';
__PACKAGE__->storage_type('+DBIO::PostgreSQL::PostGIS::Storage');

METHODS

register_column

Hooks into the column registration chain. When a column declares data_type => 'geometry' or 'geography', registers inflate/deflate handlers that round-trip DBIO::PostgreSQL::PostGIS::Geometry objects through EWKT.

Override the auto-detection by setting inflate_geometry => 0 explicitly on the column.

Also promotes the result source's resultset_class to DBIO::PostgreSQL::PostGIS::ResultSet the first time a spatial column is registered, giving the resultset spatial-query helpers (within_distance, nearest_to, etc.). If you need custom resultset methods alongside the PostGIS helpers, subclass DBIO::PostgreSQL::PostGIS::ResultSet and set resultset_class to your subclass — the promotion guard skips any class that already inherits from DBIO::PostgreSQL::PostGIS::ResultSet.

• DBIO::PostgreSQL - Base PostgreSQL driver component

• DBIO::PostgreSQL::PostGIS::Geometry - Lightweight geometry value object

• DBIO::PostgreSQL::PostGIS::Storage - Storage class with spatial methods

• DBIO::PostgreSQL::PostGIS::ResultSet - Spatial query helpers

AUTHOR

DBIO Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.