NAME

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

VERSION

version 0.900001

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.

The schema-level storage extensions (ensure_postgis, postgis_version, the PostGIS-aware deploy class) live on the DBIO::PostgreSQL::PostGIS::Storage layer. Loading this component registers that layer (via "register_storage_layer" in DBIO::Schema), so it is composed over the resolved driver storage (see DBIO::Storage::Composed). Loading the component is all you do:

package MyApp::Schema;
use DBIO 'Schema';
__PACKAGE__->load_components('PostgreSQL', 'PostgreSQL::PostGIS');

To pull in the storage layer without the result-class geometry inflation (unusual), register it directly instead of loading the component:

__PACKAGE__->register_storage_layer('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 layer 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.